13 KiB
Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
<required_reading>
read all files referenced by the invoking prompt's execution_context before starting.
</required_reading>
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)
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 inline (freeform, NOT question): "What do you want to build next?"
- Wait for their response, then use question to probe specifics
- If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another question
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:
## Current Milestone: v[X.Y] [Name]
**Goal:** [One sentence describing milestone focus]
**Target features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
Update Active requirements section and "Last updated" footer.
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 from previous milestone.
6. Cleanup and Commit
Delete MILESTONE-CONTEXT.md if exists (consumed).
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
7. Load Context and Resolve Models
INIT=$(node "./.opencode/get-shit-done/bin/gsd-tools.cjs" init new-milestone)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
Extract from init JSON: researcher_model, synthesizer_model, roadmapper_model, commit_docs, research_enabled, current_milestone, project_exists, roadmap_exists.
8. Research Decision
question: "Research the domain ecosystem for new features before defining requirements?"
- "Research first (Recommended)" — Discover patterns, features, architecture for NEW capabilities
- "Skip research" — Go straight to requirements
Persist choice to config (so future /gsd-plan-phase honors it):
# If "Research first": persist true
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research true
# If "Skip research": persist false
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" config-set workflow.research false
If "Research first":
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning 4 researchers in parallel...
→ Stack, Features, Architecture, Pitfalls
mkdir -p .planning/research
Spawn 4 parallel gsd-project-researcher agents. Each uses this template with dimension-specific fields:
Common structure for all 4 researchers:
task(prompt="
<research_type>Project Research — {DIMENSION} for [new features].</research_type>
<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.
{EXISTING_CONTEXT}
Focus ONLY on what's needed for the NEW features.
</milestone_context>
<question>{QUESTION}</question>
<files_to_read>
- .planning/PROJECT.md (Project context)
</files_to_read>
<downstream_consumer>{CONSUMER}</downstream_consumer>
<quality_gate>{GATES}</quality_gate>
<output>
write to: .planning/research/{FILE}
Use template: ./.opencode/get-shit-done/templates/research-project/{FILE}
</output>
", subagent_type="gsd-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
Dimension-specific fields:
| Field | Stack | Features | Architecture | Pitfalls |
|---|---|---|---|---|
| EXISTING_CONTEXT | Existing validated capabilities (DO NOT re-research): [from PROJECT.md] | Existing features (already built): [from PROJECT.md] | Existing architecture: [from PROJECT.md or codebase map] | Focus on common mistakes when ADDING these features to existing system |
| QUESTION | What stack additions/changes are needed for [new features]? | How do [target features] typically work? Expected behavior? | How do [target features] integrate with existing architecture? | Common mistakes when adding [target features] to [domain]? |
| CONSUMER | Specific libraries with versions for NEW capabilities, integration points, what NOT to add | Table stakes vs differentiators vs anti-features, complexity noted, dependencies on existing | Integration points, new components, data flow changes, suggested build order | Warning signs, prevention strategy, which phase should address it |
| GATES | Versions current (verify with Context7), rationale explains WHY, integration considered | Categories clear, complexity noted, dependencies identified | Integration points identified, new vs modified explicit, build order considers deps | Pitfalls specific to adding these features, integration pitfalls covered, prevention actionable |
| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
After all 4 complete, spawn synthesizer:
task(prompt="
Synthesize research outputs into SUMMARY.md.
<files_to_read>
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
</files_to_read>
write to: .planning/research/SUMMARY.md
Use template: ./.opencode/get-shit-done/templates/research-project/SUMMARY.md
Commit after writing.
", subagent_type="gsd-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
Display key findings from SUMMARY.md:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Stack additions:** [from SUMMARY.md]
**Feature table stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]
If "Skip research": Continue to Step 9.
9. Define Requirements
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
read PROJECT.md: core value, current milestone goals, validated requirements (what exists).
If research exists: read FEATURES.md, extract feature categories.
Present features by category:
## [Category 1]
**Table stakes:** Feature A, Feature B
**Differentiators:** Feature C, Feature D
**Research notes:** [any relevant notes]
If no research: Gather requirements through conversation. Ask: "What are the main things users need to do with [new features]?" Clarify, probe for related capabilities, group into categories.
Scope each category via question (multiSelect: true, header max 12 chars):
- "[Feature 1]" — [brief description]
- "[Feature 2]" — [brief description]
- "None for this milestone" — Defer entire category
Track: Selected → this milestone. Unselected table stakes → future. Unselected differentiators → out of scope.
Identify gaps via question:
- "No, research covered it" — Proceed
- "Yes, let me add some" — Capture additions
Generate REQUIREMENTS.md:
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
- Future Requirements (deferred)
- 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.
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 for 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
Does this capture what you're building? (yes / adjust)
If "adjust": Return to scoping.
Commit requirements:
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
10. Create Roadmap
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► CREATING ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning roadmapper...
Starting phase number: read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
task(prompt="
<planning_context>
<files_to_read>
- .planning/PROJECT.md
- .planning/REQUIREMENTS.md
- .planning/research/SUMMARY.md (if exists)
- .planning/config.json
- .planning/MILESTONES.md
</files_to_read>
</planning_context>
<instructions>
Create roadmap for milestone v[X.Y]:
1. Start phase numbering from [N]
2. Derive phases from THIS MILESTONE's requirements only
3. Map every requirement to exactly one phase
4. Derive 2-5 success criteria per phase (observable user behaviors)
5. Validate 100% coverage
6. write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
7. Return ROADMAP CREATED with summary
write files first, then return.
</instructions>
", subagent_type="gsd-roadmapper", model="{roadmapper_model}", description="Create roadmap")
Handle return:
If ## ROADMAP BLOCKED: Present blocker, work with user, re-spawn.
If ## ROADMAP CREATED: read ROADMAP.md, present inline:
## Proposed Roadmap
**[N] phases** | **[X] requirements mapped** | All covered ✓
| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| [N] | [Name] | [Goal] | [REQ-IDs] | [count] |
### Phase Details
**Phase [N]: [Name]**
Goal: [goal]
Requirements: [REQ-IDs]
Success criteria:
1. [criterion]
2. [criterion]
Ask for approval via question:
- "Approve" — Commit and continue
- "Adjust phases" — Tell me what to change
- "Review full file" — Show raw ROADMAP.md
If "Adjust": Get notes, re-spawn roadmapper with revision context, loop until approved. If "Review": Display raw ROADMAP.md, re-ask.
Commit roadmap (after approval):
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
11. Done
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► MILESTONE INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Milestone v[X.Y]: [Name]**
| Artifact | Location |
|----------------|-----------------------------|
| Project | `.planning/PROJECT.md` |
| Research | `.planning/research/` |
| Requirements | `.planning/REQUIREMENTS.md` |
| Roadmap | `.planning/ROADMAP.md` |
**[N] phases** | **[X] requirements** | Ready to build ✓
## ▶ Next Up
**Phase [N]: [Phase Name]** — [Goal]
`/gsd-discuss-phase [N]` — gather context and clarify approach
*`/new` first → fresh context window*
Also: `/gsd-plan-phase [N]` — skip discussion, plan directly
<success_criteria>
- PROJECT.md updated with Current Milestone section
- STATE.md reset for new milestone
- MILESTONE-CONTEXT.md consumed and deleted (if existed)
- Research completed (if selected) — 4 parallel agents, milestone-aware
- Requirements gathered and scoped per category
- REQUIREMENTS.md created with REQ-IDs
- gsd-roadmapper spawned with phase numbering context
- Roadmap files written immediately (not draft)
- User feedback incorporated (if any)
- ROADMAP.md phases continue from previous milestone
- All commits made (if planning docs committed)
- User knows next step:
/gsd-discuss-phase [N]
Atomic commits: Each phase commits its artifacts immediately. </success_criteria>