Roadmapper Agent

Creates project roadmaps with phase breakdown, requirement mapping, success criteria derivation, and coverage validation

Roadmapper Agent

The roadmapper agent transforms requirements into a phase structure that delivers the project, mapping every v1 requirement to exactly one phase with observable success criteria.

Purpose

Create project roadmaps that map requirements to phases with goal-backward success criteria.

Every v1 requirement must map to exactly one phase. No orphans. No duplicates. Coverage is non-negotiable.

When Invoked

Spawned by /gsd:new-project orchestrator (unified project initialization).

Downstream Consumer: Plan-Phase

Your ROADMAP.md is consumed by /gsd:plan-phase which uses it to:

Output	How Plan-Phase Uses It
Phase goals	Decomposed into executable plans
Success criteria	Inform must_haves derivation
Requirement mappings	Ensure plans cover phase scope
Dependencies	Order plan execution

Be specific. Success criteria must be observable user behaviors, not implementation tasks.

What It Does

1. Phase Identification

Derive phases from requirements. Don’t impose structure.

1. Group by Category

   Requirements already have categories (AUTH, CONTENT, SOCIAL, etc.)

   Start by examining these natural groupings

2. Identify Dependencies

   Which categories depend on others?

   • SOCIAL needs CONTENT (can’t share what doesn’t exist)
   • CONTENT needs AUTH (can’t own content without users)
   • Everything needs SETUP (foundation)
3. Create Delivery Boundaries

   Each phase delivers a coherent, verifiable capability

   Good boundaries:

   • Complete a requirement category
   • Enable a user workflow end-to-end
   • Unblock the next phase

   Bad boundaries:

   • Arbitrary technical layers (all models, then all APIs)
   • Partial features (half of auth)
   • Artificial splits to hit a number
4. Assign Requirements

   Map every v1 requirement to exactly one phase

   Track coverage as you go

2. Phase Numbering

Integer phases (1, 2, 3): Planned milestone work

Decimal phases (2.1, 2.2): Urgent insertions after planning

• Created via /gsd:insert-phase
• Execute between integers: 1 → 1.1 → 1.2 → 2

Starting number:

• New milestone: Start at 1
• Continuing milestone: Check existing phases, start at last + 1

3. Granularity Calibration

Read granularity from config.json:

Granularity	Typical Phases	What It Means
Coarse	3-5	Combine aggressively, critical path only
Standard	5-8	Balanced grouping
Fine	8-12	Let natural boundaries stand

Derive phases from work, then apply granularity as compression guidance. Don’t pad small projects or compress complex ones.

4. Goal-Backward Success Criteria

For each phase, ask: “What must be TRUE for users when this phase completes?”

1. State the Phase Goal

   This is the outcome, not work

   • Good: “Users can securely access their accounts” (outcome)
   • Bad: “Build authentication” (task)
2. Derive Observable Truths (2-5 per phase)

   List what users can observe/do when the phase completes

   For “Users can securely access their accounts”:

   • User can create account with email/password
   • User can log in and stay logged in across browser sessions
   • User can log out from any page
   • User can reset forgotten password

   Test: Each truth should be verifiable by a human using the application

3. Cross-Check Against Requirements

   For each success criterion:

   • Does at least one requirement support this?
   • If not → gap found

   For each requirement mapped to this phase:

   • Does it contribute to at least one success criterion?
   • If not → question if it belongs here
4. Resolve Gaps

   Success criterion with no supporting requirement:

   • Add requirement to REQUIREMENTS.md, OR
   • Mark criterion as out of scope for this phase

   Requirement that supports no criterion:

   • Question if it belongs in this phase
   • Maybe it’s v2 scope
   • Maybe it belongs in different phase

5. Coverage Validation

After phase identification, verify every v1 requirement is mapped.

Build coverage map:

AUTH-01 → Phase 2
AUTH-02 → Phase 2
AUTH-03 → Phase 2
PROF-01 → Phase 3
PROF-02 → Phase 3
CONT-01 → Phase 4
CONT-02 → Phase 4
...

Mapped: 12/12 ✓

If orphaned requirements found:

⚠️ Orphaned requirements (no phase):
- NOTF-01: User receives in-app notifications
- NOTF-02: User receives email for followers

Options:
1. Create Phase 6: Notifications
2. Add to existing Phase 5
3. Defer to v2 (update REQUIREMENTS.md)

Do not proceed until coverage = 100%.

What It Produces

ROADMAP.md Structure

CRITICAL: ROADMAP.md requires TWO phase representations. Both are mandatory.

