roadmap

name	roadmap
compatibility	Built for Claude Code (interactive questions). Installs on any Agent Skills client.
allowed-tools	Bash, Read, Grep, Glob, Write, Edit, Task, AskUserQuestion
description	Turn an idea into a living, coarse feature roadmap, or keep an existing one current. Run /roadmap with a product idea (plan), with a single feature (add one row), or bare after shipping (replan/reconcile). Writes docs/roadmap/: ordered, weighted features with intent and acceptance-criteria seeds, foundations first, sliced by a chosen build approach. Owns all roadmap files.

Read ../conventions.md first (once per session). It carries the session start gate, model routing (this skill: strongest tier), panel rules, subagent rules, and output style. Apply the start gate before anything below.

What this skill does

The planner. Produces and maintains the coarse plan every other skill navigates by: features ordered and weighted, each with a 1 to 2 line intent and a one-line Done when: (acceptance-criteria seeds /architect later grows into a full spec). Coarse on purpose: a feature starts as one checkbox (its entry command) and grows its built-ready shape only when its ADR is captured.

Owns: everything under docs/roadmap/. Never: writes ADRs, code, or AGENTS.md; never names tools or providers (capabilities, yes; the tool is /architect's call); never plans an analysis/inventory row (that is ADR research, under docs/adr/…/research/).

Execution

Step 0 — Infer the behavior (no subcommands)

• Roadmap exists + no argument (or "reconcile / what's next") → Replan.
• Roadmap exists + the argument names a single feature → Add.
• No roadmap + a product-sized idea (or a next-slice request, incl. brownfield) → Plan (below). Ambiguous: infer the likely reading, say which you chose in the report; truly unclear, ask one line. Plan behavior with no idea given: ask "What are you building? One or two sentences, what it does and who it's for." Wait.

Step 1 — Locate; greenfield / brownfield / monorepo

Detect with file tools (skip node_modules/, .git/): any source files (presence = brownfield) · root AGENTS.md · an existing roadmap (docs/roadmap/roadmap.md, or index.md + epic files; per-workspace subdirs in a monorepo).

Brownfield: read root AGENTS.md (and any roadmap) so you plan the next slice on top of what exists. Enroll already-built features for context (a fast read-only subagent maps a large repo; never read the tree inline), each with a Code area pointer, statused honestly from the code: complete and shipped → existing (a distinct marker, not done); partially built → in-progress. No root AGENTS.md: note that /audit should run first.

Existing roadmap (re-run): read the whole roadmap as the dedup baseline (all statuses). Never duplicate: overlapping requests extend the existing row. Reconcile drift: shipped work or ADRs no row covers get enrolled (existing/done/in-progress) and reported as "drift enrolled." Edit in place, never a dated copy; out-of-scope rows go dropped, never deleted.

Monorepo (workspaces config, or apps/*/packages/* manifests): each workspace gets docs/roadmap/<workspace>/; repo-wide work goes in _root/; a top-level docs/roadmap/index.md maps workspaces with a one-line status rollup each. Bare /roadmap on a monorepo asks which workspace (panel). A feature spanning workspaces is planned in _root or split per workspace, never buried in one app's file.

Step 2 — Ask (batched panel rounds)

Generate questions for this idea; infer and skip what is stated. Up to 4 per round, as few rounds as possible:

• Round 1, product and business: the MVP boundary (the most important question, everything hangs off it) · primary audience (only if unclear) · monetization (free / subscription / one-time / usage / ads / none yet) · success metric · hard constraints (deadline, budget, team, compliance). These shape phasing and weights.
• Round 2, capabilities (multi-select): the cross-cutting capabilities this product plausibly needs (auth, orgs/multi-tenant, payments, email/notifications, uploads, search, realtime, admin, public API), in scope now vs deferred. Name capabilities, never tools.
• Round 3, cross-cutting and go-to-market (routinely forgotten): SEO (public pages only) · performance targets · analytics and error monitoring · accessibility target · internationalization · legal (cookie consent, privacy/terms, GDPR, age gating). Each yes becomes a feature or a seed on one.

Step 3 — Choose the build approach (panel; the most far-reaching call)

Reason as a product engineer about this product, present the approaches by principle, recommend exactly one with a one-line why: Tracer Bullet (default for production: end-to-end vertical slices) · Skateboard (fast validation: thinnest usable whole first) · Journey (the funnel is the product: one complete path per phase) · Facade (quick clickable prototype; say plainly it is prototype-grade). Record it in the roadmap header as Build approach: <name> — <one-line principle>; it propagates project-wide (/audit//sync persist it to AGENTS.md; /architect and /develop honor it). It is the default; a single feature may override with an Approach tag beside its heading (add the tag only when it differs).

Step 4 — Foundations first (every approach obeys this)

No feature slice before the ground it stands on. Lead with explicit foundation features, in this reasoned default order:

1. Standards preferences (light, un-inferable taste; may fold into the stack feature). Needs ADR: no.
2. Stack and architecture: ONE feature, two sub-tasks: Decision (/architect) then Scaffold (/develop). The ADR records only the decision; scaffold steps are derived at build time (double-spec bug otherwise). Scaffold installs the base, not the shopping list; later features install their own dependencies just in time. Needs ADR: yes, weight medium+.
3. Coding standards and tooling: /audit captures conventions and tooling choices into root AGENTS.md from the real, scaffolded project (never before scaffold), then /develop tooling installs them. Needs ADR: no.
4. Data model: explicit, non-skippable, Needs ADR: yes. The most expensive thing to redo.
5. Design system / UI foundation (if meaningful UI): /architect → design.md, then base components. Needs ADR: yes.
6. Walking-skeleton slice: one trivial real thing wired end to end (DB → API → UI), proving the stack is connected. Under Tracer Bullet this merges with the first real slice.

Then the feature slices, shaped by the approach, not just labeled by it: a flat feature list wearing Slice N stickers has not honored the approach. Tracer Bullet: the first post-foundation slice is the thinnest thread through the core user journey touching every layer (nothing more; no full auth feature and admin panel before the loop runs once), later slices thicken one segment each. Skateboard: the thinnest usable whole, then growth. Journey: one complete path per phase. Facade: shells first, wiring later. A thin thread leans on the shared foundational ADRs, so far fewer rows need their own; if nearly every row is Needs ADR: yes, you decomposed into full features, re-slice. The Phasing column marks Foundation / Skeleton / Slice N / Deferred; Order is the integer build sequence.

Step 5 — Decompose (you reason; don't ask)

Per feature: keep it small (one page or one cohesive unit; a listing, a product page, and a cart are three features) · Intent (1 to 2 lines) · Done when: (one compact line of observable outcomes; seeds, not a spec) · Weight (lean / medium / full, from risk, scope, compliance) · Approach override only when it truly differs (its own panel, inherit (recommended) on top) · Needs ADR? by the invent-test (provider/library choice, data model, cross-cutting pattern, unspecced page, non-trivial behavior → yes; unsure → yes; full weight → almost always yes). One decision per ADR: several distinct decisions on one feature = several flagged items; one broad decision that splits = an umbrella. No build-task breakdown here: one checkbox, the entry command (/architect <feature> when flagged, else /develop <feature>; the tooling foundation's first box is /audit). /architect fills the built-ready shape when the ADR lands.

Step 6 — Write it

Re-list the location right before writing (a teammate may have moved it), then write per roadmap-template.md: small product → single roadmap.md (At-a-glance table + feature sections grouped by phase + legend); large → index.md + one file per epic, promoted only when a single file has outgrown a comfortable scan; semantic names, never numbered.

References consent (one panel): same three levels as /architect (none (recommended) · sources · sources+links); at sources+links a sourcing subagent web-verifies links into a ## References section.

Step 7 — Report and hand off

Short report: what was planned (features, phases, approach), what was enrolled or reconciled, where it was written. Close: "Next: /clear, then <the first unticked box's command>."

Replan (bare re-run after shipping)

Read the union (see Step 1 re-run rules), reconcile statuses against the code and ADRs, enroll drift, sharpen upcoming rows, re-weigh what changed, report the deltas. Never renumber or rewrite untouched rows.

Add (one ad-hoc feature)

Locate the right file, dedup, write one row in Step 5 shape with the next free #, place it in the right phase, report. No full re-plan.

Reference files (lazy)

roadmap-template.md (file structure, At-a-glance table, feature-section shape, status legend, lifecycle table).