/roadmap-management

name: roadmap-management
description: Roadmap parsing, analysis, and mutation operations for ROADMAP.md. Handles phase and milestone lifecycle including add, insert (decimal), remove, complete, and requirements coverage analysis.
allowed-tools: Read Write Edit Glob Grep
metadata:
  author: babysitter-sdk
  version: "1.0.0"
  category: gsd-core
  backlog-id: SK-GSD-006
graph:
  domains: [domain:software-engineering]
  skillAreas: [skill-area:agentic-loops, skill-area:orchestration-loop]
  workflows: [workflow:feature-development]
  topics: [topic:developer-experience]
  roles: [role:tech-lead, role:backend-engineer]

• Milestones (versioned deliverables, e.g., v1.0, v2.0)
• Phases within each milestone (numbered execution units)
• Requirements mapped to phases (100% coverage guarantee)
• Phase dependencies and ordering
• Phase status tracking (planned/in-progress/completed/verified)

This skill combines the original `lib/roadmap.cjs` and `lib/phase.cjs` modules. It handles all roadmap mutations: adding phases, inserting decimal phases for urgent work, removing phases with renumbering, and marking phases complete.

Capabilities

1. Parse Roadmap

Parse ROADMAP.md into structured data:

# Roadmap

## Milestone v1.0: MVP Launch

### Phase 70: Project Setup
- **Status**: completed
- **Requirements**: R1 (project scaffolding), R2 (dev environment)
- **Deliverables**: Package.json, tsconfig, eslint config, CI pipeline

### Phase 71: Database Layer
- **Status**: completed
- **Requirements**: R3 (data model), R4 (migrations)
- **Deliverables**: Schema definitions, migration scripts, seed data

### Phase 72: Authentication
- **Status**: in-progress
- **Requirements**: R5 (user auth), R6 (OAuth2)
- **Deliverables**: Login flow, token management, middleware

### Phase 73: API Endpoints
- **Status**: planned
- **Requirements**: R7 (REST API), R8 (validation)
- **Deliverables**: CRUD endpoints, input validation, error handling

## Milestone v2.0: Enhanced Features
...

Parsed result:

{
  "milestones": [
    {
      "version": "v1.0",
      "title": "MVP Launch",
      "phases": [
        { "number": 70, "title": "Project Setup", "status": "completed", "requirements": ["R1", "R2"] },
        { "number": 71, "title": "Database Layer", "status": "completed", "requirements": ["R3", "R4"] },
        { "number": 72, "title": "Authentication", "status": "in-progress", "requirements": ["R5", "R6"] },
        { "number": 73, "title": "API Endpoints", "status": "planned", "requirements": ["R7", "R8"] }
      ]
    }
  ]
}

2. Add Integer Phase

Append a new phase to the end of the current milestone:

add_phase(
  milestone: "v1.0",
  title: "Admin Dashboard",
  requirements: ["R12", "R13"],
  deliverables: "Admin UI, user management, analytics"
)
-> Phase 74: Admin Dashboard (appended after Phase 73)

3. Insert Decimal Phase

Insert a phase between existing phases for urgent work:

insert_phase(
  after: 72,
  title: "Fix Auth Token Refresh",
  requirements: ["R5.1"],
  deliverables: "Token refresh logic, session persistence"
)
-> Phase 72.1: Fix Auth Token Refresh (inserted between 72 and 73)

Decimal phases:

• `72.1` is between 72 and 73
• `72.2` is between 72.1 and 73
• Multiple decimals can exist between any two integer phases

4. Remove Phase and Renumber

Remove a future phase and renumber subsequent phases:

remove_phase(73)
-> Phase 73 removed
-> Phase 74 renumbered to Phase 73
-> All references updated

Only future (planned) phases can be removed. Completed and in-progress phases cannot be removed.

5. Mark Phase Complete

Update phase status in the roadmap:

complete_phase(72)
-> Phase 72 status: completed
-> If all phases in milestone completed -> milestone ready for audit

Status transitions:

• `planned` -> `in-progress` (when planning begins)
• `in-progress` -> `completed` (when execution finishes)
• `completed` -> `verified` (when verification passes)

6. Requirements Coverage Analysis

Verify 100% requirement coverage across phases:

coverage_analysis()
-> Total requirements: 13
-> Mapped to phases: 13
-> Unmapped: 0
-> Coverage: 100%

-> R1: Phase 70 (completed)
-> R2: Phase 70 (completed)
-> R5: Phase 72 (in-progress)
-> R5.1: Phase 72.1 (planned)
...

7. Phase Dependency Resolution

Determine execution order based on dependencies:

dependency_graph()
-> Phase 70: no dependencies (can start immediately)
-> Phase 71: depends on Phase 70
-> Phase 72: depends on Phase 71
-> Phase 72.1: depends on Phase 72
-> Phase 73: depends on Phase 71 (not 72, can parallelize)

8. Milestone Scope Determination

Determine which phases belong to a milestone:

milestone_scope("v1.0")
-> Phases: [70, 71, 72, 72.1, 73]
-> Total: 5 phases
-> Completed: 2
-> In Progress: 1
-> Planned: 2
-> Progress: 40%

9. Phase Status Queries

Query phases by status:

phases_by_status("completed") -> [70, 71]
phases_by_status("in-progress") -> [72]
phases_by_status("planned") -> [72.1, 73]
next_phase() -> 72.1 (first planned phase after current)

Tool Use Instructions

Parsing Roadmap

1. Use `Read` to load `.planning/ROADMAP.md` 2. Parse markdown headings to identify milestones (## level) and phases (### level) 3. Extract status, requirements, and deliverables from bullet points under each phase 4. Return structured milestone/phase hierarchy

Adding a Phase

1. Parse current roadmap to find last phase number in target milestone 2. Generate new phase number (last + 1) 3. Format phase section following existing pattern 4. Use `Edit` to insert before the next milestone heading or end of file

Inserting a Decimal Phase

1. Parse roadmap to find the target phase and next phase 2. Calculate decimal number (e.g., 72.1 if inserting after 72) 3. Format phase section 4. Use `Edit` to insert between the two phases

Requirements Coverage

1. Parse ROADMAP.md for all phase requirement mappings