get-shit-done-cc 1.7.1 → 1.9.0

package/commands/gsd/analyze-codebase.md

@@ -0,0 +1,363 @@
+---
+name: gsd:analyze-codebase
+description: Scan existing codebase and populate .planning/intel/ with file index, conventions, and semantic entity files
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Write
+  - Task
+---
+
+<objective>
+Scan codebase to populate .planning/intel/ with file index, conventions, and semantic entity files.
+
+Works standalone (without /gsd:new-project) for brownfield codebases. Creates summary.md for context injection at session start. Generates entity files that capture file PURPOSE (what it does, why it exists), not just syntax.
+
+Output: .planning/intel/index.json, conventions.json, summary.md, entities/*.md
+</objective>
+
+<context>
+This command performs bulk codebase scanning to bootstrap the Codebase Intelligence system.
+
+**Use for:**
+- Brownfield projects before /gsd:new-project
+- Refreshing intel after major changes
+- Standalone intel without full project setup
+
+After initial scan, the PostToolUse hook (hooks/intel-index.js) maintains incremental updates.
+
+**Execution model (Step 9 - Entity Generation):**
+- Claude (executing this command) generates entity content directly
+- No embedded JavaScript - Claude reads files and writes semantic documentation
+- Task tool to spawn subagents for batch processing large codebases
+- Each subagent processes 10 files, generating Purpose-focused entity markdown
+- Users can skip Step 9 if they only want the index (faster, less context)
+</context>
+
+<process>
+
+## Step 1: Create directory structure
+
+```bash
+mkdir -p .planning/intel
+```
+
+## Step 2: Find all indexable files
+
+Use Glob tool with pattern: `**/*.{js,ts,jsx,tsx,mjs,cjs}`
+
+Exclude directories (skip any path containing):
+- node_modules
+- dist
+- build
+- .git
+- vendor
+- coverage
+- .next
+- __pycache__
+
+Filter results to remove excluded paths before processing.
+
+## Step 3: Process each file
+
+Initialize the index structure:
+```javascript
+{
+  version: 1,
+  updated: Date.now(),
+  files: {}
+}
+```
+
+For each file found:
+
+1. Read file content using Read tool
+
+2. Extract exports using these patterns:
+   - Named exports: `export\s*\{([^}]+)\}`
+   - Declaration exports: `export\s+(?:const|let|var|function\*?|async\s+function|class)\s+(\w+)`
+   - Default exports: `export\s+default\s+(?:function\s*\*?\s*|class\s+)?(\w+)?`
+   - CommonJS object: `module\.exports\s*=\s*\{([^}]+)\}`
+   - CommonJS single: `module\.exports\s*=\s*(\w+)\s*[;\n]`
+   - TypeScript: `export\s+(?:type|interface)\s+(\w+)`
+
+3. Extract imports using these patterns:
+   - ES6: `import\s+(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]`
+   - Side-effect: `import\s+['"]([^'"]+)['"]` (not preceded by 'from')
+   - CommonJS: `require\s*\(\s*['"]([^'"]+)['"]\s*\)`
+
+4. Store in index:
+   ```javascript
+   index.files[absolutePath] = {
+     exports: [],  // Array of export names
+     imports: [],  // Array of import sources
+     indexed: Date.now()
+   }
+   ```
+
+## Step 4: Detect conventions
+
+Analyze the collected index for patterns.
+
+**Naming conventions** (require 5+ exports, 70%+ match rate):
+- camelCase: `^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)+$` or single lowercase `^[a-z][a-z0-9]*$`
+- PascalCase: `^[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)*$` or single `^[A-Z][a-z0-9]+$`
+- snake_case: `^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$`
+- SCREAMING_SNAKE: `^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$` or single `^[A-Z][A-Z0-9]*$`
+- Skip 'default' when counting (it's a keyword, not naming convention)
+
+**Directory patterns** (use lookup table):
+```
+components -> UI components
+hooks -> React/custom hooks
+utils, lib -> Utility functions
+services -> Service layer
+api, routes -> API endpoints
+types -> TypeScript types
+models -> Data models
+tests, __tests__, test, spec -> Test files
+controllers -> Controllers
+middleware -> Middleware
+config -> Configuration
+constants -> Constants
+pages -> Page components
+views -> View templates
+```
+
+**Suffix patterns** (require 5+ occurrences):
+```
+.test.*, .spec.* -> Test files
+.service.* -> Service layer
+.controller.* -> Controllers
+.model.* -> Data models
+.util.*, .utils.* -> Utility functions
+.helper.*, .helpers.* -> Helper functions
+.config.* -> Configuration
+.types.*, .type.* -> TypeScript types
+.hook.*, .hooks.* -> React/custom hooks
+.context.* -> React context
+.store.* -> State store
+.slice.* -> Redux slice
+.reducer.* -> Redux reducer
+.action.*, .actions.* -> Redux actions
+.api.* -> API layer
+.route.*, .routes.* -> Route definitions
+.middleware.* -> Middleware
+.schema.* -> Schema definitions
+.mock.*, .mocks.* -> Mock data
+.fixture.*, .fixtures.* -> Test fixtures
+```
+
+## Step 5: Write index.json
+
+Write to `.planning/intel/index.json`:
+```javascript
+{
+  "version": 1,
+  "updated": 1737360330000,
+  "files": {
+    "/absolute/path/to/file.js": {
+      "exports": ["functionA", "ClassB"],
+      "imports": ["react", "./utils"],
+      "indexed": 1737360330000
+    }
+  }
+}
+```
+
+## Step 6: Write conventions.json
+
+Write to `.planning/intel/conventions.json`:
+```javascript
+{
+  "version": 1,
+  "updated": 1737360330000,
+  "naming": {
+    "exports": {
+      "dominant": "camelCase",
+      "count": 42,
+      "percentage": 85
+    }
+  },
+  "directories": {
+    "components": { "purpose": "UI components", "files": 15 },
+    "hooks": { "purpose": "React/custom hooks", "files": 8 }
+  },
+  "suffixes": {
+    ".test.js": { "purpose": "Test files", "count": 12 }
+  }
+}
+```
+
+## Step 7: Generate summary.md
+
+Write to `.planning/intel/summary.md`:
+
+```markdown
+# Codebase Intelligence Summary
+
+Last updated: [ISO timestamp]
+Indexed files: [N]
+
+## Naming Conventions
+
+- Export naming: [case] ([percentage]% of [count] exports)
+
+## Key Directories
+
+- `[dir]/`: [purpose] ([N] files)
+- ... (top 5)
+
+## File Patterns
+
+- `*[suffix]`: [purpose] ([count] files)
+- ... (top 3)
+
+Total exports: [N]
+```
+
+Target: < 500 tokens. Keep concise for context injection.
+
+## Step 8: Report completion
+
+Display summary statistics:
+
+```
+Codebase Analysis Complete
+
+Files indexed: [N]
+Exports found: [N]
+Imports found: [N]
+
+Conventions detected:
+- Naming: [dominant case] ([percentage]%)
+- Directories: [list]
+- Patterns: [list]
+
+Files created:
+- .planning/intel/index.json
+- .planning/intel/conventions.json
+- .planning/intel/summary.md
+```
+
+## Step 9: Generate semantic entities (optional)
+
+Generate entity files that capture semantic understanding of key files. These provide PURPOSE, not just syntax.
+
+**Skip this step if:** User only wants the index, or codebase has < 10 files.
+
+### 9.1 Create entities directory
+
+```bash
+mkdir -p .planning/intel/entities
+```
+
+### 9.2 Select files for entity generation
+
+Select up to 50 files based on these criteria (in priority order):
+
+1. **High-export files:** 3+ exports (likely core modules)
+2. **Hub files:** Referenced by 5+ other files (via imports analysis)
+3. **Key directories:** Entry points (index.js, main.js, app.js), config files
+4. **Structural files:** Files matching convention patterns (services, controllers, models)
+
+From the index.json, identify candidates and limit to 50 files maximum per run.
+
+### 9.3 Generate entities via Task tool batching
+
+Process selected files in **batches of 10** using the Task tool to spawn subagents.
+
+For each batch, spawn a Task with this instruction:
+
+```
+Generate semantic entity files for these source files:
+[list of 10 absolute file paths]
+
+For each file:
+1. Read the file content
+2. Write an entity markdown file to .planning/intel/entities/
+
+Entity filename convention (slug):
+- Take the relative path from project root
+- Replace / with --
+- Replace . with -
+- Example: src/utils/auth.js -> src--utils--auth-js.md
+
+Entity template:
+---
+source: [absolute path]
+indexed: [ISO timestamp]
+---
+
+# [filename]
+
+## Purpose
+
+[1-2 sentences: What does this file DO? Why does it exist? What problem does it solve?]
+
+## Exports
+
+| Name | Type | Purpose |
+|------|------|---------|
+| [export] | [function/class/const/type] | [what it does] |
+
+## Dependencies
+
+| Import | Purpose |
+|--------|---------|
+| [import source] | [why this file needs it] |
+
+## Used By
+
+[If this file is imported by others in the codebase, list the key consumers and why they use it. Otherwise: "Entry point" or "Utility - used across codebase"]
+
+---
+
+Focus on PURPOSE and semantic understanding, not just listing syntax.
+```
+
+### 9.4 Verify entity generation
+
+After all batches complete:
+
+```bash
+ls .planning/intel/entities/*.md | wc -l
+```
+
+Confirm entity count matches expected file count.
+
+### 9.5 Report entity statistics
+
+```
+Entity Generation Complete
+
+Entity files created: [N]
+Location: .planning/intel/entities/
+
+Batches processed: [N]
+Files per batch: 10
+
+Next: Intel hooks will continue incremental learning as you code.
+```
+
+</process>
+
+<output>
+- .planning/intel/index.json - File index with exports and imports
+- .planning/intel/conventions.json - Detected naming and structural patterns
+- .planning/intel/summary.md - Concise summary for context injection
+- .planning/intel/entities/*.md - Semantic entity files (optional, Step 9)
+</output>
+
+<success_criteria>
+- [ ] .planning/intel/ directory created
+- [ ] All JS/TS files scanned (excluding node_modules, dist, build, .git, vendor, coverage)
+- [ ] index.json populated with exports and imports for each file
+- [ ] conventions.json has detected patterns (naming, directories, suffixes)
+- [ ] summary.md is concise (< 500 tokens)
+- [ ] Statistics reported to user
+- [ ] Entity files generated for key files (if Step 9 executed)
+- [ ] Entity files contain Purpose section with semantic understanding
+</success_criteria>

package/commands/gsd/audit-milestone.md

@@ -39,6 +39,24 @@ Glob: .planning/phases/*/*-VERIFICATION.md
 
 <process>
 
