Harness Roadmap

Harness Roadmap

Create and manage a unified project roadmap from existing specs and plans. Interactive, human-confirmed, always valid.

When to Use

• When a user asks about project status and a roadmap exists (default -- no args)
• When a project needs a unified roadmap and none exists yet (--create)
• When adding a new feature to an existing roadmap (--add <feature-name>)
• When roadmap statuses may be stale and need updating from plan execution state (--sync)
• When features need reordering, moving between milestones, or blocker updates (--edit)
• When the roadmap needs tidying -- completed work archived, dead planned rows demoted (--groom)
• When user asks about project status and no roadmap exists -- suggest --create
• NOT for programmatic CRUD (use manage_roadmap MCP tool directly)

Process

Iron Law

Never write docs/roadmap.md without the human confirming the proposed structure first.

If the human has not seen and approved the milestone groupings and feature list, do not write the file. Present. Wait. Confirm. Then write.

Prompt the human in plain text — every (y/n), "which feature?", and similar prompt in this skill is plain text only. Do not elevate them to AskUserQuestion: feature lists routinely exceed its 4-option cap, and natural header choices ("Pick feature", "Remove feature") exceed its 12-char cap, causing the call to render as ERR.

Storage mode: monolith vs sharded

The roadmap has two physical layouts, auto-detected (not configured) by the presence of docs/roadmap.d/:

• Monolith — a single docs/roadmap.md aggregate is canonical (legacy default).
• Sharded — per-row shards docs/roadmap.d/<slug>.md (plus _meta.md) are canonical, and docs/roadmap.md is a generated merge=ours aggregate. New harness init projects are sharded by default.

In sharded mode a write patches a single shard (conflict-free by construction) and regenerates the aggregate — so when committing a roadmap change, stage both docs/roadmap.d/ and the regenerated docs/roadmap.md. Read/write only through manage_roadmap / the RoadmapStore; never parse the aggregate for content (read-source invariant R, ADR 0050). Subcommands:

• harness roadmap shard — adopt sharding (split the monolith into shards), reversible with harness roadmap unshard (semantic round-trip).
• harness roadmap regen — regenerate the aggregate from the shards (the fix when harness validate warns the aggregate has drifted).
• harness roadmap reconcile — offline merge-triggered auto-done (flip closed-issue rows to done).

Stop hand-marking rows done — rows reach done automatically when the implementing PR merges (auto-done reconciler; see knowledge merge-triggered-auto-done.md). See also the adoption guide docs/guides/roadmap-sharding.md.

Command: --create -- Bootstrap Roadmap

Phase 1: SCAN -- Discover Artifacts

1. Check if docs/roadmap.md already exists.
   • If it exists: warn the human. "A roadmap already exists. Overwriting will replace it. Continue? (y/n)" Wait for confirmation before proceeding. If declined, stop.
