Skip to main content
ROADMAP.md breaks down your project into executable phases. Each phase has a clear goal, success criteria, and maps to specific requirements.

​
Location

.planning/ROADMAP.md
Created during /gsd:new-project after REQUIREMENTS.md, updated as phases are added/completed.

​
Initial Roadmap Structure

# Roadmap: [Project Name]

## Overview

[One paragraph describing the journey from start to finish]

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

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

## Phase Details

### Phase 1: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Nothing (first phase)
**Requirements**: [REQ-01, REQ-02, REQ-03]
**Success Criteria** (what must be TRUE):
  1. [Observable behavior from user perspective]
  2. [Observable behavior from user perspective]
  3. [Observable behavior from user perspective]
**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]

Plans:
- [ ] 01-01: [Brief description of first plan]
- [ ] 01-02: [Brief description of second plan]
- [ ] 01-03: [Brief description of third plan]

### Phase 2: [Name]
**Goal**: [What this phase delivers]
**Depends on**: Phase 1
**Requirements**: [REQ-04, REQ-05]
**Success Criteria** (what must be TRUE):
  1. [Observable behavior from user perspective]
  2. [Observable behavior from user perspective]
**Plans**: [Number of plans]

Plans:
- [ ] 02-01: [Brief description]
- [ ] 02-02: [Brief description]

## Progress

**Execution Order:**
Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4

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

​
Phase Structure

​
Goal

Purpose: Clear statement of what this phase delivers. Guidelines:
  • One sentence describing the outcome
  • Should be verifiable when complete
  • Answers: “What does this phase achieve?”
Example: 
**Goal**: Users can sign up, log in, and manage their sessions securely

​
Dependencies

Purpose: What must be complete before this phase can start. Typical values:
  • Nothing (first phase) - No dependencies
  • Phase 1 - Requires Phase 1 complete
  • Phase 2, Phase 3 - Multiple dependencies
Note: Dependencies create sequential execution. Phases without dependencies can be considered for parallel execution.

​
Requirements

Purpose: Links phase to specific requirements from REQUIREMENTS.md. Format: Comma-separated list of requirement IDs Example: 
**Requirements**: [AUTH-01, AUTH-02, AUTH-03, AUTH-04]
Validation: Every v1 requirement must appear in at least one phase.

​
Success Criteria

Purpose: Observable behaviors that must be true for the phase goal to be achieved. Guidelines:
  • 2-5 criteria per phase
  • From user’s perspective
  • Testable (can verify true/false)
  • Format: “User can [action]” or “[Thing] works/exists”
Good examples: 
**Success Criteria**:
  1. User can create account with email/password
  2. User receives verification email after signup
  3. User can log in and session persists across refresh
  4. Invalid credentials show clear error messages
Bad examples (too vague): 
**Success Criteria**:
  1. Authentication works
  2. User experience is good
  3. Security is implemented
Usage: Success criteria flow to must_haves in plan frontmatter, enabling automated verification.

​
Plans

Purpose: Break phase into executable task plans. Guidelines:
  • Can be “TBD” initially, refined during /gsd:plan-phase
  • Typically 1-3 plans per phase
  • Split if >3 tasks, multiple subsystems, or risk of context overflow
  • Format: {phase}-{plan} (e.g., 01-01, 01-02)
Naming: 
Plans:
- [ ] 01-01: Create auth models and database schema
- [ ] 01-02: Implement login/signup endpoints
- [ ] 01-03: Build login UI components

​
Phase Numbering

​
Integer Phases (1, 2, 3…)

Planned milestone work - Created during initial roadmap.

​
Decimal Phases (2.1, 2.2…)

Urgent insertions - Added via /gsd:insert-phase for work that can’t wait. Example: 
### Phase 2: User Profiles
...

### Phase 2.1: Critical Security Fix (INSERTED)
**Goal**: Patch authentication vulnerability
**Depends on**: Phase 2
**Success Criteria**:
  1. Password hash strength upgraded to bcrypt
  2. Session tokens regenerate on privilege change
**Plans**: 1 plan

Plans:
- [ ] 02.1-01: Implement security patches

### Phase 3: Content Features
...
Execution order: 2 → 2.1 → 2.2 → 3

​
Phase Granularity

