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:
18
CHANGELOG.md
18
CHANGELOG.md
@@ -6,6 +6,24 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|||||||
|
|
||||||
## [Unreleased]
|
## [Unreleased]
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- **Unified `/gsd:new-milestone` flow** — Now mirrors `/gsd:new-project` with questioning → research → requirements → roadmap
|
||||||
|
- **BREAKING:** Removed `/gsd:discuss-milestone` command (consolidated into `/gsd:new-milestone`)
|
||||||
|
- **BREAKING:** Removed `/gsd:create-roadmap` command (integrated into project/milestone flows)
|
||||||
|
- **BREAKING:** Removed `/gsd:define-requirements` command (integrated into project/milestone flows)
|
||||||
|
- **BREAKING:** Removed `/gsd:research-project` command (integrated into project/milestone flows)
|
||||||
|
- Roadmapper agent now references templates instead of inline structures
|
||||||
|
|
||||||
|
### Removed
|
||||||
|
- `commands/gsd/discuss-milestone.md`
|
||||||
|
- `commands/gsd/create-roadmap.md`
|
||||||
|
- `commands/gsd/define-requirements.md`
|
||||||
|
- `commands/gsd/research-project.md`
|
||||||
|
- `get-shit-done/workflows/discuss-milestone.md`
|
||||||
|
- `get-shit-done/workflows/create-roadmap.md`
|
||||||
|
- `get-shit-done/workflows/define-requirements.md`
|
||||||
|
- `get-shit-done/templates/milestone-context.md`
|
||||||
|
|
||||||
## [1.5.30] - 2026-01-17
|
## [1.5.30] - 2026-01-17
|
||||||
|
|
||||||
### Fixed
|
### Fixed
|
||||||
|
|||||||
@@ -374,8 +374,7 @@ You're never locked in. The system adapts.
|
|||||||
|
|
||||||
| Command | What it does |
|
| Command | What it does |
|
||||||
|---------|--------------|
|
|---------|--------------|
|
||||||
| `/gsd:new-milestone [name]` | Start next milestone |
|
| `/gsd:new-milestone [name]` | Start next milestone (questioning → research → requirements → roadmap) |
|
||||||
| `/gsd:discuss-milestone` | Gather context for next milestone |
|
|
||||||
|
|
||||||
### Session
|
### Session
|
||||||
|
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: gsd-project-researcher
|
name: gsd-project-researcher
|
||||||
description: Researches domain ecosystem before roadmap creation. Produces multiple files in .planning/research/ consumed by /gsd:create-roadmap. Spawned by /gsd:research-project orchestrator.
|
description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
|
||||||
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
|
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
|
||||||
color: cyan
|
color: cyan
|
||||||
---
|
---
|
||||||
@@ -10,9 +10,10 @@ You are a GSD project researcher. You research the domain ecosystem before roadm
|
|||||||
|
|
||||||
You are spawned by:
|
You are spawned by:
|
||||||
|
|
||||||
- `/gsd:research-project` orchestrator (project-wide research before roadmap)
|
- `/gsd:new-project` orchestrator (Phase 6: Research)
|
||||||
|
- `/gsd:new-milestone` orchestrator (Phase 6: Research)
|
||||||
|
|
||||||
Your job: Answer "What does this domain ecosystem look like?" Produce multiple research files that inform roadmap creation.
|
Your job: Answer "What does this domain ecosystem look like?" Produce research files that inform roadmap creation.
|
||||||
|
|
||||||
**Core responsibilities:**
|
**Core responsibilities:**
|
||||||
- Survey the domain ecosystem broadly
|
- Survey the domain ecosystem broadly
|
||||||
@@ -25,7 +26,7 @@ Your job: Answer "What does this domain ecosystem look like?" Produce multiple r
|
|||||||
</role>
|
</role>
|
||||||
|
|
||||||
<downstream_consumer>
|
<downstream_consumer>
|
||||||
Your research files are consumed by `/gsd:create-roadmap` which uses them to:
|
Your research files are consumed during roadmap creation:
|
||||||
|
|
||||||
| File | How Roadmap Uses It |
|
| File | How Roadmap Uses It |
|
||||||
|------|---------------------|
|
|------|---------------------|
|
||||||
@@ -807,7 +808,7 @@ When research finishes successfully:
|
|||||||
|
|
||||||
### Ready for Roadmap
|
### Ready for Roadmap
|
||||||
|
|
||||||
Research complete. Run `/gsd:create-roadmap` to create phase structure.
|
Research complete. Proceeding to roadmap creation.
|
||||||
```
|
```
|
||||||
|
|
||||||
## Research Blocked
|
## Research Blocked
|
||||||
|
|||||||
@@ -286,114 +286,23 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
|
|||||||
|
|
||||||
## ROADMAP.md Structure
|
## ROADMAP.md Structure
|
||||||
|
|
||||||
```markdown
|
Use template from `~/.claude/get-shit-done/templates/roadmap.md`.
|
||||||
# Roadmap
|
|
||||||
|
|
||||||
**Project:** [name]
|
Key sections:
|
||||||
**Created:** [date]
|
- Overview (2-3 sentences)
|
||||||
**Phases:** [N]
|
- Phases with Goal, Dependencies, Requirements, Success Criteria
|
||||||
|
- Progress table
|
||||||
## Overview
|
|
||||||
|
|
||||||
[2-3 sentences describing the roadmap approach]
|
|
||||||
|
|
||||||
## Phases
|
|
||||||
|
|
||||||
### Phase 1: [Name]
|
|
||||||
|
|
||||||
**Goal:** [What this phase delivers - outcome, not task]
|
|
||||||
**Depends on:** Nothing (first phase)
|
|
||||||
**Requirements:** [REQ-IDs]
|
|
||||||
|
|
||||||
**Success Criteria:**
|
|
||||||
1. [Observable user behavior]
|
|
||||||
2. [Observable user behavior]
|
|
||||||
3. [Observable user behavior]
|
|
||||||
|
|
||||||
**Plans:** (created by /gsd:plan-phase)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Phase 2: [Name]
|
|
||||||
|
|
||||||
**Goal:** [Outcome]
|
|
||||||
**Depends on:** Phase 1
|
|
||||||
**Requirements:** [REQ-IDs]
|
|
||||||
|
|
||||||
**Success Criteria:**
|
|
||||||
1. [Observable user behavior]
|
|
||||||
2. [Observable user behavior]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[... more phases ...]
|
|
||||||
|
|
||||||
## Progress
|
|
||||||
|
|
||||||
| Phase | Status | Completed |
|
|
||||||
|-------|--------|-----------|
|
|
||||||
| 1 - [Name] | Not started | — |
|
|
||||||
| 2 - [Name] | Not started | — |
|
|
||||||
| 3 - [Name] | Not started | — |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Roadmap for milestone: v1.0*
|
|
||||||
```
|
|
||||||
|
|
||||||
## STATE.md Structure
|
## STATE.md Structure
|
||||||
|
|
||||||
```markdown
|
Use template from `~/.claude/get-shit-done/templates/state.md`.
|
||||||
# Project State
|
|
||||||
|
|
||||||
## Project Reference
|
Key sections:
|
||||||
|
- Project Reference (core value, current focus)
|
||||||
See: .planning/PROJECT.md
|
- Current Position (phase, plan, status, progress bar)
|
||||||
|
- Performance Metrics
|
||||||
**Core value:** [from PROJECT.md]
|
- Accumulated Context (decisions, todos, blockers)
|
||||||
**Current focus:** Phase 1 — [name]
|
- Session Continuity
|
||||||
|
|
||||||
## Current Position
|
|
||||||
|
|
||||||
Phase: 1 of [N] ([name])
|
|
||||||
Plan: Not started
|
|
||||||
Status: Ready to plan
|
|
||||||
Last activity: [date] — Project initialized
|
|
||||||
|
|
||||||
Progress: ░░░░░░░░░░ 0%
|
|
||||||
|
|
||||||
## Performance Metrics
|
|
||||||
|
|
||||||
**Velocity:**
|
|
||||||
- Total plans completed: 0
|
|
||||||
- Average duration: —
|
|
||||||
|
|
||||||
**By Phase:**
|
|
||||||
|
|
||||||
| Phase | Plans | Total | Avg/Plan |
|
|
||||||
|-------|-------|-------|----------|
|
|
||||||
| — | — | — | — |
|
|
||||||
|
|
||||||
## Accumulated Context
|
|
||||||
|
|
||||||
### Decisions
|
|
||||||
|
|
||||||
(None yet)
|
|
||||||
|
|
||||||
### Pending Todos
|
|
||||||
|
|
||||||
(None yet)
|
|
||||||
|
|
||||||
### Blockers/Concerns
|
|
||||||
|
|
||||||
(None yet)
|
|
||||||
|
|
||||||
## Session Continuity
|
|
||||||
|
|
||||||
Last session: [date]
|
|
||||||
Stopped at: Project initialization
|
|
||||||
Resume file: None
|
|
||||||
```
|
|
||||||
|
|
||||||
## Draft Presentation Format
|
## Draft Presentation Format
|
||||||
|
|
||||||
|
|||||||
@@ -108,8 +108,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
|
|||||||
- Ask about pushing tag
|
- Ask about pushing tag
|
||||||
|
|
||||||
8. **Offer next steps:**
|
8. **Offer next steps:**
|
||||||
- `/gsd:discuss-milestone` — thinking partner, creates context file
|
- `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
|
||||||
- Then `/gsd:new-milestone` — update PROJECT.md with new goals
|
|
||||||
|
|
||||||
</process>
|
</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
|
- **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
|
- **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
|
- **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>
|
</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`
|
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
|
### Phase Planning
|
||||||
|
|
||||||
**`/gsd:discuss-phase <number>`**
|
**`/gsd:discuss-phase <number>`**
|
||||||
@@ -171,21 +163,15 @@ Result: Phase 17 deleted, phases 18-20 become 17-19
|
|||||||
|
|
||||||
### Milestone Management
|
### 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>`**
|
**`/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
|
- Deep questioning to understand what you're building next
|
||||||
- Creates phase directories
|
- Optional domain research (spawns 4 parallel researcher agents)
|
||||||
- Updates STATE.md for new milestone
|
- 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"`
|
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: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:**
|
**Capturing ideas during work:**
|
||||||
|
|||||||
@@ -6,23 +6,40 @@ allowed-tools:
|
|||||||
- Read
|
- Read
|
||||||
- Write
|
- Write
|
||||||
- Bash
|
- Bash
|
||||||
|
- Task
|
||||||
- AskUserQuestion
|
- AskUserQuestion
|
||||||
|
- Glob
|
||||||
---
|
---
|
||||||
|
|
||||||
<objective>
|
<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>
|
</objective>
|
||||||
|
|
||||||
<execution_context>
|
<execution_context>
|
||||||
|
|
||||||
@~/.claude/get-shit-done/references/questioning.md
|
@~/.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/project.md
|
||||||
|
@~/.claude/get-shit-done/templates/requirements.md
|
||||||
|
|
||||||
</execution_context>
|
</execution_context>
|
||||||
|
|
||||||
<context>
|
<context>
|
||||||
|
|
||||||
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
||||||
|
|
||||||
**Load project context:**
|
**Load project context:**
|
||||||
@@ -31,111 +48,672 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
|||||||
@.planning/MILESTONES.md
|
@.planning/MILESTONES.md
|
||||||
@.planning/config.json
|
@.planning/config.json
|
||||||
|
|
||||||
**Load milestone context (if exists, from /gsd:discuss-milestone):**
|
|
||||||
@.planning/MILESTONE-CONTEXT.md
|
|
||||||
</context>
|
</context>
|
||||||
|
|
||||||
<process>
|
<process>
|
||||||
|
|
||||||
1. **Load context:**
|
## Phase 1: Validate
|
||||||
- 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:**
|
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
|
||||||
|
|
||||||
**If MILESTONE-CONTEXT.md exists:**
|
1. **Verify project 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:**
|
|
||||||
```bash
|
```bash
|
||||||
git add .planning/PROJECT.md .planning/STATE.md
|
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||||
git commit -m "docs: start milestone v[X.Y] [Name]"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
3. **Load previous milestone context:**
|
||||||
|
```bash
|
||||||
Choose your path:
|
cat .planning/MILESTONES.md 2>/dev/null || echo "NO_MILESTONES"
|
||||||
|
cat .planning/STATE.md
|
||||||
**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>
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## 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>
|
</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>
|
<success_criteria>
|
||||||
- PROJECT.md updated with Current Milestone section
|
|
||||||
- Active requirements reflect new milestone goals
|
- [ ] Project validated (PROJECT.md exists)
|
||||||
- STATE.md reset for new milestone
|
- [ ] Previous milestone context presented
|
||||||
- MILESTONE-CONTEXT.md consumed and deleted (if existed)
|
- [ ] Deep questioning completed (threads followed)
|
||||||
- Git commit made
|
- [ ] Milestone version determined
|
||||||
- User routed to define-requirements (or research-project)
|
- [ ] 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>
|
</success_criteria>
|
||||||
|
|||||||
@@ -323,21 +323,12 @@ Ready to plan the next milestone.
|
|||||||
|
|
||||||
## ▶ Next Up
|
## ▶ 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>
|
<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>
|
|
||||||
@@ -167,18 +167,12 @@ All 4 phases shipped
|
|||||||
|
|
||||||
## ▶ Next Up
|
## ▶ Next Up
|
||||||
|
|
||||||
**Plan v1.1** — Enhanced features and optimizations
|
**Start v1.1** — questioning → research → requirements → roadmap
|
||||||
|
|
||||||
`/gsd:discuss-milestone`
|
`/gsd:new-milestone`
|
||||||
|
|
||||||
<sub>`/clear` first → fresh context window</sub>
|
<sub>`/clear` first → fresh context window</sub>
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Also available:**
|
|
||||||
- `/gsd:new-milestone` — create directly if scope is clear
|
|
||||||
- Review accomplishments before moving on
|
|
||||||
|
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -16,8 +16,9 @@ Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
|
|||||||
|
|
||||||
By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
|
By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
|
||||||
|
|
||||||
- **research-project** needs: what domain to research, what the user already knows, what unknowns exist
|
- **Research** needs: what domain to research, what the user already knows, what unknowns exist
|
||||||
- **create-roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
|
- **Requirements** needs: clear enough vision to scope v1 features
|
||||||
|
- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
|
||||||
- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
|
- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
|
||||||
- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
|
- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
|
||||||
|
|
||||||
|
|||||||
@@ -1,93 +0,0 @@
|
|||||||
# Milestone Context Template
|
|
||||||
|
|
||||||
Template for `.planning/MILESTONE-CONTEXT.md` - temporary handoff file from discuss-milestone to create-milestone.
|
|
||||||
|
|
||||||
**Purpose:** Persist milestone discussion context so `/clear` can be used between commands. This file is consumed by `/gsd:new-milestone` and deleted after the milestone is created.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Template
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Milestone Context
|
|
||||||
|
|
||||||
**Generated:** [date]
|
|
||||||
**Status:** Ready for /gsd:new-milestone
|
|
||||||
|
|
||||||
<features>
|
|
||||||
## Features to Build
|
|
||||||
|
|
||||||
[Features identified during discussion - the substance of this milestone]
|
|
||||||
|
|
||||||
- **[Feature 1]**: [description]
|
|
||||||
- **[Feature 2]**: [description]
|
|
||||||
- **[Feature 3]**: [description]
|
|
||||||
|
|
||||||
</features>
|
|
||||||
|
|
||||||
<scope>
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
**Suggested name:** v[X.Y] [Theme Name]
|
|
||||||
**Estimated phases:** [N]
|
|
||||||
**Focus:** [One sentence theme/focus]
|
|
||||||
|
|
||||||
</scope>
|
|
||||||
|
|
||||||
<phase_mapping>
|
|
||||||
## Phase Mapping
|
|
||||||
|
|
||||||
[How features map to phases - rough breakdown]
|
|
||||||
|
|
||||||
- Phase [N]: [Feature/goal]
|
|
||||||
- Phase [N+1]: [Feature/goal]
|
|
||||||
- Phase [N+2]: [Feature/goal]
|
|
||||||
|
|
||||||
</phase_mapping>
|
|
||||||
|
|
||||||
<constraints>
|
|
||||||
## Constraints
|
|
||||||
|
|
||||||
[Any constraints or boundaries mentioned during discussion]
|
|
||||||
|
|
||||||
- [Constraint 1]
|
|
||||||
- [Constraint 2]
|
|
||||||
|
|
||||||
</constraints>
|
|
||||||
|
|
||||||
<notes>
|
|
||||||
## Additional Context
|
|
||||||
|
|
||||||
[Anything else captured during discussion that informs the milestone]
|
|
||||||
|
|
||||||
</notes>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
|
|
||||||
```
|
|
||||||
|
|
||||||
<guidelines>
|
|
||||||
**This is a handoff artifact, not permanent documentation.**
|
|
||||||
|
|
||||||
The file exists only to pass context from `discuss-milestone` to `create-milestone` across a `/clear` boundary.
|
|
||||||
|
|
||||||
**Lifecycle:**
|
|
||||||
1. `/gsd:discuss-milestone` creates this file at end of discussion
|
|
||||||
2. User runs `/clear` (safe now - context is persisted)
|
|
||||||
3. `/gsd:new-milestone` reads this file
|
|
||||||
4. `/gsd:new-milestone` uses context to populate milestone
|
|
||||||
5. `/gsd:new-milestone` deletes this file after successful creation
|
|
||||||
|
|
||||||
**Content should include:**
|
|
||||||
- Features identified (the core of what to build)
|
|
||||||
- Suggested milestone name/theme
|
|
||||||
- Rough phase mapping
|
|
||||||
- Any constraints or scope boundaries
|
|
||||||
- Notes from discussion
|
|
||||||
|
|
||||||
**Content should NOT include:**
|
|
||||||
- Technical analysis (that comes during phase research)
|
|
||||||
- Detailed phase specifications (create-milestone handles that)
|
|
||||||
- Implementation details
|
|
||||||
</guidelines>
|
|
||||||
@@ -52,7 +52,7 @@ Explicitly excluded. Documented to prevent scope creep.
|
|||||||
|
|
||||||
## Traceability
|
## Traceability
|
||||||
|
|
||||||
Which phases cover which requirements. Updated by create-roadmap.
|
Which phases cover which requirements. Updated during roadmap creation.
|
||||||
|
|
||||||
| Requirement | Phase | Status |
|
| Requirement | Phase | Status |
|
||||||
|-------------|-------|--------|
|
|-------------|-------|--------|
|
||||||
@@ -97,9 +97,9 @@ Which phases cover which requirements. Updated by create-roadmap.
|
|||||||
- Anti-features from research belong here with warnings
|
- Anti-features from research belong here with warnings
|
||||||
|
|
||||||
**Traceability:**
|
**Traceability:**
|
||||||
- Empty initially, populated by create-roadmap
|
- Empty initially, populated during roadmap creation
|
||||||
- Each requirement maps to exactly one phase
|
- Each requirement maps to exactly one phase
|
||||||
- Unmapped requirements = roadmap gap (error in create-roadmap)
|
- Unmapped requirements = roadmap gap
|
||||||
|
|
||||||
**Status Values:**
|
**Status Values:**
|
||||||
- Pending: Not started
|
- Pending: Not started
|
||||||
|
|||||||
@@ -151,7 +151,7 @@ Phases with standard patterns (skip research-phase):
|
|||||||
|
|
||||||
**Implications for Roadmap:**
|
**Implications for Roadmap:**
|
||||||
- This is the most important section
|
- This is the most important section
|
||||||
- Directly informs create-roadmap workflow
|
- Directly informs roadmap creation
|
||||||
- Be explicit about phase suggestions and rationale
|
- Be explicit about phase suggestions and rationale
|
||||||
- Include research flags for each suggested phase
|
- Include research flags for each suggested phase
|
||||||
|
|
||||||
@@ -162,9 +162,9 @@ Phases with standard patterns (skip research-phase):
|
|||||||
- MEDIUM = community consensus, multiple sources agree
|
- MEDIUM = community consensus, multiple sources agree
|
||||||
- LOW = single source or inference
|
- LOW = single source or inference
|
||||||
|
|
||||||
**Integration with create-roadmap:**
|
**Integration with roadmap creation:**
|
||||||
- This file is loaded as @context in create-roadmap
|
- This file is loaded as context during roadmap creation
|
||||||
- Phase suggestions here become starting point for roadmap
|
- Phase suggestions here become starting point for roadmap
|
||||||
- Research flags inform detect_research_needs step
|
- Research flags inform phase planning
|
||||||
|
|
||||||
</guidelines>
|
</guidelines>
|
||||||
|
|||||||
@@ -528,7 +528,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
|
|||||||
✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
|
✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Important:** The next milestone workflow starts with `/gsd:define-requirements` to create a fresh REQUIREMENTS.md. PROJECT.md's Validated section carries the cumulative record across milestones.
|
**Important:** The next milestone workflow starts with `/gsd:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.
|
||||||
|
|
||||||
</step>
|
</step>
|
||||||
|
|
||||||
@@ -681,21 +681,12 @@ Tag: v[X.Y]
|
|||||||
|
|
||||||
## ▶ Next Up
|
## ▶ 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>
|
<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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -754,6 +745,6 @@ Milestone completion is successful when:
|
|||||||
- [ ] STATE.md updated with fresh project reference
|
- [ ] STATE.md updated with fresh project reference
|
||||||
- [ ] Git tag created (v[X.Y])
|
- [ ] Git tag created (v[X.Y])
|
||||||
- [ ] Milestone commit made (includes archive files and deletion)
|
- [ ] Milestone commit made (includes archive files and deletion)
|
||||||
- [ ] User knows next steps (starting with /gsd:define-requirements)
|
- [ ] User knows next step (/gsd:new-milestone)
|
||||||
|
|
||||||
</success_criteria>
|
</success_criteria>
|
||||||
|
|||||||
@@ -1,632 +0,0 @@
|
|||||||
<purpose>
|
|
||||||
Define the phases of implementation. Each phase is a coherent chunk of work
|
|
||||||
that delivers value. Phases map to requirements — every v1 requirement must
|
|
||||||
belong to exactly one phase.
|
|
||||||
|
|
||||||
The roadmap provides structure, not detailed tasks. But it ensures no
|
|
||||||
requirements are orphaned and validates coverage before planning begins.
|
|
||||||
</purpose>
|
|
||||||
|
|
||||||
<required_reading>
|
|
||||||
**Read these files NOW:**
|
|
||||||
|
|
||||||
1. ~/.claude/get-shit-done/templates/roadmap.md
|
|
||||||
2. ~/.claude/get-shit-done/templates/state.md
|
|
||||||
3. ~/.claude/get-shit-done/templates/requirements.md
|
|
||||||
4. .planning/PROJECT.md
|
|
||||||
5. .planning/REQUIREMENTS.md
|
|
||||||
6. .planning/research/SUMMARY.md (if exists)
|
|
||||||
</required_reading>
|
|
||||||
|
|
||||||
<process>
|
|
||||||
|
|
||||||
<step name="load_requirements">
|
|
||||||
Load and parse REQUIREMENTS.md:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cat .planning/REQUIREMENTS.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Extract:
|
|
||||||
- All v1 requirement IDs (AUTH-01, CONT-02, etc.)
|
|
||||||
- Requirement categories (Authentication, Content, Social, etc.)
|
|
||||||
- Total count of v1 requirements
|
|
||||||
|
|
||||||
```
|
|
||||||
Requirements loaded:
|
|
||||||
|
|
||||||
Categories: [N]
|
|
||||||
- Authentication: [X] requirements
|
|
||||||
- Content: [Y] requirements
|
|
||||||
- Social: [Z] requirements
|
|
||||||
...
|
|
||||||
|
|
||||||
Total v1 requirements: [N]
|
|
||||||
|
|
||||||
All requirements must map to exactly one phase.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Track requirement IDs** — will verify coverage after phase identification.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="check_brief">
|
|
||||||
```bash
|
|
||||||
cat .planning/PROJECT.md 2>/dev/null || echo "No brief found"
|
|
||||||
```
|
|
||||||
|
|
||||||
**If no brief exists:**
|
|
||||||
Ask: "No brief found. Want to create one first, or proceed with roadmap?"
|
|
||||||
|
|
||||||
If proceeding without brief, gather quick context:
|
|
||||||
|
|
||||||
- What are we building?
|
|
||||||
- What's the rough scope?
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="load_research">
|
|
||||||
Check for project research:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
|
||||||
```
|
|
||||||
|
|
||||||
**If RESEARCH_EXISTS:**
|
|
||||||
|
|
||||||
Read `.planning/research/SUMMARY.md` and extract:
|
|
||||||
- Suggested phase structure from "Implications for Roadmap" section
|
|
||||||
- Research flags for each suggested phase
|
|
||||||
- Key findings that inform phase ordering
|
|
||||||
|
|
||||||
```
|
|
||||||
Research found. Using findings to inform roadmap:
|
|
||||||
|
|
||||||
Suggested phases from research:
|
|
||||||
1. [Phase from research] — [rationale]
|
|
||||||
2. [Phase from research] — [rationale]
|
|
||||||
3. [Phase from research] — [rationale]
|
|
||||||
|
|
||||||
Research confidence: [HIGH/MEDIUM/LOW]
|
|
||||||
|
|
||||||
Proceeding with research-informed phase identification...
|
|
||||||
```
|
|
||||||
|
|
||||||
**If NO_RESEARCH:**
|
|
||||||
|
|
||||||
Continue without research context. Phase identification will rely on PROJECT.md only.
|
|
||||||
|
|
||||||
**Note:** Research is optional. Roadmap can be created without it, but research-informed roadmaps tend to have better phase structure and fewer surprises.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="identify_phases">
|
|
||||||
Derive phases from requirements. Each phase covers a coherent set of requirements.
|
|
||||||
|
|
||||||
**Primary input: REQUIREMENTS.md**
|
|
||||||
- Group requirements by natural delivery boundaries
|
|
||||||
- Each phase should complete one or more requirement categories
|
|
||||||
- Dependencies between requirements inform phase ordering
|
|
||||||
|
|
||||||
**Secondary inputs:**
|
|
||||||
- Research SUMMARY.md (if exists): suggested phases, architecture patterns
|
|
||||||
|
|
||||||
**Phase identification process:**
|
|
||||||
|
|
||||||
1. Group requirements by category (Authentication, Content, Social, etc.)
|
|
||||||
2. Identify dependencies between categories (Social needs Content, Content needs Auth)
|
|
||||||
3. Create phases that complete entire categories where possible
|
|
||||||
4. Split large categories across phases if needed (e.g., basic auth vs. advanced auth)
|
|
||||||
5. Assign every v1 requirement to exactly one phase
|
|
||||||
|
|
||||||
**For each phase, record:**
|
|
||||||
- Phase name and goal
|
|
||||||
- Which requirement IDs it covers (e.g., AUTH-01, AUTH-02, AUTH-03)
|
|
||||||
- Dependencies on other phases
|
|
||||||
|
|
||||||
**Check depth setting:**
|
|
||||||
```bash
|
|
||||||
cat .planning/config.json 2>/dev/null | grep depth
|
|
||||||
```
|
|
||||||
|
|
||||||
<depth_guidance>
|
|
||||||
**Depth controls compression tolerance, not artificial inflation.**
|
|
||||||
|
|
||||||
| Depth | Typical Phases | Typical Plans/Phase | Tasks/Plan |
|
|
||||||
|-------|----------------|---------------------|------------|
|
|
||||||
| Quick | 3-5 | 1-3 | 2-3 |
|
|
||||||
| Standard | 5-8 | 3-5 | 2-3 |
|
|
||||||
| Comprehensive | 8-12 | 5-10 | 2-3 |
|
|
||||||
|
|
||||||
**Key principle:** Derive phases from actual work. Depth determines how aggressively you combine things, not a target to hit.
|
|
||||||
|
|
||||||
- Comprehensive auth system = 8 phases (because auth genuinely has 8 concerns)
|
|
||||||
- Comprehensive "add favicon" = 1 phase (because that's all it is)
|
|
||||||
|
|
||||||
For comprehensive depth:
|
|
||||||
- Don't compress multiple features into single phases
|
|
||||||
- Each major capability gets its own phase
|
|
||||||
- Let small things stay small—don't pad to hit a number
|
|
||||||
- If you're tempted to combine two things, make them separate phases instead
|
|
||||||
|
|
||||||
For quick depth:
|
|
||||||
- Combine related work aggressively
|
|
||||||
- Focus on critical path only
|
|
||||||
- Defer nice-to-haves to future milestones
|
|
||||||
</depth_guidance>
|
|
||||||
|
|
||||||
**Phase Numbering System:**
|
|
||||||
|
|
||||||
**Calculate starting phase number:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Find highest existing phase number from phases/ directory
|
|
||||||
ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1
|
|
||||||
```
|
|
||||||
|
|
||||||
- If phases/ is empty or doesn't exist: start at Phase 1
|
|
||||||
- If phases exist from previous milestone: continue from last + 1
|
|
||||||
- Example: v1.0 had phases 1-4, v1.1 starts at Phase 5
|
|
||||||
|
|
||||||
Use integer phases (1, 2, 3) for planned milestone work.
|
|
||||||
|
|
||||||
Use decimal phases (2.1, 2.2) for urgent insertions:
|
|
||||||
|
|
||||||
- Decimal phases inserted between integers (2.1 between 2 and 3)
|
|
||||||
- Mark with "(INSERTED)" in phase title
|
|
||||||
- Created when urgent work discovered after planning
|
|
||||||
- Examples: bugfixes, hotfixes, critical patches
|
|
||||||
|
|
||||||
**When to use decimals:**
|
|
||||||
|
|
||||||
- Urgent work that can't wait for next milestone
|
|
||||||
- Critical bugs blocking progress
|
|
||||||
- Security patches needing immediate attention
|
|
||||||
- NOT for scope creep or "nice to haves" (capture with /gsd:add-todo instead)
|
|
||||||
|
|
||||||
**Phase execution order:**
|
|
||||||
Numeric sort: 1 → 1.1 → 1.2 → 2 → 2.1 → 3
|
|
||||||
|
|
||||||
**Deriving phases:**
|
|
||||||
|
|
||||||
1. List all distinct systems/features/capabilities required
|
|
||||||
2. Group related work into coherent deliverables
|
|
||||||
3. Each phase should deliver ONE complete, verifiable thing
|
|
||||||
4. If a phase delivers multiple unrelated capabilities: split it
|
|
||||||
5. If a phase can't stand alone as a complete deliverable: merge it
|
|
||||||
6. Order by dependencies
|
|
||||||
|
|
||||||
Good phases are:
|
|
||||||
|
|
||||||
- **Coherent**: Each delivers one complete, verifiable capability
|
|
||||||
- **Sequential**: Later phases build on earlier
|
|
||||||
- **Independent**: Can be verified and committed on its own
|
|
||||||
|
|
||||||
Common phase patterns:
|
|
||||||
|
|
||||||
- Foundation → Core Feature → Enhancement → Polish
|
|
||||||
- Setup → MVP → Iteration → Launch
|
|
||||||
- Infrastructure → Backend → Frontend → Integration
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="derive_phase_success_criteria">
|
|
||||||
**For each phase, derive what must be TRUE when it completes.**
|
|
||||||
|
|
||||||
This catches scope gaps before planning begins. Requirements tell us what to build; success criteria tell us what users can do.
|
|
||||||
|
|
||||||
**Process for each phase:**
|
|
||||||
|
|
||||||
1. **State the phase goal** (from identify_phases)
|
|
||||||
|
|
||||||
2. **Ask: "What must be TRUE for users when this phase completes?"**
|
|
||||||
- Think from user's perspective, not implementation
|
|
||||||
- 2-5 observable behaviors per phase
|
|
||||||
- Each should be testable/verifiable
|
|
||||||
|
|
||||||
3. **Cross-check against mapped requirements:**
|
|
||||||
- Does each success criterion have at least one requirement supporting it?
|
|
||||||
- Does each requirement contribute to at least one success criterion?
|
|
||||||
|
|
||||||
4. **Flag gaps:**
|
|
||||||
- Success criterion with no supporting requirement → Add requirement or mark as out of scope
|
|
||||||
- Requirement that supports no criterion → Question if it belongs in this phase
|
|
||||||
|
|
||||||
**Example:**
|
|
||||||
|
|
||||||
```
|
|
||||||
Phase 2: Authentication
|
|
||||||
Goal: Users can securely access their accounts
|
|
||||||
|
|
||||||
Success Criteria (what must be TRUE):
|
|
||||||
1. User can create account with email/password
|
|
||||||
2. User can log in and stay logged in across browser sessions
|
|
||||||
3. User can log out from any page
|
|
||||||
4. User can reset forgotten password
|
|
||||||
|
|
||||||
Requirements mapped: AUTH-01, AUTH-02, AUTH-03
|
|
||||||
|
|
||||||
Cross-check:
|
|
||||||
✓ Criterion 1 ← AUTH-01 (create account)
|
|
||||||
✓ Criterion 2 ← AUTH-02 (log in) — but "stay logged in" needs session persistence
|
|
||||||
✓ Criterion 3 ← AUTH-03 (log out)
|
|
||||||
✗ Criterion 4 ← No requirement covers password reset
|
|
||||||
|
|
||||||
Gap found: Password reset not in requirements.
|
|
||||||
→ Add AUTH-04: User can reset password via email
|
|
||||||
OR mark "Password reset" as v2 scope
|
|
||||||
```
|
|
||||||
|
|
||||||
**Present to user:**
|
|
||||||
|
|
||||||
```
|
|
||||||
Phase success criteria derived:
|
|
||||||
|
|
||||||
Phase 1: Foundation
|
|
||||||
Goal: Project scaffolding and configuration
|
|
||||||
Success criteria:
|
|
||||||
1. Project builds without errors
|
|
||||||
2. Development server runs locally
|
|
||||||
3. CI pipeline passes
|
|
||||||
Requirements: SETUP-01, SETUP-02 ✓ (all criteria covered)
|
|
||||||
|
|
||||||
Phase 2: Authentication
|
|
||||||
Goal: Users can securely access their accounts
|
|
||||||
Success criteria:
|
|
||||||
1. User can create account with email/password
|
|
||||||
2. User can log in and stay logged in across sessions
|
|
||||||
3. User can log out from any page
|
|
||||||
4. User can reset forgotten password ⚠️
|
|
||||||
Requirements: AUTH-01, AUTH-02, AUTH-03
|
|
||||||
Gap: Criterion 4 (password reset) has no requirement
|
|
||||||
|
|
||||||
Phase 3: User Profile
|
|
||||||
...
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
⚠️ 1 gap found in Phase 2
|
|
||||||
|
|
||||||
Options:
|
|
||||||
1. Add AUTH-04 for password reset
|
|
||||||
2. Mark password reset as v2 scope
|
|
||||||
3. Adjust success criteria
|
|
||||||
```
|
|
||||||
|
|
||||||
**Resolve all gaps before proceeding.**
|
|
||||||
|
|
||||||
Success criteria flow downstream:
|
|
||||||
- Written to ROADMAP.md (high-level, user-observable)
|
|
||||||
- Inform `must_haves` derivation in plan-phase (concrete artifacts/wiring)
|
|
||||||
- Verified by verify-phase after execution
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="validate_coverage">
|
|
||||||
**Verify all v1 requirements are mapped to exactly one phase.**
|
|
||||||
|
|
||||||
Compare assigned requirements against full list from load_requirements step:
|
|
||||||
|
|
||||||
```
|
|
||||||
Requirement Coverage:
|
|
||||||
|
|
||||||
✓ AUTH-01 → Phase 1
|
|
||||||
✓ AUTH-02 → Phase 1
|
|
||||||
✓ AUTH-03 → Phase 1
|
|
||||||
✓ AUTH-04 → Phase 1
|
|
||||||
✓ PROF-01 → Phase 2
|
|
||||||
✓ PROF-02 → Phase 2
|
|
||||||
...
|
|
||||||
|
|
||||||
Coverage: [X]/[Y] requirements mapped
|
|
||||||
```
|
|
||||||
|
|
||||||
**If any requirements unmapped:**
|
|
||||||
|
|
||||||
```
|
|
||||||
⚠️ Orphaned requirements (not in any phase):
|
|
||||||
|
|
||||||
- NOTF-01: User receives in-app notifications
|
|
||||||
- NOTF-02: User receives email for new followers
|
|
||||||
|
|
||||||
These v1 requirements have no phase. Options:
|
|
||||||
1. Add phase to cover them
|
|
||||||
2. Move to v2 (update REQUIREMENTS.md)
|
|
||||||
3. Assign to existing phase
|
|
||||||
```
|
|
||||||
|
|
||||||
Use AskUserQuestion to resolve orphaned requirements.
|
|
||||||
|
|
||||||
**Do not proceed until coverage = 100%.**
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="confirm_phases">
|
|
||||||
<config-check>
|
|
||||||
```bash
|
|
||||||
cat .planning/config.json 2>/dev/null
|
|
||||||
```
|
|
||||||
Note: Config may not exist yet (project initialization). If missing, default to interactive mode.
|
|
||||||
</config-check>
|
|
||||||
|
|
||||||
<if mode="yolo">
|
|
||||||
```
|
|
||||||
⚡ Auto-approved: Phase breakdown ([N] phases)
|
|
||||||
|
|
||||||
1. [Phase name] - [goal]
|
|
||||||
2. [Phase name] - [goal]
|
|
||||||
3. [Phase name] - [goal]
|
|
||||||
|
|
||||||
Proceeding to research detection...
|
|
||||||
```
|
|
||||||
|
|
||||||
Proceed directly to detect_research_needs step.
|
|
||||||
</if>
|
|
||||||
|
|
||||||
<if mode="interactive" OR="missing OR custom with gates.confirm_phases true">
|
|
||||||
Present the phase breakdown inline:
|
|
||||||
|
|
||||||
"Here's how I'd break this down:
|
|
||||||
|
|
||||||
1. [Phase name] - [goal]
|
|
||||||
2. [Phase name] - [goal]
|
|
||||||
3. [Phase name] - [goal]
|
|
||||||
...
|
|
||||||
|
|
||||||
Does this feel right? (yes / adjust)"
|
|
||||||
|
|
||||||
If "adjust": Ask what to change, revise, present again.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="decision_gate">
|
|
||||||
<if mode="yolo">
|
|
||||||
```
|
|
||||||
⚡ Auto-approved: Create roadmap with [N] phases
|
|
||||||
|
|
||||||
Proceeding to create .planning/ROADMAP.md...
|
|
||||||
```
|
|
||||||
|
|
||||||
Proceed directly to create_structure step.
|
|
||||||
</if>
|
|
||||||
|
|
||||||
<if mode="interactive" OR="missing OR custom with gates.confirm_roadmap true">
|
|
||||||
Use AskUserQuestion:
|
|
||||||
|
|
||||||
- header: "Ready"
|
|
||||||
- question: "Ready to create the roadmap, or would you like me to ask more questions?"
|
|
||||||
- options:
|
|
||||||
- "Create roadmap" - I have enough context
|
|
||||||
- "Ask more questions" - There are details to clarify
|
|
||||||
- "Let me add context" - I want to provide more information
|
|
||||||
|
|
||||||
Loop until "Create roadmap" selected.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="create_structure">
|
|
||||||
```bash
|
|
||||||
mkdir -p .planning/phases
|
|
||||||
```
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="write_roadmap">
|
|
||||||
Use template from `~/.claude/get-shit-done/templates/roadmap.md`.
|
|
||||||
|
|
||||||
Initial roadmaps use integer phases (1, 2, 3...).
|
|
||||||
Decimal phases added later via /gsd:insert-phase command (if it exists).
|
|
||||||
|
|
||||||
Write to `.planning/ROADMAP.md` with:
|
|
||||||
|
|
||||||
- Phase list with names and one-line descriptions
|
|
||||||
- Dependencies (what must complete before what)
|
|
||||||
- **Requirement mappings** (which REQ-IDs each phase covers):
|
|
||||||
```markdown
|
|
||||||
### Phase 1: Authentication
|
|
||||||
**Goal**: Secure user authentication
|
|
||||||
**Depends on**: Nothing (first phase)
|
|
||||||
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
|
|
||||||
```
|
|
||||||
- Status tracking (all start as "not started")
|
|
||||||
|
|
||||||
Create phase directories:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .planning/phases/01-{phase-name}
|
|
||||||
mkdir -p .planning/phases/02-{phase-name}
|
|
||||||
# etc.
|
|
||||||
```
|
|
||||||
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="update_requirements_traceability">
|
|
||||||
Update REQUIREMENTS.md traceability section with phase mappings:
|
|
||||||
|
|
||||||
Read current REQUIREMENTS.md and update the Traceability table:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Traceability
|
|
||||||
|
|
||||||
| Requirement | Phase | Status |
|
|
||||||
|-------------|-------|--------|
|
|
||||||
| AUTH-01 | Phase 1 | Pending |
|
|
||||||
| AUTH-02 | Phase 1 | Pending |
|
|
||||||
| AUTH-03 | Phase 1 | Pending |
|
|
||||||
| AUTH-04 | Phase 1 | Pending |
|
|
||||||
| PROF-01 | Phase 2 | Pending |
|
|
||||||
...
|
|
||||||
|
|
||||||
**Coverage:**
|
|
||||||
- v1 requirements: [X] total
|
|
||||||
- Mapped to phases: [X]
|
|
||||||
- Unmapped: 0 ✓
|
|
||||||
```
|
|
||||||
|
|
||||||
Write updated REQUIREMENTS.md.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="initialize_project_state">
|
|
||||||
|
|
||||||
Create or update STATE.md — the project's living memory.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
[ -f .planning/STATE.md ] && echo "STATE_EXISTS" || echo "NEW_STATE"
|
|
||||||
```
|
|
||||||
|
|
||||||
**If STATE_EXISTS:** Update Current Position and keep Accumulated Context.
|
|
||||||
**If NEW_STATE:** Create fresh using template from `~/.claude/get-shit-done/templates/state.md`.
|
|
||||||
|
|
||||||
Write to `.planning/STATE.md`:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Project State
|
|
||||||
|
|
||||||
## Project Reference
|
|
||||||
|
|
||||||
See: .planning/PROJECT.md (updated [today's date])
|
|
||||||
|
|
||||||
**Core value:** [Copy Core Value from PROJECT.md]
|
|
||||||
**Current focus:** Phase 1 — [First phase name]
|
|
||||||
|
|
||||||
## Current Position
|
|
||||||
|
|
||||||
Phase: 1 of [N] ([First phase name])
|
|
||||||
Plan: Not started
|
|
||||||
Status: Ready to plan
|
|
||||||
Last activity: [today's date] — Project initialized
|
|
||||||
|
|
||||||
Progress: ░░░░░░░░░░ 0%
|
|
||||||
|
|
||||||
## Performance Metrics
|
|
||||||
|
|
||||||
**Velocity:**
|
|
||||||
- Total plans completed: 0
|
|
||||||
- Average duration: —
|
|
||||||
- Total execution time: 0 hours
|
|
||||||
|
|
||||||
**By Phase:**
|
|
||||||
|
|
||||||
| Phase | Plans | Total | Avg/Plan |
|
|
||||||
|-------|-------|-------|----------|
|
|
||||||
| — | — | — | — |
|
|
||||||
|
|
||||||
**Recent Trend:**
|
|
||||||
- Last 5 plans: —
|
|
||||||
- Trend: —
|
|
||||||
|
|
||||||
## Accumulated Context
|
|
||||||
|
|
||||||
### Decisions
|
|
||||||
|
|
||||||
Decisions are logged in PROJECT.md Key Decisions table.
|
|
||||||
Recent decisions affecting current work:
|
|
||||||
|
|
||||||
(None yet)
|
|
||||||
|
|
||||||
### Pending Todos
|
|
||||||
|
|
||||||
None yet.
|
|
||||||
|
|
||||||
### Blockers/Concerns
|
|
||||||
|
|
||||||
None yet.
|
|
||||||
|
|
||||||
## Session Continuity
|
|
||||||
|
|
||||||
Last session: [today's date and time]
|
|
||||||
Stopped at: Project initialization complete
|
|
||||||
Resume file: None
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key points:**
|
|
||||||
|
|
||||||
- Project Reference points to PROJECT.md for full context
|
|
||||||
- Claude reads PROJECT.md directly for requirements, constraints, decisions
|
|
||||||
- This file will be read first in every future operation
|
|
||||||
- This file will be updated after every execution
|
|
||||||
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="git_commit_initialization">
|
|
||||||
Commit roadmap with requirement mappings:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
|
|
||||||
git add .planning/phases/
|
|
||||||
git commit -m "$(cat <<'EOF'
|
|
||||||
docs: create roadmap ([N] phases, [X] requirements)
|
|
||||||
|
|
||||||
[One-liner from PROJECT.md]
|
|
||||||
|
|
||||||
Phases:
|
|
||||||
1. [phase-name]: [requirements covered]
|
|
||||||
2. [phase-name]: [requirements covered]
|
|
||||||
3. [phase-name]: [requirements covered]
|
|
||||||
|
|
||||||
All v1 requirements mapped to phases.
|
|
||||||
EOF
|
|
||||||
)"
|
|
||||||
```
|
|
||||||
|
|
||||||
Confirm: "Committed: docs: create roadmap ([N] phases, [X] requirements)"
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="offer_next">
|
|
||||||
```
|
|
||||||
Project initialized:
|
|
||||||
- Brief: .planning/PROJECT.md
|
|
||||||
- Roadmap: .planning/ROADMAP.md
|
|
||||||
- State: .planning/STATE.md
|
|
||||||
- Committed as: docs: initialize [project] ([N] phases)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ▶ 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>
|
|
||||||
|
|
||||||
<phase_naming>
|
|
||||||
Use `XX-kebab-case-name` format:
|
|
||||||
- `01-foundation`
|
|
||||||
- `02-authentication`
|
|
||||||
- `03-core-features`
|
|
||||||
- `04-polish`
|
|
||||||
|
|
||||||
Numbers ensure ordering. Names describe content.
|
|
||||||
</phase_naming>
|
|
||||||
|
|
||||||
<anti_patterns>
|
|
||||||
- Don't add time estimates
|
|
||||||
- Don't create Gantt charts
|
|
||||||
- Don't add resource allocation
|
|
||||||
- Don't include risk matrices
|
|
||||||
- Don't impose arbitrary phase counts (let the work determine the count)
|
|
||||||
|
|
||||||
Phases are buckets of work, not project management artifacts.
|
|
||||||
</anti_patterns>
|
|
||||||
|
|
||||||
<success_criteria>
|
|
||||||
Roadmap is complete when:
|
|
||||||
- [ ] REQUIREMENTS.md loaded and parsed
|
|
||||||
- [ ] All v1 requirements mapped to exactly one phase (100% coverage)
|
|
||||||
- [ ] **Success criteria derived** for each phase (2-5 observable behaviors)
|
|
||||||
- [ ] **Success criteria cross-checked** against requirements (no gaps)
|
|
||||||
- [ ] `.planning/ROADMAP.md` exists with requirement mappings and success criteria
|
|
||||||
- [ ] `.planning/STATE.md` exists (project memory initialized)
|
|
||||||
- [ ] REQUIREMENTS.md traceability section updated
|
|
||||||
- [ ] Phases defined with clear names (count derived from requirements, not imposed)
|
|
||||||
- [ ] **Research flags assigned** (Likely/Unlikely for each phase)
|
|
||||||
- [ ] **Research topics listed** for Likely phases
|
|
||||||
- [ ] Phase directories created
|
|
||||||
- [ ] Dependencies noted if any
|
|
||||||
- [ ] Status tracking in place
|
|
||||||
</success_criteria>
|
|
||||||
```
|
|
||||||
@@ -1,330 +0,0 @@
|
|||||||
<purpose>
|
|
||||||
Define concrete, checkable requirements for v1.
|
|
||||||
|
|
||||||
Two modes:
|
|
||||||
1. **With research** — Transform FEATURES.md into scoped requirements
|
|
||||||
2. **Without research** — Gather requirements through questioning
|
|
||||||
|
|
||||||
This is the bridge between "what's possible/wanted" and "what we're committing to."
|
|
||||||
</purpose>
|
|
||||||
|
|
||||||
<required_reading>
|
|
||||||
**Read these files NOW:**
|
|
||||||
|
|
||||||
1. ~/.claude/get-shit-done/templates/requirements.md
|
|
||||||
2. .planning/PROJECT.md
|
|
||||||
3. .planning/research/FEATURES.md (if exists)
|
|
||||||
4. .planning/research/SUMMARY.md (if exists)
|
|
||||||
</required_reading>
|
|
||||||
|
|
||||||
<process>
|
|
||||||
|
|
||||||
<step name="detect_mode">
|
|
||||||
Check for research:
|
|
||||||
```bash
|
|
||||||
[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
|
|
||||||
```
|
|
||||||
|
|
||||||
**If HAS_RESEARCH:** Follow steps load_context → present_features → scope_categories
|
|
||||||
**If NO_RESEARCH:** Follow steps load_project → gather_requirements → scope_categories
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="load_context" mode="with_research">
|
|
||||||
Read PROJECT.md and extract:
|
|
||||||
- Core value (the ONE thing that must work)
|
|
||||||
- Stated constraints (budget, timeline, tech limitations)
|
|
||||||
- Any explicit scope boundaries from project definition
|
|
||||||
|
|
||||||
Read research/FEATURES.md and extract:
|
|
||||||
- Table stakes (users expect these)
|
|
||||||
- Differentiators (competitive advantage)
|
|
||||||
- Anti-features (commonly requested, often problematic)
|
|
||||||
- Feature dependencies
|
|
||||||
- MVP vs full product recommendations
|
|
||||||
|
|
||||||
Read research/SUMMARY.md for:
|
|
||||||
- Overall confidence level
|
|
||||||
- Key architectural constraints
|
|
||||||
- Suggested phase structure (informational only)
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="load_project" mode="without_research">
|
|
||||||
Read PROJECT.md and extract:
|
|
||||||
- Core value (the ONE thing that must work)
|
|
||||||
- Stated constraints (budget, timeline, tech limitations)
|
|
||||||
- Any explicit scope boundaries from project definition
|
|
||||||
- Any requirements already mentioned in PROJECT.md
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="gather_requirements" mode="without_research">
|
|
||||||
Since no research exists, gather requirements through conversation.
|
|
||||||
|
|
||||||
**Start with core value:**
|
|
||||||
```
|
|
||||||
Based on PROJECT.md, the core value is: "[core value]"
|
|
||||||
|
|
||||||
What are the main things users need to be able to do?
|
|
||||||
```
|
|
||||||
|
|
||||||
Wait for response. For each capability mentioned:
|
|
||||||
- Ask clarifying questions to make it specific
|
|
||||||
- Probe for related capabilities they might need
|
|
||||||
- Group naturally emerging categories
|
|
||||||
|
|
||||||
**Example flow:**
|
|
||||||
```
|
|
||||||
User: "Users need to create and share posts"
|
|
||||||
|
|
||||||
You: "For posts, what should users be able to include?
|
|
||||||
- Text only?
|
|
||||||
- Images?
|
|
||||||
- Links with previews?
|
|
||||||
|
|
||||||
And for sharing — to a feed, or also direct to other users?"
|
|
||||||
```
|
|
||||||
|
|
||||||
Build up a mental feature list organized by category.
|
|
||||||
|
|
||||||
**When you have enough:**
|
|
||||||
Present gathered features in same format as present_features step, then proceed to scope_categories.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="present_features">
|
|
||||||
Present features grouped by category (from research or gathered through questioning):
|
|
||||||
|
|
||||||
```
|
|
||||||
Here are the features for [domain]:
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
**Table stakes:**
|
|
||||||
- Sign up with email/password
|
|
||||||
- Email verification
|
|
||||||
- Password reset
|
|
||||||
- Session management
|
|
||||||
|
|
||||||
**Differentiators:**
|
|
||||||
- Magic link login
|
|
||||||
- OAuth (Google, GitHub)
|
|
||||||
- 2FA
|
|
||||||
|
|
||||||
**Research notes:** [any relevant notes from FEATURES.md]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## [Next Category]
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
For each category, include:
|
|
||||||
- Table stakes from FEATURES.md
|
|
||||||
- Differentiators from FEATURES.md
|
|
||||||
- Any anti-features flagged (with warnings)
|
|
||||||
- Complexity notes where relevant
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="scope_categories">
|
|
||||||
For each category, use AskUserQuestion:
|
|
||||||
|
|
||||||
- header: "[Category name]"
|
|
||||||
- question: "Which [category] features are in v1?"
|
|
||||||
- multiSelect: true
|
|
||||||
- options:
|
|
||||||
- "[Feature 1]" — [brief description or complexity note]
|
|
||||||
- "[Feature 2]" — [brief description]
|
|
||||||
- "[Feature 3]" — [brief description]
|
|
||||||
- "None for v1" — Defer entire category
|
|
||||||
|
|
||||||
Repeat for each category from research.
|
|
||||||
|
|
||||||
**Track responses:**
|
|
||||||
- Selected features → v1 requirements
|
|
||||||
- Unselected table stakes → flag as v2 (users expect these)
|
|
||||||
- Unselected differentiators → out of scope (unless user specifies v2)
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="identify_gaps">
|
|
||||||
After scoping all researched categories, ask for additions:
|
|
||||||
|
|
||||||
Use AskUserQuestion:
|
|
||||||
- header: "Additions"
|
|
||||||
- question: "Any requirements research missed? (Features specific to your vision)"
|
|
||||||
- options:
|
|
||||||
- "No, research covered it" — Proceed to generate
|
|
||||||
- "Yes, let me add some" — Capture additional requirements
|
|
||||||
|
|
||||||
**If "Yes":**
|
|
||||||
|
|
||||||
Ask inline (freeform): "What additional requirements do you need?"
|
|
||||||
|
|
||||||
Parse response into requirement format and add to v1 list.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="validate_core_value">
|
|
||||||
Cross-check requirements against Core Value from PROJECT.md:
|
|
||||||
|
|
||||||
```
|
|
||||||
Core value: "[from PROJECT.md]"
|
|
||||||
|
|
||||||
Requirements that directly support core value:
|
|
||||||
- [requirement 1]
|
|
||||||
- [requirement 2]
|
|
||||||
|
|
||||||
⚠️ Warning: Core value may not be fully covered by selected requirements.
|
|
||||||
Missing coverage: [gap description]
|
|
||||||
```
|
|
||||||
|
|
||||||
**If gap detected:**
|
|
||||||
|
|
||||||
Use AskUserQuestion:
|
|
||||||
- header: "Core value"
|
|
||||||
- question: "Core value '[X]' may need additional requirements. Add coverage?"
|
|
||||||
- options:
|
|
||||||
- "Yes, suggest requirements" — Claude suggests, user confirms
|
|
||||||
- "No, it's covered" — Proceed
|
|
||||||
- "Adjust core value" — User provides updated core value
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="generate_requirements">
|
|
||||||
Create `.planning/REQUIREMENTS.md` using template.
|
|
||||||
|
|
||||||
**Structure:**
|
|
||||||
- Header with project name and date
|
|
||||||
- v1 Requirements grouped by category (checkboxes)
|
|
||||||
- v2 Requirements (deferred, no checkboxes yet)
|
|
||||||
- Out of Scope (explicit exclusions with reasoning)
|
|
||||||
- Traceability section (empty, filled by create-roadmap)
|
|
||||||
|
|
||||||
**Requirement format:**
|
|
||||||
```markdown
|
|
||||||
### [Category]
|
|
||||||
|
|
||||||
- [ ] **[REQ-ID]**: [Requirement description]
|
|
||||||
- [ ] **[REQ-ID]**: [Requirement description]
|
|
||||||
```
|
|
||||||
|
|
||||||
**REQ-ID format:** `[CATEGORY]-[NUMBER]`
|
|
||||||
- AUTH-01, AUTH-02
|
|
||||||
- CONTENT-01, CONTENT-02
|
|
||||||
- SOCIAL-01, SOCIAL-02
|
|
||||||
|
|
||||||
IDs enable traceability from roadmap phases.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="summarize">
|
|
||||||
Present the FULL requirements list before committing — not counts, the actual requirements:
|
|
||||||
|
|
||||||
```
|
|
||||||
## v1 Requirements
|
|
||||||
|
|
||||||
### [Category 1]
|
|
||||||
- [ ] **[REQ-ID]**: [Full requirement description]
|
|
||||||
- [ ] **[REQ-ID]**: [Full requirement description]
|
|
||||||
- [ ] **[REQ-ID]**: [Full requirement description]
|
|
||||||
|
|
||||||
### [Category 2]
|
|
||||||
- [ ] **[REQ-ID]**: [Full requirement description]
|
|
||||||
- [ ] **[REQ-ID]**: [Full requirement description]
|
|
||||||
|
|
||||||
[... list ALL v1 requirements ...]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## v2 (Deferred)
|
|
||||||
|
|
||||||
### [Category]
|
|
||||||
- [REQ-ID]: [Requirement description]
|
|
||||||
- [REQ-ID]: [Requirement description]
|
|
||||||
|
|
||||||
[... list ALL v2 requirements ...]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Out of Scope
|
|
||||||
|
|
||||||
- [Feature]: [reason]
|
|
||||||
- [Feature]: [reason]
|
|
||||||
|
|
||||||
[... list ALL exclusions ...]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Core Value:** [from PROJECT.md]
|
|
||||||
**Alignment:** ✓ Covered / ⚠️ Gaps noted
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Does this capture what you're building? (yes / adjust)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Critical:** Show every single requirement. The user must see exactly what they're committing to. Counts are useless — list the actual items.
|
|
||||||
|
|
||||||
If "adjust": Return to scope_categories or identify_gaps as appropriate.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="git_commit">
|
|
||||||
Commit requirements:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add .planning/REQUIREMENTS.md
|
|
||||||
git commit -m "$(cat <<'EOF'
|
|
||||||
docs: define v1 requirements
|
|
||||||
|
|
||||||
[X] requirements across [N] categories.
|
|
||||||
[Y] requirements deferred to v2.
|
|
||||||
|
|
||||||
Core value: [from PROJECT.md]
|
|
||||||
EOF
|
|
||||||
)"
|
|
||||||
```
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="offer_next">
|
|
||||||
```
|
|
||||||
Requirements defined:
|
|
||||||
|
|
||||||
- Requirements: .planning/REQUIREMENTS.md
|
|
||||||
- v1 scope: [X] requirements across [N] categories
|
|
||||||
- v2 deferred: [Y] requirements
|
|
||||||
- Out of scope: [Z] exclusions
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ▶ Next Up
|
|
||||||
|
|
||||||
**Create roadmap** — phases mapped to requirements
|
|
||||||
|
|
||||||
`/gsd:create-roadmap`
|
|
||||||
|
|
||||||
<sub>`/clear` first → fresh context window</sub>
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
|
||||||
</step>
|
|
||||||
|
|
||||||
</process>
|
|
||||||
|
|
||||||
<quality_criteria>
|
|
||||||
**Good requirements:**
|
|
||||||
- Specific and testable ("User can reset password via email link")
|
|
||||||
- User-centric ("User can X" not "System does Y")
|
|
||||||
- Atomic (one capability per requirement)
|
|
||||||
- Independent where possible (minimal dependencies)
|
|
||||||
|
|
||||||
**Bad requirements:**
|
|
||||||
- Vague ("Handle authentication")
|
|
||||||
- Technical implementation ("Use bcrypt for passwords")
|
|
||||||
- Compound ("User can login and manage profile and change settings")
|
|
||||||
- Dependent on unstated assumptions
|
|
||||||
</quality_criteria>
|
|
||||||
|
|
||||||
<success_criteria>
|
|
||||||
- [ ] PROJECT.md core value extracted
|
|
||||||
- [ ] Features gathered (from research OR conversation)
|
|
||||||
- [ ] All categories presented to user
|
|
||||||
- [ ] User scoped each category (v1/v2/out of scope)
|
|
||||||
- [ ] User had opportunity to add requirements
|
|
||||||
- [ ] Core value alignment validated
|
|
||||||
- [ ] REQUIREMENTS.md created with REQ-IDs
|
|
||||||
- [ ] v1, v2, and out of scope clearly separated
|
|
||||||
- [ ] Requirements committed to git
|
|
||||||
</success_criteria>
|
|
||||||
@@ -1,227 +0,0 @@
|
|||||||
<purpose>
|
|
||||||
Help the user figure out what they want to build in the next milestone through collaborative thinking.
|
|
||||||
|
|
||||||
You're a thinking partner helping them crystallize their vision for what's next. Features first — everything else (scope, phases) derives from what they want to build.
|
|
||||||
</purpose>
|
|
||||||
|
|
||||||
<process>
|
|
||||||
|
|
||||||
<step name="check_state" priority="first">
|
|
||||||
Load project state:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cat .planning/STATE.md
|
|
||||||
cat .planning/ROADMAP.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**If no active milestone (expected state after completing previous):**
|
|
||||||
Continue to milestone_context.
|
|
||||||
|
|
||||||
**If active milestone exists:**
|
|
||||||
|
|
||||||
```
|
|
||||||
Current milestone in progress: v[X.Y] [Name]
|
|
||||||
Phases [N]-[M], [P]% complete
|
|
||||||
|
|
||||||
Did you want to:
|
|
||||||
1. Complete current milestone first (/gsd:complete-milestone)
|
|
||||||
2. Add phases to current milestone (/gsd:add-phase)
|
|
||||||
3. Continue anyway - discuss next milestone scope
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
Wait for user response. If "Continue anyway", proceed to milestone_context.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="milestone_context">
|
|
||||||
Present context from previous milestone:
|
|
||||||
|
|
||||||
```
|
|
||||||
Last completed: v[X.Y] [Name] (shipped [DATE])
|
|
||||||
Key accomplishments:
|
|
||||||
- [From MILESTONES.md or STATE.md]
|
|
||||||
|
|
||||||
Total phases delivered: [N]
|
|
||||||
Next phase number: [N+1]
|
|
||||||
```
|
|
||||||
|
|
||||||
Continue to intake_gate.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="intake_gate">
|
|
||||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
|
||||||
|
|
||||||
The primary question is: **What do you want to build/add/fix?**
|
|
||||||
|
|
||||||
Everything else (scope, priority, constraints) is secondary and derived from features.
|
|
||||||
|
|
||||||
Check for inputs:
|
|
||||||
- Pending todos from STATE.md (potential features)
|
|
||||||
- Known gaps or pain points from usage
|
|
||||||
- User's ideas for what's next
|
|
||||||
|
|
||||||
**1. Open:**
|
|
||||||
|
|
||||||
Use AskUserQuestion:
|
|
||||||
- header: "Next"
|
|
||||||
- question: "What do you want to add, improve, or fix in this milestone?"
|
|
||||||
- options: [Pending todos from STATE.md if any] + ["New features", "Improvements to existing", "Bug fixes", "Let me describe"]
|
|
||||||
|
|
||||||
**2. Explore features:**
|
|
||||||
|
|
||||||
Based on their response, use AskUserQuestion:
|
|
||||||
|
|
||||||
If they named specific features:
|
|
||||||
- header: "Feature Details"
|
|
||||||
- question: "Tell me more about [feature] - what should it do?"
|
|
||||||
- options: [Contextual options based on feature type + "Let me describe it"]
|
|
||||||
|
|
||||||
If they described a general direction:
|
|
||||||
- header: "Breaking It Down"
|
|
||||||
- question: "That could involve [A], [B], [C] - which matter most?"
|
|
||||||
- options: [Specific sub-features + "All of them" + "Something else"]
|
|
||||||
|
|
||||||
If they're not sure:
|
|
||||||
- header: "Starting Points"
|
|
||||||
- question: "What's been frustrating or missing?"
|
|
||||||
- options: [Pending todos from STATE.md + pain point categories + "Let me think about it"]
|
|
||||||
|
|
||||||
**3. Prioritize:**
|
|
||||||
|
|
||||||
Use AskUserQuestion:
|
|
||||||
- header: "Priority"
|
|
||||||
- question: "Which of these matters most?"
|
|
||||||
- options: [Features they mentioned + "All equally important" + "Let me prioritize"]
|
|
||||||
|
|
||||||
After gathering features, synthesize:
|
|
||||||
|
|
||||||
```
|
|
||||||
Based on what you described:
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- [Feature 1]: [brief description]
|
|
||||||
- [Feature 2]: [brief description]
|
|
||||||
- [Feature 3]: [brief description]
|
|
||||||
|
|
||||||
**Estimated scope:** [N] phases
|
|
||||||
**Theme suggestion:** v[X.Y] [Name]
|
|
||||||
```
|
|
||||||
|
|
||||||
**4. Decision gate:**
|
|
||||||
|
|
||||||
Use AskUserQuestion:
|
|
||||||
- header: "Ready?"
|
|
||||||
- question: "Ready to create the milestone, or explore more?"
|
|
||||||
- options (ALL THREE REQUIRED):
|
|
||||||
- "Create milestone" - Proceed to /gsd:new-milestone
|
|
||||||
- "Ask more questions" - Help me think through this more
|
|
||||||
- "Let me add context" - I have more to share
|
|
||||||
|
|
||||||
If "Ask more questions" → return to step 2 with new probes.
|
|
||||||
If "Let me add context" → receive input → return to step 2.
|
|
||||||
Loop until "Create milestone" selected.
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="write_context">
|
|
||||||
Write milestone context to file for handoff.
|
|
||||||
|
|
||||||
**File:** `.planning/MILESTONE-CONTEXT.md`
|
|
||||||
|
|
||||||
Use template from ~/.claude/get-shit-done/templates/milestone-context.md
|
|
||||||
|
|
||||||
Populate with:
|
|
||||||
- Features identified during discussion
|
|
||||||
- Suggested milestone name and theme
|
|
||||||
- Estimated phase count
|
|
||||||
- How features map to phases
|
|
||||||
- Any constraints or scope boundaries mentioned
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Write the context file
|
|
||||||
cat > .planning/MILESTONE-CONTEXT.md << 'EOF'
|
|
||||||
# Milestone Context
|
|
||||||
|
|
||||||
**Generated:** [today's date]
|
|
||||||
**Status:** Ready for /gsd:new-milestone
|
|
||||||
|
|
||||||
<features>
|
|
||||||
## Features to Build
|
|
||||||
|
|
||||||
- **[Feature 1]**: [description]
|
|
||||||
- **[Feature 2]**: [description]
|
|
||||||
- **[Feature 3]**: [description]
|
|
||||||
|
|
||||||
</features>
|
|
||||||
|
|
||||||
<scope>
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
**Suggested name:** v[X.Y] [Theme Name]
|
|
||||||
**Estimated phases:** [N]
|
|
||||||
**Focus:** [One sentence theme/focus]
|
|
||||||
|
|
||||||
</scope>
|
|
||||||
|
|
||||||
|
|
||||||
<constraints>
|
|
||||||
## Constraints
|
|
||||||
|
|
||||||
- [Any constraints mentioned]
|
|
||||||
|
|
||||||
</constraints>
|
|
||||||
|
|
||||||
<notes>
|
|
||||||
## Additional Context
|
|
||||||
|
|
||||||
[Anything else from discussion]
|
|
||||||
|
|
||||||
</notes>
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
|
|
||||||
EOF
|
|
||||||
```
|
|
||||||
</step>
|
|
||||||
|
|
||||||
<step name="handoff">
|
|
||||||
Present summary and hand off to create-milestone:
|
|
||||||
|
|
||||||
```
|
|
||||||
Milestone scope defined:
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- [Feature 1]: [description]
|
|
||||||
- [Feature 2]: [description]
|
|
||||||
- [Feature 3]: [description]
|
|
||||||
|
|
||||||
**Suggested milestone:** v[X.Y] [Theme Name]
|
|
||||||
|
|
||||||
Context saved to `.planning/MILESTONE-CONTEXT.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ▶ Next Up
|
|
||||||
|
|
||||||
**Create Milestone v[X.Y]** — [Theme Name]
|
|
||||||
|
|
||||||
`/gsd:new-milestone`
|
|
||||||
|
|
||||||
<sub>`/clear` first → fresh context window</sub>
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
|
||||||
</step>
|
|
||||||
|
|
||||||
</process>
|
|
||||||
|
|
||||||
<success_criteria>
|
|
||||||
|
|
||||||
- Project state loaded (STATE.md, MILESTONES.md)
|
|
||||||
- Previous milestone context presented
|
|
||||||
- **Features identified** - What to build/add/fix (the substance)
|
|
||||||
- Features explored with clarifying questions
|
|
||||||
- Scope synthesized from features (not asked abstractly)
|
|
||||||
- **MILESTONE-CONTEXT.md created** with features and scope
|
|
||||||
- Context handed off to /gsd:new-milestone
|
|
||||||
</success_criteria>
|
|
||||||
Reference in New Issue
Block a user