2. Scan for specs:
   • docs/changes/*/proposal.md
   • Record each spec's title, status (if detectable from frontmatter or content), and file path.
3. Scan for plans:
   • docs/changes/*/plans/*.md (preferred — co-located with proposals)
   • docs/plans/*.md (legacy fallback for plans not yet migrated)
   • Record each plan's title, estimated tasks, and file path.
4. Match plans to specs:
   • Plans often reference their spec in frontmatter (spec:) or body text. Link them when a match is found.
   • Unmatched plans become standalone features.
5. Infer feature status from artifacts:
   • Has spec + plan + implementation evidence (committed code referenced in plan) -> in-progress or complete
   • Has spec + plan but no implementation -> planned
   • Has spec but no plan -> backlog
   • Has plan but no spec -> planned (unusual, flag for human review)
6. Detect project name from harness.config.json project field, or package.json name field, or directory name as fallback.

Present scan summary:

SCAN COMPLETE

Project: <name>
Found: N specs, N plans
Matched: N spec-plan pairs
Unmatched specs: N (backlog candidates)
Unmatched plans: N (flag for review)

Phase 2: PROPOSE -- Interactive Grouping

1. Present discovered features in default milestone groupings:

   • Current Work -- features with status in-progress
   • Backlog -- everything else

   Proposed Roadmap Structure:
   
   ## Current Work
   - Feature A (in-progress) -- spec: docs/changes/feature-a/proposal.md
   - Feature B (in-progress) -- spec: docs/changes/feature-b/proposal.md
   
   ## Backlog
   - Feature C (planned) -- spec: docs/changes/feature-c/proposal.md
   - Feature D (backlog) -- spec: docs/changes/feature-d/proposal.md
   

2. Offer choices:

   • (A) Accept -- proceed with this structure
   • (B) Rename -- rename milestones or features
   • (C) Reorganize -- move features between milestones
   • (D) Add milestones -- create additional milestones (e.g., "v2.0", "Q2 2026")

3. Ask: "Are there additional features not captured in specs that should be on the roadmap?"

   • If yes: collect name, summary, and milestone for each.

4. Repeat until the human selects (A) Accept.

Phase 3: WRITE -- Generate Roadmap

1. Build the roadmap structure:

   • Frontmatter: project, version: 1, created, updated timestamps
   • One H2 section per milestone
   • One H3 section per feature with 5 fields: Status, Spec, Summary, Blockers, Plan

2. Write via manage_roadmap MCP tool if available. If MCP is unavailable, write directly using the roadmap markdown format and warn: "External sync skipped (MCP unavailable). Run manage_roadmap sync when MCP is restored to push changes to GitHub."

   ---
   project: <name>
   version: 1
   created: YYYY-MM-DD
   updated: YYYY-MM-DD
   ---
   
   # Roadmap
   
   ## Current Work
   
   ### Feature A
   
   - **Status:** in-progress
   - **Spec:** docs/changes/feature-a/proposal.md
   - **Summary:** One-line description of the feature
   - **Blockers:** none
   - **Plan:** docs/changes/feature-a/plans/2026-03-20-feature-a-plan.md
   

3. Write to docs/roadmap.md.

Phase 4: VALIDATE -- Verify Output

1. Read back docs/roadmap.md.

2. Verify via manage_roadmap show if MCP is available -- confirms round-trip parsing.

3. Run harness validate.

4. Present summary to human:

   Roadmap created: docs/roadmap.md
   Milestones: N
   Features: N
   harness validate: passed
   

Command: --add <feature-name> -- Add a Feature

Phase 1: SCAN -- Load Existing Roadmap

1. Check if docs/roadmap.md exists.
   • If missing: error with clear message. "No roadmap found at docs/roadmap.md. Run --create first to bootstrap one."
2. Parse the roadmap (via manage_roadmap show or direct read).
3. Check for duplicate feature names. If <feature-name> already exists: error with message. "Feature '' already exists in milestone ''. Use a different name or edit the existing feature."

Phase 2: PROPOSE -- Collect Feature Details

Ask the human for each field interactively:

1. Milestone: "Which milestone should this feature belong to?" List existing milestones plus a [NEW] option. If [NEW]: ask for the new milestone name.
2. Status: "What is the current status?" Offer: backlog, planned, in-progress, blocked.
3. Spec: "Is there a spec for this feature?" If yes, ask for the path. If no, leave as none.
4. Summary: "One-line summary of the feature."
5. Blockers: "Any blockers?" If yes, collect. If no, set to none.
6. Plan: "Is there a plan for this feature?" If yes, ask for the path. If no, leave as none.

Present the collected details for confirmation:

New feature to add:

  Milestone: Current Work
  Name: Feature E
  Status: planned
  Spec: docs/changes/feature-e/proposal.md
  Summary: Add feature E to the system
  Blockers: none
  Plan: none

Confirm? (y/n)

Wait for confirmation before proceeding.

Phase 3: WRITE -- Add Feature to Roadmap

1. Add via manage_roadmap add MCP tool if available. If MCP is unavailable, parse the roadmap, add the feature to the specified milestone, and serialize back. Warn: "External sync skipped (MCP unavailable). Run manage_roadmap sync when MCP is restored to push changes to GitHub."
2. If the milestone is [NEW]: create the milestone section, then add the feature.
3. Write to docs/roadmap.md.

Phase 4: VALIDATE -- Verify Output

1. Read back docs/roadmap.md.

2. Verify the new feature appears in the correct milestone.

3. Run harness validate.

4. Confirm to human:

   Feature added: Feature E -> Current Work
   Total features: N
   harness validate: passed
   

Command: (no args) -- Show Roadmap Summary

Phase 1: SCAN -- Load Roadmap

1. Check if docs/roadmap.md exists.
   • If missing: suggest --create. "No roadmap found at docs/roadmap.md. Run --create to bootstrap one from existing specs and plans."
2. Parse the roadmap (via manage_roadmap show or direct read).

Phase 2: PRESENT -- Display Summary

1. Display a compact summary of the roadmap:

   ROADMAP: <project-name>
   Last synced: YYYY-MM-DD HH:MM
   
   ## <Milestone 1> (N features)
     - Feature A .................. in-progress
     - Feature B .................. planned
     - Feature C .................. blocked (by: Feature A)
   
   ## <Milestone 2> (N features)
     - Feature D .................. done
     - Feature E .................. backlog
   
   Total: N features | N done | N in-progress | N planned | N blocked | N backlog
   

2. If any features have stale sync timestamps (last_synced older than 24 hours), append a note:

   Hint: Roadmap may be stale. Run `--sync` to update statuses from plan execution state.
   

3. No file writes. This is a read-only operation. No harness validate needed.

Command: --sync -- Sync Statuses from Execution State

Phase 1: SCAN -- Load Roadmap and Execution State

1. Check if docs/roadmap.md exists.
   • If missing: error with clear message. "No roadmap found at docs/roadmap.md. Run --create first to bootstrap one."
   • Do NOT create a roadmap. Do NOT offer alternatives. Stop.
2. Parse the roadmap (via manage_roadmap show or direct read).
3. For each feature with linked plans, scan execution state:
   • .harness/state.json (root execution state)
   • .harness/sessions/*/autopilot-state.json (session-scoped execution state)
   • Plan file completion markers

