Knowledge Islands repository roadmap standard
This governance skill owns the shared flat forward-work model. A project repository keeps canonical work items directly under docs/roadmap/ and one concise root orientation file; a Knowledge Base keeps the same record model directly under Streams/Roadmap/, with ki-repo-kb-streams owning that container. A repository either issues one repository-wide sequence or declares fixed area namespaces; a work item's project or theme gives its territory grouping. ki-work next is the separate process skill that applies this skill's user-confirmed transition rules to select the next work; this governance skill has no process-skill dependency.
Read the repository-roadmap standard before changing a roadmap shape or lifecycle. Read the generated rubric for the mechanical and judgment criteria. Work-item details live in the work-item-format standard. Tracked methodology sources and the REFRESH cadence live in the source list.
A status: triage record captures substantive prospective work without adopting it; ideas that do not yet pass the graduation test start as Idea: bullets in the owning Project note or theme page, or wait in _IDEAS.md when neither owns them. The ki-work next process skill owns capture, human-approved adoption, and later selection transitions.
Shared model
ROADMAP.md is a project-repository orientation: it points to docs/roadmap/ and deliberately repeats no queue information. Each canonical item is a single file at docs/roadmap/<REPO>-<NNN>-<slug>.md or Streams/Roadmap/<REPO>-<NNN>-<slug>.md; where fixed issuing areas are declared, the identifier includes its immutable area code. The matching _ISSUES.md ledger remains in the same directory, so an issued number is never reused after pruning. The item’s project, initiative, and component fields group related work for reporting; the horizon field establishes queue position; and status records the common draft → ready → in-progress → awaiting-review → done delivery lifecycle. Triage is captured but unadopted: open intake is draft, while a human-approved rejected, duplicate, or merged disposition may close directly as retained Triage / done without fabricated delivery evidence. A concise adopted item becomes an execution plan by gaining task-list plan sections in the same file: new work starts - [ ], and completed work becomes - [x]. The ki-repo table declares the stable uppercase repo_code; the roadmap table optionally declares fixed issuing areas as a map from code to title. The globally unique identifier is also used by dependencies.
Records may carry an optional target mapping with date, due-or-milestone kind and outcome; it orders only within one horizon and priority. Project references must resolve in an available registry. UNATTENDED-FIELD remains undecided and adds no field.
Operating modes
Carries the universal AUDIT · CONFORM · EDUCATE · REFRESH modes. Invoked as help / -h / ?, it emits generated HELP and stops. With no recognised mode, it emits the same HELP and, only in an interactive session, offers the mode choice and prompts for the target shown in argument-hint.
Mode AUDIT
Run ki repo audit --skill ki-work-roadmap --repo <repo> for a project repository. The catalogue applies the mechanical criteria in the generated rubric: concise root orientation; configured theme vocabulary; work-item placement, frontmatter, identity, theme grouping, lifecycle, and dependency integrity. A Knowledge Base uses ki-repo-kb-streams for container audit while its Streams/Roadmap/ records follow this shared model.
Then apply the rubric's judgment criteria by reading: item quality, horizon placement and transition readiness, stage-appropriate detail, final topic-oriented Discussion, honest lifecycle state, and coherent classification (kind, purpose, project or theme, component). Where declared ki-trades records exist, identify inbound submissions that need receiver review, outbound records with observable receiver progress that may warrant local follow-up, trade-aware hold conditions, and completion-observation references that prevent pruning a done item. Report structural or proposed local roadmap action only: never set a trade disposition, infer adoption or acceptance, move or prune a record, prioritize work, or edit another repository's state. Iterate until mechanical findings are clean and judgment findings are resolved.
After changing the catalogue or contexts, run their colocated Bun tests for item identity, frontmatter, horizon, dependency, root orientation, KB, and safe-draft fixtures.
Mode CONFORM
Run ki repo conform --skill ki-work-roadmap --repo <repo> --dry-run to inspect the proposal. In a valid repository, CONFORM repairs the concise root orientation and scaffolds a missing docs/roadmap/_ISSUES.md ledger from the highest retained issue number. It never overwrites a malformed ledger, invents work items, moves horizons, removes or rewrites authored prose, reallocates identifiers, or changes lifecycle content. Re-run AUDIT afterward.
Mode EDUCATE
Run ki repo educate --skill ki-work-roadmap --repo <repo> to render the catalogue's concern and families. To establish a new non-KB repository, scaffold the root orientation only when ROADMAP.md and docs/roadmap/ are both absent. In a KB, use the ki-repo-kb-streams skill and create no repository-roadmap artifact.
Mode REFRESH
Precondition: REFRESH writes only the canonical skill files in ki-agent-backpack. If invoked from an installed copy, stop and redirect to that harness; route recurring base-specific pressure through the ki-repo-kb IMPROVE mode.
On the cadence in the source list, compare actual repository-roadmap usage with the repository-roadmap standard, the work-item-format standard, and the generated rubric. Revisit the horizon model, item identity, theme grouping, CLI reporting, and execution quality bar. Update the source review dates and explain normative changes in the commit.
Notes
- Not every change needs a plan. A focused single-file or one-step fix can execute directly.
- Exploration needs no plan; multi-file or multi-step implementation enriches its item before execution.
- A plan answers “how”; a Decision Record answers “why”. Use
ki-decision-recordsfor the latter. - The
ki-work nextprocess skill selects and promotes work through the readiness contract defined here. - The
ki-work planprocess skill shapes an immediate draft through Ready. ki-work implementowns Ready → In progress → Awaiting review;ki-work acceptowns Awaiting review → Done and pruning by explicit work-record path or glob.- Lifecycle transitions may share a coherent planning, implementation, or closure commit; only pruning requires its own later commit after the
donerecord has landed. ki-work recapandki-work nextmay recommend pruning; they never delete canonical work-item records.- The local
scripts/shared/rubric.tsis the materialised compile-time contract fromki-skills; generic execution, findings, progress, transaction safety, rollback, and reporting belong toki.