From c096ead2f449deedeb07d96481e939b317015f89 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 7 Jan 2026 17:42:46 -0600 Subject: [PATCH] feat: add /gsd:remove-phase command Remove future phases from roadmap and renumber subsequent phases. - Validates phase is unstarted (no SUMMARY.md files) - Deletes phase directory - Renumbers all subsequent phases (integers and decimals) - Updates ROADMAP.md and STATE.md - Git commit preserves historical record Co-Authored-By: Claude Opus 4.5 --- README.md | 1 + commands/gsd/help.md | 11 ++ commands/gsd/remove-phase.md | 338 +++++++++++++++++++++++++++++++++++ 3 files changed, 350 insertions(+) create mode 100644 commands/gsd/remove-phase.md diff --git a/README.md b/README.md index d159b1826..44b0d9163 100644 --- a/README.md +++ b/README.md @@ -307,6 +307,7 @@ You're never locked in. The system adapts. | `/gsd:new-milestone [name]` | Create new milestone with phases | | `/gsd:add-phase` | Append phase to roadmap | | `/gsd:insert-phase [N]` | Insert urgent work | +| `/gsd:remove-phase [N]` | Remove future phase, renumber subsequent | | `/gsd:discuss-phase [N]` | Gather context before planning | | `/gsd:research-phase [N]` | Deep ecosystem research for niche domains | | `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it | diff --git a/commands/gsd/help.md b/commands/gsd/help.md index e11ac2124..e4b8ce0c0 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -137,6 +137,17 @@ Insert urgent work as decimal phase between existing phases. Usage: `/gsd:insert-phase 7 "Fix critical auth bug"` Result: Creates Phase 7.1 +**`/gsd:remove-phase `** +Remove a future phase and renumber subsequent phases. + +- Deletes phase directory and all references +- Renumbers all subsequent phases to close the gap +- Only works on future (unstarted) phases +- Git commit preserves historical record + +Usage: `/gsd:remove-phase 17` +Result: Phase 17 deleted, phases 18-20 become 17-19 + ### Milestone Management **`/gsd:discuss-milestone`** diff --git a/commands/gsd/remove-phase.md b/commands/gsd/remove-phase.md new file mode 100644 index 000000000..f59d3d6ea --- /dev/null +++ b/commands/gsd/remove-phase.md @@ -0,0 +1,338 @@ +--- +name: gsd:remove-phase +description: Remove a future phase from roadmap and renumber subsequent phases +argument-hint: +allowed-tools: + - Read + - Write + - Bash + - Glob +--- + + +Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence. + +Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers. +Output: Phase deleted, all subsequent phases renumbered, git commit as historical record. + + + +@.planning/ROADMAP.md +@.planning/STATE.md + + + + + +Parse the command arguments: +- Argument is the phase number to remove (integer or decimal) +- Example: `/gsd:remove-phase 17` → phase = 17 +- Example: `/gsd:remove-phase 16.1` → phase = 16.1 + +If no argument provided: + +``` +ERROR: Phase number required +Usage: /gsd:remove-phase +Example: /gsd:remove-phase 17 +``` + +Exit. + + + +Load project state: + +```bash +cat .planning/STATE.md 2>/dev/null +cat .planning/ROADMAP.md 2>/dev/null +``` + +Parse current phase number from STATE.md "Current Position" section. + + + +Verify the target phase exists in ROADMAP.md: + +1. Search for `### Phase {target}:` heading +2. If not found: + + ``` + ERROR: Phase {target} not found in roadmap + Available phases: [list phase numbers] + ``` + + Exit. + + + +Verify the phase is a future phase (not started): + +1. Compare target phase to current phase from STATE.md +2. Target must be > current phase number + +If target <= current phase: + +``` +ERROR: Cannot remove Phase {target} + +Only future phases can be removed: +- Current phase: {current} +- Phase {target} is current or completed + +To abandon current work, use /gsd:pause-work instead. +``` + +Exit. + +3. Check for SUMMARY.md files in phase directory: + +```bash +ls .planning/phases/{target}-*/*-SUMMARY.md 2>/dev/null +``` + +If any SUMMARY.md files exist: + +``` +ERROR: Phase {target} has completed work + +Found executed plans: +- {list of SUMMARY.md files} + +Cannot remove phases with completed work. +``` + +Exit. + + + +Collect information about the phase being removed: + +1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}` +2. Find phase directory: `.planning/phases/{target}-{slug}/` +3. Find all subsequent phases (integer and decimal) that need renumbering + +**Subsequent phase detection:** + +For integer phase removal (e.g., 17): +- Find all phases > 17 (integers: 18, 19, 20...) +- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x +- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent + +For decimal phase removal (e.g., 17.1): +- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down +- Integer phases unchanged + +List all phases that will be renumbered. + + + +Present removal summary and confirm: + +``` +Removing Phase {target}: {Name} + +This will: +- Delete: .planning/phases/{target}-{slug}/ +- Renumber {N} subsequent phases: + - Phase 18 → Phase 17 + - Phase 18.1 → Phase 17.1 + - Phase 19 → Phase 18 + [etc.] + +Proceed? (y/n) +``` + +Wait for confirmation. + + + +Delete the target phase directory if it exists: + +```bash +if [ -d ".planning/phases/{target}-{slug}" ]; then + rm -rf ".planning/phases/{target}-{slug}" + echo "Deleted: .planning/phases/{target}-{slug}/" +fi +``` + +If directory doesn't exist, note: "No directory to delete (phase not yet created)" + + + +Rename all subsequent phase directories: + +For each phase directory that needs renumbering (in reverse order to avoid conflicts): + +```bash +# Example: renaming 18-dashboard to 17-dashboard +mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard" +``` + +Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting. + +Also rename decimal phase directories: +- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17) +- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1) + + + +Rename plan files inside renumbered directories: + +For each renumbered directory, rename files that contain the phase number: + +```bash +# Inside 17-dashboard (was 18-dashboard): +mv "18-01-PLAN.md" "17-01-PLAN.md" +mv "18-02-PLAN.md" "17-02-PLAN.md" +mv "18-01-SUMMARY.md" "17-01-SUMMARY.md" # if exists +# etc. +``` + +Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed). + + + +Update ROADMAP.md: + +1. **Remove the phase section entirely:** + - Delete from `### Phase {target}:` to the next phase heading (or section end) + +2. **Remove from phase list:** + - Delete line `- [ ] **Phase {target}: {Name}**` or similar + +3. **Remove from Progress table:** + - Delete the row for Phase {target} + +4. **Renumber all subsequent phases:** + - `### Phase 18:` → `### Phase 17:` + - `- [ ] **Phase 18:` → `- [ ] **Phase 17:` + - Table rows: `| 18. Dashboard |` → `| 17. Dashboard |` + - Plan references: `18-01:` → `17-01:` + +5. **Update dependency references:** + - `**Depends on:** Phase 18` → `**Depends on:** Phase 17` + - For the phase that depended on the removed phase: + - `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16` + +6. **Renumber decimal phases:** + - `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed) + - Update all references consistently + +Write updated ROADMAP.md. + + + +Update STATE.md: + +1. **Update total phase count:** + - `Phase: 16 of 20` → `Phase: 16 of 19` + +2. **Recalculate progress percentage:** + - New percentage based on completed plans / new total plans + +Do NOT add a "Roadmap Evolution" note - the git commit is the record. + +Write updated STATE.md. + + + +Search for and update phase references inside plan files: + +```bash +# Find files that reference the old phase numbers +grep -r "Phase 18" .planning/phases/17-*/ 2>/dev/null +grep -r "Phase 19" .planning/phases/18-*/ 2>/dev/null +# etc. +``` + +Update any internal references to reflect new numbering. + + + +Stage and commit the removal: + +```bash +git add .planning/ +git commit -m "chore: remove phase {target} ({original-phase-name})" +``` + +The commit message preserves the historical record of what was removed. + + + +Present completion summary: + +``` +Phase {target} ({original-name}) removed. + +Changes: +- Deleted: .planning/phases/{target}-{slug}/ +- Renumbered: Phases {first-renumbered}-{last-old} → {first-renumbered-1}-{last-new} +- Updated: ROADMAP.md, STATE.md +- Committed: chore: remove phase {target} ({original-name}) + +Current roadmap: {total-remaining} phases +Current position: Phase {current} of {new-total} + +--- + +## What's Next + +Would you like to: +- `/gsd:progress` — see updated roadmap status +- Continue with current phase +- Review roadmap + +--- +``` + + + + + + +- Don't remove completed phases (have SUMMARY.md files) +- Don't remove current or past phases +- Don't leave gaps in numbering - always renumber +- Don't add "removed phase" notes to STATE.md - git commit is the record +- Don't ask about each decimal phase - just renumber them +- Don't modify completed phase directories + + + + +**Removing a decimal phase (e.g., 17.1):** +- Only affects other decimals in same series (17.2 → 17.1, 17.3 → 17.2) +- Integer phases unchanged +- Simpler operation + +**No subsequent phases to renumber:** +- Removing the last phase (e.g., Phase 20 when that's the end) +- Just delete and update ROADMAP.md, no renumbering needed + +**Phase directory doesn't exist:** +- Phase may be in ROADMAP.md but directory not created yet +- Skip directory deletion, proceed with ROADMAP.md updates + +**Decimal phases under removed integer:** +- Removing Phase 17 when 17.1, 17.2 exist +- 17.1 → 16.1, 17.2 → 16.2 +- They maintain their position in execution order (after current last integer) + + + + +Phase removal is complete when: + +- [ ] Target phase validated as future/unstarted +- [ ] Phase directory deleted (if existed) +- [ ] All subsequent phase directories renumbered +- [ ] Files inside directories renamed ({old}-01-PLAN.md → {new}-01-PLAN.md) +- [ ] ROADMAP.md updated (section removed, all references renumbered) +- [ ] STATE.md updated (phase count, progress percentage) +- [ ] Dependency references updated in subsequent phases +- [ ] Changes committed with descriptive message +- [ ] No gaps in phase numbering +- [ ] User informed of changes +