ROADMAP.md

Structure and purpose of ROADMAP.md - phases, dependencies, and execution plan

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:

Granularity	Phase Count	When to Use
coarse	3-5 phases	Small projects, fast iterations
standard	5-8 phases	Most projects (default)
fine	8-12 phases	Complex 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

Status	Meaning
Not started	Haven’t begun
In progress	Currently working
Complete	Done (add completion date)
Deferred	Pushed 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

• REQUIREMENTS.md Structure
• STATE.md Structure
• PLAN.xml Structure
• .planning Directory