From c54071ccb8db41e1fbde3a1e93b2e297ffc9fadc Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sat, 17 Jan 2026 00:28:41 -0600 Subject: [PATCH] refactor: unify milestone flow, remove deprecated commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CHANGELOG.md | 18 + README.md | 3 +- agents/gsd-project-researcher.md | 11 +- agents/gsd-roadmapper.md | 115 +-- commands/gsd/complete-milestone.md | 5 +- commands/gsd/create-roadmap.md | 145 ---- commands/gsd/define-requirements.md | 134 --- commands/gsd/discuss-milestone.md | 47 -- commands/gsd/help.md | 31 +- commands/gsd/new-milestone.md | 762 +++++++++++++++--- commands/gsd/progress.md | 13 +- commands/gsd/research-project.md | 323 -------- .../references/continuation-format.md | 10 +- get-shit-done/references/questioning.md | 5 +- get-shit-done/templates/milestone-context.md | 93 --- get-shit-done/templates/requirements.md | 6 +- .../templates/research-project/SUMMARY.md | 8 +- get-shit-done/workflows/complete-milestone.md | 17 +- get-shit-done/workflows/create-roadmap.md | 632 --------------- .../workflows/define-requirements.md | 330 -------- get-shit-done/workflows/discuss-milestone.md | 227 ------ 21 files changed, 736 insertions(+), 2199 deletions(-) delete mode 100644 commands/gsd/create-roadmap.md delete mode 100644 commands/gsd/define-requirements.md delete mode 100644 commands/gsd/discuss-milestone.md delete mode 100644 commands/gsd/research-project.md delete mode 100644 get-shit-done/templates/milestone-context.md delete mode 100644 get-shit-done/workflows/create-roadmap.md delete mode 100644 get-shit-done/workflows/define-requirements.md delete mode 100644 get-shit-done/workflows/discuss-milestone.md diff --git a/CHANGELOG.md b/CHANGELOG.md index cc39f3acf..c07792b37 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index b3fde8c99..5bb443881 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/agents/gsd-project-researcher.md b/agents/gsd-project-researcher.md index d964b0fbf..dd7ad200b 100644 --- a/agents/gsd-project-researcher.md +++ b/agents/gsd-project-researcher.md @@ -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 -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 diff --git a/agents/gsd-roadmapper.md b/agents/gsd-roadmapper.md index abe71abb5..c0cff6787 100644 --- a/agents/gsd-roadmapper.md +++ b/agents/gsd-roadmapper.md @@ -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 diff --git a/commands/gsd/complete-milestone.md b/commands/gsd/complete-milestone.md index ae8618b22..6ece8b800 100644 --- a/commands/gsd/complete-milestone.md +++ b/commands/gsd/complete-milestone.md @@ -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) @@ -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 diff --git a/commands/gsd/create-roadmap.md b/commands/gsd/create-roadmap.md deleted file mode 100644 index b4f4399f0..000000000 --- a/commands/gsd/create-roadmap.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -name: gsd:create-roadmap -description: Create roadmap with phases for the project -allowed-tools: - - Read - - Write - - Bash - - AskUserQuestion - - Glob - - Task ---- - - - - -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. - - - -@~/.claude/get-shit-done/workflows/create-roadmap.md -@~/.claude/get-shit-done/templates/roadmap.md -@~/.claude/get-shit-done/templates/state.md - - - -@.planning/PROJECT.md -@.planning/config.json -@.planning/REQUIREMENTS.md -@.planning/research/SUMMARY.md (if exists) - - - - - -```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; } -``` - - - -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 - - - -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 - - - -``` -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 - -`/clear` first → fresh context window - ---- - -**Also available:** -- `/gsd:plan-phase 1` — skip discussion, plan directly -- Review roadmap - ---- -``` - - - - - -- `.planning/ROADMAP.md` -- `.planning/STATE.md` -- `.planning/phases/XX-name/` directories - - - -- [ ] 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 - diff --git a/commands/gsd/define-requirements.md b/commands/gsd/define-requirements.md deleted file mode 100644 index 64c24b63f..000000000 --- a/commands/gsd/define-requirements.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -name: gsd:define-requirements -description: Define what "done" looks like with checkable requirements -allowed-tools: - - Read - - Write - - Bash - - Glob - - AskUserQuestion ---- - - - - -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. - - - -@~/.claude/get-shit-done/workflows/define-requirements.md -@~/.claude/get-shit-done/templates/requirements.md - - - -@.planning/PROJECT.md -@.planning/research/FEATURES.md (if exists) -@.planning/research/SUMMARY.md (if exists) - - - - - -```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" -``` - - - -**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 - - - -**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). - - - -``` -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` - -`/clear` first → fresh context window - ---- -``` - - - - - -- [ ] 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) - diff --git a/commands/gsd/discuss-milestone.md b/commands/gsd/discuss-milestone.md deleted file mode 100644 index c68ab8410..000000000 --- a/commands/gsd/discuss-milestone.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: gsd:discuss-milestone -description: Gather context for next milestone through adaptive questioning ---- - - -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 - - - -@~/.claude/get-shit-done/workflows/discuss-milestone.md - - - -**Load project state first:** -@.planning/STATE.md - -**Load project:** -@.planning/PROJECT.md - -**Load milestones (if exists):** -@.planning/MILESTONES.md - - - -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.** - - - - -- Project state loaded and presented -- Previous milestone context summarized -- Milestone scope gathered through adaptive questioning -- Context handed off to /gsd:new-milestone - diff --git a/commands/gsd/help.md b/commands/gsd/help.md index 987fd7654..df581784d 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -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 `** @@ -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 `** -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:** diff --git a/commands/gsd/new-milestone.md b/commands/gsd/new-milestone.md index 9f85a0211..20f528337 100644 --- a/commands/gsd/new-milestone.md +++ b/commands/gsd/new-milestone.md @@ -6,23 +6,40 @@ allowed-tools: - Read - Write - Bash + - Task - AskUserQuestion + - Glob --- -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 + @~/.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 + + 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 -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` - - `/clear` first → fresh context window - - --- +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=" + +Project Research — Stack dimension for [domain]. + + + +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. + + + +What's needed to add [target features] to [domain]? + + + +[PROJECT.md summary - core value, validated requirements, new goals] + + + +Your STACK.md feeds into roadmap creation. Be prescriptive: +- Specific libraries with versions +- Clear rationale for each choice +- What NOT to use and why + + + +Write to: .planning/research/STACK.md +Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md + +", subagent_type="gsd-project-researcher", description="Stack research") + +Task(prompt=" + +Project Research — Features dimension for [domain]. + + + +Subsequent milestone (v[X.Y]). + +How do [target features] typically work? What's expected behavior? + + + +What features are expected for [target features]? + + + +[PROJECT.md summary] + + + +Your FEATURES.md feeds into requirements definition. Categorize clearly: +- Table stakes (must have) +- Differentiators (competitive advantage) +- Anti-features (things to deliberately NOT build) + + + +Write to: .planning/research/FEATURES.md +Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md + +", subagent_type="gsd-project-researcher", description="Features research") + +Task(prompt=" + +Project Research — Architecture dimension for [domain]. + + + +Subsequent milestone (v[X.Y]). + +How do [target features] integrate with existing [domain] architecture? + + + +How should [target features] integrate with the existing system? + + + +[PROJECT.md summary] + + + +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) + + + +Write to: .planning/research/ARCHITECTURE.md +Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md + +", subagent_type="gsd-project-researcher", description="Architecture research") + +Task(prompt=" + +Project Research — Pitfalls dimension for [domain]. + + + +Subsequent milestone (v[X.Y]). + +What are common mistakes when adding [target features] to [domain]? + + + +What pitfalls should we avoid when adding [target features]? + + + +[PROJECT.md summary] + + + +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 + + + +Write to: .planning/research/PITFALLS.md +Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md + +", subagent_type="gsd-project-researcher", description="Pitfalls research") +``` + +After all 4 agents complete, spawn synthesizer: + +``` +Task(prompt=" + +Synthesize research outputs into SUMMARY.md. + + + +Read these files: +- .planning/research/STACK.md +- .planning/research/FEATURES.md +- .planning/research/ARCHITECTURE.md +- .planning/research/PITFALLS.md + + + +Write to: .planning/research/SUMMARY.md +Use template: ~/.claude/get-shit-done/templates/research-project/SUMMARY.md +Commit after writing. + +", 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=" + + +**Project:** +@.planning/PROJECT.md + +**Requirements:** +@.planning/REQUIREMENTS.md + +**Research (if exists):** +@.planning/research/SUMMARY.md + +**Config:** +@.planning/config.json + +**Starting phase number:** [N] + + + + +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. + +", 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 + +`/clear` first → fresh context window + +--- + +**Also available:** +- `/gsd:plan-phase [N]` — skip discussion, plan directly + +─────────────────────────────────────────────────────────────── +``` + + + +- `.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 + + + -- 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]` + diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index a86918d5b..3b8e2597f 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -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` `/clear` first → fresh context window ---- - -**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 - --- ``` diff --git a/commands/gsd/research-project.md b/commands/gsd/research-project.md deleted file mode 100644 index d23ba60b9..000000000 --- a/commands/gsd/research-project.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -name: gsd:research-project -description: Research domain ecosystem before creating roadmap -allowed-tools: - - Read - - Write - - Bash - - Task - - AskUserQuestion ---- - - - - -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. - - - -@.planning/PROJECT.md -@.planning/config.json (if exists) - - - - -## 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=" - -Project Research — Stack dimension for [domain]. - - - -{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. - - - -[stack question from step 4] - - - -[PROJECT.md summary] - - - -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 - - - -- [ ] Versions are current (not Claude's training data) -- [ ] Rationale explains WHY, not just WHAT -- [ ] Confidence levels assigned - - - -Write to: .planning/research/STACK.md -Use template: ~/.claude/get-shit-done/templates/research-project/STACK.md - -", subagent_type="gsd-project-researcher", description="Stack research") - -Task(prompt=" - -Project Research — Features dimension for [domain]. - - - -{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? - - - -[features question from step 4] - - - -[PROJECT.md summary] - - - -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) - - - -- [ ] Categories are clear -- [ ] Complexity noted for each -- [ ] Dependencies between features identified - - - -Write to: .planning/research/FEATURES.md -Use template: ~/.claude/get-shit-done/templates/research-project/FEATURES.md - -", subagent_type="gsd-project-researcher", description="Features research") - -Task(prompt=" - -Project Research — Architecture dimension for [domain]. - - - -{greenfield OR subsequent} - -Greenfield: How are [domain] systems typically structured? What are major components? -Subsequent: How do [target features] integrate with existing [domain] architecture? - - - -[architecture question from step 4] - - - -[PROJECT.md summary] - - - -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) - - - -- [ ] Components clearly defined -- [ ] Boundaries explicit -- [ ] Build order implications noted - - - -Write to: .planning/research/ARCHITECTURE.md -Use template: ~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md - -", subagent_type="gsd-project-researcher", description="Architecture research") - -Task(prompt=" - -Project Research — Pitfalls dimension for [domain]. - - - -{greenfield OR subsequent} - -Greenfield: What do [domain] projects commonly get wrong? Critical mistakes? -Subsequent: What are common mistakes when adding [target features] to [domain]? - - - -[pitfalls question from step 4] - - - -[PROJECT.md summary] - - - -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 - - - -- [ ] Pitfalls are specific, not generic -- [ ] Prevention is actionable -- [ ] Phase mapping included - - - -Write to: .planning/research/PITFALLS.md -Use template: ~/.claude/get-shit-done/templates/research-project/PITFALLS.md - -", 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` -`/clear` first ---- -``` - - - - -- [ ] 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 - diff --git a/get-shit-done/references/continuation-format.md b/get-shit-done/references/continuation-format.md index 92e609c67..34b85dfc3 100644 --- a/get-shit-done/references/continuation-format.md +++ b/get-shit-done/references/continuation-format.md @@ -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` `/clear` first → fresh context window ---- - -**Also available:** -- `/gsd:new-milestone` — create directly if scope is clear -- Review accomplishments before moving on - --- ``` diff --git a/get-shit-done/references/questioning.md b/get-shit-done/references/questioning.md index 8056a9aaa..5fc7f19cc 100644 --- a/get-shit-done/references/questioning.md +++ b/get-shit-done/references/questioning.md @@ -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 diff --git a/get-shit-done/templates/milestone-context.md b/get-shit-done/templates/milestone-context.md deleted file mode 100644 index 3cd081e87..000000000 --- a/get-shit-done/templates/milestone-context.md +++ /dev/null @@ -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 to Build - -[Features identified during discussion - the substance of this milestone] - -- **[Feature 1]**: [description] -- **[Feature 2]**: [description] -- **[Feature 3]**: [description] - - - - -## Scope - -**Suggested name:** v[X.Y] [Theme Name] -**Estimated phases:** [N] -**Focus:** [One sentence theme/focus] - - - - -## Phase Mapping - -[How features map to phases - rough breakdown] - -- Phase [N]: [Feature/goal] -- Phase [N+1]: [Feature/goal] -- Phase [N+2]: [Feature/goal] - - - - -## Constraints - -[Any constraints or boundaries mentioned during discussion] - -- [Constraint 1] -- [Constraint 2] - - - - -## Additional Context - -[Anything else captured during discussion that informs the milestone] - - - ---- - -*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.* -``` - - -**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 - diff --git a/get-shit-done/templates/requirements.md b/get-shit-done/templates/requirements.md index 685142fcd..d55313480 100644 --- a/get-shit-done/templates/requirements.md +++ b/get-shit-done/templates/requirements.md @@ -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 diff --git a/get-shit-done/templates/research-project/SUMMARY.md b/get-shit-done/templates/research-project/SUMMARY.md index c336b8a8e..edd67ddf0 100644 --- a/get-shit-done/templates/research-project/SUMMARY.md +++ b/get-shit-done/templates/research-project/SUMMARY.md @@ -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 diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md index 680870c48..2c40f3251 100644 --- a/get-shit-done/workflows/complete-milestone.md +++ b/get-shit-done/workflows/complete-milestone.md @@ -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. @@ -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` `/clear` first → fresh context window ---- - -**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) diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md deleted file mode 100644 index 58ad4840a..000000000 --- a/get-shit-done/workflows/create-roadmap.md +++ /dev/null @@ -1,632 +0,0 @@ - -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. - - - -**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) - - - - - -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. - - - -```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? - - - -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. - - - -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 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 - - -**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 - - - -**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 - - - -**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%.** - - - - -```bash -cat .planning/config.json 2>/dev/null -``` -Note: Config may not exist yet (project initialization). If missing, default to interactive mode. - - - -``` -⚡ 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. - - - -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. - - - - -``` -⚡ Auto-approved: Create roadmap with [N] phases - -Proceeding to create .planning/ROADMAP.md... -``` - -Proceed directly to create_structure step. - - - -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. - - - -```bash -mkdir -p .planning/phases -``` - - - -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. -``` - - - - -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. - - - - -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 - - - - -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)" - - - -``` -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 - -`/clear` first → fresh context window - ---- - -**Also available:** -- `/gsd:plan-phase 1` — skip discussion, plan directly -- Review roadmap - ---- -``` - - - - - -Use `XX-kebab-case-name` format: -- `01-foundation` -- `02-authentication` -- `03-core-features` -- `04-polish` - -Numbers ensure ordering. Names describe content. - - - -- 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. - - - -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 - -``` diff --git a/get-shit-done/workflows/define-requirements.md b/get-shit-done/workflows/define-requirements.md deleted file mode 100644 index fefbc28da..000000000 --- a/get-shit-done/workflows/define-requirements.md +++ /dev/null @@ -1,330 +0,0 @@ - -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." - - - -**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) - - - - - -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 - - - -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) - - - -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 - - - -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. - - - -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 - - - -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) - - - -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. - - - -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 - - - -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. - - - -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. - - - -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 -)" -``` - - - -``` -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` - -`/clear` first → fresh context window - ---- -``` - - - - - -**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 - - - -- [ ] 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 - diff --git a/get-shit-done/workflows/discuss-milestone.md b/get-shit-done/workflows/discuss-milestone.md deleted file mode 100644 index 3fb00e658..000000000 --- a/get-shit-done/workflows/discuss-milestone.md +++ /dev/null @@ -1,227 +0,0 @@ - -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. - - - - - -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. - - - -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. - - - -**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. - - - -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 to Build - -- **[Feature 1]**: [description] -- **[Feature 2]**: [description] -- **[Feature 3]**: [description] - - - - -## Scope - -**Suggested name:** v[X.Y] [Theme Name] -**Estimated phases:** [N] -**Focus:** [One sentence theme/focus] - - - - - -## Constraints - -- [Any constraints mentioned] - - - - -## Additional Context - -[Anything else from discussion] - - - ---- - -*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.* -EOF -``` - - - -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` - -`/clear` first → fresh context window - ---- -``` - - - - - - -- 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 -