> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```markdown theme={null}
# 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:**

```markdown theme={null}
**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:**

```markdown theme={null}
**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:**

```markdown theme={null}
**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):**

```markdown theme={null}
**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:**

```markdown theme={null}
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:**

```markdown theme={null}
### 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:

```markdown theme={null}
| 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:

```markdown theme={null}
# 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:**

```markdown theme={null}
### 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:**

```markdown theme={null}
### 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:**

```bash theme={null}
/gsd:add-phase
```

**Insert urgent work:**

```bash theme={null}
/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](/reference/requirements-md)
* [STATE.md Structure](/reference/state-md)
* [PLAN.xml Structure](/reference/plan-xml)
* [.planning Directory](/reference/planning-directory)