# Harness Roadmap > Harness Roadmap - Skill: `intense-visions/harness-roadmap` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/harness-roadmap` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/harness-roadmap/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/intense-visions/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 `) - 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/.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`](../../../../docs/knowledge/roadmap/merge-triggered-auto-done.md)). See also the adoption guide [`docs/guides/roadmap-sharding.md`](../../../../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: 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." ```markdown --- project: 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 ` -- 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 `` 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: Last synced: YYYY-MM-DD HH:MM ## (N features) - Feature A .................. in-progress - Feature B .................. planned - Feature C .................. blocked (by: Feature A) ## (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: ## 1. Feature A (in-progress) 2. Feature B (planned) ## 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 ` -- 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:` -- returns all features in the named milestone (partial match) 2. Display matching features with their milestone context: ``` QUERY: 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 | Rationalization | Reality | | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | "The feature list looks correct, so I can skip the PROPOSE phase and write the roadmap directly" | The Iron Law: never write docs/roadmap.md without the human confirming the proposed structure first. | | "This sync detected a status change and the inference is clearly correct, so I can apply it without confirmation" | The sync PROPOSE phase requires presenting proposed changes and waiting for human confirmation. The human-always-wins rule applies. | | "The existing roadmap is outdated, so I will recreate it with --create to get a fresh start" | No overwriting an existing roadmap without explicit user consent. Silent overwrites destroy prior manual edits and status tracking. | | "There is no roadmap yet but the user asked me to add a feature, so I will create one as a side effect of --add" | When the roadmap does not exist, --add must error with a clear message directing the user to --create. | ## 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."