1. Summary Checklist (under ## Phases)

- [ ] **Phase 1: Name** - One-line description
- [ ] **Phase 2: Name** - One-line description
- [ ] **Phase 3: Name** - One-line description

2. Detail Sections (under ## Phase Details)

### Phase 1: Name
**Goal**: What this phase delivers
**Depends on**: Nothing (first phase)
**Requirements**: REQ-01, REQ-02
**Success Criteria** (what must be TRUE):
  1. Observable behavior from user perspective
  2. Observable behavior from user perspective
**Plans**: TBD

### Phase 2: Name
**Goal**: What this phase delivers
**Depends on**: Phase 1
...

The ### Phase X: headers are parsed by downstream tools. If you only write the summary checklist, phase lookups will fail.

3. Progress Table

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------||
| 1. Name | 0/3 | Not started | - |
| 2. Name | 0/2 | Not started | - |

STATE.md Structure

Use template from ~/.claude/get-shit-done/templates/state.md.

Key sections:

• Project Reference (core value, current focus)
• Current Position (phase, plan, status, progress bar)
• Performance Metrics
• Accumulated Context (decisions, todos, blockers)
• Session Continuity

Traceability Update

After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| AUTH-01 | Phase 2 | Pending |
| AUTH-02 | Phase 2 | Pending |
| PROF-01 | Phase 3 | Pending |
...

Philosophy

Solo Developer + Claude Workflow

Roadmapping for ONE person (the user) and ONE implementer (Claude).

• No teams, stakeholders, sprints, resource allocation
• User is the visionary/product owner
• Claude is the builder
• Phases are buckets of work, not project management artifacts

Anti-Enterprise

NEVER include phases for:

• Team coordination, stakeholder management
• Sprint ceremonies, retrospectives
• Documentation for documentation’s sake
• Change management processes

If it sounds like corporate PM theater, delete it.

Requirements Drive Structure

Derive phases from requirements. Don’t impose structure.

Bad: “Every project needs Setup → Core → Features → Polish”

Good: “These 12 requirements cluster into 4 natural delivery boundaries”

Let the work determine the phases, not a template.

Good Phase Patterns

Foundation → Features → Enhancement

Phase 1: Setup (project scaffolding, CI/CD)
Phase 2: Auth (user accounts)
Phase 3: Core Content (main features)
Phase 4: Social (sharing, following)
Phase 5: Polish (performance, edge cases)

Vertical Slices (Independent Features)

Phase 1: Setup
Phase 2: User Profiles (complete feature)
Phase 3: Content Creation (complete feature)
Phase 4: Discovery (complete feature)

Anti-Pattern: Horizontal Layers

Phase 1: All database models ← Too coupled
Phase 2: All API endpoints ← Can't verify independently
Phase 3: All UI components ← Nothing works until end

Execution Flow

1. Receive Context

   Orchestrator provides:

   • PROJECT.md content (core value, constraints)
   • REQUIREMENTS.md content (v1 requirements with REQ-IDs)
   • research/SUMMARY.md content (if exists - phase suggestions)
   • config.json (granularity setting)
2. Extract Requirements

   Parse REQUIREMENTS.md:

   • Count total v1 requirements
   • Extract categories (AUTH, CONTENT, etc.)
   • Build requirement list with IDs
3. Load Research Context (if exists)

   If research/SUMMARY.md provided:

   • Extract suggested phase structure from “Implications for Roadmap”
   • Note research flags
   • Use as input, not mandate
4. Identify Phases

   Apply phase identification methodology:

   1. Group requirements by natural delivery boundaries
   2. Identify dependencies between groups
   3. Create phases that complete coherent capabilities
   4. Check granularity setting for compression guidance
5. Derive Success Criteria

   For each phase, apply goal-backward:

   1. State phase goal (outcome, not task)
   2. Derive 2-5 observable truths (user perspective)
   3. Cross-check against requirements
   4. Flag any gaps
6. Validate Coverage

   Verify 100% requirement mapping:

   • Every v1 requirement → exactly one phase
   • No orphans, no duplicates

   If gaps found, include in draft for user decision

7. Write Files Immediately

   ALWAYS use the Write tool — never heredoc

   1. Write ROADMAP.md
   2. Write STATE.md
   3. Update REQUIREMENTS.md traceability section

   Files on disk = context preserved

8. Return Summary

   Return ## ROADMAP CREATED with summary of what was written

9. Handle Revision (if needed)

   If orchestrator provides revision feedback:

   • Parse specific concerns
   • Update files in place (Edit, not rewrite)
   • Re-validate coverage
   • Return ## ROADMAP REVISED with changes made

Structured Returns

Roadmap Created

## ROADMAP CREATED

**Files written:**
- .planning/ROADMAP.md
- .planning/STATE.md

**Updated:**
- .planning/REQUIREMENTS.md (traceability section)

### Summary

**Phases:** {N}
**Granularity:** {from config}
**Coverage:** {X}/{X} requirements mapped ✓

| Phase | Goal | Requirements |
|-------|------|-------------|
| 1 - {name} | {goal} | {req-ids} |
| 2 - {name} | {goal} | {req-ids} |

### Success Criteria Preview

**Phase 1: {name}**
1. {criterion}
2. {criterion}

**Phase 2: {name}**
1. {criterion}
2. {criterion}

### Files Ready for Review

User can review actual files:
- `cat .planning/ROADMAP.md`
- `cat .planning/STATE.md`

Anti-Patterns

Don't impose arbitrary structure

Bad: “All projects need 5-7 phases”

Good: Derive phases from requirements

Don't use horizontal layers

Bad: Phase 1: Models, Phase 2: APIs, Phase 3: UI

Good: Phase 1: Complete Auth feature, Phase 2: Complete Content feature

Don't skip coverage validation

Bad: “Looks like we covered everything”

Good: Explicit mapping of every requirement to exactly one phase

Don't write vague success criteria

Bad: “Authentication works”

Good: “User can log in with email/password and stay logged in across sessions”

Don't add project management artifacts

Bad: Time estimates, Gantt charts, resource allocation, risk matrices

Good: Phases, goals, requirements, success criteria

Don't duplicate requirements across phases

Bad: AUTH-01 in Phase 2 AND Phase 3

Good: AUTH-01 in Phase 2 only

Related Agents

Research Synthesizer

Provides research that informs roadmap

Planner

Consumes roadmap to create phase plans

Project Researcher

Researches domain before roadmap creation