New Milestone

---
name: gsd: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
  - Task
  - AskUserQuestion
  - Glob
---

<objective>

Start a new milestone through unified flow: questioning → research (optional) → requirements → roadmap.

This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and takes you through the full cycle.

**Creates/Updates:**
- `.planning/PROJECT.md` — updated with new milestone goals
- `.planning/research/` — domain research (optional)
- `.planning/REQUIREMENTS.md` — scoped requirements
- `.planning/ROADMAP.md` — phase structure
- `.planning/STATE.md` — updated project memory

**After this command:** Run `/gsd:plan-phase [N]` to start execution.

</objective>

<execution_context>

@./.claude/get-shit-done/references/questioning.md
@./.claude/get-shit-done/references/ui-brand.md
@./.claude/get-shit-done/templates/project.md
@./.claude/get-shit-done/templates/requirements.md

</execution_context>

<context>

Milestone name: $ARGUMENTS (optional - will prompt if not provided)

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

</context>

<process>

## Phase 1: Validate

**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**

1. **Verify project exists:**
   ```bash
   [ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }

2. Check for active milestone (ROADMAP.md exists):

   [ -f .planning/ROADMAP.md ] && echo "ACTIVE_MILESTONE" || echo "READY_FOR_NEW"
   

   If ACTIVE_MILESTONE: Use AskUserQuestion:

   • header: "Active Milestone"
   • question: "A milestone is in progress. What would you like to do?"
   • options:
     • "Complete current first" — Run /gsd:complete-milestone
     • "Continue anyway" — Start new milestone (will archive current)

   If "Complete current first": Exit with routing to /gsd:complete-milestone If "Continue anyway": Continue to Phase 2

3. Load previous milestone context:

   cat .planning/MILESTONES.md 2>/dev/null || echo "NO_MILESTONES"
   cat .planning/STATE.md
   

Phase 2: Present Context

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► NEW MILESTONE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Present what shipped:

Last milestone: v[X.Y] [Name] (shipped [DATE])

Key accomplishments:
- [From MILESTONES.md]
- [From MILESTONES.md]
- [From MILESTONES.md]

Validated requirements:
- [From PROJECT.md Validated section]

Pending todos:
- [From STATE.md if any]

Phase 3: Deep Questioning

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Open the conversation:

Ask inline (freeform, NOT AskUserQuestion):

"What do you want to build next?"

Wait for their response. This gives you the context needed to ask intelligent follow-up questions.

Follow the thread:

Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.

Keep following threads. Each answer opens new threads to explore. Ask about:

• What excited them
• What problem sparked this
• What they mean by vague terms
• What it would actually look like
• What's already decided

Consult questioning.md for techniques:

• Challenge vagueness
• Make abstract concrete
• Surface assumptions
• Find edges
• Reveal motivation

Decision gate:

When you could update PROJECT.md with clear new goals, use AskUserQuestion:

• header: "Ready?"
• question: "I think I understand what you're after. Ready to update PROJECT.md?"
• options:
  • "Update PROJECT.md" — Let's move forward
  • "Keep exploring" — I want to share more / ask me more

If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.

Loop until "Update PROJECT.md" selected.

Phase 4: Determine Milestone Version

Parse last version from MILESTONES.md and suggest next:

Use AskUserQuestion:

• header: "Version"
• question: "What version is this milestone?"
• options:
  • "v[X.Y+0.1] (patch)" — Minor update: [suggested name]
  • "v[X+1].0 (major)" — Major release
  • "Custom" — I'll specify

Phase 5: Update PROJECT.md

Update .planning/PROJECT.md with new milestone section:

## 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 (keep Validated section intact).

Update "Last updated" footer.

Commit PROJECT.md:

git add .planning/PROJECT.md
git commit -m "$(cat <<'EOF'
docs: start milestone v[X.Y] [Name]

[One-liner describing milestone focus]
EOF
)"

Phase 6: Research Decision

Use AskUserQuestion:

• header: "Research"
• question: "Research the domain ecosystem before defining requirements?"
• options:
  • "Research first (Recommended)" — Discover patterns, expected features, architecture
  • "Skip research" — I know this domain well, go straight to requirements

If "Research first":

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Researching [domain] ecosystem...

Create research directory:

mkdir -p .planning/research

Milestone context is "subsequent" — Research focuses on new features, not re-researching validated requirements.

Display spawning indicator:

◆ Spawning 4 researchers in parallel...
  → Stack research
  → Features research
  → Architecture researc