!${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh roadmap 2>&1 || true

@.claude/shirabe-extensions/roadmap.md @.claude/shirabe-extensions/roadmap.local.md

Roadmap Documents

Roadmap documents sequence features into a coordinated initiative. They capture the theme (why these features belong together), the features themselves, dependency relationships, sequencing rationale, and progress. They are the last link in the strategic chain (VISION -> STRATEGY -> ROADMAP): a roadmap's upstream is the STRATEGY it sequences -- its immediate neighbour, and not the VISION two levels up, which this skill never writes even though the validator tolerates it in an existing corpus (see references/roadmap-format.md) -- and downstream of it sit the BRIEFs and PRDs that frame and define individual features in detail.

What a Roadmap Is For

Sequencing is only half a roadmap's job. The other half matters just as much:

• It is the progress ledger for a strategy's execution. The per-feature status in the Features and Progress sections is the only place that records how far along the work is, and the completion cascade updates it as downstream plans land. Without a roadmap, a strategy has no ledger.
• It is the only bridge from the strategic chain to the tactical one. /brief is framed against a ROADMAP -- never a STRATEGY, and never a PRD, which sits downstream of a BRIEF rather than above it. The brief reads the roadmap and records the roadmap's own parent, often this roadmap's STRATEGY; the ROADMAP itself is named by the PLAN the chain produces, because a durable document may not name one that the cascade deletes. A strategy whose work is a single feature would be stranded if it could not have a roadmap: no legal path into /scope, and no progress tracking.

Both jobs work with one feature. A roadmap requires at least one feature; there is no two-feature floor. Most roadmaps do sequence several features, and coordinated multi-feature work is where a roadmap earns the most -- but a one-feature roadmap is a coherent ledger, not a degenerate one, and refusing to write it strands actionable work for no benefit.

A roadmap with zero features is still malformed: there is nothing to track, nothing to sequence, and nothing to hand downstream. That is the only count shirabe transition rejects on Draft -> Active.

Writing style: Read skills/writing-style/SKILL.md for guidance.

Artifact Lifecycle

Lifecycle: Working. Completion condition: all features on the ROADMAP are at status Done AND all referenced GitHub issues are closed.

The lifecycle states are Draft -> Active -> Done -> DELETED, mirroring the working-artifact lifecycle template established in docs/designs/current/DESIGN-lifecycle-draft-ready-discipline.md.

Deleted by: the work-on cascade's handle_roadmap_deletion step.

The handle_roadmap_deletion step is the new cascade extension shipped alongside this contract. It runs after the existing PLAN finalization step, inside the same cascade window the work-on flow already uses.

Roadmap Format

See references/roadmap-format.md for the full format specification: frontmatter schema, required and optional sections, lifecycle states, validation rules, and quality guidance. Load it during Phases 3 and 4.

New roadmaps are milestone roadmaps (schema: roadmap/v3): each item is an outcome someone can exercise end to end, with Evidence someone other than the delivering session can judge and a Left open for the decisions that session makes. The items sit under ## Milestones, and a classic item is headed ### Milestone <N>: <title>. The format reference's Milestones section has the fields, the Evidence rule, the rule for when a milestone is Done, and what may change once the roadmap is Active. roadmap/v2 (the same milestones under ## Features, headed ### Feature <N>:) and the per-feature roadmap/v1 stay valid; this skill edits them in their own version and never migrates one unasked.

File Location

Roadmap documents live at docs/roadmaps/ROADMAP-<topic>.md (kebab-case). No directory movement at any lifecycle stage -- all roadmaps stay in docs/roadmaps/ regardless of status. Stable paths keep cross-references durable and git blame readable.

Creating a Roadmap Document

When invoked as /roadmap, this skill drives a structured creation workflow that scopes the initiative conversationally, fans out research agents to validate features and dependencies, drafts the ROADMAP with section-level review, and validates through jury review.

Unlike an explore workflow (which is open-ended and can produce any artifact type), /roadmap always produces a ROADMAP document. Use /roadmap when you know you need a sequenced, tracked feature list for a strategy's execution. Use an explore workflow when you don't know what artifact type you need yet.

Input Modes

From $ARGUMENTS:

1. Empty -- ask the user what initiative or theme they want to create a roadmap for
2. Path to existing ROADMAP with lifecycle verb (activate, done) -- execute the lifecycle transition via shirabe transition <roadmap-path> <status>
3. populate <path> -- the issue-filing action, and the way to re-populate a roadmap's reserved sections out of band. A normal /roadmap run already fills those sections issuelessly (Phase 4), so the reason to type this is usually to file GitHub issues for an already-approved roadmap. Invokes the shirabe roadmap populate subcommand on the shirabe CLI. The mode resolves on flag > ## Roadmap Issues: header > issueless default: pass --issues to create one GitHub issue per feature and key the table/diagram on those issues, or --no-issues to re-render from feature context with no issues created. Issue filing goes through the R14 approval gate; issueless population does not. See Populating the Issues Table below.
4. Anything else -- use as the starting topic for Phase 1 scoping

Session and Keys

/roadmap keeps its working state as keys in its own koto session, roadmap-<topic>, following ${CLAUDE_PLUGIN_ROOT}/references/skill-session-convention.md. It writes no file to the staging folder, chained or direct. Its first act, once the topic is known (from the argument) and before Context Resolution or the resume rows below, opens the session and records whether it runs under a parent:

"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" open roadmap <topic>
"${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" adopt roadmap <topic>

open attaches to a live roadmap-<topic> (an interrupted run, whose keys the resume rows read), replaces a finished one (a fresh run), or creates it. Any non-zero exit from either command stops the run with the script's message: 127 or 69 means koto is missing or too old, and the skill never falls back to files. adopt exiting 3 is the two-parents case below.

Keys are read and written with koto against roadmap-<topic>: koto context exists roadmap-<topic> <key> tests one (exit 0 present, 1 absent), koto context get roadmap-<topic> <key> prints it, koto context add roadmap-<topic> <key> stores the content given on stdin (the whole content: to change part of it, get the key, edit it, and add it back), koto context list roadmap-<topic> --prefix <prefix> lists keys, and koto context remove roadmap-<topic> <key> removes one. Research and reviewer agents never write keys: each phase that spawns them pins every output to a file in a skill-session.sh scratch directory and ingests it.

Closing. A direct run closes its session when it finishes: "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" close roadmap-<topic> done at the end of Phase 4, or close roadmap-<topic> abandoned after a discard. Under a parent /roadmap never closes its own session: the parent closes it at its own exit (skill-session.sh close-children), and the keys stay readable until then.

Standalone Entry and Handoff Detection

/roadmap works both standalone and as a handoff target from /charter.

Under /charter (the first resume row below matches parent=charter-<topic>), /charter has written the scope it derived from the STRATEGY the chain just produced to key chain/roadmap-scope in its own session. /roadmap reads it with koto context get charter-<topic> chain/roadmap-scope, uses it as its scope input, and records its own work/scope.md in roadmap-<topic> from it. It carries the seven fields /charter derives (theme statement, initial scope, candidate features, dependency sketch, sequencing constraints, downstream artifact state, coverage notes). Skip Phase 1 (scoping) and proceed directly to Phase 2 (discover) -- the scope provides the theme and candidate features as investigation targets. Nothing pre-populates a roadmap scope file on disk.

/roadmap ignores chain/roadmap-scope when dispatch read names another child or matches no parent: it never reads that key on the strength of a charter-<topic> session merely existing. It then derives scope as a direct run does. The other way work/scope.md can already exist is that /roadmap's own Phase 1 wrote it and the run was interrupted before Phase 2 finished, which lands in the same place: Phase 1 is done either way, so the run continues at Phase 2.

If neither exists, start from Phase 1.

Context Resolution

Execution mode: check $ARGUMENTS for --auto or --interactive flags, then CLAUDE.md ## Execution Mode: header (default: interactive). Also parse --max-rounds=N (default: 2 for roadmap's discover loop). In --auto mode, follow decision-protocol conventions -- make decisions based on evidence rather than blocking on user input. Track decisions in key work/decisions.md in roadmap-<topic>.

Roadmap issues preference: read CLAUDE.md's ## Roadmap Issues: header the same way ## Execution Mode: is read -- grep the header, take the value after the colon. Resolve to required only when the value is exactly required; resolve to optional when the header is absent or carries any other value (fail-closed toward the path with no remote side effect). Record the resolved value in the run's context so the populate phase can branch on it. The validator never reads this header; it's a skill-only preference. See ${CLAUDE_PLUGIN_ROOT}/references/fixes/claude-md-conventions.md for the header format.

The preference governs one thing only: which mode a human-invoked /roadmap populate <path> picks when they pass no flag. It does NOT govern the automatic population this workflow performs in Phase 4 and on the activate path -- those are always issueless, because an automatic run must never create issues. The full resolution stack is flag > ## Roadmap Issues: header > issueless default.

Upstream: check $ARGUMENTS for --upstream <path>. If present, the path is stored and written to frontmatter during Phase 3 (draft). It points to the STRATEGY this roadmap sequences -- the roadmap's immediate neighbour one level up the strategic chain. /charter passes it on every chain it runs; a user invoking /roadmap standalone passes it when a STRATEGY exists. When no STRATEGY exists, omit the flag rather than reaching past the neighbour to a VISION; the upstream field is then omitted from frontmatter. See references/roadmap-format.md for the rule and why the links stay one level deep.

Log: Drafting roadmap...

Workflow Phases

Phase 0: SETUP --> Phase 1: SCOPE --> Phase 2: DISCOVER --> Phase 3: DRAFT --> Phase 4: VALIDATE
(branch)          (conversational)   (agents fan out)     (iterative)        (jury review)
                       |                                       ^
                       |                                       |
                       +--- may loop back to DISCOVER or DRAFT-+

Phase 1 tracks 6 roadmap-specific coverage dimensions:

Phase 2 agents investigate: feature completeness (gaps, granularity), dependency accuracy (hidden dependencies, stated dependency validation), and sequencing justification (ordering rationale, parallelization opportunities, needs-* annotation accuracy).

Phase 4 jury focuses on roadmap-specific quality: Do features belong together under the theme? Are dependencies explicit, not implied? Is there circular dependency? Do needs-* labels match feature descriptions? Does the roadmap avoid downstream content (requirements, architecture, timelines)? Is there at least one feature to track?

Resume Logic

dispatch read roadmap <topic> prints parent=<session>
                                                           -> run under that parent; see ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md
ROADMAP exists, "Active", schema roadmap/v2 or roadmap/v3  -> Offer: sharpen one milestone's Evidence or Left open in place,
                                                              or start a new roadmap (references/phases/sharpen.md)
ROADMAP exists, "Active", schema roadmap/v1                -> Offer: start a new roadmap
ROADMAP exists with status "Done"                          -> Offer to revise or start fresh
ROADMAP exists with status "Draft"                         -> Offer to continue from Phase 3
keys research/phase2_* exist in roadmap-<topic>            -> Resume at Phase 3
key work/scope.md exists in roadmap-<topic>                -> Resume at Phase 2
On a branch related to the topic                           -> Resume at Phase 1
On main or unrelated branch                                -> Start at Phase 0

Running under a parent. The first row runs "${CLAUDE_PLUGIN_ROOT}/scripts/skill-session.sh" dispatch read roadmap <topic> with the topic this run works on. A printed parent=<session> line means /roadmap runs under that parent (scope-<topic> or charter-<topic>), with the parent's upfront decision in the rationale= and suppress_status_aware_prompt= lines; what changes under a parent is in ${CLAUDE_PLUGIN_ROOT}/references/fixes/sub-agent-dispatch.md. Four cases are no match. Three print nothing and exit 0, and the run is a direct one with the rows below unchanged: no parent session, a finished parent session, and a parent whose chain/dispatch key names another child. The fourth, two parent sessions that both name /roadmap, exits 3: don't pick one and don't run directly; stop and report both sessions, which the script names on stderr, so the author can clear the stale key. Any other non-zero exit stops the run with the script's message (open has already checked koto). adopt has recorded the same match as chain/parent in roadmap-<topic>, or removed a chain/parent an earlier chained run left.

Critical Requirements

• Conversational First: Phase 1 is a dialogue, not a form to fill out
• Research Before Drafting: Don't draft sequencing you haven't validated
• At Least One Feature: A roadmap with no features has nothing to sequence and nothing to track. One feature is enough -- see What a Roadmap Is For for why there is no two-feature floor
• User Review: Never finalize a ROADMAP the user hasn't reviewed and given feedback on
• Jury Validation: Phase 4 is not optional -- theme coherence, sequencing validity, and annotation accuracy all get checked

Execution

Execute phases sequentially by reading the corresponding phase file:

0. Setup: Ensure work happens on a feature branch
   • If already on a branch that matches the topic, skip branch creation
   • If on main or an unrelated branch, create docs/<topic> (kebab-case)
   • If unsure whether the current branch is related, ask the user
1. Scope: Conversational scoping
   • Instructions: references/phases/phase-1-scope.md
   • Skipped when /charter's chain/roadmap-scope was read, or key work/scope.md exists
2. Discover: Parallel research agents investigate features
   • Instructions: references/phases/phase-2-discover.md
3. Draft: Produce ROADMAP draft and walk through with user
   • Instructions: references/phases/phase-3-draft.md
4. Validate: Jury review and finalization
   • Instructions: references/phases/phase-4-validate.md

Output

Final artifact: docs/roadmaps/ROADMAP-<topic>.md, created in Draft status. After user approval, transition to Active via shirabe transition <roadmap-path> Active.

A roadmap must be Active before merging to main. Draft roadmaps should not appear on the default branch -- the transition to Active signals that the feature list is locked and the sequencing is approved.

After activation, suggest next steps:

Lifecycle Management

Roadmaps use the four-state working lifecycle: Draft -> Active -> Done -> DELETED.

Forbidden transitions: Active -> Draft (no regression), Draft -> Done (can't skip Active). Done -> DELETED is cascade-only -- it runs from the work-on cascade's handle_roadmap_deletion step and is not human-invokable; no shirabe transition <path> DELETED form exists.

Done roadmaps retain all content: features, sequencing rationale, progress, and any Implementation Issues table or Mermaid dependency graph added by /plan. Nothing is stripped. Done roadmaps are historical artifacts that remain on disk until the cascade deletes them.

The four-state machinery here mirrors the working-artifact lifecycle template established in docs/designs/current/DESIGN-lifecycle-draft-ready-discipline.md, matching the contract recorded in the ## Artifact Lifecycle section above.

Lifecycle verbs are invoked as:

/roadmap activate docs/roadmaps/ROADMAP-<topic>.md
/roadmap done docs/roadmaps/ROADMAP-<topic>.md

Both delegate to shirabe transition. The cascade-only DELETED transition has no /roadmap verb form.

Chain CI Gate (DRAFT-vs-READY Discipline)

The lifecycle.yml reusable workflow runs on every PR with strictness conditional on the PR's draft state. A DRAFT PR passes against mid-PR chain states; a READY PR requires the chain to be at one of its terminals — single-pr at-merge (PLAN deleted, BRIEF/PRD Done, DESIGN Current) or multi-pr in-flight (BRIEF Accepted, PRD Accepted/In Progress, DESIGN Current, PLAN Active) for intermediate multi-pr PRs, or multi-pr at-merge for the final verify-then-delete PR. ROADMAP-rooted multi-pr chains follow the same shape — the final per-feature PR in the chain runs the work-on cascade, which performs the atomic PLAN-delete plus BRIEF/PRD/DESIGN-transition commit before gh pr ready fires. The CI gate is the backstop for authors who bypass the cascade.

See docs/decisions/DECISION-lifecycle-strict-mode-interface-2026-06-06.md and docs/decisions/DECISION-cascade-trigger-mechanism-2026-06-06.md for the rationale on the --strict CLI flag and the cascade trigger mechanism.

Populating the Issues Table

The roadmap's reserved Implementation Issues and Dependency Graph sections are populated by the shirabe roadmap populate subcommand on the shirabe CLI. This is a roadmap-native path: the subcommand reads the items section (## Milestones on v3, ## Features on v1 and v2) using the shared shirabe-validate parser, builds a per-feature manifest, then renders the canonical table and dependency diagram and writes both into the reserved sections by structural section replacement (the body between each section's heading and the next ## heading is replaced; the heading itself is preserved).

The subcommand runs in one of two modes. Always pass one of the two mode flags explicitly. The subcommand defaults to issueless when neither is given, but that default is a backstop for a human at a shell -- no path in this skill may depend on it:

• Issueless mode (--no-issues). Creates no issues -- no gh issue create runs, and no gh call of any kind -- and renders the sections from feature context: a table keyed on each feature's label (the feature's needs-* label in the Issues column) and an F<n>-node diagram, with Dependencies cells naming features by those same F<n> indices so the column stays narrow while the key column stays readable. A label that can't serve as a table key falls back to F<n> and the run says so on stderr. The R14 gate is skipped, since there are no issues to approve (see below). This is what the automatic population in Phase 4 and on the activate path uses, unconditionally.
• Issue-creating mode (--issues). Creates one GitHub issue per feature (one gh issue create invocation per feature, discrete args), then renders an issue-keyed table and diagram. This path goes through the R14 approval gate below. Reached only by an explicit human invocation of /roadmap populate <path> --issues, after the roadmap is approved.

Passing both flags is an error: the subcommand rejects the invocation during argument parsing, so nothing is written and no gh call is made.

When population happens

1. Automatically, during a /roadmap run. Phase 4 populates issuelessly after the jury findings resolve and before the approval walkthrough, so the author reviews a complete roadmap rather than an empty skeleton. See references/phases/phase-4-validate.md.
2. Automatically, on the Draft -> Active transition. The activate path re-runs the issueless population before shirabe transition. This catches an items section edited during review and covers roadmaps created before automatic population existed. Populate is idempotent, so the re-run is a no-op when nothing changed.
3. Explicitly, to file issues. After the roadmap is approved, a human runs /roadmap populate <path> --issues. This is the only path that creates issues, and it regenerates both sections so the table carries issue links instead of labels.

The roadmap profile shape (Feature | Issues | Dependencies | Status, whose key column reads Milestone on a roadmap/v3 roadmap) and the dependency-diagram convention come from ${CLAUDE_PLUGIN_ROOT}/references/issues-table.md and ${CLAUDE_PLUGIN_ROOT}/references/dependency-diagram.md.

Invocation

/roadmap populate <path> --issues
/roadmap populate <path> --no-issues

Name the mode at the slash-command layer too. /roadmap populate <path> with no flag is the human-at-a-shell form documented under Context Resolution, where the ## Roadmap Issues: header resolves it; it is not a form this skill emits.

Or, equivalently, invoking the CLI directly from the project root. The issue-creating form, used by the post-approval issue-filing action:

shirabe roadmap populate <roadmap-path> --issues \
    --milestone "<Milestone Name>" \
    --milestone-description "Roadmap: <roadmap-path>" \
    --output-map "<mapping-output-path>"

The issueless form drops the milestone and mapping flags -- no issues are created, so there's nothing to file under a milestone or map:

shirabe roadmap populate <roadmap-path> --no-issues

Both forms name their mode. Never invoke the subcommand from this skill without one of the two flags, even though the CLI would default to issueless: the safety property is that the workflow says what it wants, not that the default happens to be harmless.

Options:

• --issues -- issue-creating mode: create one GitHub issue per feature and key both reserved sections on those issues. Mutually exclusive with --no-issues. Required to reach GitHub at all.
• --no-issues -- issueless mode: create no issues and render the reserved sections from the items section, keying table rows on item labels and naming dependencies by F<n> index. The subcommand's default when neither mode flag is given, and named explicitly by every invocation in this skill.
• --milestone <name> -- milestone for the created issues
• --milestone-description <desc> -- milestone description
• --mapping <file> -- pre-existing id->github_number mapping (re-render only)
• --output-map <file> -- write the final id->github_number mapping
• --repo <owner/repo> -- override the repo used when rendering issue links
• --dry-run -- skip gh invocations; synthesize a deterministic mapping
• -h, --help -- print help

Mode-scoped prerequisite check (issue-creating mode)

Selecting issue-creating mode is the moment /roadmap's mode:issues records become live. skills/roadmap/requires.tsv declares two of them: shirabe roadmap populate with the milestone and mapping flags, and gh, which no issueless run touches at all. Neither was checked when this skill loaded -- the load-time check evaluates always records only, because the mode had not been chosen and reporting on a record it never evaluated would be a claim it can't support. Field four of the declaration is where the deferral is visible.

So verify them here, once issue-creating mode is settled and before the R14 gate presents anything to the author:

${CLAUDE_PLUGIN_ROOT}/scripts/skill-preflight.sh roadmap --mode issues 2>&1 || true

Silence means every mode:issues record is satisfied; run the gate and carry on. Output means a prerequisite the issue-creating path depends on is not met -- report it to the author before filing anything, because a gh that isn't there fails partway through a per-feature loop and leaves the roadmap half-filed.

This is a command the skill runs mid-run through Bash, not a !-prefixed injected line at column 0, so scripts/check-skill-injection.sh -- which reads only injected lines -- never sees it and the allowed-tools frontmatter is not what governs it. It is deliberately placed here rather than in the frontmatter: the injected line runs before the model sees the body, which is before this decision exists. The 2>&1 || true guard is carried for the same reason the injected line carries it -- a missing script or an unexpanded ${CLAUDE_PLUGIN_ROOT} exits 127, and an unguarded 127 at this point kills a run that has already written the roadmap. The contract for the --mode call is in ${CLAUDE_PLUGIN_ROOT}/references/tool-declaration-policy.md.

R14 approval gate (lives in this caller, not in the subcommand)

Issue creation is the gated step (R14 in the requirements). The gate lives in this skill phase, NOT in the subcommand. The subcommand is a primitive that creates issues when invoked.

R14 gates issue creation, so it applies only in issue-creating mode. Present the gate as described below before any invocation carrying --issues. When the subcommand runs with --no-issues -- which is every automatic population, and any human invocation that resolves to issueless -- it creates no issues, so there is nothing to approve and the gate is skipped entirely. Skipping it removes a gate over an action that does not occur; it does not bypass approval over any side effect.

Because issue creation is now reached only by an explicit --issues, the gate guards a path a human has already chosen deliberately. That does not make it redundant: the gate is where the author sees the feature count, the names, and the milestone before anything is filed.

The rest of this section describes the gate as it applies in issue-creating mode.

Interactive runs. Before invoking the subcommand without --dry-run, present a summary of the features that will be turned into issues (count, names, the planned milestone). Stop for the author's approval. On approval, invoke the subcommand. On rejection, abort without calling it.

--auto runs. Record an assumed approval decision block per ${CLAUDE_PLUGIN_ROOT}/references/decision-protocol.md at high review priority (the block surfaces in the terminal summary and the PR body), then invoke the subcommand. The non-interactive guarantee is preserved.

A separate --dry-run invocation is available for the skill to inspect what the subcommand will write before the gate is reached; under --dry-run no GitHub API calls are made.

Security guarantees

• Manifest values (feature names, titles) are passed to gh as discrete Command::arg(...) arguments by Rust's std::process::Command. No shell is invoked, so content with shell metacharacters cannot inject a command -- the title round-trips verbatim into the issue and the rendered table.
• Section-replacement writes are atomic: render into a temp file inside the roadmap's parent directory, then std::fs::rename over the original. A failed run leaves the roadmap unchanged byte-for-byte.

Team Shape

/roadmap's team shape is declared in team.yaml as the machine-readable contract surface. The child layer spawns three reviewer peers at Phase 4 (theme-coherence-reviewer, sequencing-and-dependency-reviewer, annotation-and-boundary-reviewer) to validate the drafted ROADMAP.

See Dispatch Contract for v1 parent-side consumption rules.

Reference Files