/gsd new-milestone
What It Does
Section titled “What It Does”/gsd new-milestone is the brownfield equivalent of /gsd new-project. Your project already exists, PROJECT.md has history, and phases have shipped — this command starts the next cycle. It loads your existing project context, gathers what you want to build next, updates PROJECT.md and STATE.md, optionally runs parallel domain research, scopes requirements with REQ-IDs, and spawns the roadmapper to produce a phased execution plan that continues your phase numbering from where the last milestone left off.
The command accepts an optional milestone name as an argument. If no MILESTONE-CONTEXT.md file exists (a pre-gathered context file you can prepare in advance), it falls back to interactive Q&A — asking what you want to build next and exploring features, priorities, and constraints.
After the roadmap is approved and committed, you get a clear next step: /gsd:discuss-phase [N] to clarify the first phase, or /gsd:plan-phase [N] to start execution directly.
/gsd new-milestone [milestone name]The milestone name argument is optional. If provided, it pre-fills the milestone label (e.g., v1.1 Notifications). If omitted, GSD will prompt for it during the workflow.
/gsd new-milestone/gsd new-milestone "v2.0 Social Features"/gsd new-milestone v1.1 NotificationsHow It Works
Section titled “How It Works”Workflow Overview
Section titled “Workflow Overview”Step-by-Step
Section titled “Step-by-Step”1. Load context — Reads PROJECT.md (existing stack, decisions, validated requirements), MILESTONES.md (what has shipped), and STATE.md (pending todos, blockers). Checks for a pre-existing MILESTONE-CONTEXT.md.
2. Gather milestone goals — If MILESTONE-CONTEXT.md exists (a pre-prepared context file), its features and scope are used and presented for confirmation. Otherwise, GSD shows what shipped in the last milestone and asks inline (freeform): “What do you want to build next?” — then follows up with AskUserQuestion to probe features, priorities, constraints, and scope.
3. Determine milestone version — Parses the last version from MILESTONES.md, suggests the next increment (e.g., v1.0 → v1.1, or v2.0 for a major), and confirms with you.
4. Update PROJECT.md and STATE.md — Adds a ## Current Milestone section to PROJECT.md with the goal and target features. Resets STATE.md with Phase: Not started (defining requirements), preserving the Accumulated Context section from the previous milestone.
5. Consume MILESTONE-CONTEXT.md — If the context file existed, it’s deleted (consumed). Then both updated files are committed.
6. Resolve models — Runs gsd-tools init new-milestone to extract researcher_model, synthesizer_model, roadmapper_model, and workflow config flags.
7. Research decision — Asks whether to research the domain ecosystem for new features before defining requirements. The choice is persisted to config so future commands honor it. If “Research first” is selected, 4 parallel gsd-project-researcher agents run (see below).
8. Research (optional) — Spawns 4 parallel agents, each focused on a different dimension:
| Dimension | Question answered |
|---|---|
| Stack | What library/version additions are needed for the new features? |
| Features | How do the target features typically work? Table stakes vs differentiators? |
| Architecture | How do new features integrate with the existing architecture? |
| Pitfalls | Common mistakes when adding these features to an existing system? |
After all 4 complete, a gsd-research-synthesizer agent writes SUMMARY.md with key findings displayed inline.
9. Define requirements — Presents features by category (from research or gathered via conversation). For each category, AskUserQuestion (multi-select) lets you scope what’s in vs deferred vs out of scope. Requirements are written with REQ-IDs in [CATEGORY]-[NUMBER] format (e.g., AUTH-01, NOTIF-02), continuing numbering from existing requirements. You confirm the full list before it’s committed.
10. Create roadmap — Spawns gsd-roadmapper with the phase starting number taken from MILESTONES.md (e.g., if v1.0 ended at phase 5, v1.1 starts at phase 6). The roadmapper maps every requirement to exactly one phase, derives 2–5 success criteria per phase, and validates 100% coverage. The roadmap is presented inline for approval — you can request adjustments and the roadmapper is re-spawned until you approve.
11. Final commit — Commits ROADMAP.md, STATE.md, and REQUIREMENTS.md together (with the traceability section filled in by the roadmapper). Displays a completion summary with the artifact table and the next command.
Milestone Version Numbering
Section titled “Milestone Version Numbering”GSD reads the last version from MILESTONES.md and suggests the next increment:
v1.0→ suggestsv1.1(minor increment)- Suggest
v2.0yourself for major reboots
Phase numbering continues across milestones — if v1.0 delivered phases 1–5, v1.1’s roadmap starts at phase 6. This preserves the full build history in a single continuous phase sequence.
Context File Shortcut
Section titled “Context File Shortcut”If a MILESTONE-CONTEXT.md file is present in .planning/ when you run new-milestone, the Q&A step is skipped entirely — GSD uses that file’s features and scope directly and presents a summary for confirmation. This is the fastest path through new-milestone when the goals are already clear.
What Files It Touches
Section titled “What Files It Touches”| File | Purpose |
|---|---|
.planning/PROJECT.md | Existing stack, decisions, validated requirements |
.planning/MILESTONES.md | What shipped previously; last phase number for continuation |
.planning/STATE.md | Pending todos and blockers from previous milestone |
.planning/MILESTONE-CONTEXT.md | Pre-gathered milestone goals (optional — skips Q&A if present) |
.planning/research/SUMMARY.md | Research findings (if research ran) — used during requirements scoping |
Creates
Section titled “Creates”| File | Purpose |
|---|---|
.planning/REQUIREMENTS.md | Scoped requirements with REQ-IDs, categories, future and out-of-scope sections |
.planning/ROADMAP.md | Phased execution plan with success criteria, continuing phase numbering |
.planning/research/STACK.md | Stack additions needed for new features (research only) |
.planning/research/FEATURES.md | Feature analysis: table stakes vs differentiators (research only) |
.planning/research/ARCHITECTURE.md | Integration points and build order (research only) |
.planning/research/PITFALLS.md | Common mistakes and prevention strategies (research only) |
.planning/research/SUMMARY.md | Synthesized research summary (research only) |
Writes
Section titled “Writes”| File | Purpose |
|---|---|
.planning/PROJECT.md | Updated with ## Current Milestone section and active requirements |
.planning/STATE.md | Reset to Phase: Not started (defining requirements) for new milestone |
.planning/REQUIREMENTS.md | Traceability section filled by roadmapper after roadmap creation |
Deletes
Section titled “Deletes”| File | Purpose |
|---|---|
.planning/MILESTONE-CONTEXT.md | Consumed and deleted after goals are extracted |
Examples
Section titled “Examples”Start a new milestone with a name:
/gsd new-milestone "v2.0 Social Features"GSD loads your project history, shows what shipped in v1.0, and jumps straight to version confirmation and research decision — saving the “what to build” Q&A since you’ve named the milestone.
Start with no name — full interactive flow:
/gsd new-milestoneGSD asks what you want to build next, explores priorities and constraints, suggests a version number, then proceeds through research → requirements → roadmap.
Fastest path — pre-prepare context then plan:
If you’ve created a MILESTONE-CONTEXT.md file in .planning/ ahead of time, running /gsd new-milestone skips the goal-gathering Q&A entirely:
/gsd new-milestone
● Found MILESTONE-CONTEXT.md — using pre-gathered scope Milestone: v1.1 Notifications Features: Push alerts, in-app notification center, digest emails
Confirm? (yes / adjust)Research output example:
When research is selected, GSD runs 4 parallel agents and shows a summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► RESEARCH COMPLETE ✓━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stack additions: expo-notifications 0.28, @supabase/realtime-jsFeature table stakes: delivery receipts, badge counts, opt-out per typeWatch Out For: APNs certificate expiry, notification permission timingRequirements scoping:
After research (or Q&A), GSD scopes each category interactively:
## Push NotificationsTable stakes: Delivery receipts, Badge countsDifferentiators: Rich media, Scheduled sends
Which features are in scope for v1.1? (multi-select)✓ Delivery receipts✓ Badge counts Rich media — deferred to v1.2 Scheduled sends — out of scopeRelated Commands
Section titled “Related Commands”/gsd new-project— Greenfield equivalent — initializes a brand-new project from scratch/gsd complete-milestone— Archive the current milestone before running new-milestone/gsd discuss-phase— Clarify implementation decisions for a specific phase before planning/gsd plan-phase— Create a detailed phase plan after the roadmap is ready