---
name: forge:complete-milestone
description: Archive completed milestone and prepare for next version
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Bash
---

<objective>
Archive the completed milestone and prepare the project for the next version.

Routes to audit-milestone workflow which validates completion before archiving.
</objective>

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

<context>
**Milestone Completion Workflow:**
1. Validate all phases in milestone are complete
2. Generate milestone summary
3. Archive milestone artifacts
4. Update ROADMAP.md
5. Prepare next milestone
6. Tag and release (optional)
</context>

<process>
**Execute complete-milestone workflow:**

1. **Load State**
   - Read state/STATE.json
   - Read ROADMAP.md
   - Identify current milestone

2. **Validate Completion**
   Check all phases in current milestone:
   - Status is "completed"
   - All tasks complete
   - All tests passing
   - No pending blockers

   If validation fails:
   - Show incomplete phases
   - Ask: "Continue anyway?" or "Fix issues first?"

3. **Generate Milestone Summary**
   ```markdown
   # Milestone {name} Summary

   **Completed:** {date}
   **Duration:** {start-date} to {end-date}

   ## Phases Delivered
   - {phase-1}: {description}
   - {phase-2}: {description}

   ## Key Metrics
   - Total Phases: {count}
   - Total Tasks: {count}
   - Completion Rate: {percentage}
   - Test Coverage: {percentage}

   ## Technical Highlights
   - {highlight-1}
   - {highlight-2}

   ## Challenges Overcome
   - {challenge-1}
   - {challenge-2}

   ## Next Steps
   - {next-milestone-goals}
   ```

4. **Archive Artifacts**
   ```bash
   mkdir -p .planning/archive/milestone-{name}/
   cp ROADMAP.md .planning/archive/milestone-{name}/
   cp PLAN.md .planning/archive/milestone-{name}/ || true
   cp -r .planning/phases/* .planning/archive/milestone-{name}/phases/ || true
   ```

5. **Update ROADMAP.md**
   - Move completed milestone to "Completed" section
   - Mark as ✅ COMPLETE
   - Add milestone summary

6. **Update STATE.json**
   - Set `project.status` = "completed"
   - Archive milestone data
   - Prepare for next milestone

7. **Submit Events**
   - Event type: MILESTONE_COMPLETED
   - Include: milestoneId, summary, metrics
   - Write to state/events/

8. **Git Tag** (optional)
   - Ask: "Create git tag for this milestone?"
   - If yes: `git tag -a milestone-{name} -m "Milestone {name} complete"`

9. **Confirm**
   - Show milestone summary
   - List archived artifacts
   - Suggest next: `/forge:new-milestone` or manual planning

10. **Cleanup**
    - Offer to remove completed phase directories
    - Ask: "Clean up .planning/phases/?"
</process>

<deliverables>
- .planning/archive/milestone-{name}/ (archived artifacts)
- ROADMAP.md updated (milestone moved to completed)
- STATE.json updated (milestone archived)
- Event: MILESTONE_COMPLETED in state/events/
- Optional: Git tag milestone-{name}
</deliverables>

<next_steps>
- Run `forge new-milestone` to start next milestone
- Or manually plan next work
- Celebrate! 🎉
</next_steps>