get-shit-done-cc 1.4.28 → 1.5.0

package/commands/gsd/create-roadmap.md

@@ -12,7 +12,9 @@ allowed-tools:
 <objective>
 Create project roadmap with phase breakdown.
 
-Roadmaps define what work happens in what order. Run after /gsd:new-project.
+Roadmaps define what work happens in what order. Phases map to requirements.
+
+Run after `/gsd:define-requirements`.
 </objective>
 
 <execution_context>
@@ -24,6 +26,8 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project.
 <context>
 @.planning/PROJECT.md
 @.planning/config.json
+@.planning/REQUIREMENTS.md
+@.planning/research/SUMMARY.md (if exists)
 </context>
 
 <process>
@@ -32,6 +36,9 @@ Roadmaps define what work happens in what order. Run after /gsd:new-project.
 ```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>
 
@@ -60,12 +67,15 @@ If "Replace": Continue with workflow
 Follow the create-roadmap.md workflow starting from detect_domain step.
 
 The workflow handles:
+- Loading requirements
 - Domain expertise detection
-- Phase identification
+- Phase identification mapped to requirements
+- Requirement coverage validation (no orphaned requirements)
 - Research flags for each phase
 - Confirmation gates (respecting config mode)
-- ROADMAP.md creation
+- ROADMAP.md creation with requirement mappings
 - STATE.md initialization
+- REQUIREMENTS.md traceability update
 - Phase directory creation
 - Git commit
 </step>
@@ -108,8 +118,11 @@ Roadmap created:
 
 <success_criteria>
 - [ ] PROJECT.md validated
-- [ ] ROADMAP.md created with phases
+- [ ] REQUIREMENTS.md validated
+- [ ] All v1 requirements mapped to phases (no orphans)
+- [ ] ROADMAP.md created with phases and requirement mappings
 - [ ] STATE.md initialized
+- [ ] REQUIREMENTS.md traceability section updated
 - [ ] Phase directories created
 - [ ] Changes committed
 </success_criteria>

package/commands/gsd/define-requirements.md

@@ -0,0 +1,110 @@
+---
+name: gsd:define-requirements
+description: Define what "done" looks like with checkable requirements
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Define concrete, checkable requirements from research findings.
+
+Research answers "what do products like this have?"
+Requirements answers "what are WE building?"
+
+Transforms research features into scoped v1/v2 requirements that roadmap phases map to.
+
+Run after `/gsd:research-project`, before `/gsd:create-roadmap`.
+
+Output: `.planning/REQUIREMENTS.md`
+</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 (required)
+@.planning/research/SUMMARY.md
+</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 research exists
+[ -f .planning/research/FEATURES.md ] || { echo "ERROR: No research found. Run /gsd:research-project first."; exit 1; }
+
+# 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">
+Follow the define-requirements.md workflow:
+- Load research features
+- 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
+</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
+- [ ] Research FEATURES.md loaded
+- [ ] Features presented by category
+- [ ] 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>

package/commands/gsd/new-project.md

@@ -12,7 +12,7 @@ allowed-tools:
 
 Initialize a new project through comprehensive context gathering.
 
-This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
+This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. The quality of PROJECT.md determines the quality of everything downstream.
 
 Creates `.planning/` with PROJECT.md and config.json.
 
@@ -90,52 +90,48 @@ Exit command.
 
 <step name="question">
 
-**1. Open (FREEFORM — do NOT use AskUserQuestion):**
+**Open the conversation:**
 
-Ask inline: "What do you want to build?"
+Ask inline (freeform, NOT AskUserQuestion):
 
-Wait for their freeform response. This gives you the context needed to ask intelligent follow-up questions.
+"What do you want to build?"
 
-**2. Follow the thread (NOW use AskUserQuestion):**
+Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
 
-Based on their response, use AskUserQuestion with options that probe what they mentioned:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that look like?"
-- options: 2-3 interpretations + "Something else"
+**Follow the thread:**
 
-**3. Sharpen the core:**
+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.
 
-Use AskUserQuestion:
-- header: "Core"
-- question: "If you could only nail one thing, what would it be?"
-- options: Key aspects they've mentioned + "All equally important" + "Something else"
+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
 
-**4. Find boundaries:**
+Consult `questioning.md` for techniques:
+- Challenge vagueness
+- Make abstract concrete
+- Surface assumptions
+- Find edges
+- Reveal motivation
 
-Use AskUserQuestion:
-- header: "Scope"
-- question: "What's explicitly NOT in v1?"
-- options: Things that might be tempting + "Nothing specific" + "Let me list them"
+**Check context (background, not out loud):**
 
-**5. Ground in reality:**
+As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
 
-Use AskUserQuestion:
-- header: "Constraints"
-- question: "Any hard constraints?"
-- options: Relevant constraint types + "None" + "Yes, let me explain"
+**Decision gate:**
 
-**6. Decision gate:**
+When you could write a clear PROJECT.md, use AskUserQuestion:
 
-Use AskUserQuestion:
 - header: "Ready?"
-- question: "Ready to create PROJECT.md, or explore more?"
-- options (ALL THREE REQUIRED):
-  - "Create PROJECT.md" — Finalize and continue
-  - "Ask more questions" — I'll dig deeper
-  - "Let me add context" — You have more to share
-
-If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2.
-If "Let me add context" → receive input via their response → return to step 2.
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create 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 "Create PROJECT.md" selected.
 
 </step>
@@ -303,7 +299,15 @@ Project initialized:
 
 ## ▶ Next Up
 
-**[Project Name]** — create roadmap
+Choose your path:
+
+**Option A: Research first** (recommended for new domains)
+Research the ecosystem before creating roadmap. Discovers standard stacks, expected features, architecture patterns, and common pitfalls.
+
+`/gsd:research-project`
+
+**Option B: Create roadmap directly** (for familiar domains)
+Skip research if you know this domain well or have a clear spec.
 
 `/gsd:create-roadmap`
 
@@ -325,7 +329,7 @@ Project initialized:
 
 <success_criteria>
 
-- [ ] Deep questioning completed (not rushed)
+- [ ] Deep questioning completed (not rushed, threads followed)
 - [ ] PROJECT.md captures full context with evolutionary structure
 - [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
 - [ ] Key Decisions table initialized

package/commands/gsd/research-project.md

@@ -0,0 +1,136 @@
+---
+name: gsd:research-project
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - WebFetch
+  - WebSearch
+  - mcp__context7__*
+---
+
+<objective>
+Comprehensive domain research before roadmap creation.
+
+Answers the questions that inform quality roadmaps:
+- What's the standard stack for this type of product?
+- What features do users expect?
+- How are these systems typically structured?
+- What do projects in this domain commonly get wrong?
+
+Run after `/gsd:new-project`, before `/gsd:define-requirements`.
+
+Output: `.planning/research/` folder with ecosystem knowledge.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/research-project.md
+@~/.claude/get-shit-done/templates/research-project/SUMMARY.md
+@~/.claude/get-shit-done/templates/research-project/STACK.md
+@~/.claude/get-shit-done/templates/research-project/FEATURES.md
+@~/.claude/get-shit-done/templates/research-project/ARCHITECTURE.md
+@~/.claude/get-shit-done/templates/research-project/PITFALLS.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/config.json (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 if roadmap already exists
+[ -f .planning/ROADMAP.md ] && echo "WARNING: ROADMAP.md already exists. Research is typically done before roadmap creation."
+
+# Check if research already exists
+[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+</step>
+
+<step name="check_existing">
+**If RESEARCH_EXISTS:**
+
+Use AskUserQuestion:
+- header: "Research exists"
+- question: "Research folder already exists. What would you like to do?"
+- options:
+  - "View existing" — Show current research summary
+  - "Replace" — Run fresh research (will overwrite)
+  - "Cancel" — Keep existing research
+
+If "View existing": Read and display `.planning/research/SUMMARY.md`, then exit
+If "Cancel": Exit
+If "Replace": Continue with workflow
+</step>
+
+<step name="execute_research">
+Follow the research-project.md workflow:
+- Analyze PROJECT.md to determine domain
+- Identify research questions based on domain
+- Spawn parallel research agents
+- Aggregate results into `.planning/research/`
+- Create SUMMARY.md with roadmap implications
+</step>
+
+<step name="done">
+```
+Research complete:
+
+- Summary: .planning/research/SUMMARY.md
+- Stack: .planning/research/STACK.md
+- Features: .planning/research/FEATURES.md
+- Architecture: .planning/research/ARCHITECTURE.md
+- Pitfalls: .planning/research/PITFALLS.md
+
+---
+
+## ▶ Next Up
+
+**Define requirements** — scope your v1 from research findings
+
+`/gsd:define-requirements`
+
+<sub>`/clear` first → fresh context window</sub>
+
+**Flow:** research-project → **define-requirements** → create-roadmap
+
+---
+```
+</step>
+
+</process>
+
+<when_to_use>
+**Use research-project for:**
+- Greenfield projects in established domains (community, e-commerce, SaaS)
+- When "what features should exist" is partially unknown
+- Complex integrations requiring ecosystem knowledge
+- Domains where best practices matter (auth, payments, real-time)
+- Any project where you'd Google "how to build a [X]" before starting
+
+**Skip research-project for:**
+- Well-defined specs ("build exactly this API")
+- Simple tools/utilities with clear scope
+- Adding features to existing codebases (use research-phase instead)
+- Domains you've built in many times before
+</when_to_use>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] Domain identified from project description
+- [ ] Research questions determined and approved
+- [ ] Parallel research agents spawned
+- [ ] All research documents created in .planning/research/
+- [ ] SUMMARY.md includes roadmap implications
+- [ ] Research committed to git
+- [ ] User knows next step (define-requirements)
+</success_criteria>