+## 0. Resolve Model Profile
+
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-integration-checker | sonnet | sonnet | haiku |
+
+Store resolved model for use in Task call below.
+
 ## 1. Determine Milestone Scope
 
 ```bash
@@ -83,7 +101,8 @@ Phase exports: {from SUMMARYs}
 API routes: {routes created}
 
 Verify cross-phase wiring and E2E user flows.",
-  subagent_type="gsd-integration-checker"
+  subagent_type="gsd-integration-checker",
+  model="{integration_checker_model}"
 )
 ```
 

package/commands/gsd/check-todos.md

@@ -177,6 +177,17 @@ Update STATE.md "### Pending Todos" section if exists.
 <step name="git_commit">
 If todo was moved to done/, commit the change:
 
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo moved (not committed - commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 ```bash
 git add .planning/todos/done/[filename]
 git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true

package/commands/gsd/debug.md

@@ -28,6 +28,24 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 
 <process>
 
+## 0. Resolve Model Profile
+
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-debugger | opus | sonnet | sonnet |
+
+Store resolved model for use in Task calls below.
+
 ## 1. Check Active Sessions
 
 If active sessions exist AND no $ARGUMENTS:
@@ -82,6 +100,7 @@ Create: .planning/debug/{slug}.md
 Task(
   prompt=filled_prompt,
   subagent_type="gsd-debugger",
+  model="{debugger_model}",
   description="Debug {slug}"
 )
 ```
@@ -134,6 +153,7 @@ goal: find_and_fix
 Task(
   prompt=continuation_prompt,
   subagent_type="gsd-debugger",
+  model="{debugger_model}",
   description="Continue debug {slug}"
 )
 ```

package/commands/gsd/execute-phase.md

@@ -38,6 +38,24 @@ Phase: $ARGUMENTS
 </context>
 
 <process>
+0. **Resolve Model Profile**
+
+   Read model profile for agent spawning:
+   ```bash
+   MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+   ```
+
+   Default to "balanced" if not set.
+
+   **Model lookup table:**
+
+   | Agent | quality | balanced | budget |
+   |-------|---------|----------|--------|
+   | gsd-executor | opus | sonnet | sonnet |
+   | gsd-verifier | sonnet | sonnet | haiku |
+
+   Store resolved models for use in Task calls below.
+
 1. **Validate phase exists**
    - Find phase directory matching argument
    - Count PLAN.md files
@@ -79,6 +97,11 @@ Phase: $ARGUMENTS
    **If clean:** Continue to verification.
 
 7. **Verify phase goal**
+   Check config: `WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")`
+
+   **If `workflow.verifier` is `false`:** Skip to step 8 (treat as passed).
+
+   **Otherwise:**
    - Spawn `gsd-verifier` subagent with phase directory and goal
    - Verifier checks must_haves against actual codebase (not SUMMARY claims)
    - Creates VERIFICATION.md with detailed report
@@ -99,7 +122,9 @@ Phase: $ARGUMENTS
    - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
 10. **Commit phase completion**
-    Bundle all phase metadata updates in one commit:
+    Check `COMMIT_PLANNING_DOCS` from config.json (default: true).
+    If false: Skip git operations for .planning/ files.
+    If true: Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
@@ -228,12 +253,22 @@ After user runs /gsd:plan-phase {Z} --gaps:
 <wave_execution>
 **Parallel spawning:**
 
-Spawn all plans in a wave with a single message containing multiple Task calls:
+Before spawning, read file contents. The `@` syntax does not work across Task() boundaries.
+
+```bash
+# Read each plan and STATE.md
+PLAN_01_CONTENT=$(cat "{plan_01_path}")
+PLAN_02_CONTENT=$(cat "{plan_02_path}")
+PLAN_03_CONTENT=$(cat "{plan_03_path}")
+STATE_CONTENT=$(cat .planning/STATE.md)
+```
+
+Spawn all plans in a wave with a single message containing multiple Task calls, with inlined content:
 
 ```
-Task(prompt="Execute plan at {plan_01_path}\n\nPlan: @{plan_01_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
-Task(prompt="Execute plan at {plan_02_path}\n\nPlan: @{plan_02_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
-Task(prompt="Execute plan at {plan_03_path}\n\nPlan: @{plan_03_path}\nProject state: @.planning/STATE.md", subagent_type="gsd-executor")
+Task(prompt="Execute plan at {plan_01_path}\n\nPlan:\n{plan_01_content}\n\nProject state:\n{state_content}", subagent_type="gsd-executor", model="{executor_model}")
+Task(prompt="Execute plan at {plan_02_path}\n\nPlan:\n{plan_02_content}\n\nProject state:\n{state_content}", subagent_type="gsd-executor", model="{executor_model}")
+Task(prompt="Execute plan at {plan_03_path}\n\nPlan:\n{plan_03_content}\n\nProject state:\n{state_content}", subagent_type="gsd-executor", model="{executor_model}")
 ```
 
 All three run in parallel. Task tool blocks until all complete.

package/commands/gsd/help.md

@@ -76,6 +76,17 @@ Map an existing codebase for brownfield projects.
 
 Usage: `/gsd:map-codebase`
 
+**`/gsd:analyze-codebase`**
+Bootstrap codebase intelligence for existing projects.
+
+- Scans all JS/TS files and extracts exports/imports
+- Detects naming conventions, directory patterns, file suffixes
+- Creates `.planning/intel/` with index, conventions, and summary
+- Works standalone (no `/gsd:new-project` required)
+- After initial scan, PostToolUse hook continues incremental learning
+
+Usage: `/gsd:analyze-codebase`
+
 ### Phase Planning
 
 **`/gsd:discuss-phase <number>`**
@@ -274,6 +285,73 @@ List pending todos and select one to work on.
 Usage: `/gsd:check-todos`
 Usage: `/gsd:check-todos api`
 
+### User Acceptance Testing
+
+**`/gsd:verify-work [phase]`**
+Validate built features through conversational UAT.
+
+- Extracts testable deliverables from SUMMARY.md files
+- Presents tests one at a time (yes/no responses)
+- Automatically diagnoses failures and creates fix plans
+- Ready for re-execution if issues found
+
+Usage: `/gsd:verify-work 3`
+
+### Milestone Auditing
+
+**`/gsd:audit-milestone [version]`**
+Audit milestone completion against original intent.
+
+- Reads all phase VERIFICATION.md files
+- Checks requirements coverage
+- Spawns integration checker for cross-phase wiring
+- Creates MILESTONE-AUDIT.md with gaps and tech debt
+
+Usage: `/gsd:audit-milestone`
+
+**`/gsd:plan-milestone-gaps`**
+Create phases to close gaps identified by audit.
+
+- Reads MILESTONE-AUDIT.md and groups gaps into phases
+- Prioritizes by requirement priority (must/should/nice)
+- Adds gap closure phases to ROADMAP.md
+- Ready for `/gsd:plan-phase` on new phases
+
+Usage: `/gsd:plan-milestone-gaps`
+
+### Configuration
+
+**`/gsd:settings`**
+Configure workflow toggles and model profile interactively.
+
+- Toggle researcher, plan checker, verifier agents
+- Select model profile (quality/balanced/budget)
+- Updates `.planning/config.json`
+
+Usage: `/gsd:settings`
+
+**`/gsd:set-profile <profile>`**
+Quick switch model profile for GSD agents.
+
+- `quality` — Opus everywhere except verification
+- `balanced` — Opus for planning, Sonnet for execution (default)
+- `budget` — Sonnet for writing, Haiku for research/verification
+
+Usage: `/gsd:set-profile budget`
+
+### Codebase Intelligence
+
+**`/gsd:query-intel <type> [path]`**
+Query the codebase intelligence graph database.
+
+- `dependents <file>` — What files depend on this? (blast radius)
+- `hotspots` — Which files have the most dependents?
+
+Requires `/gsd:analyze-codebase` to build the graph first.
+
+Usage: `/gsd:query-intel dependents src/lib/db.ts`
+Usage: `/gsd:query-intel hotspots`
+
 ### Utility Commands
 
 **`/gsd:help`**
@@ -289,6 +367,15 @@ See what's changed since your installed version.
 
 Usage: `/gsd:whats-new`
 
+**`/gsd:update`**
+Update GSD to latest version with changelog preview.
+
+- Shows what changed before updating
+- Confirms before running install
+- Better than raw `npx get-shit-done-cc`
+
+Usage: `/gsd:update`
+
 ## Files & Structure
 
 ```
@@ -302,6 +389,10 @@ Usage: `/gsd:whats-new`
 │   └── done/             # Completed todos
 ├── debug/                # Active debug sessions
 │   └── resolved/         # Archived resolved issues
+├── intel/                # Codebase intelligence (auto-populated)
+│   ├── index.json        # File exports and imports
+│   ├── conventions.json  # Detected patterns
+│   └── summary.md        # Context for session injection
 ├── codebase/             # Codebase map (brownfield projects)
 │   ├── STACK.md          # Languages, frameworks, dependencies
 │   ├── ARCHITECTURE.md   # Patterns, layers, data flow
@@ -337,6 +428,33 @@ Set during `/gsd:new-project`:
 
 Change anytime by editing `.planning/config.json`
 
+## Planning Configuration
+
+Configure how planning artifacts are managed in `.planning/config.json`:
+
+**`planning.commit_docs`** (default: `true`)
+- `true`: Planning artifacts committed to git (standard workflow)
+- `false`: Planning artifacts kept local-only, not committed
+
+When `commit_docs: false`:
+- Add `.planning/` to your `.gitignore`
+- Useful for OSS contributions, client projects, or keeping planning private
+- All planning files still work normally, just not tracked in git
+
+**`planning.search_gitignored`** (default: `false`)
+- `true`: Add `--no-ignore` to broad ripgrep searches
+- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
+
+Example config:
+```json
+{
+  "planning": {
+    "commit_docs": false,
+    "search_gitignored": true
+  }
+}
+```
+
 ## Common Workflows
 
 **Starting a new project:**