---
name: forge:remove-phase
description: Remove a future phase from roadmap and renumber subsequent phases
argument-hint: <phase-number>
allowed-tools:
  - Read
  - Write
  - Bash
---

<objective>
Remove a future phase from the roadmap and renumber all subsequent phases.

Use when: Phase is no longer needed, duplicate, or superseded by another phase.

**Safety:** Cannot remove in-progress or completed phases.
</objective>

<execution_context>
@state/STATE.json
@ROADMAP.md
@CLAUDE.md
</execution_context>

<context>
**Phase to Remove:** $ARGUMENTS

**Phase Removal Validation:**
1. Check phase status (must be "pending")
2. Verify phase is in the future
3. Check for dependents
4. Warn if other phases depend on this one
</context>

<process>
**Execute remove-phase workflow:**

1. **Parse Arguments**
   - Extract phase number to remove

2. **Load State**
   - Read state/STATE.json
   - Read ROADMAP.md
   - Check phase status

3. **Validate Removal**
   - If phase is "in_progress" or "completed" → ERROR
   - If phase is "pending" → continue
   - Check for phases that depend on this one
   - If dependents exist → warn and require confirmation

4. **Renumber Subsequent Phases**
   - Find all phases with higher numbers in the same milestone
   - Decrement each phase number by 1
   - Update phase directory names if needed
   - Update phase IDs in ROADMAP.md
   - Update dependencies in other phases

5. **Remove from ROADMAP.md**
   - Delete phase entry from ROADMAP.md
   - Renumber subsequent phases
   - Update all cross-references

6. **Remove Directory** (optional)
   - Ask user if they want to remove the phase directory
   - If yes: `rm -rf .planning/phases/<phase-slug>/`
   - If no: Keep for reference

7. **Submit Event**
   - Event type: PHASE_REMOVED
   - Include: removedPhaseId, renumberedPhases
   - Write to state/events/

8. **Confirm**
   - Show removed phase info
   - List renumbered phases
   - Notify of any dependency updates
</process>

<deliverables>
- ROADMAP.md updated (phase removed, subsequent phases renumbered)
- Phase directory removed (if user confirmed)
- Event: PHASE_REMOVED in state/events/
- STATE.json updated
</deliverables>

<next_steps>
- Review updated roadmap with `/forge:status`
- Update any dependent phases manually if needed
- Continue work with `/forge:execute <phase-number>`
- Tip: Use `/clear` to start from a fresh context
</next_steps>