Phase 2: PROPOSE -- Present Status Changes

1. Infer status for each feature:

   • All tasks complete -> suggest done
   • Any task started -> suggest in-progress
   • Blocker feature not done -> suggest blocked
   • No execution data found -> no change

2. Check the human-always-wins rule: if last_manual_edit is more recent than last_synced for a feature, preserve the manually set status. Report it as "skipped (manual override)".

3. Present proposed changes:

   SYNC RESULTS
   
   Changes detected:
     - Feature A: planned -> in-progress (3/8 tasks started)
     - Feature B: in-progress -> done (all tasks complete)
     - Feature C: planned -> blocked (blocked by: Feature A, not done)
   
   Unchanged:
     - Feature D: done (no change)
   
   Skipped (manual override):
     - Feature E: kept as "planned" (manually edited 2h ago)
   
   Apply these changes? (y/n)
   

4. Wait for human confirmation before applying.

Phase 3: WRITE -- Apply Changes

1. Apply via manage_roadmap sync MCP tool if available, or via manage_roadmap update for each changed feature. If MCP is unavailable, parse the roadmap, update statuses, and serialize back. Warn: "External sync skipped (MCP unavailable). Run manage_roadmap sync when MCP is restored to push changes to GitHub."
2. Update last_synced timestamp in frontmatter.
3. Write to docs/roadmap.md.

Phase 4: VALIDATE -- Verify Output

1. Read back docs/roadmap.md.

2. Verify changes applied correctly via manage_roadmap show if MCP is available.

3. Run harness validate.

4. Present summary:

   Sync complete: docs/roadmap.md
   Updated: N features
   Skipped: N (manual override)
   Unchanged: N
   harness validate: passed
   

Command: --edit -- Interactive Edit Session

Phase 1: SCAN -- Load Existing Roadmap

1. Check if docs/roadmap.md exists.

   • If missing: error with clear message. "No roadmap found at docs/roadmap.md. Run --create first to bootstrap one."

2. Parse the roadmap (via manage_roadmap show or direct read).

3. Present current structure:

   Current roadmap: <project-name>
   
   ## <Milestone 1>
     1. Feature A (in-progress)
     2. Feature B (planned)
   
   ## <Milestone 2>
     3. Feature C (done)
     4. Feature D (backlog)
   

Phase 2: EDIT -- Interactive Modifications

Offer edit actions in a loop until the human is done:

