refactor: unify milestone flow, remove deprecated commands
Consolidate /gsd:new-milestone to mirror /gsd:new-project:
- questioning → research (optional) → requirements → roadmap
BREAKING CHANGES:
- Remove /gsd:discuss-milestone (consolidated into new-milestone)
- Remove /gsd:create-roadmap (integrated into project/milestone flows)
- Remove /gsd:define-requirements (integrated into project/milestone flows)
- Remove /gsd:research-project (integrated into project/milestone flows)
Deleted files:
- commands/gsd/{discuss-milestone,create-roadmap,define-requirements,research-project}.md
- get-shit-done/workflows/{discuss-milestone,create-roadmap,define-requirements}.md
- get-shit-done/templates/milestone-context.md
Updated references in:
- progress.md, complete-milestone.md, help.md
- complete-milestone workflow, continuation-format.md
- questioning.md, requirements.md template, SUMMARY.md template
- gsd-project-researcher.md, gsd-roadmapper.md
- README.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -108,8 +108,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
|
||||
- Ask about pushing tag
|
||||
|
||||
8. **Offer next steps:**
|
||||
- `/gsd:discuss-milestone` — thinking partner, creates context file
|
||||
- Then `/gsd:new-milestone` — update PROJECT.md with new goals
|
||||
- `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
|
||||
|
||||
</process>
|
||||
|
||||
@@ -133,5 +132,5 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
|
||||
- **Archive before deleting:** Always create archive files before updating/deleting originals
|
||||
- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
|
||||
- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
|
||||
- **Fresh requirements:** Next milestone starts with `/gsd:define-requirements`, not reusing old file
|
||||
- **Fresh requirements:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition
|
||||
</critical_rules>
|
||||
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
name: gsd:create-roadmap
|
||||
description: Create roadmap with phases for the project
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- Glob
|
||||
- Task
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes roadmap creation as Phase 8,
|
||||
using the gsd-roadmapper agent for heavy lifting.
|
||||
|
||||
This standalone command is kept for users who want to:
|
||||
- Recreate roadmap after significant scope changes
|
||||
- Create roadmap for a project initialized before this integration
|
||||
- Replace an existing roadmap
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Create project roadmap with phase breakdown.
|
||||
|
||||
Roadmaps define what work happens in what order. Phases map to requirements.
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes roadmap creation. Use this command to recreate roadmap later.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/create-roadmap.md
|
||||
@~/.claude/get-shit-done/templates/roadmap.md
|
||||
@~/.claude/get-shit-done/templates/state.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json
|
||||
@.planning/REQUIREMENTS.md
|
||||
@.planning/research/SUMMARY.md (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Verify requirements exist
|
||||
[ -f .planning/REQUIREMENTS.md ] || { echo "ERROR: No REQUIREMENTS.md found. Run /gsd:define-requirements first."; exit 1; }
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if roadmap already exists:
|
||||
|
||||
```bash
|
||||
[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
|
||||
```
|
||||
|
||||
**If ROADMAP_EXISTS:**
|
||||
Use AskUserQuestion:
|
||||
- header: "Roadmap exists"
|
||||
- question: "A roadmap already exists. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" - Show current roadmap
|
||||
- "Replace" - Create new roadmap (will overwrite)
|
||||
- "Cancel" - Keep existing roadmap
|
||||
|
||||
If "View existing": `cat .planning/ROADMAP.md` and exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="create_roadmap">
|
||||
Follow the create-roadmap.md workflow starting from identify_phases step.
|
||||
|
||||
The workflow handles:
|
||||
- Loading requirements
|
||||
- Phase identification mapped to requirements
|
||||
- Requirement coverage validation (no orphaned requirements)
|
||||
- Research flags for each phase
|
||||
- Confirmation gates (respecting config mode)
|
||||
- ROADMAP.md creation with requirement mappings
|
||||
- STATE.md initialization
|
||||
- REQUIREMENTS.md traceability update
|
||||
- Phase directory creation
|
||||
- Git commit
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Roadmap created:
|
||||
- Roadmap: .planning/ROADMAP.md
|
||||
- State: .planning/STATE.md
|
||||
- [N] phases defined
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 1: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:discuss-phase 1` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase 1` — skip discussion, plan directly
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/phases/XX-name/` directories
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] REQUIREMENTS.md validated
|
||||
- [ ] All v1 requirements mapped to phases (no orphans)
|
||||
- [ ] Success criteria derived for each phase (2-5 observable behaviors)
|
||||
- [ ] Success criteria cross-checked against requirements (gaps resolved)
|
||||
- [ ] ROADMAP.md created with phases, requirement mappings, and success criteria
|
||||
- [ ] STATE.md initialized
|
||||
- [ ] REQUIREMENTS.md traceability section updated
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed
|
||||
</success_criteria>
|
||||
@@ -1,134 +0,0 @@
|
||||
---
|
||||
name: gsd:define-requirements
|
||||
description: Define what "done" looks like with checkable requirements
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes requirements definition as Phase 7.
|
||||
This standalone command is kept for users who want to:
|
||||
- Redefine requirements mid-project
|
||||
- Add new requirements after initial project setup
|
||||
- Adjust v1/v2 scope boundaries
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Define concrete, checkable requirements for v1.
|
||||
|
||||
Two modes:
|
||||
1. **With research** — Transform FEATURES.md into scoped requirements
|
||||
2. **Without research** — Gather requirements through questioning
|
||||
|
||||
Output: `.planning/REQUIREMENTS.md`
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes requirements definition. Use this command to redefine requirements later.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/define-requirements.md
|
||||
@~/.claude/get-shit-done/templates/requirements.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/research/FEATURES.md (if exists)
|
||||
@.planning/research/SUMMARY.md (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Check for research
|
||||
[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
|
||||
|
||||
# Check if requirements already exist
|
||||
[ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
**If REQUIREMENTS_EXISTS:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Requirements exist"
|
||||
- question: "Requirements already defined. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" — Show current requirements
|
||||
- "Replace" — Define requirements fresh (will overwrite)
|
||||
- "Cancel" — Keep existing requirements
|
||||
|
||||
If "View existing": Read and display `.planning/REQUIREMENTS.md`, then exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="execute">
|
||||
**If HAS_RESEARCH:**
|
||||
Follow the define-requirements.md workflow:
|
||||
- Load research features from FEATURES.md
|
||||
- Present features by category
|
||||
- Ask user to scope each category (v1 / v2 / out of scope)
|
||||
- Capture any additions research missed
|
||||
- Generate REQUIREMENTS.md with checkable list
|
||||
|
||||
**If NO_RESEARCH:**
|
||||
Gather requirements through questioning:
|
||||
- Read PROJECT.md for core value and context
|
||||
- Ask: "What are the main things users need to be able to do?"
|
||||
- For each capability mentioned, probe for specifics
|
||||
- Group into categories (Authentication, Content, etc.)
|
||||
- For each category, ask what's v1 vs v2 vs out of scope
|
||||
- Generate REQUIREMENTS.md with checkable list
|
||||
|
||||
Same output format either way — the difference is source (research vs conversation).
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Requirements defined:
|
||||
|
||||
- Requirements: .planning/REQUIREMENTS.md
|
||||
- v1 scope: [N] requirements across [M] categories
|
||||
- v2 scope: [X] requirements deferred
|
||||
- Out of scope: [Y] requirements excluded
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create roadmap** — phases mapped to requirements
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] Features gathered (from research OR questioning)
|
||||
- [ ] User scoped each category (v1/v2/out of scope)
|
||||
- [ ] User had opportunity to add missing requirements
|
||||
- [ ] REQUIREMENTS.md created with checkable list
|
||||
- [ ] Requirements committed to git
|
||||
- [ ] User knows next step (create-roadmap)
|
||||
</success_criteria>
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
name: gsd:discuss-milestone
|
||||
description: Gather context for next milestone through adaptive questioning
|
||||
---
|
||||
|
||||
<objective>
|
||||
Help you figure out what to build in the next milestone through collaborative thinking.
|
||||
|
||||
Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
|
||||
Output: Context gathered, then routes to /gsd:new-milestone
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/discuss-milestone.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Load project state first:**
|
||||
@.planning/STATE.md
|
||||
|
||||
**Load project:**
|
||||
@.planning/PROJECT.md
|
||||
|
||||
**Load milestones (if exists):**
|
||||
@.planning/MILESTONES.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Verify previous milestone complete (or acknowledge active milestone)
|
||||
2. Present context from previous milestone (accomplishments, phase count)
|
||||
3. Follow discuss-milestone.md workflow with **ALL questions using AskUserQuestion**:
|
||||
- Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
|
||||
- Use AskUserQuestion to dig into features they mention
|
||||
- Use AskUserQuestion to help them articulate what matters most
|
||||
- Use AskUserQuestion for decision gate (ready / ask more / let me add context)
|
||||
4. Hand off to /gsd:new-milestone with gathered context
|
||||
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Project state loaded and presented
|
||||
- Previous milestone context summarized
|
||||
- Milestone scope gathered through adaptive questioning
|
||||
- Context handed off to /gsd:new-milestone
|
||||
</success_criteria>
|
||||
@@ -76,14 +76,6 @@ Map an existing codebase for brownfield projects.
|
||||
|
||||
Usage: `/gsd:map-codebase`
|
||||
|
||||
### Standalone Commands (deprecated, kept for mid-project use)
|
||||
|
||||
These commands are now integrated into `/gsd:new-project` but remain available for mid-project adjustments:
|
||||
|
||||
**`/gsd:research-project`** — Re-research a domain (integrated into new-project Phase 6)
|
||||
**`/gsd:define-requirements`** — Redefine requirements (integrated into new-project Phase 7)
|
||||
**`/gsd:create-roadmap`** — Recreate roadmap (integrated into new-project Phase 8)
|
||||
|
||||
### Phase Planning
|
||||
|
||||
**`/gsd:discuss-phase <number>`**
|
||||
@@ -171,21 +163,15 @@ Result: Phase 17 deleted, phases 18-20 become 17-19
|
||||
|
||||
### Milestone Management
|
||||
|
||||
**`/gsd:discuss-milestone`**
|
||||
Figure out what you want to build in the next milestone.
|
||||
|
||||
- Reviews what shipped in previous milestone
|
||||
- Helps you identify features to add, improve, or fix
|
||||
- Routes to /gsd:new-milestone when ready
|
||||
|
||||
Usage: `/gsd:discuss-milestone`
|
||||
|
||||
**`/gsd:new-milestone <name>`**
|
||||
Create a new milestone with phases for an existing project.
|
||||
Start a new milestone through unified flow.
|
||||
|
||||
- Adds milestone section to ROADMAP.md
|
||||
- Creates phase directories
|
||||
- Updates STATE.md for new milestone
|
||||
- Deep questioning to understand what you're building next
|
||||
- Optional domain research (spawns 4 parallel researcher agents)
|
||||
- Requirements definition with scoping
|
||||
- Roadmap creation with phase breakdown
|
||||
|
||||
Mirrors `/gsd:new-project` flow for brownfield projects (existing PROJECT.md).
|
||||
|
||||
Usage: `/gsd:new-milestone "v2.0 Features"`
|
||||
|
||||
@@ -366,7 +352,8 @@ Change anytime by editing `.planning/config.json`
|
||||
|
||||
```
|
||||
/gsd:complete-milestone 1.0.0
|
||||
/gsd:new-milestone # Start next milestone
|
||||
/clear
|
||||
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
|
||||
```
|
||||
|
||||
**Capturing ideas during work:**
|
||||
|
||||
@@ -6,23 +6,40 @@ allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
- Glob
|
||||
---
|
||||
|
||||
<objective>
|
||||
Start a new milestone by updating PROJECT.md with new goals, then routing to the requirements → roadmap cycle.
|
||||
|
||||
This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.
|
||||
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
|
||||
- `.planning/phases/` — phase directories
|
||||
|
||||
**After this command:** Run `/gsd:plan-phase [N]` to start execution.
|
||||
|
||||
Output: Updated PROJECT.md, routes to research-project or define-requirements
|
||||
</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:**
|
||||
@@ -31,111 +48,672 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
||||
@.planning/MILESTONES.md
|
||||
@.planning/config.json
|
||||
|
||||
**Load milestone context (if exists, from /gsd:discuss-milestone):**
|
||||
@.planning/MILESTONE-CONTEXT.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
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 1: Validate
|
||||
|
||||
2. **Gather milestone goals:**
|
||||
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
|
||||
|
||||
**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
|
||||
|
||||
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 these sections:
|
||||
|
||||
```markdown
|
||||
## 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.
|
||||
|
||||
5. **Update STATE.md:**
|
||||
|
||||
```markdown
|
||||
## Current Position
|
||||
|
||||
Phase: Not started (run /gsd:create-roadmap)
|
||||
Plan: —
|
||||
Status: Defining requirements
|
||||
Last activity: [today] — Milestone v[X.Y] started
|
||||
```
|
||||
|
||||
Keep Accumulated Context section (decisions, blockers) from previous milestone.
|
||||
|
||||
6. **Cleanup:**
|
||||
- Delete MILESTONE-CONTEXT.md if exists (consumed)
|
||||
|
||||
7. **Git commit:**
|
||||
1. **Verify project exists:**
|
||||
```bash
|
||||
git add .planning/PROJECT.md .planning/STATE.md
|
||||
git commit -m "docs: start milestone v[X.Y] [Name]"
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||
```
|
||||
|
||||
8. **Route to next step:**
|
||||
|
||||
2. **Check for active milestone (ROADMAP.md exists):**
|
||||
```bash
|
||||
[ -f .planning/ROADMAP.md ] && echo "ACTIVE_MILESTONE" || echo "READY_FOR_NEW"
|
||||
```
|
||||
Milestone v[X.Y] [Name] initialized.
|
||||
|
||||
PROJECT.md updated with new goals.
|
||||
**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
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
Choose your path:
|
||||
|
||||
**Option A: Research first** (new domains/capabilities)
|
||||
Research ecosystem before scoping. Discovers patterns, expected features, architecture approaches.
|
||||
|
||||
`/gsd:research-project`
|
||||
|
||||
**Option B: Define requirements directly** (familiar territory)
|
||||
Skip research, define requirements from what you know.
|
||||
|
||||
`/gsd:define-requirements`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
3. **Load previous milestone context:**
|
||||
```bash
|
||||
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:
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
|
||||
```bash
|
||||
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:
|
||||
```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:
|
||||
- Specific libraries with versions
|
||||
- Clear rationale for each choice
|
||||
- What NOT to use and why
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/STACK.md
|
||||
Use template: ~/.claude/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:
|
||||
- Table stakes (must have)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (things to deliberately NOT build)
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/FEATURES.md
|
||||
Use template: ~/.claude/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:
|
||||
- Component boundaries (what talks to what)
|
||||
- Data flow (how information moves)
|
||||
- Suggested build order (dependencies between components)
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/ARCHITECTURE.md
|
||||
Use template: ~/.claude/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:
|
||||
- Warning signs (how to detect early)
|
||||
- Prevention strategy (how to avoid)
|
||||
- Which phase should address it
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/PITFALLS.md
|
||||
Use template: ~/.claude/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:
|
||||
- .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: ~/.claude/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 ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
## Key Findings
|
||||
|
||||
**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.
|
||||
|
||||
## Phase 7: Define Requirements
|
||||
|
||||
Display stage banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DEFINING REQUIREMENTS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
**Load context:**
|
||||
|
||||
Read PROJECT.md and extract:
|
||||
- Core value (the ONE thing that must work)
|
||||
- New milestone goals
|
||||
- Validated requirements (what already works)
|
||||
- Stated constraints
|
||||
|
||||
**If research exists:** Read research/FEATURES.md and extract feature categories.
|
||||
|
||||
**Present features by category:**
|
||||
|
||||
```
|
||||
Here are the features for [milestone focus]:
|
||||
|
||||
## [Category 1]
|
||||
**Table stakes:**
|
||||
- [Feature]
|
||||
- [Feature]
|
||||
|
||||
**Differentiators:**
|
||||
- [Feature]
|
||||
|
||||
**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 in this milestone?"
|
||||
|
||||
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]
|
||||
- "None for this milestone" — Defer
|
||||
|
||||
Track responses:
|
||||
- Selected features → v1 requirements
|
||||
- Unselected table stakes → v2 (users expect these)
|
||||
- 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
|
||||
|
||||
**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:
|
||||
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
|
||||
- v2 Requirements (deferred)
|
||||
- Out of Scope (explicit exclusions with reasoning)
|
||||
- Traceability section (empty, filled by roadmap)
|
||||
|
||||
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
|
||||
|
||||
**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
|
||||
- **Independent:** Minimal dependencies on other requirements
|
||||
|
||||
**Present full requirements list for confirmation:**
|
||||
|
||||
Show every requirement (not counts) for user confirmation:
|
||||
|
||||
```
|
||||
## v1 Requirements
|
||||
|
||||
### [Category]
|
||||
- [ ] **[CAT]-01**: [Requirement description]
|
||||
- [ ] **[CAT]-02**: [Requirement description]
|
||||
|
||||
[... 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
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 8: Create Roadmap
|
||||
|
||||
Display stage banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CREATING ROADMAP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning roadmapper...
|
||||
```
|
||||
|
||||
**Calculate starting phase number:**
|
||||
|
||||
```bash
|
||||
# Find highest existing phase number
|
||||
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, phase directories, 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`:**
|
||||
- Present blocker information
|
||||
- Work with user to resolve
|
||||
- Re-spawn when resolved
|
||||
|
||||
**If `## ROADMAP CREATED`:**
|
||||
|
||||
Read the created ROADMAP.md and present it inline.
|
||||
|
||||
**Ask for approval:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Roadmap"
|
||||
- question: "Does this roadmap structure work for you?"
|
||||
- options:
|
||||
- "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":**
|
||||
- Get user's adjustment notes
|
||||
- Re-spawn roadmapper with revision context
|
||||
- Loop until approved
|
||||
|
||||
**Commit roadmap:**
|
||||
|
||||
```bash
|
||||
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/
|
||||
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
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 9: Done
|
||||
|
||||
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 ✓
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**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:**
|
||||
- `/gsd:plan-phase [N]` — skip discussion, plan directly
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
|
||||
- `.planning/PROJECT.md` (updated)
|
||||
- `.planning/research/` (if research selected)
|
||||
- `STACK.md`
|
||||
- `FEATURES.md`
|
||||
- `ARCHITECTURE.md`
|
||||
- `PITFALLS.md`
|
||||
- `SUMMARY.md`
|
||||
- `.planning/REQUIREMENTS.md`
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/phases/XX-name/` directories
|
||||
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- PROJECT.md updated with Current Milestone section
|
||||
- Active requirements reflect new milestone goals
|
||||
- STATE.md reset for new milestone
|
||||
- MILESTONE-CONTEXT.md consumed and deleted (if existed)
|
||||
- Git commit made
|
||||
- User routed to define-requirements (or research-project)
|
||||
|
||||
- [ ] Project validated (PROJECT.md exists)
|
||||
- [ ] Previous milestone context presented
|
||||
- [ ] Deep questioning completed (threads followed)
|
||||
- [ ] Milestone version determined
|
||||
- [ ] PROJECT.md updated with new milestone goals → **committed**
|
||||
- [ ] Research completed (if selected) → **committed**
|
||||
- [ ] Requirements gathered and scoped
|
||||
- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
|
||||
- [ ] gsd-roadmapper spawned with context
|
||||
- [ ] Roadmap files written immediately
|
||||
- [ ] User feedback incorporated (if any)
|
||||
- [ ] ROADMAP.md, STATE.md, phase directories → **committed**
|
||||
- [ ] User knows next step is `/gsd:plan-phase [N]`
|
||||
|
||||
</success_criteria>
|
||||
|
||||
@@ -323,21 +323,12 @@ Ready to plan the next milestone.
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Discuss Next Milestone** — figure out what to build next
|
||||
**Start Next Milestone** — questioning → research → requirements → roadmap
|
||||
|
||||
`/gsd:discuss-milestone`
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Next milestone flow:**
|
||||
1. `/gsd:discuss-milestone` — thinking partner, creates context file
|
||||
2. `/gsd:new-milestone` — update PROJECT.md with new goals
|
||||
3. `/gsd:research-project` — (optional) research ecosystem
|
||||
4. `/gsd:define-requirements` — scope what to build
|
||||
5. `/gsd:create-roadmap` — plan how to build it
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -1,323 +0,0 @@
|
||||
---
|
||||
name: gsd:research-project
|
||||
description: Research domain ecosystem before creating roadmap
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes optional research as Phase 6.
|
||||
This standalone command is kept for users who want to:
|
||||
- Re-research a domain mid-project
|
||||
- Research without running full new-project flow
|
||||
- Add research after skipping it initially
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Research domain ecosystem. Spawns 4 parallel gsd-project-researcher agents for comprehensive coverage.
|
||||
|
||||
**Orchestrator role:** Analyze project, generate research questions, spawn 4 parallel agents, synthesize SUMMARY.md.
|
||||
|
||||
**Why subagents:** Research burns context fast. Fresh 200k context per domain. Main context stays lean.
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes research as an optional step. Use this command to re-research or add research later.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Validate Prerequisites
|
||||
|
||||
```bash
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||
[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md exists. Research is typically done before roadmap."
|
||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
||||
```
|
||||
|
||||
## 2. Handle Existing Research
|
||||
|
||||
**If RESEARCH_EXISTS:** Use AskUserQuestion (View existing / Replace / Cancel)
|
||||
|
||||
## 3. Analyze Project
|
||||
|
||||
Read PROJECT.md, extract domain/stack/core value/constraints. Present for approval:
|
||||
```
|
||||
Domain analysis:
|
||||
- Type: [domain]
|
||||
- Stack: [stated or TBD]
|
||||
- Core: [core value]
|
||||
Does this look right? (yes / adjust)
|
||||
```
|
||||
|
||||
## 4. Generate Research Questions
|
||||
|
||||
| Dimension | Question |
|
||||
|-----------|----------|
|
||||
| Stack | "What's the standard 2025 stack for [domain]?" |
|
||||
| Features | "What features do [domain] products have?" |
|
||||
| Architecture | "How are [domain] systems structured?" |
|
||||
| Pitfalls | "What do [domain] projects get wrong?" |
|
||||
|
||||
Present for approval.
|
||||
|
||||
## 5. Spawn Research Agents
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
**Determine milestone context:**
|
||||
- If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
|
||||
- If "Validated" requirements exist → Subsequent milestone (v1.1+)
|
||||
|
||||
Spawn all 4 in parallel with rich context:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Stack dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: Research the standard stack for building [domain] from scratch.
|
||||
Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[stack question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your STACK.md feeds into /gsd:create-roadmap. Be prescriptive:
|
||||
- Specific libraries with versions
|
||||
- Clear rationale for each choice
|
||||
- What NOT to use and why
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Versions are current (not Claude's training data)
|
||||
- [ ] Rationale explains WHY, not just WHAT
|
||||
- [ ] Confidence levels assigned
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/STACK.md
|
||||
Use template: ~/.claude/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>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
|
||||
Subsequent: How do [target features] typically work? What's expected behavior?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[features question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your FEATURES.md feeds into /gsd:define-requirements. Categorize clearly:
|
||||
- Table stakes (must have or users leave)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (things to deliberately NOT build)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Categories are clear
|
||||
- [ ] Complexity noted for each
|
||||
- [ ] Dependencies between features identified
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/FEATURES.md
|
||||
Use template: ~/.claude/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>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: How are [domain] systems typically structured? What are major components?
|
||||
Subsequent: How do [target features] integrate with existing [domain] architecture?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[architecture question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
|
||||
- Component boundaries (what talks to what)
|
||||
- Data flow (how information moves)
|
||||
- Suggested build order (dependencies between components)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Components clearly defined
|
||||
- [ ] Boundaries explicit
|
||||
- [ ] Build order implications noted
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/ARCHITECTURE.md
|
||||
Use template: ~/.claude/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>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
|
||||
Subsequent: What are common mistakes when adding [target features] to [domain]?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[pitfalls question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</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, not generic
|
||||
- [ ] Prevention is actionable
|
||||
- [ ] Phase mapping included
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/PITFALLS.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Pitfalls research")
|
||||
```
|
||||
|
||||
**Announce:** "Spawning 4 research agents... may take 2-3 minutes."
|
||||
|
||||
## 6. Synthesize Results
|
||||
|
||||
After all agents complete, read their outputs and write `.planning/research/SUMMARY.md`:
|
||||
- Read template: `~/.claude/get-shit-done/templates/research-project/SUMMARY.md`
|
||||
- Synthesize executive summary from all 4 files
|
||||
- Add confidence assessment
|
||||
|
||||
**Critical: Include "Implications for Roadmap" section:**
|
||||
|
||||
```markdown
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
|
||||
1. **[Phase name]** — [rationale from research]
|
||||
- Addresses: [features from FEATURES.md]
|
||||
- Avoids: [pitfall from PITFALLS.md]
|
||||
- Uses: [stack element from STACK.md]
|
||||
|
||||
2. **[Phase name]** — [rationale from research]
|
||||
- Implements: [architecture component from ARCHITECTURE.md]
|
||||
...
|
||||
|
||||
**Phase ordering rationale:**
|
||||
- [Why this order based on dependencies discovered in ARCHITECTURE.md]
|
||||
- [Why this grouping based on PITFALLS.md prevention strategies]
|
||||
|
||||
**Research flags for phases:**
|
||||
- Phase [X]: Likely needs deeper research (reason)
|
||||
- Phase [Y]: Standard patterns, unlikely to need research
|
||||
```
|
||||
|
||||
This section directly feeds into `/gsd:create-roadmap`.
|
||||
|
||||
## 7. Commit Research
|
||||
|
||||
```bash
|
||||
git add .planning/research/
|
||||
git commit -m "docs: research [domain] ecosystem
|
||||
|
||||
Key findings:
|
||||
- Stack: [one-liner]
|
||||
- Architecture: [one-liner]
|
||||
- Critical pitfall: [one-liner]"
|
||||
```
|
||||
|
||||
## 8. Present Results
|
||||
|
||||
```
|
||||
Research complete:
|
||||
|
||||
Files: SUMMARY.md, STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
|
||||
|
||||
Key findings:
|
||||
- Stack: [one-liner]
|
||||
- Architecture: [one-liner]
|
||||
- Critical pitfall: [one-liner]
|
||||
|
||||
---
|
||||
## > Next Up
|
||||
**Define requirements** - `/gsd:define-requirements`
|
||||
<sub>`/clear` first</sub>
|
||||
---
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] Domain identified and approved
|
||||
- [ ] 4 gsd-project-researcher agents spawned in parallel
|
||||
- [ ] All research files created
|
||||
- [ ] SUMMARY.md synthesized with roadmap implications
|
||||
- [ ] Research committed
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user