refactor: unify milestone flow, remove deprecated commands
Consolidate /gsd:new-milestone to mirror /gsd:new-project:
- questioning → research (optional) → requirements → roadmap
BREAKING CHANGES:
- Remove /gsd:discuss-milestone (consolidated into new-milestone)
- Remove /gsd:create-roadmap (integrated into project/milestone flows)
- Remove /gsd:define-requirements (integrated into project/milestone flows)
- Remove /gsd:research-project (integrated into project/milestone flows)
Deleted files:
- commands/gsd/{discuss-milestone,create-roadmap,define-requirements,research-project}.md
- get-shit-done/workflows/{discuss-milestone,create-roadmap,define-requirements}.md
- get-shit-done/templates/milestone-context.md
Updated references in:
- progress.md, complete-milestone.md, help.md
- complete-milestone workflow, continuation-format.md
- questioning.md, requirements.md template, SUMMARY.md template
- gsd-project-researcher.md, gsd-roadmapper.md
- README.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -528,7 +528,7 @@ Archive requirements and prepare for fresh requirements in 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>
|
||||
|
||||
@@ -681,21 +681,12 @@ Tag: v[X.Y]
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Discuss Next Milestone** — figure out what to build next
|
||||
**Start Next Milestone** — questioning → research → requirements → roadmap
|
||||
|
||||
`/gsd:discuss-milestone`
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Next milestone flow:**
|
||||
1. `/gsd:discuss-milestone` — thinking partner, creates context file
|
||||
2. `/gsd:new-milestone` — update PROJECT.md with new goals
|
||||
3. `/gsd:research-project` — (optional) research ecosystem
|
||||
4. `/gsd:define-requirements` — scope what to build
|
||||
5. `/gsd:create-roadmap` — plan how to build it
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
@@ -754,6 +745,6 @@ Milestone completion is successful when:
|
||||
- [ ] STATE.md updated with fresh project reference
|
||||
- [ ] Git tag created (v[X.Y])
|
||||
- [ ] 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>
|
||||
|
||||
@@ -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