openspec-roadmap

OpenSpec Roadmap

Bridge PRD / large epic → multiple OpenSpec changes using openspec/roadmap.md. Do not replace OpenSpec CLI skills (openspec-propose, openspec-apply-change, openspec-archive-change); orchestrate them and keep the roadmap current.

Roadmap format and templates: REFERENCE.md. The consumer repo uses exactly one roadmap file at openspec/roadmap.md.

When to use

Orchestration

`PRD.md` file / tracked issue
    ↓
openspec-roadmap → openspec/roadmap.md (concise slices)
    ↓ (per slice, status Ready)
openspec-propose → openspec/changes/<Candidate OpenSpec change id>/
openspec-apply-change → implementation
openspec-archive-change → archive
    ↓
openspec-roadmap → update slice status + progress log

File layout

The roadmap is a planning file, not an OpenSpec change. Do not duplicate proposal/design/tasks content from openspec/changes/ into the roadmap.

Temporary working files used to prepare or apply slices (for example audit.md, checklists, scratch analysis notes, or intermediate outputs) must be stored under openspec/.temp_assets/. These files are ephemeral support artifacts and must not be committed.

Token budget and loading scope

Use openspec/config.yaml to keep context bounded. Default to these constraints unless the repo has stricter values:

• Mode: default roadmap format (preferred).
• Load only:
  • openspec/roadmap.md
  • selected slice
  • linked OpenSpec change
  • directly referenced files
• Do not load the full PRD unless the selected slice is ambiguous.
• Respect token ceilings from config before adding optional context.
• openspec/config.yaml is reference-only guidance for limits and loading; it must never be used to regenerate, rewrite, or recreate OpenSpec specs.

Slice ↔ change

• 1:1 for implementable slices: each slice has a Candidate OpenSpec change id that becomes one change under openspec/changes/.
• Exception: doc-only / audit slices may use a single audit-* change.

Change id naming rule (mandatory)

• Always prefix Candidate OpenSpec change id with the slice id lowercased, followed by the slice title slug.
• Format: <slice-id-lower>-<slice-title-kebab>.
• Example: T10 - audit legacy test harness -> t10-audit-legacy-test-harness.
• Keep Spec link aligned with the same id: openspec/changes/<change-id>/.
• If the slice title changes while the slice is still non-executed (Ready or Spec Proposed), update both the candidate id and spec link to keep them aligned.

At propose (mandatory)

When delegating to openspec-propose for a slice in Ready:

1. Read Candidate OpenSpec change id from that slice block in openspec/roadmap.md.
2. Pass that exact id to openspec-propose so the change folder is openspec/changes/<change-id>/.
3. Do not invent a new slug from the goal, PRD text, or conversation — the roadmap id is the source of truth.
4. If Candidate OpenSpec change id is missing or does not match <slice-id-lower>-<slice-title-kebab>, fix the roadmap first, then propose.
5. After propose, set Spec link and progress log to the same id; reject mismatched folder names.

Example: ### T09 - Location Search And Proposal Add Discovery with candidate id t09-location-search-and-proposal-add-discovery → propose into openspec/changes/t09-location-search-and-proposal-add-discovery/.

Why this matters: stable 1:1 mapping between slice headings, roadmap status, change folders, and archive paths.

Slice IDs

Number sequentially within prefix (F01, R02, …).

Prefix decision rules:

• Use F when user-visible behavior or API behavior changes.
• Use R for structural code improvements without intended behavior changes.
• Use T when the primary output is tests, coverage, or reliability harness work.
• Use D when the primary output is documentation/runbook/spec support text.
• Use I for CI, build, tooling, or environment changes.
• Split mixed slices into smaller slices when possible (for example R + T).

Status model

Fixed lifecycle: Ready → Spec Proposed → Applying → Applied → Archived, plus Blocked.

Follow the Agent update checklist in REFERENCE.md at each step.

Parallel execution policy

OpenSpec supports multiple open changes, but lifecycle transitions must stay deterministic.

• Allow parallel proposals: multiple slices can be in Spec Proposed.
• Limit active implementation: keep at most 2 slices in Applying at once.
• Critical-area safeguard: allow at most 1 Applying slice at a time for critical domains (for example payments, auth, checkout).
• Keep next atomic: one next command moves exactly one lifecycle gate for one slice.

Spec verification gate (mandatory)

Between propose, apply, and archive, always run the repository OpenSpec spec verification command and fix any issues before continuing.

• after openspec-propose: verify spec health before moving to openspec-apply-change
• after openspec-apply-change: verify spec health before moving to openspec-archive-change
• after openspec-archive-change: verify spec health before selecting the next slice

If verification fails, stop progression, resolve issues, re-run verification, then continue.

Modes

1. Bootstrap

Create or update openspec/roadmap.md from a PRD or epic:

1. Read PRD/issue, CONTEXT.md (domain terms), and AGENTS.md (OpenSpec + GitNexus gates).
2. Legacy migration (mandatory when present): if openspec/TIMELINE_*.md or openspec/programs/*.md exists, run legacy migration before writing the roadmap.
   • Merge slice content into the single canonical file openspec/roadmap.md (fixed path; no <context> suffix).
   • Delete every legacy file after a successful merge. Do not git mv / rename TIMELINE_* → roadmap.md and do not keep legacy paths as fallbacks.
   • If openspec/roadmap.md already exists, merge legacy slices into it (resolve id collisions); do not create a second planning file.
3. Create or update openspec/config.yaml with openspec_roadmap defaults and token/context limits.
4. Ensure .gitignore contains openspec/.temp_assets/ (create/update it if needed).
5. Decompose into short, actionable slices.
6. Write roadmap sections per REFERENCE.md and ROADMAP_SKELETON.md: header, how-to, status model, compacted history, slices, dependency map, recommended execution order, agent checklist.
7. Link PRD at top (PRD: issue URL or path).
8. Register the workflow in agent docs — see Agent documentation below.
9. Do not run openspec-propose until user asks to start a slice.

Parameters (adapt per roadmap):

• scope — what the roadmap covers
• Priority scale — default P0 (urgent) / P1 / P2
• principles — optional global constraints (testing, security, etc.)
• execution_order — ordered slice list; note when reordered
• Item kind — F | R | T | D (I optional) per slice

2. Add slice / lifecycle

• Add slice: append one ### <ID> - Title block using the default skeleton (see REFERENCE).
• Update lifecycle: change status and progress log only; link paths, do not copy OpenSpec artifacts.
• Pick next: highest priority among Ready, respecting execution order unless user overrides.
• Reorder: update Recommended Execution Order + short note why.

Quick commands

Support lightweight command-style prompts that map to deterministic actions on openspec/roadmap.md.

Content truncated.