get-shit-done-cc 1.0.10 → 1.1.0

package/commands/gsd/create-roadmap.md

@@ -0,0 +1,146 @@
+---
+description: Create roadmap with phases for the project
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+  - Glob
+---
+
+<objective>
+Create project roadmap, optionally incorporating research findings from /gsd:research-project.
+
+Roadmaps define the phase breakdown - what work happens in what order. This command can be used:
+1. After /gsd:new-project (without research)
+2. After /gsd:research-project (with domain research incorporated)
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/create-roadmap.md
+@~/.claude/get-shit-done/templates/roadmap.md
+@~/.claude/get-shit-done/templates/state.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+
+**Check for research:**
+!`ls .planning/research/*.md 2>/dev/null || echo "NO_RESEARCH"`
+
+**Load config:**
+@.planning/config.json
+</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; }
+```
+</step>
+
+<step name="check_existing">
+Check if roadmap already exists:
+
+```bash
+[ -f .planning/ROADMAP.md ] && echo "ROADMAP_EXISTS" || echo "NO_ROADMAP"
+```
+
+**If ROADMAP_EXISTS:**
+Use AskUserQuestion:
+- header: "Roadmap exists"
+- question: "A roadmap already exists. What would you like to do?"
+- options:
+  - "View existing" - Show current roadmap
+  - "Replace" - Create new roadmap (will overwrite)
+  - "Cancel" - Keep existing roadmap
+
+If "View existing": `cat .planning/ROADMAP.md` and exit
+If "Cancel": Exit
+If "Replace": Continue with workflow
+</step>
+
+<step name="check_research">
+Check for project research:
+
+```bash
+ls .planning/research/*.md 2>/dev/null
+```
+
+**If research found:**
+Load and summarize each research file:
+- ecosystem.md → Key libraries/frameworks recommended
+- architecture.md → Architectural patterns to follow
+- pitfalls.md → Top 2-3 critical pitfalls to avoid
+- standards.md → Standards and conventions to follow
+
+Present summary:
+```
+Found project research:
+
+Ecosystem: [key libraries/frameworks]
+Architecture: [key patterns]
+Pitfalls: [top 2-3 to avoid]
+Standards: [key conventions]
+
+This will inform phase structure.
+```
+
+**If no research found:**
+```
+No project research found.
+Creating roadmap based on PROJECT.md alone.
+(Optional: Run /gsd:research-project first for niche/complex domains)
+```
+</step>
+
+<step name="create_roadmap">
+Follow the create-roadmap.md workflow starting from detect_domain step.
+
+The workflow handles:
+- Domain expertise detection
+- Phase identification (informed by research if present)
+- Research flags for each phase
+- Confirmation gates (respecting config mode)
+- ROADMAP.md creation
+- STATE.md initialization
+- Phase directory creation
+- Git commit
+</step>
+
+<step name="done">
+```
+Roadmap created:
+- Roadmap: .planning/ROADMAP.md
+- State: .planning/STATE.md
+- [N] phases defined
+
+What's next?
+1. Discuss Phase 1 context (/gsd:discuss-phase 1)
+2. Plan Phase 1 in detail (/gsd:plan-phase 1)
+3. Review/adjust phases
+4. Done for now
+```
+
+If user selects "Discuss Phase 1 context" → invoke `/gsd:discuss-phase 1`
+If user selects "Plan Phase 1 in detail" → invoke `/gsd:plan-phase 1`
+</step>
+
+</process>
+
+<output>
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+- `.planning/phases/XX-name/` directories
+</output>
+
+<success_criteria>
+- [ ] PROJECT.md validated
+- [ ] Research incorporated if present
+- [ ] ROADMAP.md created with phases
+- [ ] STATE.md initialized
+- [ ] Phase directories created
+- [ ] Changes committed
+</success_criteria>

package/commands/gsd/help.md

@@ -20,9 +20,11 @@ Output ONLY the reference content below. Do NOT add:
 
 ## Quick Start
 
-1. `/gsd:new-project` - Initialize project with brief and roadmap
-2. `/gsd:plan-phase <number>` - Create detailed plan for first phase
-3. `/gsd:execute-plan <path>` - Execute the plan
+1. `/gsd:new-project` - Initialize project with brief
+2. `/gsd:research-project` - (Optional) Research domain ecosystem
+3. `/gsd:create-roadmap` - Create roadmap and phases
+4. `/gsd:plan-phase <number>` - Create detailed plan for first phase
+5. `/gsd:execute-plan <path>` - Execute the plan
 
 ## Core Workflow
 
@@ -33,17 +35,35 @@ Initialization → Planning → Execution → Milestone Completion
 ### Project Initialization
 
 **`/gsd:new-project`**
-Initialize new project with brief, roadmap, and state tracking.
+Initialize new project with brief and configuration.
 
 - Creates `.planning/PROJECT.md` (vision and requirements)
-- Creates `.planning/ROADMAP.md` (phase breakdown)
-- Creates `.planning/STATE.md` (project memory)
 - Creates `.planning/config.json` (workflow mode)
 - Asks for workflow mode (interactive/yolo) upfront
-- Commits all initialization files to git
+- Commits initialization files to git
 
 Usage: `/gsd:new-project`
 
+**`/gsd:research-project`**
+Research domain ecosystem before creating roadmap.
+
+- Spawns batched subagents to research domain patterns
+- Creates `.planning/research/` with ecosystem findings
+- Optional step for niche/complex domains
+- Run after new-project, before create-roadmap
+
+Usage: `/gsd:research-project`
+
+**`/gsd:create-roadmap`**
+Create roadmap and state tracking for initialized project.
+
+- Creates `.planning/ROADMAP.md` (phase breakdown)
+- Creates `.planning/STATE.md` (project memory)
+- Creates `.planning/phases/` directories
+- Incorporates research findings if present
+
+Usage: `/gsd:create-roadmap`
+
 ### Phase Planning
 
 **`/gsd:discuss-phase <number>`**
@@ -55,6 +75,16 @@ Gather phase context through adaptive questioning before planning.
 
 Usage: `/gsd:discuss-phase 2`
 
+**`/gsd:research-phase <number>`**
+Comprehensive ecosystem research for niche/complex domains.
+
+- Discovers standard stack, architecture patterns, pitfalls
+- Creates RESEARCH.md with "how experts build this" knowledge
+- Use for 3D, games, audio, shaders, ML, and other specialized domains
+- Goes beyond "which library" to ecosystem knowledge
+
+Usage: `/gsd:research-phase 3`
+
 **`/gsd:list-phase-assumptions <number>`**
 Surface Claude's assumptions about a phase before planning.
 
@@ -232,6 +262,17 @@ Change anytime by editing `.planning/config.json`
 
 ```
 /gsd:new-project
+/gsd:create-roadmap
+/gsd:plan-phase 1
+/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
+```
+
+**Building something in a niche domain (3D, games, audio, shaders):**
+
+```
+/gsd:new-project
+/gsd:research-project  # Research domain ecosystem before roadmap
+/gsd:create-roadmap    # Roadmap incorporates research findings
 /gsd:plan-phase 1
 /gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md
 ```

package/commands/gsd/new-project.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize a new project with deep context gathering, PROJECT.md, roadmap, and state tracking
+description: Initialize a new project with deep context gathering and PROJECT.md
 allowed-tools:
   - Read
   - Bash
@@ -7,27 +7,15 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-<!--
-DESIGN NOTE: Command + Workflow Pattern
-
-This command handles the questioning phase directly (user interaction intensive),
-then delegates roadmap/state creation to the create-roadmap workflow.
-
-Architecture:
-- Command: new-project.md - questioning, PROJECT.md, config.json
-- Workflow: create-roadmap.md - domain detection, research flags, ROADMAP.md, STATE.md
--->
-
 <objective>
 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.
 
-Creates `.planning/` with PROJECT.md, ROADMAP.md, STATE.md, and config.json.
+Creates `.planning/` with PROJECT.md and config.json.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/create-roadmap.md
 @~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/references/questioning.md
 @~/.claude/get-shit-done/templates/project.md
@@ -57,21 +45,25 @@ Silent setup - execute before any user output:
 <step name="question">
 Start: "What do you want to build?"
 
-Then use AskUserQuestion to cover the 9 domains (project type, problem, audience, success, constraints, scope, current state, decisions, open questions).
+Let them talk. Then follow the conversation arc from `questioning.md`:
+1. **Follow the thread** — dig into what they said, what excites them
+2. **Sharpen the core** — essential vs nice-to-have
+3. **Find boundaries** — what is it NOT
+4. **Ground in reality** — only constraints that actually exist
 
-Skip domains already clear from user input. Probe for specifics on vague answers.
+Be a thinking partner, not an interviewer. Help them discover and articulate their vision.
 
-**Decision gate (MUST have all 3 options):**
+When you feel you understand it, offer the decision gate:
 
 ```
 Header: "Ready?"
 Options:
   1. "Create PROJECT.md" - Finalize
-  2. "Ask more questions" - Dig into uncovered domains
+  2. "Ask more questions" - I'll dig deeper
   3. "Let me add context" - User shares more
 ```
 
-If "Ask more questions" → ask about 2-3 uncovered domains → return to gate.
+If "Ask more questions" → check coverage gaps from `questioning.md` → ask naturally → return to gate.
 Loop until "Create PROJECT.md" selected.
 </step>
 
@@ -95,41 +87,17 @@ Use AskUserQuestion:
 Create `.planning/config.json` with chosen mode using `templates/config.json` structure.
 </step>
 
-<step name="roadmap_and_state">
-**Follow the create-roadmap workflow** from `@~/.claude/get-shit-done/workflows/create-roadmap.md`.
-
-This handles:
-
-1. Domain expertise detection (scan for applicable skills)
-2. Phase identification (3-6 phases based on PROJECT.md)
-3. Research needs detection (flag phases needing investigation)
-4. Phase confirmation (respects yolo/interactive mode)
-5. ROADMAP.md creation with research flags
-6. STATE.md initialization
-7. Phase directory creation
-
-The workflow will create:
-
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
-- `.planning/phases/XX-name/` directories
-  </step>
-
 <step name="commit">
 ```bash
-git add .planning/
+git add .planning/PROJECT.md .planning/config.json
 git commit -m "$(cat <<'EOF'
-docs: initialize [project-name] ([N] phases)
+docs: initialize [project-name]
 
 [One-liner from PROJECT.md]
 
-Phases:
-
-1. [phase-name]: [goal]
-2. [phase-name]: [goal]
-3. [phase-name]: [goal]
-   EOF
-   )"
+Creates PROJECT.md with vision and requirements.
+EOF
+)"
 
 ```
 </step>
@@ -140,38 +108,31 @@ Phases:
 Project initialized:
 
 - Project: .planning/PROJECT.md
-- Roadmap: .planning/ROADMAP.md ([N] phases)
-- State: .planning/STATE.md
 - Config: .planning/config.json (mode: [chosen mode])
 
 What's next?
 
-1. Plan Phase 1 (/gsd:plan-phase 01)
-2. Review project setup
+1. Research domain ecosystem (/gsd:research-project) - For niche/complex domains
+2. Create roadmap (/gsd:create-roadmap) - Skip research, go straight to planning
 3. Done for now
 
 ```
 
-If user selects "Plan Phase 1" → invoke `/gsd:plan-phase 01`
+If user selects "Research domain ecosystem" → invoke `/gsd:research-project`
+If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
 </step>
 
 </process>
 
 <output>
 - `.planning/PROJECT.md`
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
 - `.planning/config.json`
-- `.planning/phases/XX-name/` directories
 </output>
 
 <success_criteria>
 - [ ] Deep questioning completed (not rushed)
 - [ ] PROJECT.md captures full context
 - [ ] config.json has workflow mode
-- [ ] ROADMAP.md has 3-6 phases with research flags
-- [ ] STATE.md initialized with project summary
-- [ ] Phase directories created
 - [ ] All committed to git
 </success_criteria>
 ```

package/commands/gsd/research-phase.md

@@ -0,0 +1,90 @@
+---
+description: Research how to implement a phase before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - WebFetch
+  - WebSearch
+  - mcp__context7__*
+---
+
+<objective>
+Comprehensive research on HOW to implement a phase before planning.
+
+This is for niche/complex domains where Claude's training data is sparse or outdated. Research discovers:
+- What libraries exist for this problem
+- What architecture patterns experts use
+- What the standard stack looks like
+- What problems people commonly hit
+- What NOT to hand-roll (use existing solutions)
+
+Output: RESEARCH.md with ecosystem knowledge that informs quality planning.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/research-phase.md
+@~/.claude/get-shit-done/templates/research.md
+@~/.claude/get-shit-done/references/research-pitfalls.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Load project state:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+
+**Load phase context if exists:**
+Check for `.planning/phases/XX-name/{phase}-CONTEXT.md` - bonus context from discuss-phase.
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap - extract phase description
+3. Check if RESEARCH.md already exists (offer to update or use existing)
+4. Load CONTEXT.md if it exists (bonus context for research direction)
+5. Follow research-phase.md workflow:
+   - Analyze phase to identify knowledge gaps
+   - Determine research domains (architecture, ecosystem, patterns, pitfalls)
+   - Execute comprehensive research via Context7, official docs, WebSearch
+   - Cross-verify all findings
+   - Create RESEARCH.md with actionable ecosystem knowledge
+6. Offer next steps (plan the phase)
+</process>
+
+<when_to_use>
+**Use research-phase for:**
+- 3D graphics (Three.js, WebGL, procedural generation)
+- Game development (physics, collision, AI, procedural content)
+- Audio/music (Web Audio API, DSP, synthesis)
+- Shaders (GLSL, Metal, ISF)
+- ML/AI integration (model serving, inference, pipelines)
+- Real-time systems (WebSockets, WebRTC, sync)
+- Specialized frameworks with active ecosystems
+- Any domain where "how do experts do this" matters
+
+**Skip research-phase for:**
+- Standard web dev (auth, CRUD, REST APIs)
+- Well-known patterns (forms, validation, testing)
+- Simple integrations (Stripe, SendGrid with clear docs)
+- Commodity features Claude handles well
+</when_to_use>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Domain/ecosystem identified from phase description
+- [ ] Comprehensive research executed (Context7 + official docs + WebSearch)
+- [ ] All WebSearch findings cross-verified with authoritative sources
+- [ ] RESEARCH.md created with ecosystem knowledge
+- [ ] Standard stack/libraries identified
+- [ ] Architecture patterns documented
+- [ ] Common pitfalls catalogued
+- [ ] What NOT to hand-roll is clear
+- [ ] User knows next steps (plan phase)
+</success_criteria>

package/commands/gsd/research-project.md

@@ -0,0 +1,142 @@
+---
+description: Research domain ecosystem before creating roadmap
+allowed-tools:
+  - Task
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Research domain ecosystem via batched subagents before roadmap creation.
+
+Spawns 3-4 subagents in parallel to research:
+
+- Ecosystem (libraries, frameworks, tools)
+- Architecture (patterns, project structure)
+- Pitfalls (common mistakes, what NOT to do)
+- Standards (best practices, conventions)
+
+Each subagent writes directly to `.planning/research/` preserving main context.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/research-project.md
+@~/.claude/get-shit-done/templates/project-research.md
+@~/.claude/get-shit-done/references/research-subagent-prompts.md
+</execution_context>
+
+<context>
+**Load project vision:**
+@.planning/PROJECT.md
+
+**Check for existing research:**
+!`ls .planning/research/ 2>/dev/null || echo "NO_RESEARCH_DIR"`
+</context>
+
+<process>
+
+<step name="validate">
+Check prerequisites:
+
+```bash
+# Verify .planning/ exists
+[ -d .planning ] || { echo "No .planning/ directory. Run /gsd:new-project first."; exit 1; }
+
+# Verify PROJECT.md exists
+[ -f .planning/PROJECT.md ] || { echo "No PROJECT.md. Run /gsd:new-project first."; exit 1; }
+
+# Check for existing research
+[ -d .planning/research ] && echo "RESEARCH_EXISTS" || echo "NO_RESEARCH"
+```
+
+If RESEARCH_EXISTS:
+
+```
+Research already exists at .planning/research/
+
+What would you like to do?
+1. View existing research
+2. Re-run research (overwrites existing)
+3. Skip to create-roadmap
+```
+
+Wait for user decision.
+</step>
+
+<step name="detect_domain">
+Parse PROJECT.md to identify the domain and research scope.
+
+Look for:
+
+- Technologies mentioned (Three.js, WebGL, audio, etc.)
+- Problem domain (3D, games, real-time, etc.)
+- Technical constraints that suggest specific ecosystems
+
+If domain unclear, use AskUserQuestion:
+
+- header: "Domain"
+- question: "What domain should we research?"
+- options:
+  - "3D/Graphics" - Three.js, WebGL, shaders
+  - "Games/Interactive" - Physics, collision, procedural
+  - "Audio/Music" - Web Audio, synthesis, DSP
+  - (other relevant options based on PROJECT.md)
+    </step>
+
+<step name="research">
+Follow research-project.md workflow:
+
+1. Create `.planning/research/` directory
+2. Spawn first batch of subagents (ecosystem + architecture)
+3. Wait for completion
+4. Spawn second batch (pitfalls + standards)
+5. Wait for completion
+6. Verify all outputs exist
+   </step>
+
+<step name="summarize">
+After all subagents complete:
+
+```
+Research complete:
+- .planning/research/ecosystem.md
+- .planning/research/architecture.md
+- .planning/research/pitfalls.md
+- .planning/research/standards.md
+
+Key findings:
+- [Top ecosystem recommendation]
+- [Key architecture pattern]
+- [Critical pitfall to avoid]
+
+What's next?
+1. Create roadmap (/gsd:create-roadmap) - Incorporates research
+2. Review research files
+3. Done for now
+```
+
+If user selects "Create roadmap" → invoke `/gsd:create-roadmap`
+</step>
+
+</process>
+
+<output>
+- `.planning/research/ecosystem.md`
+- `.planning/research/architecture.md`
+- `.planning/research/pitfalls.md`
+- `.planning/research/standards.md`
+</output>
+
+<success_criteria>
+
+- [ ] PROJECT.md exists (prerequisite checked)
+- [ ] Domain detected or user clarified
+- [ ] Subagents spawned in batches of 3-4 max
+- [ ] All subagents wrote files directly to .planning/research/
+- [ ] All 4 research files exist
+- [ ] User knows next steps (create-roadmap)
+      </success_criteria>

package/commands/gsd/resume-work.md

@@ -8,17 +8,6 @@ allowed-tools:
   - SlashCommand
 ---
 
-<!--
-DESIGN NOTE: Command + Workflow Pattern
-
-This command is a thin wrapper that routes to the resume-project workflow.
-All resumption logic lives in the workflow for maintainability.
-
-Architecture:
-- Command: resume-work.md - entry point only
-- Workflow: resume-project.md - all resumption logic
--->
-
 <objective>
 Restore complete project context and resume work seamlessly from previous session.
 

package/get-shit-done/references/git-integration.md

@@ -16,7 +16,7 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 | BRIEF + ROADMAP created | YES     | Project initialization                |
 | PLAN.md created         | NO      | Intermediate - commit with completion |
 | RESEARCH.md created     | NO      | Intermediate                          |
-| FINDINGS.md created     | NO      | Intermediate                          |
+| DISCOVERY.md created    | NO      | Intermediate                          |
 | **Phase completed**     | YES     | Actual code shipped                   |
 | Handoff created         | YES     | WIP state preserved                   |
 
@@ -118,7 +118,7 @@ e]2f4a8 docs: initialize ecommerce-app (5 phases)
 
 - PLAN.md creation (wait for phase completion)
 - RESEARCH.md (intermediate)
-- FINDINGS.md (intermediate)
+- DISCOVERY.md (intermediate)
 - Minor planning tweaks
 - "Fixed typo in roadmap"
 

package/get-shit-done/references/plan-format.md

@@ -250,7 +250,7 @@ Use @file references to load context for the prompt:
 <context>
 @.planning/PROJECT.md           # Project vision
 @.planning/ROADMAP.md         # Phase structure
-@.planning/phases/02-auth/FINDINGS.md  # Research results
+@.planning/phases/02-auth/DISCOVERY.md  # Discovery results
 @src/lib/db.ts                # Existing database setup
 @src/types/user.ts            # Existing type definitions
 </context>