new-milestone

---

name: new-milestone description: Start a new milestone cycle — update PROJECT.md and route to requirements argument-hint: "[milestone name, e.g., 'v1.1 Notifications']" allowed-tools:

• Read
• Write
• Bash
• AskUserQuestion

---

This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.

Output: Updated PROJECT.md, routes to research-project or define-requirements

<execution_context> @/.claude/ag4one/references/questioning.md @/.claude/ag4one/templates/project.md </execution_context>

Load project context: @.planning/PROJECT.md @.planning/STATE.md @.planning/MILESTONES.md @.planning/config.json

1. Load context:

   • Read PROJECT.md (existing project, Validated requirements, decisions)
   • Read MILESTONES.md (what shipped previously)
   • Read STATE.md (pending todos, blockers)
   • Check for MILESTONE-CONTEXT.md (from /ag4:discuss-milestone)

2. Gather milestone goals:

   If MILESTONE-CONTEXT.md exists:

   • Use features and scope from discuss-milestone
   • Present summary for confirmation

   If no context file:

   • Present what shipped in last milestone
   • Ask: "What do you want to build next?"
   • Use AskUserQuestion to explore features
   • Probe for priorities, constraints, scope

3. Determine milestone version:

   • Parse last version from MILESTONES.md
   • Suggest next version (v1.0 → v1.1, or v2.0 for major)
   • Confirm with user

4. Update PROJECT.md:

   Add/update these sections:

   Copy## Current Milestone: v[X.Y] [Name]
   
   **Goal:** [One sentence describing milestone focus]
   
   **Target features:**
   - [Feature 1]
   - [Feature 2]
   - [Feature 3]
   

   Update Active requirements section with new goals.

   Update "Last updated" footer.

5. Update STATE.md:

   Copy## Current Position
   
   Phase: Not started (run /ag4:create-roadmap)
   Plan: —
   Status: Defining requirements
   Last activity: [today] — Milestone v[X.Y] started
   

6. Cleanup:

   • Delete MILESTONE-CONTEXT.md if exists (consumed)

7. Git commit:

   Copygit add .planning/PROJECT.md .planning/STATE.md
   git commit -m "docs: start milestone v[X.Y] [Name]"
   

8. Route to next step:

   CopyMilestone v[X.Y] [Name] initialized.
   
   PROJECT.md updated with new goals.
   
   ---
   
   ## ▶ Next Up
   
   Choose your path:
   
   **Option A: Research first** (new domains/capabilities)
   Research ecosystem before scoping. Discovers patterns, expected features, architecture approaches.
   
   `/ag4:research-project`
   
   **Option B: Define requirements directly** (familiar territory)
   Skip research, define requirements from what you know.
   
   `/ag4:define-requirements`
   
   <sub>`/clear` first → fresh context window</sub>
   
   ---
   

<success_criteria>

• PROJECT.md updated with Current Milestone section
• Active requirements reflect new milestone goals
• STATE.md reset for new milestone
• MILESTONE-CONTEXT.md consumed and deleted (if existed)
• Git commit made
• User routed to define-requirements (or research-project) </success_criteria>