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
18
CHANGELOG.md
18
CHANGELOG.md
@@ -6,6 +6,24 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
## [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
|
||||
|
||||
### Fixed
|
||||
|
||||
@@ -374,8 +374,7 @@ You're never locked in. The system adapts.
|
||||
|
||||
| Command | What it does |
|
||||
|---------|--------------|
|
||||
| `/gsd:new-milestone [name]` | Start next milestone |
|
||||
| `/gsd:discuss-milestone` | Gather context for next milestone |
|
||||
| `/gsd:new-milestone [name]` | Start next milestone (questioning → research → requirements → roadmap) |
|
||||
|
||||
### Session
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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__*
|
||||
color: cyan
|
||||
---
|
||||
@@ -10,9 +10,10 @@ You are a GSD project researcher. You research the domain ecosystem before roadm
|
||||
|
||||
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:**
|
||||
- Survey the domain ecosystem broadly
|
||||
@@ -25,7 +26,7 @@ Your job: Answer "What does this domain ecosystem look like?" Produce multiple r
|
||||
</role>
|
||||
|
||||
<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 |
|
||||
|------|---------------------|
|
||||
@@ -807,7 +808,7 @@ When research finishes successfully:
|
||||
|
||||
### Ready for Roadmap
|
||||
|
||||
Research complete. Run `/gsd:create-roadmap` to create phase structure.
|
||||
Research complete. Proceeding to roadmap creation.
|
||||
```
|
||||
|
||||
## Research Blocked
|
||||
|
||||
@@ -286,114 +286,23 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
|
||||
|
||||
## ROADMAP.md Structure
|
||||
|
||||
```markdown
|
||||
# Roadmap
|
||||
Use template from `~/.claude/get-shit-done/templates/roadmap.md`.
|
||||
|
||||
**Project:** [name]
|
||||
**Created:** [date]
|
||||
**Phases:** [N]
|
||||
|
||||
## 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*
|
||||
```
|
||||
Key sections:
|
||||
- Overview (2-3 sentences)
|
||||
- Phases with Goal, Dependencies, Requirements, Success Criteria
|
||||
- Progress table
|
||||
|
||||
## STATE.md Structure
|
||||
|
||||
```markdown
|
||||
# Project State
|
||||
Use template from `~/.claude/get-shit-done/templates/state.md`.
|
||||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md
|
||||
|
||||
**Core value:** [from PROJECT.md]
|
||||
**Current focus:** Phase 1 — [name]
|
||||
|
||||
## 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
|
||||
```
|
||||
Key sections:
|
||||
- Project Reference (core value, current focus)
|
||||
- Current Position (phase, plan, status, progress bar)
|
||||
- Performance Metrics
|
||||
- Accumulated Context (decisions, todos, blockers)
|
||||
- Session Continuity
|
||||
|
||||
## Draft Presentation Format
|
||||
|
||||
|
||||
@@ -108,8 +108,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
|
||||
- Ask about pushing tag
|
||||
|
||||
8. **Offer next steps:**
|
||||
- `/gsd:discuss-milestone` — thinking partner, creates context file
|
||||
- Then `/gsd:new-milestone` — update PROJECT.md with new goals
|
||||
- `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
|
||||
|
||||
</process>
|
||||
|
||||
@@ -133,5 +132,5 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
|
||||
- **Archive before deleting:** Always create archive files before updating/deleting originals
|
||||
- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
|
||||
- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
|
||||
- **Fresh requirements:** Next milestone starts with `/gsd:define-requirements`, not reusing old file
|
||||
- **Fresh requirements:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition
|
||||
</critical_rules>
|
||||
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
name: gsd:create-roadmap
|
||||
description: Create roadmap with phases for the project
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- AskUserQuestion
|
||||
- Glob
|
||||
- Task
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes roadmap creation as Phase 8,
|
||||
using the gsd-roadmapper agent for heavy lifting.
|
||||
|
||||
This standalone command is kept for users who want to:
|
||||
- Recreate roadmap after significant scope changes
|
||||
- Create roadmap for a project initialized before this integration
|
||||
- Replace an existing roadmap
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Create project roadmap with phase breakdown.
|
||||
|
||||
Roadmaps define what work happens in what order. Phases map to requirements.
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes roadmap creation. Use this command to recreate roadmap later.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/create-roadmap.md
|
||||
@~/.claude/get-shit-done/templates/roadmap.md
|
||||
@~/.claude/get-shit-done/templates/state.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json
|
||||
@.planning/REQUIREMENTS.md
|
||||
@.planning/research/SUMMARY.md (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Verify requirements exist
|
||||
[ -f .planning/REQUIREMENTS.md ] || { echo "ERROR: No REQUIREMENTS.md found. Run /gsd:define-requirements first."; exit 1; }
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
Check if roadmap already exists:
|
||||
|
||||
```bash
|
||||
[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
|
||||
```
|
||||
|
||||
**If ROADMAP_EXISTS:**
|
||||
Use AskUserQuestion:
|
||||
- header: "Roadmap exists"
|
||||
- question: "A roadmap already exists. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" - Show current roadmap
|
||||
- "Replace" - Create new roadmap (will overwrite)
|
||||
- "Cancel" - Keep existing roadmap
|
||||
|
||||
If "View existing": `cat .planning/ROADMAP.md` and exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="create_roadmap">
|
||||
Follow the create-roadmap.md workflow starting from identify_phases step.
|
||||
|
||||
The workflow handles:
|
||||
- Loading requirements
|
||||
- Phase identification mapped to requirements
|
||||
- Requirement coverage validation (no orphaned requirements)
|
||||
- Research flags for each phase
|
||||
- Confirmation gates (respecting config mode)
|
||||
- ROADMAP.md creation with requirement mappings
|
||||
- STATE.md initialization
|
||||
- REQUIREMENTS.md traceability update
|
||||
- Phase directory creation
|
||||
- Git commit
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Roadmap created:
|
||||
- Roadmap: .planning/ROADMAP.md
|
||||
- State: .planning/STATE.md
|
||||
- [N] phases defined
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase 1: [Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:discuss-phase 1` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase 1` — skip discussion, plan directly
|
||||
- Review roadmap
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/phases/XX-name/` directories
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] REQUIREMENTS.md validated
|
||||
- [ ] All v1 requirements mapped to phases (no orphans)
|
||||
- [ ] Success criteria derived for each phase (2-5 observable behaviors)
|
||||
- [ ] Success criteria cross-checked against requirements (gaps resolved)
|
||||
- [ ] ROADMAP.md created with phases, requirement mappings, and success criteria
|
||||
- [ ] STATE.md initialized
|
||||
- [ ] REQUIREMENTS.md traceability section updated
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed
|
||||
</success_criteria>
|
||||
@@ -1,134 +0,0 @@
|
||||
---
|
||||
name: gsd:define-requirements
|
||||
description: Define what "done" looks like with checkable requirements
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes requirements definition as Phase 7.
|
||||
This standalone command is kept for users who want to:
|
||||
- Redefine requirements mid-project
|
||||
- Add new requirements after initial project setup
|
||||
- Adjust v1/v2 scope boundaries
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Define concrete, checkable requirements for v1.
|
||||
|
||||
Two modes:
|
||||
1. **With research** — Transform FEATURES.md into scoped requirements
|
||||
2. **Without research** — Gather requirements through questioning
|
||||
|
||||
Output: `.planning/REQUIREMENTS.md`
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes requirements definition. Use this command to redefine requirements later.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/define-requirements.md
|
||||
@~/.claude/get-shit-done/templates/requirements.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/research/FEATURES.md (if exists)
|
||||
@.planning/research/SUMMARY.md (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="validate">
|
||||
```bash
|
||||
# Verify project exists
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md found. Run /gsd:new-project first."; exit 1; }
|
||||
|
||||
# Check for research
|
||||
[ -f .planning/research/FEATURES.md ] && echo "HAS_RESEARCH" || echo "NO_RESEARCH"
|
||||
|
||||
# Check if requirements already exist
|
||||
[ -f .planning/REQUIREMENTS.md ] && echo "REQUIREMENTS_EXISTS" || echo "NO_REQUIREMENTS"
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing">
|
||||
**If REQUIREMENTS_EXISTS:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Requirements exist"
|
||||
- question: "Requirements already defined. What would you like to do?"
|
||||
- options:
|
||||
- "View existing" — Show current requirements
|
||||
- "Replace" — Define requirements fresh (will overwrite)
|
||||
- "Cancel" — Keep existing requirements
|
||||
|
||||
If "View existing": Read and display `.planning/REQUIREMENTS.md`, then exit
|
||||
If "Cancel": Exit
|
||||
If "Replace": Continue with workflow
|
||||
</step>
|
||||
|
||||
<step name="execute">
|
||||
**If HAS_RESEARCH:**
|
||||
Follow the define-requirements.md workflow:
|
||||
- Load research features from FEATURES.md
|
||||
- Present features by category
|
||||
- Ask user to scope each category (v1 / v2 / out of scope)
|
||||
- Capture any additions research missed
|
||||
- Generate REQUIREMENTS.md with checkable list
|
||||
|
||||
**If NO_RESEARCH:**
|
||||
Gather requirements through questioning:
|
||||
- Read PROJECT.md for core value and context
|
||||
- Ask: "What are the main things users need to be able to do?"
|
||||
- For each capability mentioned, probe for specifics
|
||||
- Group into categories (Authentication, Content, etc.)
|
||||
- For each category, ask what's v1 vs v2 vs out of scope
|
||||
- Generate REQUIREMENTS.md with checkable list
|
||||
|
||||
Same output format either way — the difference is source (research vs conversation).
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
```
|
||||
Requirements defined:
|
||||
|
||||
- Requirements: .planning/REQUIREMENTS.md
|
||||
- v1 scope: [N] requirements across [M] categories
|
||||
- v2 scope: [X] requirements deferred
|
||||
- Out of scope: [Y] requirements excluded
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Create roadmap** — phases mapped to requirements
|
||||
|
||||
`/gsd:create-roadmap`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] Features gathered (from research OR questioning)
|
||||
- [ ] User scoped each category (v1/v2/out of scope)
|
||||
- [ ] User had opportunity to add missing requirements
|
||||
- [ ] REQUIREMENTS.md created with checkable list
|
||||
- [ ] Requirements committed to git
|
||||
- [ ] User knows next step (create-roadmap)
|
||||
</success_criteria>
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
name: gsd:discuss-milestone
|
||||
description: Gather context for next milestone through adaptive questioning
|
||||
---
|
||||
|
||||
<objective>
|
||||
Help you figure out what to build in the next milestone through collaborative thinking.
|
||||
|
||||
Purpose: After completing a milestone, explore what features you want to add, improve, or fix. Features first — scope and phases derive from what you want to build.
|
||||
Output: Context gathered, then routes to /gsd:new-milestone
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/discuss-milestone.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
**Load project state first:**
|
||||
@.planning/STATE.md
|
||||
|
||||
**Load project:**
|
||||
@.planning/PROJECT.md
|
||||
|
||||
**Load milestones (if exists):**
|
||||
@.planning/MILESTONES.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
1. Verify previous milestone complete (or acknowledge active milestone)
|
||||
2. Present context from previous milestone (accomplishments, phase count)
|
||||
3. Follow discuss-milestone.md workflow with **ALL questions using AskUserQuestion**:
|
||||
- Use AskUserQuestion: "What do you want to add, improve, or fix?" with feature categories
|
||||
- Use AskUserQuestion to dig into features they mention
|
||||
- Use AskUserQuestion to help them articulate what matters most
|
||||
- Use AskUserQuestion for decision gate (ready / ask more / let me add context)
|
||||
4. Hand off to /gsd:new-milestone with gathered context
|
||||
|
||||
**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- Project state loaded and presented
|
||||
- Previous milestone context summarized
|
||||
- Milestone scope gathered through adaptive questioning
|
||||
- Context handed off to /gsd:new-milestone
|
||||
</success_criteria>
|
||||
@@ -76,14 +76,6 @@ Map an existing codebase for brownfield projects.
|
||||
|
||||
Usage: `/gsd:map-codebase`
|
||||
|
||||
### Standalone Commands (deprecated, kept for mid-project use)
|
||||
|
||||
These commands are now integrated into `/gsd:new-project` but remain available for mid-project adjustments:
|
||||
|
||||
**`/gsd:research-project`** — Re-research a domain (integrated into new-project Phase 6)
|
||||
**`/gsd:define-requirements`** — Redefine requirements (integrated into new-project Phase 7)
|
||||
**`/gsd:create-roadmap`** — Recreate roadmap (integrated into new-project Phase 8)
|
||||
|
||||
### Phase Planning
|
||||
|
||||
**`/gsd:discuss-phase <number>`**
|
||||
@@ -171,21 +163,15 @@ Result: Phase 17 deleted, phases 18-20 become 17-19
|
||||
|
||||
### Milestone Management
|
||||
|
||||
**`/gsd:discuss-milestone`**
|
||||
Figure out what you want to build in the next milestone.
|
||||
|
||||
- Reviews what shipped in previous milestone
|
||||
- Helps you identify features to add, improve, or fix
|
||||
- Routes to /gsd:new-milestone when ready
|
||||
|
||||
Usage: `/gsd:discuss-milestone`
|
||||
|
||||
**`/gsd:new-milestone <name>`**
|
||||
Create a new milestone with phases for an existing project.
|
||||
Start a new milestone through unified flow.
|
||||
|
||||
- Adds milestone section to ROADMAP.md
|
||||
- Creates phase directories
|
||||
- Updates STATE.md for new milestone
|
||||
- Deep questioning to understand what you're building next
|
||||
- Optional domain research (spawns 4 parallel researcher agents)
|
||||
- Requirements definition with scoping
|
||||
- Roadmap creation with phase breakdown
|
||||
|
||||
Mirrors `/gsd:new-project` flow for brownfield projects (existing PROJECT.md).
|
||||
|
||||
Usage: `/gsd:new-milestone "v2.0 Features"`
|
||||
|
||||
@@ -366,7 +352,8 @@ Change anytime by editing `.planning/config.json`
|
||||
|
||||
```
|
||||
/gsd:complete-milestone 1.0.0
|
||||
/gsd:new-milestone # Start next milestone
|
||||
/clear
|
||||
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
|
||||
```
|
||||
|
||||
**Capturing ideas during work:**
|
||||
|
||||
@@ -6,23 +6,40 @@ allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
- Glob
|
||||
---
|
||||
|
||||
<objective>
|
||||
Start a new milestone by updating PROJECT.md with new goals, then routing to the requirements → roadmap cycle.
|
||||
|
||||
This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.
|
||||
Start a new milestone through unified flow: questioning → research (optional) → requirements → roadmap.
|
||||
|
||||
This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and takes you through the full cycle.
|
||||
|
||||
**Creates/Updates:**
|
||||
- `.planning/PROJECT.md` — updated with new milestone goals
|
||||
- `.planning/research/` — domain research (optional)
|
||||
- `.planning/REQUIREMENTS.md` — scoped requirements
|
||||
- `.planning/ROADMAP.md` — phase structure
|
||||
- `.planning/STATE.md` — updated project memory
|
||||
- `.planning/phases/` — phase directories
|
||||
|
||||
**After this command:** Run `/gsd:plan-phase [N]` to start execution.
|
||||
|
||||
Output: Updated PROJECT.md, routes to research-project or define-requirements
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
|
||||
@~/.claude/get-shit-done/references/questioning.md
|
||||
@~/.claude/get-shit-done/references/ui-brand.md
|
||||
@~/.claude/get-shit-done/templates/project.md
|
||||
@~/.claude/get-shit-done/templates/requirements.md
|
||||
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
|
||||
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
||||
|
||||
**Load project context:**
|
||||
@@ -31,111 +48,672 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
|
||||
@.planning/MILESTONES.md
|
||||
@.planning/config.json
|
||||
|
||||
**Load milestone context (if exists, from /gsd:discuss-milestone):**
|
||||
@.planning/MILESTONE-CONTEXT.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
1. **Load context:**
|
||||
- Read PROJECT.md (existing project, Validated requirements, decisions)
|
||||
- Read MILESTONES.md (what shipped previously)
|
||||
- Read STATE.md (pending todos, blockers)
|
||||
- Check for MILESTONE-CONTEXT.md (from /gsd:discuss-milestone)
|
||||
## Phase 1: Validate
|
||||
|
||||
2. **Gather milestone goals:**
|
||||
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
|
||||
|
||||
**If MILESTONE-CONTEXT.md exists:**
|
||||
- Use features and scope from discuss-milestone
|
||||
- Present summary for confirmation
|
||||
|
||||
**If no context file:**
|
||||
- Present what shipped in last milestone
|
||||
- Ask: "What do you want to build next?"
|
||||
- Use AskUserQuestion to explore features
|
||||
- Probe for priorities, constraints, scope
|
||||
|
||||
3. **Determine milestone version:**
|
||||
- Parse last version from MILESTONES.md
|
||||
- Suggest next version (v1.0 → v1.1, or v2.0 for major)
|
||||
- Confirm with user
|
||||
|
||||
4. **Update PROJECT.md:**
|
||||
|
||||
Add/update these sections:
|
||||
|
||||
```markdown
|
||||
## Current Milestone: v[X.Y] [Name]
|
||||
|
||||
**Goal:** [One sentence describing milestone focus]
|
||||
|
||||
**Target features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
```
|
||||
|
||||
Update Active requirements section with new goals.
|
||||
|
||||
Update "Last updated" footer.
|
||||
|
||||
5. **Update STATE.md:**
|
||||
|
||||
```markdown
|
||||
## Current Position
|
||||
|
||||
Phase: Not started (run /gsd:create-roadmap)
|
||||
Plan: —
|
||||
Status: Defining requirements
|
||||
Last activity: [today] — Milestone v[X.Y] started
|
||||
```
|
||||
|
||||
Keep Accumulated Context section (decisions, blockers) from previous milestone.
|
||||
|
||||
6. **Cleanup:**
|
||||
- Delete MILESTONE-CONTEXT.md if exists (consumed)
|
||||
|
||||
7. **Git commit:**
|
||||
1. **Verify project exists:**
|
||||
```bash
|
||||
git add .planning/PROJECT.md .planning/STATE.md
|
||||
git commit -m "docs: start milestone v[X.Y] [Name]"
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||
```
|
||||
|
||||
8. **Route to next step:**
|
||||
|
||||
2. **Check for active milestone (ROADMAP.md exists):**
|
||||
```bash
|
||||
[ -f .planning/ROADMAP.md ] && echo "ACTIVE_MILESTONE" || echo "READY_FOR_NEW"
|
||||
```
|
||||
Milestone v[X.Y] [Name] initialized.
|
||||
|
||||
PROJECT.md updated with new goals.
|
||||
**If ACTIVE_MILESTONE:**
|
||||
Use AskUserQuestion:
|
||||
- header: "Active Milestone"
|
||||
- question: "A milestone is in progress. What would you like to do?"
|
||||
- options:
|
||||
- "Complete current first" — Run /gsd:complete-milestone
|
||||
- "Continue anyway" — Start new milestone (will archive current)
|
||||
|
||||
---
|
||||
If "Complete current first": Exit with routing to `/gsd:complete-milestone`
|
||||
If "Continue anyway": Continue to Phase 2
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
Choose your path:
|
||||
|
||||
**Option A: Research first** (new domains/capabilities)
|
||||
Research ecosystem before scoping. Discovers patterns, expected features, architecture approaches.
|
||||
|
||||
`/gsd:research-project`
|
||||
|
||||
**Option B: Define requirements directly** (familiar territory)
|
||||
Skip research, define requirements from what you know.
|
||||
|
||||
`/gsd:define-requirements`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
3. **Load previous milestone context:**
|
||||
```bash
|
||||
cat .planning/MILESTONES.md 2>/dev/null || echo "NO_MILESTONES"
|
||||
cat .planning/STATE.md
|
||||
```
|
||||
|
||||
## Phase 2: Present Context
|
||||
|
||||
**Display stage banner:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► NEW MILESTONE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
**Present what shipped:**
|
||||
|
||||
```
|
||||
Last milestone: v[X.Y] [Name] (shipped [DATE])
|
||||
|
||||
Key accomplishments:
|
||||
- [From MILESTONES.md]
|
||||
- [From MILESTONES.md]
|
||||
- [From MILESTONES.md]
|
||||
|
||||
Validated requirements:
|
||||
- [From PROJECT.md Validated section]
|
||||
|
||||
Pending todos:
|
||||
- [From STATE.md if any]
|
||||
```
|
||||
|
||||
## Phase 3: Deep Questioning
|
||||
|
||||
**Display stage banner:**
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► QUESTIONING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
**Open the conversation:**
|
||||
|
||||
Ask inline (freeform, NOT AskUserQuestion):
|
||||
|
||||
"What do you want to build next?"
|
||||
|
||||
Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
|
||||
|
||||
**Follow the thread:**
|
||||
|
||||
Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
|
||||
|
||||
Keep following threads. Each answer opens new threads to explore. Ask about:
|
||||
- What excited them
|
||||
- What problem sparked this
|
||||
- What they mean by vague terms
|
||||
- What it would actually look like
|
||||
- What's already decided
|
||||
|
||||
Consult `questioning.md` for techniques:
|
||||
- Challenge vagueness
|
||||
- Make abstract concrete
|
||||
- Surface assumptions
|
||||
- Find edges
|
||||
- Reveal motivation
|
||||
|
||||
**Decision gate:**
|
||||
|
||||
When you could update PROJECT.md with clear new goals, use AskUserQuestion:
|
||||
|
||||
- header: "Ready?"
|
||||
- question: "I think I understand what you're after. Ready to update PROJECT.md?"
|
||||
- options:
|
||||
- "Update PROJECT.md" — Let's move forward
|
||||
- "Keep exploring" — I want to share more / ask me more
|
||||
|
||||
If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
|
||||
|
||||
Loop until "Update PROJECT.md" selected.
|
||||
|
||||
## Phase 4: Determine Milestone Version
|
||||
|
||||
Parse last version from MILESTONES.md and suggest next:
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Version"
|
||||
- question: "What version is this milestone?"
|
||||
- options:
|
||||
- "v[X.Y+0.1] (patch)" — Minor update: [suggested name]
|
||||
- "v[X+1].0 (major)" — Major release
|
||||
- "Custom" — I'll specify
|
||||
|
||||
## Phase 5: Update PROJECT.md
|
||||
|
||||
Update `.planning/PROJECT.md` with new milestone section:
|
||||
|
||||
```markdown
|
||||
## Current Milestone: v[X.Y] [Name]
|
||||
|
||||
**Goal:** [One sentence describing milestone focus]
|
||||
|
||||
**Target features:**
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
```
|
||||
|
||||
Update Active requirements section with new goals (keep Validated section intact).
|
||||
|
||||
Update "Last updated" footer.
|
||||
|
||||
**Commit PROJECT.md:**
|
||||
|
||||
```bash
|
||||
git add .planning/PROJECT.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: start milestone v[X.Y] [Name]
|
||||
|
||||
[One-liner describing milestone focus]
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 6: Research Decision
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Research"
|
||||
- question: "Research the domain ecosystem before defining requirements?"
|
||||
- options:
|
||||
- "Research first (Recommended)" — Discover patterns, expected features, architecture
|
||||
- "Skip research" — I know this domain well, go straight to requirements
|
||||
|
||||
**If "Research first":**
|
||||
|
||||
Display stage banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCHING
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Researching [domain] ecosystem...
|
||||
```
|
||||
|
||||
Create research directory:
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
**Milestone context is "subsequent"** — Research focuses on new features, not re-researching validated requirements.
|
||||
|
||||
Display spawning indicator:
|
||||
```
|
||||
◆ Spawning 4 researchers in parallel...
|
||||
→ Stack research
|
||||
→ Features research
|
||||
→ Architecture research
|
||||
→ Pitfalls research
|
||||
```
|
||||
|
||||
Spawn 4 parallel gsd-project-researcher agents with context:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Stack dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
Subsequent milestone (v[X.Y]).
|
||||
|
||||
Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
What's needed to add [target features] to [domain]?
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary - core value, validated requirements, new goals]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your STACK.md feeds into roadmap creation. Be prescriptive:
|
||||
- Specific libraries with versions
|
||||
- Clear rationale for each choice
|
||||
- What NOT to use and why
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/STACK.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Stack research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Features dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
Subsequent milestone (v[X.Y]).
|
||||
|
||||
How do [target features] typically work? What's expected behavior?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
What features are expected for [target features]?
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your FEATURES.md feeds into requirements definition. Categorize clearly:
|
||||
- Table stakes (must have)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (things to deliberately NOT build)
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/FEATURES.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Features research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Architecture dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
Subsequent milestone (v[X.Y]).
|
||||
|
||||
How do [target features] integrate with existing [domain] architecture?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
How should [target features] integrate with the existing system?
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
|
||||
- Component boundaries (what talks to what)
|
||||
- Data flow (how information moves)
|
||||
- Suggested build order (dependencies between components)
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/ARCHITECTURE.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Architecture research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Pitfalls dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
Subsequent milestone (v[X.Y]).
|
||||
|
||||
What are common mistakes when adding [target features] to [domain]?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
What pitfalls should we avoid when adding [target features]?
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
|
||||
- Warning signs (how to detect early)
|
||||
- Prevention strategy (how to avoid)
|
||||
- Which phase should address it
|
||||
</downstream_consumer>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/PITFALLS.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Pitfalls research")
|
||||
```
|
||||
|
||||
After all 4 agents complete, spawn synthesizer:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<task>
|
||||
Synthesize research outputs into SUMMARY.md.
|
||||
</task>
|
||||
|
||||
<research_files>
|
||||
Read these files:
|
||||
- .planning/research/STACK.md
|
||||
- .planning/research/FEATURES.md
|
||||
- .planning/research/ARCHITECTURE.md
|
||||
- .planning/research/PITFALLS.md
|
||||
</research_files>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/SUMMARY.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md
|
||||
Commit after writing.
|
||||
</output>
|
||||
", subagent_type="gsd-research-synthesizer", description="Synthesize research")
|
||||
```
|
||||
|
||||
Display research complete:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► RESEARCH COMPLETE ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
## Key Findings
|
||||
|
||||
**Stack:** [from SUMMARY.md]
|
||||
**Table Stakes:** [from SUMMARY.md]
|
||||
**Watch Out For:** [from SUMMARY.md]
|
||||
|
||||
Files: `.planning/research/`
|
||||
```
|
||||
|
||||
**If "Skip research":** Continue to Phase 7.
|
||||
|
||||
## Phase 7: Define Requirements
|
||||
|
||||
Display stage banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► DEFINING REQUIREMENTS
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
**Load context:**
|
||||
|
||||
Read PROJECT.md and extract:
|
||||
- Core value (the ONE thing that must work)
|
||||
- New milestone goals
|
||||
- Validated requirements (what already works)
|
||||
- Stated constraints
|
||||
|
||||
**If research exists:** Read research/FEATURES.md and extract feature categories.
|
||||
|
||||
**Present features by category:**
|
||||
|
||||
```
|
||||
Here are the features for [milestone focus]:
|
||||
|
||||
## [Category 1]
|
||||
**Table stakes:**
|
||||
- [Feature]
|
||||
- [Feature]
|
||||
|
||||
**Differentiators:**
|
||||
- [Feature]
|
||||
|
||||
**Research notes:** [any relevant notes]
|
||||
|
||||
---
|
||||
|
||||
## [Next Category]
|
||||
...
|
||||
```
|
||||
|
||||
**If no research:** Gather requirements through conversation instead.
|
||||
|
||||
Ask: "What are the main things users need to be able to do in this milestone?"
|
||||
|
||||
For each capability mentioned:
|
||||
- Ask clarifying questions to make it specific
|
||||
- Probe for related capabilities
|
||||
- Group into categories
|
||||
|
||||
**Scope each category:**
|
||||
|
||||
For each category, use AskUserQuestion:
|
||||
|
||||
- header: "[Category name]"
|
||||
- question: "Which [category] features are in this milestone?"
|
||||
- multiSelect: true
|
||||
- options:
|
||||
- "[Feature 1]" — [brief description]
|
||||
- "[Feature 2]" — [brief description]
|
||||
- "None for this milestone" — Defer
|
||||
|
||||
Track responses:
|
||||
- Selected features → v1 requirements
|
||||
- Unselected table stakes → v2 (users expect these)
|
||||
- Unselected differentiators → out of scope
|
||||
|
||||
**Identify gaps:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Additions"
|
||||
- question: "Any requirements research missed? (Features specific to your vision)"
|
||||
- options:
|
||||
- "No, research covered it" — Proceed
|
||||
- "Yes, let me add some" — Capture additions
|
||||
|
||||
**Validate core value:**
|
||||
|
||||
Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
|
||||
|
||||
**Generate REQUIREMENTS.md:**
|
||||
|
||||
Create `.planning/REQUIREMENTS.md` with:
|
||||
- v1 Requirements grouped by category (checkboxes, REQ-IDs)
|
||||
- v2 Requirements (deferred)
|
||||
- Out of Scope (explicit exclusions with reasoning)
|
||||
- Traceability section (empty, filled by roadmap)
|
||||
|
||||
**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
|
||||
|
||||
**Requirement quality criteria:**
|
||||
|
||||
Good requirements are:
|
||||
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
|
||||
- **User-centric:** "User can X" (not "System does Y")
|
||||
- **Atomic:** One capability per requirement
|
||||
- **Independent:** Minimal dependencies on other requirements
|
||||
|
||||
**Present full requirements list for confirmation:**
|
||||
|
||||
Show every requirement (not counts) for user confirmation:
|
||||
|
||||
```
|
||||
## v1 Requirements
|
||||
|
||||
### [Category]
|
||||
- [ ] **[CAT]-01**: [Requirement description]
|
||||
- [ ] **[CAT]-02**: [Requirement description]
|
||||
|
||||
[... full list ...]
|
||||
|
||||
---
|
||||
|
||||
Does this capture what you're building? (yes / adjust)
|
||||
```
|
||||
|
||||
If "adjust": Return to scoping.
|
||||
|
||||
**Commit requirements:**
|
||||
|
||||
```bash
|
||||
git add .planning/REQUIREMENTS.md
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: define v[X.Y] requirements
|
||||
|
||||
[X] requirements across [N] categories
|
||||
[Y] requirements deferred to v2
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 8: Create Roadmap
|
||||
|
||||
Display stage banner:
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► CREATING ROADMAP
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
◆ Spawning roadmapper...
|
||||
```
|
||||
|
||||
**Calculate starting phase number:**
|
||||
|
||||
```bash
|
||||
# Find highest existing phase number
|
||||
ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1
|
||||
```
|
||||
|
||||
If phases exist: New phases start at last + 1
|
||||
If no phases: Start at Phase 1
|
||||
|
||||
Spawn gsd-roadmapper agent with context:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<planning_context>
|
||||
|
||||
**Project:**
|
||||
@.planning/PROJECT.md
|
||||
|
||||
**Requirements:**
|
||||
@.planning/REQUIREMENTS.md
|
||||
|
||||
**Research (if exists):**
|
||||
@.planning/research/SUMMARY.md
|
||||
|
||||
**Config:**
|
||||
@.planning/config.json
|
||||
|
||||
**Starting phase number:** [N]
|
||||
|
||||
</planning_context>
|
||||
|
||||
<instructions>
|
||||
Create roadmap:
|
||||
1. Derive phases from requirements (don't impose structure)
|
||||
2. Map every v1 requirement to exactly one phase
|
||||
3. Derive 2-5 success criteria per phase (observable user behaviors)
|
||||
4. Validate 100% coverage
|
||||
5. Write files immediately (ROADMAP.md, STATE.md, phase directories, update REQUIREMENTS.md traceability)
|
||||
6. Return ROADMAP CREATED with summary
|
||||
|
||||
Write files first, then return.
|
||||
</instructions>
|
||||
", subagent_type="gsd-roadmapper", description="Create roadmap")
|
||||
```
|
||||
|
||||
**Handle roadmapper return:**
|
||||
|
||||
**If `## ROADMAP BLOCKED`:**
|
||||
- Present blocker information
|
||||
- Work with user to resolve
|
||||
- Re-spawn when resolved
|
||||
|
||||
**If `## ROADMAP CREATED`:**
|
||||
|
||||
Read the created ROADMAP.md and present it inline.
|
||||
|
||||
**Ask for approval:**
|
||||
|
||||
Use AskUserQuestion:
|
||||
- header: "Roadmap"
|
||||
- question: "Does this roadmap structure work for you?"
|
||||
- options:
|
||||
- "Approve" — Commit and continue
|
||||
- "Adjust phases" — Tell me what to change
|
||||
- "Review full file" — Show raw ROADMAP.md
|
||||
|
||||
**If "Approve":** Continue to commit.
|
||||
|
||||
**If "Adjust phases":**
|
||||
- Get user's adjustment notes
|
||||
- Re-spawn roadmapper with revision context
|
||||
- Loop until approved
|
||||
|
||||
**Commit roadmap:**
|
||||
|
||||
```bash
|
||||
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: create v[X.Y] roadmap ([N] phases)
|
||||
|
||||
Phases:
|
||||
1. [phase-name]: [requirements covered]
|
||||
2. [phase-name]: [requirements covered]
|
||||
...
|
||||
|
||||
All v1 requirements mapped to phases.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
## Phase 9: Done
|
||||
|
||||
Present completion with next steps:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GSD ► MILESTONE INITIALIZED ✓
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**v[X.Y] [Name]**
|
||||
|
||||
| Artifact | Location |
|
||||
|----------------|-----------------------------
|
||||
| Project | `.planning/PROJECT.md` |
|
||||
| Research | `.planning/research/` |
|
||||
| Requirements | `.planning/REQUIREMENTS.md` |
|
||||
| Roadmap | `.planning/ROADMAP.md` |
|
||||
|
||||
**[N] phases** | **[X] requirements** | Ready to build ✓
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Phase [N]: [Phase Name]** — [Goal from ROADMAP.md]
|
||||
|
||||
`/gsd:discuss-phase [N]` — gather context and clarify approach
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:plan-phase [N]` — skip discussion, plan directly
|
||||
|
||||
───────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
|
||||
- `.planning/PROJECT.md` (updated)
|
||||
- `.planning/research/` (if research selected)
|
||||
- `STACK.md`
|
||||
- `FEATURES.md`
|
||||
- `ARCHITECTURE.md`
|
||||
- `PITFALLS.md`
|
||||
- `SUMMARY.md`
|
||||
- `.planning/REQUIREMENTS.md`
|
||||
- `.planning/ROADMAP.md`
|
||||
- `.planning/STATE.md`
|
||||
- `.planning/phases/XX-name/` directories
|
||||
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
- PROJECT.md updated with Current Milestone section
|
||||
- Active requirements reflect new milestone goals
|
||||
- STATE.md reset for new milestone
|
||||
- MILESTONE-CONTEXT.md consumed and deleted (if existed)
|
||||
- Git commit made
|
||||
- User routed to define-requirements (or research-project)
|
||||
|
||||
- [ ] Project validated (PROJECT.md exists)
|
||||
- [ ] Previous milestone context presented
|
||||
- [ ] Deep questioning completed (threads followed)
|
||||
- [ ] Milestone version determined
|
||||
- [ ] PROJECT.md updated with new milestone goals → **committed**
|
||||
- [ ] Research completed (if selected) → **committed**
|
||||
- [ ] Requirements gathered and scoped
|
||||
- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
|
||||
- [ ] gsd-roadmapper spawned with context
|
||||
- [ ] Roadmap files written immediately
|
||||
- [ ] User feedback incorporated (if any)
|
||||
- [ ] ROADMAP.md, STATE.md, phase directories → **committed**
|
||||
- [ ] User knows next step is `/gsd:plan-phase [N]`
|
||||
|
||||
</success_criteria>
|
||||
|
||||
@@ -323,21 +323,12 @@ Ready to plan the next milestone.
|
||||
|
||||
## ▶ Next Up
|
||||
|
||||
**Discuss Next Milestone** — figure out what to build next
|
||||
**Start Next Milestone** — questioning → research → requirements → roadmap
|
||||
|
||||
`/gsd:discuss-milestone`
|
||||
`/gsd:new-milestone`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
|
||||
---
|
||||
|
||||
**Next milestone flow:**
|
||||
1. `/gsd:discuss-milestone` — thinking partner, creates context file
|
||||
2. `/gsd:new-milestone` — update PROJECT.md with new goals
|
||||
3. `/gsd:research-project` — (optional) research ecosystem
|
||||
4. `/gsd:define-requirements` — scope what to build
|
||||
5. `/gsd:create-roadmap` — plan how to build it
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
|
||||
@@ -1,323 +0,0 @@
|
||||
---
|
||||
name: gsd:research-project
|
||||
description: Research domain ecosystem before creating roadmap
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash
|
||||
- Task
|
||||
- AskUserQuestion
|
||||
---
|
||||
|
||||
<!--
|
||||
DEPRECATED: This command is now integrated into /gsd:new-project
|
||||
|
||||
The unified /gsd:new-project flow includes optional research as Phase 6.
|
||||
This standalone command is kept for users who want to:
|
||||
- Re-research a domain mid-project
|
||||
- Research without running full new-project flow
|
||||
- Add research after skipping it initially
|
||||
|
||||
For new projects, use /gsd:new-project instead.
|
||||
|
||||
Deprecated: 2026-01-16
|
||||
-->
|
||||
|
||||
<objective>
|
||||
Research domain ecosystem. Spawns 4 parallel gsd-project-researcher agents for comprehensive coverage.
|
||||
|
||||
**Orchestrator role:** Analyze project, generate research questions, spawn 4 parallel agents, synthesize SUMMARY.md.
|
||||
|
||||
**Why subagents:** Research burns context fast. Fresh 200k context per domain. Main context stays lean.
|
||||
|
||||
**Note:** For new projects, `/gsd:new-project` includes research as an optional step. Use this command to re-research or add research later.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/config.json (if exists)
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Validate Prerequisites
|
||||
|
||||
```bash
|
||||
[ -f .planning/PROJECT.md ] || { echo "ERROR: No PROJECT.md. Run /gsd:new-project first."; exit 1; }
|
||||
[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md exists. Research is typically done before roadmap."
|
||||
[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
|
||||
```
|
||||
|
||||
## 2. Handle Existing Research
|
||||
|
||||
**If RESEARCH_EXISTS:** Use AskUserQuestion (View existing / Replace / Cancel)
|
||||
|
||||
## 3. Analyze Project
|
||||
|
||||
Read PROJECT.md, extract domain/stack/core value/constraints. Present for approval:
|
||||
```
|
||||
Domain analysis:
|
||||
- Type: [domain]
|
||||
- Stack: [stated or TBD]
|
||||
- Core: [core value]
|
||||
Does this look right? (yes / adjust)
|
||||
```
|
||||
|
||||
## 4. Generate Research Questions
|
||||
|
||||
| Dimension | Question |
|
||||
|-----------|----------|
|
||||
| Stack | "What's the standard 2025 stack for [domain]?" |
|
||||
| Features | "What features do [domain] products have?" |
|
||||
| Architecture | "How are [domain] systems structured?" |
|
||||
| Pitfalls | "What do [domain] projects get wrong?" |
|
||||
|
||||
Present for approval.
|
||||
|
||||
## 5. Spawn Research Agents
|
||||
|
||||
```bash
|
||||
mkdir -p .planning/research
|
||||
```
|
||||
|
||||
**Determine milestone context:**
|
||||
- If no "Validated" requirements in REQUIREMENTS.md → Greenfield (v1.0)
|
||||
- If "Validated" requirements exist → Subsequent milestone (v1.1+)
|
||||
|
||||
Spawn all 4 in parallel with rich context:
|
||||
|
||||
```
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Stack dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: Research the standard stack for building [domain] from scratch.
|
||||
Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[stack question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your STACK.md feeds into /gsd:create-roadmap. Be prescriptive:
|
||||
- Specific libraries with versions
|
||||
- Clear rationale for each choice
|
||||
- What NOT to use and why
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Versions are current (not Claude's training data)
|
||||
- [ ] Rationale explains WHY, not just WHAT
|
||||
- [ ] Confidence levels assigned
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/STACK.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Stack research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Features dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
|
||||
Subsequent: How do [target features] typically work? What's expected behavior?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[features question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your FEATURES.md feeds into /gsd:define-requirements. Categorize clearly:
|
||||
- Table stakes (must have or users leave)
|
||||
- Differentiators (competitive advantage)
|
||||
- Anti-features (things to deliberately NOT build)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Categories are clear
|
||||
- [ ] Complexity noted for each
|
||||
- [ ] Dependencies between features identified
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/FEATURES.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Features research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Architecture dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: How are [domain] systems typically structured? What are major components?
|
||||
Subsequent: How do [target features] integrate with existing [domain] architecture?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[architecture question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
|
||||
- Component boundaries (what talks to what)
|
||||
- Data flow (how information moves)
|
||||
- Suggested build order (dependencies between components)
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Components clearly defined
|
||||
- [ ] Boundaries explicit
|
||||
- [ ] Build order implications noted
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/ARCHITECTURE.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Architecture research")
|
||||
|
||||
Task(prompt="
|
||||
<research_type>
|
||||
Project Research — Pitfalls dimension for [domain].
|
||||
</research_type>
|
||||
|
||||
<milestone_context>
|
||||
{greenfield OR subsequent}
|
||||
|
||||
Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
|
||||
Subsequent: What are common mistakes when adding [target features] to [domain]?
|
||||
</milestone_context>
|
||||
|
||||
<question>
|
||||
[pitfalls question from step 4]
|
||||
</question>
|
||||
|
||||
<project_context>
|
||||
[PROJECT.md summary]
|
||||
</project_context>
|
||||
|
||||
<downstream_consumer>
|
||||
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
|
||||
- Warning signs (how to detect early)
|
||||
- Prevention strategy (how to avoid)
|
||||
- Which phase should address it
|
||||
</downstream_consumer>
|
||||
|
||||
<quality_gate>
|
||||
- [ ] Pitfalls are specific, not generic
|
||||
- [ ] Prevention is actionable
|
||||
- [ ] Phase mapping included
|
||||
</quality_gate>
|
||||
|
||||
<output>
|
||||
Write to: .planning/research/PITFALLS.md
|
||||
Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md
|
||||
</output>
|
||||
", subagent_type="gsd-project-researcher", description="Pitfalls research")
|
||||
```
|
||||
|
||||
**Announce:** "Spawning 4 research agents... may take 2-3 minutes."
|
||||
|
||||
## 6. Synthesize Results
|
||||
|
||||
After all agents complete, read their outputs and write `.planning/research/SUMMARY.md`:
|
||||
- Read template: `~/.claude/get-shit-done/templates/research-project/SUMMARY.md`
|
||||
- Synthesize executive summary from all 4 files
|
||||
- Add confidence assessment
|
||||
|
||||
**Critical: Include "Implications for Roadmap" section:**
|
||||
|
||||
```markdown
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
|
||||
1. **[Phase name]** — [rationale from research]
|
||||
- Addresses: [features from FEATURES.md]
|
||||
- Avoids: [pitfall from PITFALLS.md]
|
||||
- Uses: [stack element from STACK.md]
|
||||
|
||||
2. **[Phase name]** — [rationale from research]
|
||||
- Implements: [architecture component from ARCHITECTURE.md]
|
||||
...
|
||||
|
||||
**Phase ordering rationale:**
|
||||
- [Why this order based on dependencies discovered in ARCHITECTURE.md]
|
||||
- [Why this grouping based on PITFALLS.md prevention strategies]
|
||||
|
||||
**Research flags for phases:**
|
||||
- Phase [X]: Likely needs deeper research (reason)
|
||||
- Phase [Y]: Standard patterns, unlikely to need research
|
||||
```
|
||||
|
||||
This section directly feeds into `/gsd:create-roadmap`.
|
||||
|
||||
## 7. Commit Research
|
||||
|
||||
```bash
|
||||
git add .planning/research/
|
||||
git commit -m "docs: research [domain] ecosystem
|
||||
|
||||
Key findings:
|
||||
- Stack: [one-liner]
|
||||
- Architecture: [one-liner]
|
||||
- Critical pitfall: [one-liner]"
|
||||
```
|
||||
|
||||
## 8. Present Results
|
||||
|
||||
```
|
||||
Research complete:
|
||||
|
||||
Files: SUMMARY.md, STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
|
||||
|
||||
Key findings:
|
||||
- Stack: [one-liner]
|
||||
- Architecture: [one-liner]
|
||||
- Critical pitfall: [one-liner]
|
||||
|
||||
---
|
||||
## > Next Up
|
||||
**Define requirements** - `/gsd:define-requirements`
|
||||
<sub>`/clear` first</sub>
|
||||
---
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] PROJECT.md validated
|
||||
- [ ] Domain identified and approved
|
||||
- [ ] 4 gsd-project-researcher agents spawned in parallel
|
||||
- [ ] All research files created
|
||||
- [ ] SUMMARY.md synthesized with roadmap implications
|
||||
- [ ] Research committed
|
||||
</success_criteria>
|
||||
@@ -167,18 +167,12 @@ All 4 phases shipped
|
||||
|
||||
## ▶ 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>
|
||||
|
||||
---
|
||||
|
||||
**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:
|
||||
|
||||
- **research-project** 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
|
||||
- **Research** needs: what domain to research, what the user already knows, what unknowns exist
|
||||
- **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
|
||||
- **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
|
||||
|
||||
Which phases cover which requirements. Updated by create-roadmap.
|
||||
Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
@@ -97,9 +97,9 @@ Which phases cover which requirements. Updated by create-roadmap.
|
||||
- Anti-features from research belong here with warnings
|
||||
|
||||
**Traceability:**
|
||||
- Empty initially, populated by create-roadmap
|
||||
- Empty initially, populated during roadmap creation
|
||||
- Each requirement maps to exactly one phase
|
||||
- Unmapped requirements = roadmap gap (error in create-roadmap)
|
||||
- Unmapped requirements = roadmap gap
|
||||
|
||||
**Status Values:**
|
||||
- Pending: Not started
|
||||
|
||||
@@ -151,7 +151,7 @@ Phases with standard patterns (skip research-phase):
|
||||
|
||||
**Implications for Roadmap:**
|
||||
- This is the most important section
|
||||
- Directly informs create-roadmap workflow
|
||||
- Directly informs roadmap creation
|
||||
- Be explicit about phase suggestions and rationale
|
||||
- Include research flags for each suggested phase
|
||||
|
||||
@@ -162,9 +162,9 @@ Phases with standard patterns (skip research-phase):
|
||||
- MEDIUM = community consensus, multiple sources agree
|
||||
- LOW = single source or inference
|
||||
|
||||
**Integration with create-roadmap:**
|
||||
- This file is loaded as @context in create-roadmap
|
||||
**Integration with roadmap creation:**
|
||||
- This file is loaded as context during roadmap creation
|
||||
- Phase suggestions here become starting point for roadmap
|
||||
- Research flags inform detect_research_needs step
|
||||
- Research flags inform phase planning
|
||||
|
||||
</guidelines>
|
||||
|
||||
@@ -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