Gsd New Milestone

Load milestone context (if exists, from /gsd-discuss-milestone): @.planning/MILESTONE-CONTEXT.md </context>

Phase 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 /gsd-discuss-milestone)

Phase 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

Phase 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

Phase 4: Update PROJECT.md

Add/update these sections:

## 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.

Phase 5: Update STATE.md

## Current Position

Phase: Not started (defining requirements)
Plan: —
Status: Defining requirements
Last activity: [today] — Milestone v[X.Y] started

Keep Accumulated Context section (decisions, blockers) from previous milestone.

Phase 6: Cleanup and Commit

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

Check planning config:

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations

If COMMIT_PLANNING_DOCS=true (default):

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

Phase 6.5: Resolve Model Profile

Read model profile for agent spawning:

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to "balanced" if not set.

Model lookup table:

Store resolved models for use in Task calls below.

Phase 7: Research Decision

Use AskUserQuestion:

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

If "Research first":

Display stage banner:

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

Researching [new features] ecosystem...

Create research directory:

mkdir -p .planning/research

Display spawning indicator:

◆ Spawning 4 researchers in parallel...
  → Stack research (for new features)
  → Features research
  → Architecture research (integration)
  → Pitfalls research

Spawn 4 parallel gsd-project-researcher agents with milestone-aware context:

Task(prompt="
<research_type>
Project Research — Stack dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing validated capabilities (DO NOT re-research):
[List from PROJECT.md Validated requirements]

Focus ONLY on what's needed for the NEW features.
</milestone_context>

<question>
What stack additions/changes are needed for [new features]?
</question>

<project_context>
[PROJECT.md summary - current state, new milestone goals]
</project_context>

<downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions for NEW capabilities
- Integration points with existing stack
- What NOT to add and why
</downstream_consumer>

<quality_gate>
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Integration with existing stack considered
</quality_gate>

<output>
Write to: .planning/research/STACK.md
Use template: .github/get-shit-done/templates/research-project/STACK.md
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Stack research")

Task(prompt="
<research_type>
Project Research — Features dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing features (already built):
[List from PROJECT.md Validated requirements]

Focus on how [new features] typically work, expected behavior.
</milestone_context>

<question>
How do [target features] typically work? What's expected behavior?
</question>

<project_context>
[PROJECT.md summary - new milestone goals]
</project_context>

<downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly:
- Table stakes (must have for these features)
- Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build)
</downstream_consumer>

<quality_gate>
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies on existing features identified
</quality_gate>

<output>
Write to: .planning/research/FEATURES.md
Use template: .github/get-shit-done/templates/research-project/FEATURES.md
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Features research")

Task(prompt="
<research_type>
Project Research — Architecture dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing architecture:
[Summary from PROJECT.md or codebase map]

Focus on how [new features] integrate with existing architecture.
</milestone_context>

<question>
How do [target features] integrate with existing [domain] architecture?
</question>

<project_context>
[PROJECT.md summary - current architecture, new features]
</project_context>

<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Integration points with existing components
- New components needed
- Data flow changes
- Suggested build order
</downstream_consumer>

<quality_gate>
- [ ] Integration points clearly identified
- [ ] New vs modified components explicit
- [ ] Build order considers existing dependencies
</quality_gate>

<output>
Write to: .planning/research/ARCHITECTURE.md
Use template: .github/get-shit-done/templates/research-project/ARCHITECTURE.md
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Architecture research")

Task(prompt="
<research_type>
Project Research — Pitfalls dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Focus on common mistakes when ADDING these features to an existing system.
</milestone_context>

<question>
What are common mistakes when adding [target features] to [domain]?
</question>

<project_context>
[PROJECT.md summary - current state, new features]
</project_context>

<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Warning signs (how to detect early)
- Prevention strategy (how to avoid)
- Which phase should address it
</downstream_consumer>

<quality_gate>
- [ ] Pitfalls are specific to adding these features (not generic)
- [ ] Integration pitfalls with existing system covered
- [ ] Prevention strategies are actionable
</quality_gate>

<output>
Write to: .planning/research/PITFALLS.md
Use template: .github/get-shit-done/templates/research-project/PITFALLS.md
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="Pitfalls research")

After all 4 agents complete, spawn synthesizer to create SUMMARY.md:

Task(prompt="
<task>
Synthesize research outputs into SUMMARY.md.
</task>

<research_files>
Read these files:
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
</research_files>

<output>
Write to: .planning/research/SUMMARY.md
Use template: .github/get-shit-done/templates/research-project/SUMMARY.md
Commit after writing.
</output>
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")

Display research complete banner and key findings:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Key Findings

**Stack additions:** [from SUMMARY.md]
**New feature table stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]

Files: `.planning/research/`

If "Skip research": Continue to Phase 8.

Phase 8: Define Requirements

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Load context:

Read PROJECT.md and extract:

• Core value (the ONE thing that must work)
• Current milestone goals
• Validated requirements (what already exists)

If research exists: Read research/FEATURES.md and extract feature categories.

Present features by category:

Here are the features for [new capabilities]:

## [Category 1]
**Table stakes:**
- Feature A
- Feature B

**Differentiators:**
- Feature C
- Feature D

**Research notes:** [any relevant notes]

---

## [Next Category]
...

If no research: Gather requirements through conversation instead.

Ask: "What are the main things users need to be able to do with [new features]?"

For each capability mentioned:

• Ask clarifying questions to make it specific
• Probe for related capabilities
• Group into categories

Scope each category:

For each category, use AskUserQuestion:

• header: "[Category name]"
• question: "Which [category] features are in this milestone?"
• multiSelect: true
• options:
  • "[Feature 1]" — [brief description]
  • "[Feature 2]" — [brief description]
  • "[Feature 3]" — [brief description]
  • "None for this milestone" — Defer entire category

Track responses:

• Selected features → this milestone's requirements
• Unselected table stakes → future milestone
• Unselected differentiators → out of scope

Identify gaps:

Use AskUserQuestion:

• header: "Additions"
• question: "Any requirements research missed? (Features specific to your vision)"
• options:
  • "No, research covered it" — Proceed
  • "Yes, let me add some" — Capture additions

Generate REQUIREMENTS.md:

Create .planning/REQUIREMENTS.md with:

• v1 Requirements for THIS milestone grouped by category (checkboxes, REQ-IDs)
• Future Requirements (deferred to later milestones)
• Out of Scope (explicit exclusions with reasoning)
• Traceability section (empty, filled by roadmap)

REQ-ID format: [CATEGORY]-[NUMBER] (AUTH-01, NOTIF-02)

Continue numbering from existing requirements if applicable.

Requirement quality criteria:

Good requirements are:

• Specific and testable: "User can reset password via email link" (not "Handle password reset")
• User-centric: "User can X" (not "System does Y")
• Atomic: One capability per requirement (not "User can login and manage profile")
• Independent: Minimal dependencies on other requirements

Present full requirements list:

Show every requirement (not counts) for user confirmation:

## Milestone v[X.Y] Requirements

### [Category 1]
- [ ] **CAT1-01**: User can do X
- [ ] **CAT1-02**: User can do Y

### [Category 2]
- [ ] **CAT2-01**: User can do Z

[... full list ...]

---

Does this capture what you're building? (yes / adjust)

If "adjust": Return to scoping.

Commit requirements:

Check planning config (same pattern as Phase 6).

If committing:

git add .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'