gsd:add-phase

This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.

Purpose: Add planned work discovered during execution that belongs at the end of current milestone.

<execution_context> @.planning/ROADMAP.md @.planning/STATE.md </execution_context>

If no arguments provided:

ERROR: Phase description required
Usage: /gsd:add-phase <description>
Example: /gsd:add-phase Add authentication system

Exit.

if [ -f .planning/ROADMAP.md ]; then
  ROADMAP=".planning/ROADMAP.md"
else
  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
  exit 1
fi

Read roadmap content for parsing.

1. Locate the "## Current Milestone:" heading
2. Extract milestone name and version
3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
4. Parse existing phase numbers (including decimals if present)

Example structure:

## Current Milestone: v1.0 Foundation

### Phase 4: Focused Command System
### Phase 5: Path Routing & Validation
### Phase 6: Documentation & Distribution

1. Extract all phase numbers from phase headings (### Phase N:)
2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
3. Find the maximum integer value
4. Add 1 to get the next phase number

Example: If phases are 4, 5, 5.1, 6 → next is 7

Format as two-digit: printf "%02d" $next_phase

# Example transformation:
# "Add authentication" → "add-authentication"
# "Fix critical performance issues" → "fix-critical-performance-issues"

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')

Phase directory name: {two-digit-phase}-{slug} Example: 07-add-authentication

phase_dir=".planning/phases/${phase_num}-${slug}"
mkdir -p "$phase_dir"

Confirm: "Created directory: $phase_dir"

1. Find the insertion point (after last phase in current milestone, before "---" separator)

2. Insert new phase heading:

   ### Phase {N}: {Description}
   
   **Goal:** [To be planned]
   **Depends on:** Phase {N-1}
   **Plans:** 0 plans
   
   Plans:
   - [ ] TBD (run /gsd:plan-phase {N} to break down)
   
   **Details:**
   [To be added during planning]
   

3. Write updated roadmap back to file

Preserve all other content exactly (formatting, spacing, other phases).

1. Read .planning/STATE.md
2. Under "## Current Position" → "Next Phase:" add reference to new phase
3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:

   - Phase {N} added: {description}
   

If "Roadmap Evolution" section doesn't exist, create it.

Phase {N} added to current milestone:
- Description: {description}
- Directory: .planning/phases/{phase-num}-{slug}/
- Status: Not planned yet

Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md

---

## ▶ Next Up

**Phase {N}: {description}**

`/gsd:plan-phase {N}`

<sub>`/clear` first → fresh context window</sub>

---

**Also available:**
- `/gsd:add-phase <description>` — add another phase
- Review roadmap

---