Orchestrate milestone planning with parallel research for subsequent project phases
<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:**
**After this command:** Run `$gsd-plan-phase [N]` to start execution.
</objective>
<execution_context>
@.codex/get-shit-done/references/questioning.md
@.codex/get-shit-done/references/ui-brand.md
@.codex/get-shit-done/templates/project.md
@.codex/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>
**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):**
```bash
[ -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:**
```bash
cat .planning/MILESTONES.md 2>/dev/null || echo "NO_MILESTONES"
cat .planning/STATE.md
```
**Display stage banner:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► NEW MILESTONE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Present what shipped:**
```
Last milestone: v[X.Y] [Name] (shipped [DATE])
Key accomplishments:
Validated requirements:
Pending todos:
```
**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:
Consult `questioning.md` for techniques:
**Decision gate:**
When you could update PROJECT.md with clear new goals, use AskUserQuestion:
- "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.
Parse last version from MILESTONES.md and suggest next:
Use AskUserQuestion:
- "v[X.Y+0.1] (patch)" — Minor update: [suggested name]
- "v[X+1].0 (major)" — Major release
- "Custom" — I'll specify
Update `.planning/PROJECT.md` with new milestone section:
```markdown
**Goal:** [One sentence describing milestone focus]
**Target features:**
```
Update Active requirements section with new goals (keep Validated section intact).
Update "Last updated" footer.
**Commit PROJECT.md:**
```bash
git add .planning/PROJECT.md
git commit -m "$(cat <<'EOF'
docs: start milestone v[X.Y] [Name]
[One-liner describing milestone focus]
EOF
)"
```
Use AskUserQuestion:
- "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:
```bash
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 research
→ Pitfalls research
```
Spawn 4 parallel gsd-project-researcher agents with context:
```
Task(prompt="
<research_type>
Project Research — Stack dimension for [domain].
</research_type>
<milestone_context>
Subsequent milestone (v[X.Y]).
Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
</milestone_context>
<question>
What's needed to add [target features] to [domain]?
</question>
<project_context>
[PROJECT.md summary - core value, validated requirements, new goals]
</project_context>
<downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive:
</downstream_consumer>
<output>
Write to: .planning/research/STACK.md
Use template: .codex/get-shit-done/templates/research-project/STACK.md
</output>
", subagent_type="gsd-project-researcher", description="Stack research")
Task(prompt="
<research_type>
Project Research — Features dimension for [domain].
</research_type>
<milestone_context>
Subsequent milestone (v[X.Y]).
How do [target features] typically work? What's expected behavior?
</milestone_context>
<question>
What features are expected for [target features]?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly:
</downstream_consumer>
<output>
Write to: .planning/research/FEATURES.md
Use template: .codex/get-shit-done/templates/research-project/FEATURES.md
</output>
", subagent_type="gsd-project-researcher", description="Features research")
Task(prompt="
<research_type>
Project Research — Architecture dimension for [domain].
</research_type>
<milestone_context>
Subsequent milestone (v[X.Y]).
How do [target features] integrate with existing [domain] architecture?
</milestone_context>
<question>
How should [target features] integrate with the existing system?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
</downstream_consumer>
<output>
Write to: .planning/research/ARCHITECTURE.md
Use template: .codex/get-shit-done/templates/research-project/ARCHITECTURE.md
</output>
", subagent_type="gsd-project-researcher", description="Architecture research")
Task(prompt="
<research_type>
Project Research — Pitfalls dimension for [domain].
</research_type>
<milestone_context>
Subsequent milestone (v[X.Y]).
What are common mistakes when adding [target features] to [domain]?
</milestone_context>
<question>
What pitfalls should we avoid when adding [target features]?
</question>
<project_context>
[PROJECT.md summary]
</project_context>
<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
</downstream_consumer>
<output>
Write to: .planning/research/PITFALLS.md
Use template: .codex/get-shit-done/templates/research-project/PITFALLS.md
</output>
", subagent_type="gsd-project-researcher", description="Pitfalls research")
```
After all 4 agents complete, spawn synthesizer:
```
Task(prompt="
<task>
Synthesize research outputs into SUMMARY.md.
</task>
<research_files>
Read these files:
</research_files>
<output>
Write to: .planning/research/SUMMARY.md
Use template: .codex/get-shit-done/templates/research-project/SUMMARY.md
Commit after writing.
</output>
", subagent_type="gsd-research-synthesizer", description="Synthesize research")
```
Display research complete:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**Stack:** [from SUMMARY.md]
**Table Stakes:** [from SUMMARY.md]
**Watch Out For:** [from SUMMARY.md]
Files: `.planning/research/`
```
**If "Skip research":** Continue to Phase 7.
Display stage banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Load context:**
Read PROJECT.md and extract:
**If research exists:** Read research/FEATURES.md and extract feature categories.
**Present features by category:**
```
Here are the features for [milestone focus]:
**Table stakes:**
**Differentiators:**
**Research notes:** [any relevant notes]
---
...
```
**If no research:** Gather requirements through conversation instead.
Ask: "What are the main things users need to be able to do in this milestone?"
For each capability mentioned:
**Scope each category:**
For each category, use AskUserQuestion:
- "[Feature 1]" — [brief description]
- "[Feature 2]" — [brief description]
- "None for this milestone" — Defer
Track responses:
**Identify gaps:**
Use AskUserQuestion:
- "No, research covered it" — Proceed
- "Yes, let me add some" — Capture additions
**Validate core value:**
Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
**Generate REQUIREMENTS.md:**
Create `.planning/REQUIREMENTS.md` with:
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
**Requirement quality criteria:**
Good requirements are:
**Present full requirements list for confirmation:**
Show every requirement (not counts) for user confirmation:
```
[... full list ...]
---
Does this capture what you're building? (yes / adjust)
```
If "adjust": Return to scoping.
**Commit requirements:**
```bash
git add .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'
docs: define v[X.Y] requirements
[X] requirements across [N] categories
[Y] requirements deferred to v2
EOF
)"
```
Display stage banner:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► CREATING ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning roadmapper...
```
**Calculate starting phase number:**
```bash
ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1
```
If phases exist: New phases start at last + 1
If no phases: Start at Phase 1
Spawn gsd-roadmapper agent with context:
```
Task(prompt="
<planning_context>
**Project:**
@.planning/PROJECT.md
**Requirements:**
@.planning/REQUIREMENTS.md
**Research (if exists):**
@.planning/research/SUMMARY.md
**Config:**
@.planning/config.json
**Starting phase number:** [N]
</planning_context>
<instructions>
Create roadmap:
1. Derive phases from requirements (don't impose structure)
2. Map every v1 requirement to exactly one phase
3. Derive 2-5 success criteria per phase (observable user behaviors)
4. Validate 100% coverage
5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
6. Return ROADMAP CREATED with summary
Write files first, then return.
</instructions>
", subagent_type="gsd-roadmapper", description="Create roadmap")
```
**Handle roadmapper return:**
**If `## ROADMAP BLOCKED`:**
**If `## ROADMAP CREATED`:**
Read the created ROADMAP.md and present it inline.
**Ask for approval:**
Use AskUserQuestion:
- "Approve" — Commit and continue
- "Adjust phases" — Tell me what to change
- "Review full file" — Show raw ROADMAP.md
**If "Approve":** Continue to commit.
**If "Adjust phases":**
**Commit roadmap:**
```bash
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'
docs: create v[X.Y] roadmap ([N] phases)
Phases:
1. [phase-name]: [requirements covered]
2. [phase-name]: [requirements covered]
...
All v1 requirements mapped to phases.
EOF
)"
```
Present completion with next steps:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GSD ► MILESTONE INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**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 ✓
───────────────────────────────────────────────────────────────
**Phase [N]: [Phase Name]** — [Goal from ROADMAP.md]
`$gsd-discuss-phase [N]` — gather context and clarify approach
<sub>`/clear` first → fresh context window</sub>
---
**Also available:**
───────────────────────────────────────────────────────────────
```
</process>
<output>
- `STACK.md`
- `FEATURES.md`
- `ARCHITECTURE.md`
- `PITFALLS.md`
- `SUMMARY.md`
</output>
<success_criteria>
</success_criteria>
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/gsd-new-milestone/raw