1. Reorder features within a milestone:

   • "Move which feature? (number)" -> "To which position?" -> reorder.

2. Move a feature between milestones:

   • "Move which feature? (number)" -> "To which milestone?" (list milestones + [NEW]) -> move.
   • If [NEW]: ask for the new milestone name, create it.

3. Update blockers:

   • "Update blockers for which feature? (number)" -> "Blocked by? (feature names, comma-separated, or 'none')" -> update.

4. Update status:

   • "Update status for which feature? (number)" -> offer: backlog, planned, in-progress, blocked, done -> update.

5. Rename a feature:

   • "Rename which feature? (number)" -> "New name?" -> rename.

6. Remove a feature:

   • "Remove which feature? (number)" -> "Confirm removal of ''? (y/n)" -> remove on confirm.

7. Rename a milestone:

   • "Rename which milestone?" -> "New name?" -> rename.

8. Done:

   • Exit edit loop, proceed to WRITE phase.

Present the menu after each action:

Edit actions:
  (1) Reorder features within a milestone
  (2) Move feature to different milestone
  (3) Update blockers
  (4) Update status
  (5) Rename feature
  (6) Remove feature
  (7) Rename milestone
  (D) Done -- save and exit

Choice?

Phase 3: WRITE -- Save Changes

1. Present a diff summary of all changes made during the edit session:

   Changes to apply:
   
     - Moved "Feature B" from "Current Work" to "Q2 Release"
     - Updated "Feature A" blockers: none -> Feature C
     - Reordered "Q2 Release": Feature B now at position 1
   
   Apply? (y/n)
   

2. Wait for confirmation before writing.

3. Apply all changes via manage_roadmap update / manage_roadmap remove MCP tool calls, or direct file manipulation if MCP is unavailable. If falling back to direct manipulation, warn: "External sync skipped (MCP unavailable). Run manage_roadmap sync when MCP is restored to push changes to GitHub."

4. Update last_manual_edit timestamp in frontmatter (since this is a human-driven edit).

5. Write to docs/roadmap.md.

Phase 4: VALIDATE -- Verify Output

1. Read back docs/roadmap.md.

2. Verify changes applied correctly.

3. Run harness validate.

4. Present summary:

   Edit complete: docs/roadmap.md
   Changes applied: N
   harness validate: passed
   

Command: --query <filter> -- Query Features by Filter

Phase 1: SCAN -- Load Roadmap

1. Check if docs/roadmap.md exists.
   • If missing: error with clear message. "No roadmap found at docs/roadmap.md. Run --create first to bootstrap one."
2. Parse the roadmap (via manage_roadmap query or direct read).

Phase 2: FILTER -- Apply Query

1. Accept filter patterns:

   • Status filter: backlog, planned, in-progress, done, blocked -- returns all features with that status
   • Milestone filter: milestone:<name> -- returns all features in the named milestone (partial match)

2. Display matching features with their milestone context:

   QUERY: <filter>
   
   Results (N matches):
     - Feature A (Current Work) .................. in-progress
     - Feature B (Backlog) ....................... planned
   
   Total: N matches
   

3. No file writes. This is a read-only operation.

Command: --groom -- Tidy the Roadmap

Keeps the roadmap manageable over time. Milestones are themes; statuses are lifecycle stages -- grooming enforces that separation so the backlog never decays back into an undifferentiated dump.

Phase 1: SCAN -- Detect Untidiness

1. Check if docs/roadmap.md exists. If missing: error and direct the user to --create.
2. Run manage_roadmap (action: "groom") in a dry-run frame, or call checkRoadmapHealth from @harness-engineering/core, to surface the four health signals:
   • RMH001 -- completed (done) features still sitting in an active milestone.
   • RMH002 -- planned rows with neither a spec nor a plan (the orchestrator cannot auto-execute these; it escalates them to a human).
   • RMH003 -- lifecycle catch-all milestones (Backlog, Current Work) that should not exist.
   • RMH004 -- active milestones that have grown past the size cap (a mini-dump).

Phase 2: PROPOSE -- Present the Plan

Show the human exactly what grooming will do, in plain text:

GROOM PLAN

Demote to backlog (planned with no spec/plan):
  - Feature A (Theme X)
  - Feature B (Theme Y)

