Imported from bardaxx/skillbook (skills/engineering/openspec-roadmap/SKILL.md). Install upstream with npx skills add bardaxx/skillbook --skill openspec-roadmap. Copyright stays with the author.

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.

Command handling rules:

1. Always operate on openspec/roadmap.md unless the user gives another path explicitly.
2. Keep command responses concise and operational: current state, decision, and exact next action.
3. Never skip OpenSpec delegation steps: openspec-propose / openspec-apply-change / openspec-archive-change.
4. On next, start, or any Ready → propose transition: use the slice's Candidate OpenSpec change id verbatim for the change folder name; never substitute a goal-derived slug.
5. Always update the roadmap after any command that changes lifecycle state.
6. For add and add-next, do not require user-provided slice id or title. Generate both from intent using the repository prefix/sequence rules and preserve uniqueness.
7. For add, do not append blindly to the end. Evaluate dependencies, risk, and leverage against existing slices, then insert the slice at the most suitable position in Recommended Execution Order.
8. When add or add-next causes reordering, explicitly report inserted position, concise rationale, and whether it changes the next recommended slice.
9. For add-next, insert as the nearest valid next position. If hard dependencies prevent immediate placement, place at the earliest valid slot, explain why, and add a short note that it was forced in pipeline.
10. For update, reject lifecycle-only edits; use it only for feature-scope updates on non-executed slices. If a slice is already Applying, Applied, or Archived, do not mutate scope and return a follow-up recommendation (for example create a new slice via add).
11. For reorder, add, add-next, update, deprecate, and restore, enforce folder-name consistency for non-applied slices only:
    • if execution order or slice title changes and a related openspec/changes/<change-id>/ folder already exists for a slice in Ready or Spec Proposed, rename that folder to the new <slice-id-lower>-<slice-title-kebab> value
    • update Candidate OpenSpec change id, Spec link, and any in-roadmap references accordingly
    • do not rename folders for Applying, Applied, or Archived slices
12. For deprecate and restore, run reorder logic whenever queue consistency or priority is impacted.
13. For next, execute one gate only and stop. Never chain propose + apply + archive in a single next call.
14. For next, stop immediately on blocker, failed verification/tests, or missing required approval; record progress up to the reached step and return the stop reason with the exact next manual action.
15. After every propose, apply, and archive, run the repository OpenSpec spec verification command; if it reports issues, resolve and re-run before proceeding.
16. If temporary helper files are needed during roadmap work, place them only under openspec/.temp_assets/ and keep them out of version control via .gitignore.

Deprecation policy:

• Prefer deprecate over delete for slices that are no longer planned, to preserve auditability.
• Keep deprecated slices in the file with a clear marker in Notes and Progress log (include date and reason).
• Exclude deprecated slices from Recommended Execution Order; add a short note if they were replaced.
• Hard delete a slice only when the user explicitly asks for permanent removal.

Per-slice minimum fields

Lite mode fields only: Status, Goal, Candidate OpenSpec change id, Spec link, Files to inspect, Notes, Progress log.

Do not switch to a full template by default. Keep roadmap entries short and operational.

Anti-overengineering gate

Do not use openspec-roadmap for:

• bugfixes under 30 minutes
• isolated copy/UI tweaks
• one-file refactors
• exploratory spikes

Repository agent instructions

Coding agents discover repo rules from repository agent instruction files (commonly AGENTS.md, sometimes additional entrypoints per repo). When this skill is first adopted in a repo, or when bootstrapping a roadmap, ensure those files document the roadmap layer — do not rely on the skill folder alone.

When to update

Files to patch

1. Primary instruction file (required) — usually AGENTS.md: extend ## OpenSpec Feature Workflow or add the section from REFERENCE.md.
2. Secondary entrypoints (required when the repo uses them) — mirror the same OpenSpec Roadmap block in every file that loads agent rules for that repo.
3. One canonical wording — pick the primary file as source of truth; keep mirrors aligned.

Use the skill path actually installed in routing tables (e.g. .agents/skills/openspec-roadmap/SKILL.md, skills/openspec-roadmap/SKILL.md).

What instruction files must say

• Large PRD/epic work uses openspec-roadmap before multiple openspec-propose calls.
• Slices and status live in openspec/roadmap.md.
• One implementable slice → one OpenSpec change; the roadmap tracks status, not artifact content.
• After propose / apply / archive, update the roadmap and delegate to the OpenSpec CLI skills.
• Roadmap uses the default concise format.
• Token budget is enforced via openspec/config.yaml (openspec_roadmap).

Idempotency

• If the OpenSpec Roadmap subsection already exists and matches, do not duplicate.
• If wording differs only slightly, reconcile to one canonical block and mirror to secondary entrypoints.

Snippets and a routing table template: REFERENCE.md — Agent docs snippet.

Repo gates (delegate, do not duplicate)

• OpenSpec: tests and production behavior changes require a change under openspec/changes/ before implementation.
• GitNexus: explore + impact analysis before editing application symbols (see AGENTS.md).
• Domain language: use terms from CONTEXT.md in slice text and when invoking propose.

Related skills

Anti-patterns

• Using verbose, spec-like prose inside openspec/roadmap.md.
• One mega OpenSpec change for an entire PRD when slices are independent.
• Duplicating proposal.md / design.md / tasks.md content in the roadmap.
• Skipping roadmap updates after propose / apply / archive.
• Inventing a propose folder name from goal/PRD text instead of the slice's Candidate OpenSpec change id.
• Installing the skill or bootstrapping a roadmap without updating repository agent instructions — other sessions will miss the roadmap layer.

Additional resources

• Overview and intent (agents): README.md
• Roadmap template and checklists: REFERENCE.md