---
name: forge:new-milestone
description: Start new milestone cycle — update ROADMAP.md and route to requirements
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Bash
---

<objective>
Initialize a new milestone cycle in the ROADMAP.md after completing the previous one.

Updates ROADMAP.md structure and routes to requirements gathering for the new milestone.
</objective>

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

<context>
**New Milestone Workflow:**
1. Validate previous milestone is complete
2. Get milestone details (name, goals)
3. Create new milestone section in ROADMAP.md
4. Update STATE.json
5. Route to requirements gathering
</context>

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

1. **Validate Previous Milestone**
   - Check STATE.json for current milestone status
   - If "in_progress" → warn: "Previous milestone not complete. Continue?"
   - If "completed" → proceed

2. **Gather Milestone Details**
   Use AskUserQuestion:
   - **Milestone Name**: What is this milestone called?
   - **Milestone Goals**: What are the primary goals?
   - **Success Criteria**: How do we know it's complete?
   - **Estimated Duration**: How long will this take?

3. **Calculate Milestone Number**
   - Find last milestone in ROADMAP.md
   - Increment by 1 (e.g., M2 → M3)

4. **Update ROADMAP.md**
   ```markdown
   ## Milestone {number}: {name}

   **Status:** 🚧 In Progress
   **Started:** {date}
   **Goals:** {goals}

   ### Success Criteria
   - {criterion-1}
   - {criterion-2}

   ### Phases
   _Phases will be added here_

   ---
   ```

5. **Update STATE.json**
   ```json
   {
     "project": {
       "currentMilestone": "M{number}",
       "currentPhase": null,
       "status": "in_progress"
     }
   }
   ```

6. **Submit Events**
   - Event type: MILESTONE_STARTED
   - Include: milestoneId, name, goals
   - Write to state/events/

7. **Create Milestone Directory**
   ```bash
   mkdir -p .planning/phases/
   ```

8. **Route to Requirements**
   - Suggest: Run `/forge:generate requirements` or manual requirements gathering
   - Ask: "Do you want to gather requirements now?"
     - Yes: Route to requirements workflow
     - No: Complete, user can gather later

9. **Confirm**
   - Show new milestone details
   - Display ROADMAP.md structure
   - Provide next steps
</process>

<deliverables>
- ROADMAP.md updated (new milestone section added)
- STATE.json updated (currentMilestone set)
- Event: MILESTONE_STARTED in state/events/
- .planning/phases/ ready for new phases
</deliverables>

<next_steps>
- Gather requirements: `forge generate requirements` or manual
- Add phases: `forge add-phase "description"`
- Discuss phase: `forge discuss <phase>`
- Plan phase: `forge plan <phase>`
</next_steps>