Archive to docs/roadmap-archive.md (completed):
  - Feature C (Theme X)

Flagged for manual routing (not auto-changed):
  - Intake lane has 3 items awaiting a theme
  - "Theme Z" has 28 features (cap 25) -- consider splitting

Apply? (y/n)

Wait for confirmation. The mechanical changes (demote, archive) are safe and automated; draining the Intake lane into themed milestones and splitting oversized milestones are human decisions -- propose, do not auto-apply.

Phase 3: WRITE -- Apply

1. Run manage_roadmap (action: "groom"). It demotes unactionable planned rows to backlog and moves done features into docs/roadmap-archive.md under a Shipped milestone, returning the list of changes.
2. For Intake-draining or milestone-splitting the human approved, follow up with --edit (move features between milestones).

Phase 4: VALIDATE -- Verify

1. Run harness validate and confirm the roadmapHealth check passed -- checks.roadmapHealth === true in --json, not merely "not false" (no RMH003 errors; RMH001/002/004 warnings cleared or acknowledged). If validate exits 3 or reports the check under "Checks that could not run", the roadmap could not be parsed and NO health rule ran: fix the reported section and re-run. A check that did not run is not a check that passed.

2. Summarize:

   Groom complete.
   Demoted: N | Archived: N -> docs/roadmap-archive.md | Flagged for manual routing: N
   harness validate (roadmapHealth): passed
   

Harness Integration

