get-shit-done-cc 1.8.0 → 1.9.1

package/commands/gsd/analyze-codebase.md

@@ -0,0 +1,410 @@
+---
+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):**
+- Orchestrator selects files for entity generation (up to 50 based on priority)
+- Spawns `gsd-entity-generator` subagent with file list (paths only, not contents)
+- Subagent reads files in fresh 200k context, generates entities, writes to disk
+- PostToolUse hook automatically syncs entities to graph.db
+- Subagent returns statistics only (not entity contents)
+- This preserves orchestrator context for large codebases (500+ files)
+- Users can skip Step 9 if they only want the index (faster)
+</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 Spawn entity generator subagent
+
+Spawn `gsd-entity-generator` with the selected file list.
+
+**Pass to subagent:**
+- Total file count
+- Output directory: `.planning/intel/entities/`
+- Slug convention: `src/lib/db.ts` -> `src-lib-db` (replace / with -, remove extension, lowercase)
+- Entity template (include full template from agent definition)
+- List of absolute file paths (one per line)
+
+**Task tool invocation:**
+
+```python
+# Build file list (one absolute path per line)
+file_list = "\n".join(selected_files)
+today = date.today().isoformat()
+
+Task(
+  prompt=f"""Generate semantic entity documentation for key codebase files.
+
+You are a GSD entity generator. Read source files and create semantic documentation that captures PURPOSE (what/why), not just syntax.
+
+**Parameters:**
+- Files to process: {len(selected_files)}
+- Output directory: .planning/intel/entities/
+- Date: {today}
+
+**Slug convention:**
+- Remove leading /
+- Remove file extension
+- Replace / and . with -
+- Lowercase everything
+- Example: src/lib/db.ts -> src-lib-db
+
+**Entity template:**
+```markdown
+---
+path: {{absolute_path}}
+type: [module|component|util|config|api|hook|service|model|test]
+updated: {today}
+status: active
+---
+
+# {{filename}}
+
+## Purpose
+
+[1-3 sentences: What does this file do? Why does it exist? What problem does it solve?]
+
+## Exports
+
+- `functionName(params): ReturnType` - Brief description
+- `ClassName` - What this class represents
+
+If no exports: "None"
+
+## Dependencies
+
+- [[internal-file-slug]] - Why needed (for internal deps)
+- external-package - What it provides (for npm packages)
+
+If no dependencies: "None"
+
+## Used By
+
+TBD
+```
+
+**Process:**
+For each file path below:
+1. Read file content using Read tool
+2. Analyze purpose, exports, dependencies
+3. Check if entity already exists (skip if so)
+4. Write entity to .planning/intel/entities/{{slug}}.md
+5. PostToolUse hook syncs to graph.db automatically
+
+**Files:**
+{file_list}
+
+**Return format:**
+When complete, return ONLY statistics:
+
+## ENTITY GENERATION COMPLETE
+
+**Files processed:** {{N}}
+**Entities created:** {{M}}
+**Already existed:** {{K}}
+**Errors:** {{E}}
+
+Entities written to: .planning/intel/entities/
+
+Do NOT include entity contents in your response.
+""",
+  subagent_type="gsd-entity-generator"
+)
+```
+
+**Wait for completion:** Task() blocks until subagent finishes.
+
+**Parse result:** Extract entities_created count from response for final report.
+
+### 9.4 Verify entity generation
+
+Confirm entities were written:
+
+```bash
+ls .planning/intel/entities/*.md 2>/dev/null | wc -l
+```
+
+### 9.5 Report entity statistics
+
+```
+Entity Generation Complete
+
+Entity files created: [N] (from subagent response)
+Location: .planning/intel/entities/
+Graph database: Updated automatically via PostToolUse hook
+
+Next: Intel hooks will continue incremental updates 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/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
@@ -230,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