From 0c96b309019a1c431375a7f7f25809180bac8d90 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sat, 17 Jan 2026 00:45:48 -0600 Subject: [PATCH] refactor: defer phase directory creation to discuss/plan-phase Phase directories are now created on-demand when discuss-phase or plan-phase first touches a phase, rather than upfront by roadmapper. Prevents duplicate folders when roadmapper names phases differently than what discuss/plan-phase derives from the roadmap. Co-Authored-By: Claude Opus 4.5 --- agents/gsd-roadmapper.md | 21 +++------------------ commands/gsd/new-milestone.md | 8 +++----- commands/gsd/new-project.md | 7 ++----- 3 files changed, 8 insertions(+), 28 deletions(-) diff --git a/agents/gsd-roadmapper.md b/agents/gsd-roadmapper.md index c0cff6787..5f3dafbf8 100644 --- a/agents/gsd-roadmapper.md +++ b/agents/gsd-roadmapper.md @@ -414,22 +414,11 @@ If gaps found, include in draft for user decision. **Write files first, then return.** This ensures artifacts persist even if context is lost. -1. **Create phase directories (zero-padded):** - ```bash - # Always zero-pad phase numbers: 01, 02, ... 09, 10, 11 - for i in 1 2 3; do - PADDED=$(printf "%02d" $i) - mkdir -p ".planning/phases/${PADDED}-{phase-name}" - done - ``` +1. **Write ROADMAP.md** using output format - Examples: `01-foundation`, `02-core-features`, `10-polish` +2. **Write STATE.md** using output format -2. **Write ROADMAP.md** using output format - -3. **Write STATE.md** using output format - -4. **Update REQUIREMENTS.md traceability section** +3. **Update REQUIREMENTS.md traceability section** Files on disk = context preserved. User can review actual files. @@ -459,9 +448,6 @@ When files are written and returning to orchestrator: **Files written:** - .planning/ROADMAP.md - .planning/STATE.md -- .planning/phases/01-{phase-name}/ -- .planning/phases/02-{phase-name}/ -- ... (all phases zero-padded) **Updated:** - .planning/REQUIREMENTS.md (traceability section) @@ -602,7 +588,6 @@ Roadmap is complete when: - [ ] 100% requirement coverage validated (no orphans) - [ ] ROADMAP.md structure complete - [ ] STATE.md structure complete -- [ ] Phase directories identified - [ ] REQUIREMENTS.md traceability update prepared - [ ] Draft presented for user approval - [ ] User feedback incorporated (if any) diff --git a/commands/gsd/new-milestone.md b/commands/gsd/new-milestone.md index 20f528337..81ed4ee5c 100644 --- a/commands/gsd/new-milestone.md +++ b/commands/gsd/new-milestone.md @@ -23,7 +23,6 @@ This is the brownfield equivalent of new-project. The project exists, PROJECT.md - `.planning/REQUIREMENTS.md` — scoped requirements - `.planning/ROADMAP.md` — phase structure - `.planning/STATE.md` — updated project memory -- `.planning/phases/` — phase directories **After this command:** Run `/gsd:plan-phase [N]` to start execution. @@ -591,7 +590,7 @@ Create roadmap: 2. Map every v1 requirement to exactly one phase 3. Derive 2-5 success criteria per phase (observable user behaviors) 4. Validate 100% coverage -5. Write files immediately (ROADMAP.md, STATE.md, phase directories, update REQUIREMENTS.md traceability) +5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability) 6. Return ROADMAP CREATED with summary Write files first, then return. @@ -630,7 +629,7 @@ Use AskUserQuestion: **Commit roadmap:** ```bash -git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/ +git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md git commit -m "$(cat <<'EOF' docs: create v[X.Y] roadmap ([N] phases) @@ -696,7 +695,6 @@ Present completion with next steps: - `.planning/REQUIREMENTS.md` - `.planning/ROADMAP.md` - `.planning/STATE.md` -- `.planning/phases/XX-name/` directories @@ -713,7 +711,7 @@ Present completion with next steps: - [ ] gsd-roadmapper spawned with context - [ ] Roadmap files written immediately - [ ] User feedback incorporated (if any) -- [ ] ROADMAP.md, STATE.md, phase directories → **committed** +- [ ] ROADMAP.md, STATE.md → **committed** - [ ] User knows next step is `/gsd:plan-phase [N]` diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md index 17b2a2040..f71bf6be7 100644 --- a/commands/gsd/new-project.md +++ b/commands/gsd/new-project.md @@ -22,7 +22,6 @@ This is the most leveraged moment in any project. Deep questioning here means be - `.planning/REQUIREMENTS.md` — scoped requirements - `.planning/ROADMAP.md` — phase structure - `.planning/STATE.md` — project memory -- `.planning/phases/` — phase directories **After this command:** Run `/gsd:plan-phase 1` to start execution. @@ -710,7 +709,7 @@ Create roadmap: 2. Map every v1 requirement to exactly one phase 3. Derive 2-5 success criteria per phase (observable user behaviors) 4. Validate 100% coverage -5. Write files immediately (ROADMAP.md, STATE.md, phase directories, update REQUIREMENTS.md traceability) +5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability) 6. Return ROADMAP CREATED with summary Write files first, then return. This ensures artifacts persist even if context is lost. @@ -801,7 +800,7 @@ Use AskUserQuestion: **Commit roadmap (after approval):** ```bash -git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/ +git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md git commit -m "$(cat <<'EOF' docs: create roadmap ([N] phases) @@ -869,7 +868,6 @@ Present completion with next steps: - `.planning/REQUIREMENTS.md` - `.planning/ROADMAP.md` - `.planning/STATE.md` -- `.planning/phases/XX-name/` directories @@ -891,7 +889,6 @@ Present completion with next steps: - [ ] ROADMAP.md created with phases, requirement mappings, success criteria - [ ] STATE.md initialized - [ ] REQUIREMENTS.md traceability updated -- [ ] Phase directories created → **committed** - [ ] User knows next step is `/gsd:discuss-phase 1` **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.