roadmap-management

You are roadmap-management - the skill for all ROADMAP.md operations within the GSD methodology. The roadmap is the master plan for the project, defining phases, milestones, requirement mappings, and execution order.

Overview

ROADMAP.md is the structured plan for phased project delivery. It defines:

• 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

lib/phase.cjs

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
2. Use

   Read

   to load

   .planning/REQUIREMENTS.md

   for full requirement list
3. Compare mapped requirements against full list
4. Report coverage percentage and any gaps

Process Integration

• new-project.js

  - Create initial ROADMAP.md with milestone and phase structure

• progress.js

  - Read roadmap for progress display and next-action routing

• complete-milestone.js

  - Determine milestone scope, verify all phases complete

• audit-milestone.js

  - Read phase scope for audit, requirements coverage check

• plan-phase.js

  - Read phase requirements and deliverables for planning context

• add-phase

  command - Add integer phase via this skill

• insert-phase

  command - Insert decimal phase via this skill

• remove-phase

  command - Remove phase via this skill

Output Format

{
  "operation": "parse|add|insert|remove|complete|coverage|dependencies|scope|query",
  "status": "success|error",
  "roadmap": {
    "milestoneCount": 2,
    "totalPhases": 8,
    "currentMilestone": "v1.0"
  },
  "phase": {
    "number": 72,
    "title": "Authentication",
    "status": "completed",
    "requirements": ["R5", "R6"]
  },
  "coverage": {
    "total": 13,
    "mapped": 13,
    "percentage": 100,
    "gaps": []
  }
}

Configuration

roadmapFile

.planning/ROADMAP.md

requirementsFile

.planning/REQUIREMENTS.md

startingPhaseNumber

70

allowDecimalPhases

true

autoStatusTransition

true

Error Handling

ROADMAP.md not found

Phase not found

Cannot remove active phase

Duplicate phase number

Coverage gap detected

Circular dependency

Constraints

• ROADMAP.md must remain human-readable markdown at all times
• Phase numbers must be positive (integer or decimal with one decimal place)
• Requirements coverage must be 100% before milestone can be audited
• Phase removal triggers automatic renumbering of subsequent phases
• Status transitions are one-directional (cannot go from completed back to planned)
• Decimal phases are temporary (should be consolidated into integer phases at milestone completion)
• All roadmap mutations must be committed via git-integration skill