roadmap

Create a phased roadmap for: $ARGUMENTS

Parse Arguments

The argument can be:

• Phase name: /roadmap auth-system — creates docs/roadmap/NNN_auth-system.md where NNN is the next available 3-digit prefix
• No argument: /roadmap — reads PRD, architecture, and any existing specs to create a full roadmap with numbered phase files
• Doc path: /roadmap docs/specs/feature_x.md — creates a roadmap for a single spec or feature area

Phase Numbering

All phase files get a zero-padded 3-digit prefix so phase order is obvious at a glance and files sort correctly: 001_foundations.md, 002_api-layer.md, 003_frontend.md, etc. The index file docs/roadmap/README.md stays unnumbered — it's the table of contents, not a phase.

Rules:

• Scan, don't renumber. Before creating a phase, list docs/roadmap/ and extract existing NNN_*.md prefixes. Use max(existing) + 1, zero-padded to 3 digits. Never renumber existing files — commits, PRs, and specs may reference them by name.
• Full roadmap from scratch: first phase is 001_, numbered in dependency order.
• Adding to an existing roadmap: continue from the next available number.
• Separator is underscore (001_auth-system.md), not dash, to keep the numeric prefix visually distinct from the kebab-case phase slug.

Context Gathering

Before anything, read what exists:

1. Design docs (primary input for the roadmap):

   • Read docs/PRD.md or docs/prd/ — the source of what needs to be built
   • Read docs/ARCHITECTURE.md — the source of how the system is structured
   • Read docs/TECHNICAL_DESIGN_DOCUMENT.md — testing strategy, dev environment, CI/CD
   • Read docs/THREAT_MODEL.md — security constraints, trust boundaries
   • Read CLAUDE.md for build commands and conventions
   • Read README.md for project overview

2. Existing specs (optional — specs may not exist yet):

   • List all files in docs/specs/
   • If feature specs exist, read them — they add detail to the roadmap
   • If no feature specs exist, that's fine — the roadmap will define what needs to be specified