Phase count depends on the granularity setting in config.json:
GranularityPhase CountWhen to Use
coarse3-5 phasesSmall projects, fast iterations
standard5-8 phasesMost projects (default)
fine8-12 phasesComplex projects, detailed tracking
Set via /gsd:settings or during /gsd:new-project.

​
Progress Tracking

​
Progress Table

Updated by execute workflow after each plan completes: 
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|--------|
| 1. Foundation | 3/3 | Complete | 2025-01-15 |
| 2. Features | 1/2 | In progress | - |
| 3. Polish | 0/2 | Not started | - |

​
Status Values

StatusMeaning
Not startedHaven’t begun
In progressCurrently working
CompleteDone (add completion date)
DeferredPushed to later (with reason)

​
Milestone-Grouped Roadmap

After completing first milestone, reorganize with milestone groupings: 
# Roadmap: [Project Name]

## Milestones

- ✅ **v1.0 MVP** - Phases 1-4 (shipped 2025-01-20)
- 🚧 **v1.1 Security** - Phases 5-6 (in progress)
- 📋 **v2.0 Advanced Features** - Phases 7-10 (planned)

## Phases

<details>
<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED 2025-01-20</summary>

### Phase 1: Foundation
**Goal**: Core authentication working
**Plans**: 3 plans

Plans:
- [x] 01-01: Auth models and database
- [x] 01-02: Login/signup endpoints
- [x] 01-03: Login UI

[... remaining v1.0 phases ...]

</details>

### 🚧 v1.1 Security (In Progress)

**Milestone Goal:** Harden security and add role-based access

#### Phase 5: RBAC Implementation
**Goal**: Role-based access control for admin features
**Depends on**: Phase 4
**Requirements**: [AUTHZ-01, AUTHZ-02]
**Success Criteria**:
  1. Admin role can access dashboard
  2. Regular users see permission denied for admin routes
**Plans**: 2 plans

Plans:
- [ ] 05-01: Role system and middleware
- [ ] 05-02: Protected admin routes

[... remaining v1.1 phases ...]

### 📋 v2.0 Advanced Features (Planned)

**Milestone Goal:** Advanced social features and notifications

[... v2.0 phases ...]

## Progress

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|--------|
| 1. Foundation | v1.0 | 3/3 | Complete | 2025-01-15 |
| 2. Features | v1.0 | 2/2 | Complete | 2025-01-17 |
| 5. RBAC | v1.1 | 0/2 | Not started | - |
Notes:
  • Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
  • Completed milestones collapsed in <details> for readability
  • Current/future milestones expanded
  • Continuous phase numbering (never restart at 01)

​
Vertical Slices vs Horizontal Layers

​
Preferred: Vertical Slices

Each phase delivers a complete feature: 
### Phase 3: User Profiles
**Goal**: Complete user profile feature
**Plans**: 2 plans

Plans:
- [ ] 03-01: Profile model, API, and UI (complete vertical slice)
- [ ] 03-02: Avatar upload and display

### Phase 4: Content Posts
**Goal**: Complete post creation feature
**Plans**: 2 plans

Plans:
- [ ] 04-01: Post model, API, and UI (complete vertical slice)
- [ ] 04-02: Image upload for posts
Benefits:
  • Plans can run in parallel
  • Each phase delivers working features
  • Easier to test end-to-end

​
Avoid: Horizontal Layers

Each phase does one layer across all features: 
### Phase 3: Database Models
**Plans**: All models for all features

### Phase 4: API Endpoints (depends on Phase 3)
**Plans**: All endpoints for all features

### Phase 5: UI Components (depends on Phase 4)
**Plans**: All UI for all features
Downsides:
  • Forced sequential execution
  • Nothing works until final phase
  • Hard to test incrementally

​
Evolution

​
Adding Phases

Append to roadmap: 
/gsd:add-phase
Insert urgent work: 
/gsd:insert-phase 2  # Creates Phase 2.1

​
Completing Phases

After /gsd:execute-phase completes:
  • Progress table updates automatically
  • Phase marked complete with date
  • STATE.md updates current position

​
Archiving Milestones

After /gsd:complete-milestone:
  • Completed phases moved to milestones/ directory
  • Roadmap collapses completed milestone in <details>
  • Progress table preserved for history

​
See Also