• manage_roadmap MCP tool -- Primary read/write interface for roadmap operations. Supports show, add, update, remove, query, sync, promote, and groom actions. Use this when MCP is available for structured CRUD.
• harness validate -- Run after any roadmap modification to verify project health. Mandatory in the VALIDATE phase of --create, --add, and --groom. The roadmapHealth check enforces the maintenance rules (RMH001-RMH004) as a regression guard.
• Core checkRoadmapHealth/groomRoadmap -- Maintenance engine in packages/core/src/roadmap/health.ts. checkRoadmapHealth is read-only diagnostics; groomRoadmap is the pure transform (demote unactionable planned, archive done). Both are surfaced via manage_roadmap and harness validate.
• Core parseRoadmap/serializeRoadmap -- Fallback when MCP is unavailable. These functions in packages/core/src/roadmap/ handle parsing and serializing the roadmap markdown format directly. Note: the serializer only preserves frontmatter, milestones, features, and the Assignment History table -- never add convention prose or comments to docs/roadmap.md, they are dropped on the next write.
• Roadmap files -- Live work in docs/roadmap.md (the orchestrator's source of truth); completed work archived to docs/roadmap-archive.md by --groom. Milestones are themes, not lifecycle stages -- promoted items land in the Intake lane and are groomed into themes.

Success Criteria

1. --create discovers all specs (docs/changes/*/proposal.md) and plans (docs/changes/*/plans/*.md and legacy docs/plans/*.md)
2. --create proposes groupings and waits for human confirmation before writing
3. --create produces a valid docs/roadmap.md that round-trips through parseRoadmap/serializeRoadmap
4. --add collects all fields interactively (milestone, status, spec, summary, blockers, plan)
5. --add rejects duplicate feature names with a clear error message
6. --add errors gracefully when no roadmap exists, directing the user to --create
7. Default (no args) displays a compact status summary with feature counts by status
8. Default (no args) suggests --create when no roadmap exists
9. Default (no args) hints at --sync when roadmap may be stale
10. --sync scans .harness/state.json and .harness/sessions/*/autopilot-state.json for execution state
11. --sync respects the human-always-wins rule -- manually edited statuses are preserved
12. --sync presents proposed changes and waits for human confirmation before applying
13. --sync errors gracefully when no roadmap exists, directing the user to --create
14. --edit offers reorder, move, blocker update, status update, rename, and remove actions
15. --edit presents a diff summary and waits for confirmation before writing
16. --edit updates last_manual_edit timestamp (since changes are human-driven)
17. Output matches the roadmap markdown format exactly (frontmatter, H2 milestones, H3 features, 5 fields each)
18. harness validate passes after all operations
19. --query filters features by status or milestone and displays results with milestone context
20. --query errors gracefully when no roadmap exists, directing the user to --create

Rationalizations to Reject

Examples

Example: --create -- Bootstrap a Roadmap from Existing Artifacts

Context: A project with 3 specs and 2 plans. Two specs have matching plans (in-progress), one spec has no plan (backlog).

Phase 1: SCAN

SCAN COMPLETE

Project: my-project
Found: 3 specs, 2 plans
Matched: 2 spec-plan pairs
Unmatched specs: 1 (backlog candidates)
Unmatched plans: 0

Phase 2: PROPOSE

Proposed Roadmap Structure:

## Current Work
- Unified Code Review (in-progress) -- spec: docs/changes/unified-code-review/proposal.md
- Update Checker (in-progress) -- spec: docs/changes/update-checker/proposal.md

## Backlog
- Design System (backlog) -- spec: docs/changes/design-system/proposal.md

Options:
  (A) Accept this structure
  (B) Rename milestones or features
  (C) Reorganize -- move features between milestones
  (D) Add milestones

Any additional features not captured in specs? (y/n)

Human selects (A) Accept.

Phase 3: WRITE

Writing docs/roadmap.md...
  2 milestones, 3 features

Phase 4: VALIDATE

Roadmap created: docs/roadmap.md
Milestones: 2 (Current Work, Backlog)
Features: 3
harness validate: passed

Example: --add -- Add a Feature to an Existing Roadmap

Context: A roadmap exists with 2 milestones and 3 features. Adding a new feature.

Phase 1: SCAN

Roadmap loaded: docs/roadmap.md
Milestones: 2 (Current Work, Backlog)
Features: 3
No duplicate found for "Notification System"

Phase 2: PROPOSE

Which milestone? [1] Current Work  [2] Backlog  [NEW] Create new
> 1

Status? [backlog] [planned] [in-progress] [blocked]
> planned

Spec? (path or "none")
> docs/changes/notification-system/proposal.md

One-line summary:
> Real-time notification delivery with WebSocket and email channels

Blockers? (or "none")
> none

Plan? (path or "none")
> none

New feature to add:

  Milestone: Current Work
  Name: Notification System
  Status: planned
  Spec: docs/changes/notification-system/proposal.md
  Summary: Real-time notification delivery with WebSocket and email channels
  Blockers: none
  Plan: none

Confirm? (y/n)

Human confirms y.

Phase 3: WRITE

Adding feature to Current Work...

Phase 4: VALIDATE

Feature added: Notification System -> Current Work
Total features: 4
harness validate: passed

Gates

These are hard stops. Violating any gate means the process has broken down.

• No writing docs/roadmap.md without human confirmation of structure. The PROPOSE phase must complete with an explicit accept before any file is written. Skipping confirmation produces a roadmap the human did not agree to.
• No overwriting an existing roadmap without explicit user consent. If docs/roadmap.md exists when --create runs, the human must confirm the overwrite. Silent overwrites destroy prior work.
• No adding features with duplicate names. If a feature with the same name already exists in any milestone, reject the add with a clear error. Duplicates corrupt the roadmap structure.
• No proceeding when docs/roadmap.md is missing for --add. If the roadmap does not exist, do not create one silently. Error and direct the user to --create.
• No syncing when docs/roadmap.md does not exist. --sync must error immediately with a message directing the user to --create. Do not create a roadmap as a side effect of sync.
• No writing changes from --edit without showing a diff summary and getting confirmation. The WRITE phase must present all pending changes and wait for explicit accept before modifying docs/roadmap.md.

Escalation

• When no specs or plans are found during --create: Suggest creating a minimal roadmap with just a Backlog milestone containing features described verbally by the human. Alternatively, suggest running harness:brainstorming first to generate specs that can then be discovered by --create.
• When the roadmap file is malformed and cannot be parsed: Report the specific parse error with line numbers if available. Suggest manual inspection of docs/roadmap.md or recreation with --create (after backing up the existing file).
• When MCP tool is unavailable: Fall back to direct file manipulation via Read/Write tools using the roadmap markdown format. The core parseRoadmap/serializeRoadmap functions handle the format. Report the fallback to the human: "MCP tool unavailable, using direct file operations. External sync skipped — run manage_roadmap sync when MCP is restored to push changes to GitHub."