get-shit-done-cc 1.8.0 → 1.9.0

package/README.md

@@ -324,6 +324,50 @@ Use for: bug fixes, small features, config changes, one-off tasks.
 
 ## Why It Works
 
+### Codebase Intelligence
+
+GSD learns your codebase patterns automatically. As Claude writes code, a PostToolUse hook indexes exports and imports, detects naming conventions, and builds a semantic understanding of your codebase.
+
+**How it works:**
+
+1. **Automatic learning** — Every time Claude writes or edits a JS/TS file, the hook extracts exports/imports and updates `.planning/intel/index.json`
+2. **Convention detection** — Analyzes exports for naming patterns (camelCase, PascalCase, etc.), identifies directory purposes, detects file suffixes
+3. **Graph database** — Stores entity relationships in SQLite for dependency analysis
+4. **Context injection** — At session start, injects a summary into Claude's context so it knows your codebase structure and conventions
+
+**For existing codebases:**
+
+```
+/gsd:analyze-codebase
+```
+
+Performs a bulk scan of your codebase to bootstrap the intelligence layer. Works standalone — no `/gsd:new-project` required. After initial analysis, hooks continue incremental learning.
+
+**Query the graph:**
+
+```
+/gsd:query-intel dependents src/lib/db.ts   # What depends on this file?
+/gsd:query-intel hotspots                    # Most-depended-on files
+```
+
+**Files created:**
+
+| File | Purpose |
+|------|---------|
+| `.planning/intel/index.json` | File exports and imports index |
+| `.planning/intel/conventions.json` | Detected patterns (naming, directories, suffixes) |
+| `.planning/intel/graph.db` | SQLite database with entity relationships |
+| `.planning/intel/summary.md` | Concise context for session injection |
+
+**Benefits:**
+
+- Claude follows your naming conventions automatically
+- New files go in the right directories
+- Consistency maintained across sessions
+- Query blast radius before refactoring
+- Identify high-impact hotspot files
+- No manual documentation of patterns needed
+
 ### Context Engineering
 
 Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.
@@ -416,6 +460,7 @@ You're never locked in. The system adapts.
 | `/gsd:plan-phase [N]` | Research + plan + verify for a phase |
 | `/gsd:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
 | `/gsd:verify-work [N]` | Manual user acceptance testing ¹ |
+| `/gsd:audit-milestone` | Verify milestone achieved its definition of done |
 | `/gsd:complete-milestone` | Archive milestone, tag release |
 | `/gsd:new-milestone [name]` | Start next version: questions → research → requirements → roadmap |
 
@@ -425,12 +470,16 @@ You're never locked in. The system adapts.
 |---------|--------------|
 | `/gsd:progress` | Where am I? What's next? |
 | `/gsd:help` | Show all commands and usage guide |
+| `/gsd:whats-new` | See what changed since your installed version |
+| `/gsd:update` | Update GSD with changelog preview |
 
 ### Brownfield
 
 | Command | What it does |
 |---------|--------------|
 | `/gsd:map-codebase` | Analyze existing codebase before new-project |
+| `/gsd:analyze-codebase` | Bootstrap codebase intelligence for existing projects |
+| `/gsd:query-intel <type>` | Query dependency graph (dependents, hotspots) |
 
 ### Phase Management
 
@@ -439,6 +488,8 @@ You're never locked in. The system adapts.
 | `/gsd:add-phase` | Append phase to roadmap |
 | `/gsd:insert-phase [N]` | Insert urgent work between phases |
 | `/gsd:remove-phase [N]` | Remove future phase, renumber |
+| `/gsd:list-phase-assumptions [N]` | See Claude's intended approach before planning |
+| `/gsd:plan-milestone-gaps` | Create phases to close gaps from audit |
 
 ### Session
 
@@ -451,6 +502,8 @@ You're never locked in. The system adapts.
 
 | Command | What it does |
 |---------|--------------|
+| `/gsd:settings` | Configure model profile and workflow agents |
+| `/gsd:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
 | `/gsd:add-todo [desc]` | Capture idea for later |
 | `/gsd:check-todos` | List pending todos |
 | `/gsd:debug [desc]` | Systematic debugging with persistent state |
@@ -460,6 +513,57 @@ You're never locked in. The system adapts.
 
 ---
 
+## Configuration
+
+GSD stores project settings in `.planning/config.json`. Configure during `/gsd:new-project` or update later with `/gsd:settings`.
+
+### Core Settings
+
+| Setting | Options | Default | What it controls |
+|---------|---------|---------|------------------|
+| `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
+| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) |
+
+### Model Profiles
+
+Control which Claude model each agent uses. Balance quality vs token spend.
+
+| Profile | Planning | Execution | Verification |
+|---------|----------|-----------|--------------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced` (default) | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
+
+Switch profiles:
+```
+/gsd:set-profile budget
+```
+
+Or configure via `/gsd:settings`.
+
+### Workflow Agents
+
+These spawn additional agents during planning/execution. They improve quality but add tokens and time.
+
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `workflow.research` | `true` | Researches domain before planning each phase |
+| `workflow.plan_check` | `true` | Verifies plans achieve phase goals before execution |
+| `workflow.verifier` | `true` | Confirms must-haves were delivered after execution |
+
+Use `/gsd:settings` to toggle these, or override per-invocation:
+- `/gsd:plan-phase --skip-research`
+- `/gsd:plan-phase --skip-verify`
+
+### Execution
+
+| Setting | Default | What it controls |
+|---------|---------|------------------|
+| `parallelization.enabled` | `true` | Run independent plans simultaneously |
+| `planning.commit_docs` | `true` | Track `.planning/` in git |
+
+---
+
 ## Troubleshooting
 
 **Commands not found after install?**

package/agents/gsd-executor.md

@@ -52,6 +52,21 @@ git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
 Store `COMMIT_PLANNING_DOCS` for use in git operations.
 </step>
 
+<step name="load_codebase_intelligence">
+Check for codebase intelligence:
+
+```bash
+cat .planning/intel/summary.md 2>/dev/null
+```
+
+If exists:
+- Follow detected naming conventions when writing code
+- Place new files in directories that match their purpose
+- Use established patterns (camelCase, PascalCase, etc.)
+
+This context helps maintain codebase consistency during execution.
+</step>
+
 <step name="load_plan">
 Read the plan file provided in your prompt context.
 

package/agents/gsd-planner.md

@@ -416,6 +416,9 @@ Output: [What artifacts will be created]
 @.planning/ROADMAP.md
 @.planning/STATE.md
 
+# Codebase intelligence (if exists)
+@.planning/intel/summary.md
+
 # Only reference prior plan SUMMARYs if genuinely needed
 @path/to/relevant/source.ts
 </context>
@@ -1036,6 +1039,25 @@ If exists, load relevant documents based on phase type:
 | (default) | STACK.md, ARCHITECTURE.md |
 </step>
 
+<step name="load_codebase_intelligence">
+Check for codebase intelligence:
+
+```bash
+cat .planning/intel/summary.md 2>/dev/null
+```
+
+If exists, this provides:
+- File count and structure overview
+- Detected naming conventions (use these when creating new files)
+- Key directories and their purposes
+- Export patterns
+
+**How to use:**
+- Follow detected naming conventions when planning new exports
+- Place new files in directories that match their purpose
+- Reference existing patterns when describing implementation
+</step>
+
 <step name="identify_phase">
 Check roadmap and existing phases:
 

package/bin/install.js

@@ -162,6 +162,7 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
 function cleanupOrphanedFiles(claudeDir) {
   const orphanedFiles = [
     'hooks/gsd-notify.sh',  // Removed in v1.6.x
+    'hooks/statusline.js',  // Renamed to gsd-statusline.js in v1.9.0
   ];
 
   for (const relPath of orphanedFiles) {
@@ -179,6 +180,7 @@ function cleanupOrphanedFiles(claudeDir) {
 function cleanupOrphanedHooks(settings) {
   const orphanedHookPatterns = [
     'gsd-notify.sh',  // Removed in v1.6.x
+    'hooks/statusline.js',  // Renamed to gsd-statusline.js in v1.9.0
   ];
 
   let cleaned = false;
@@ -353,19 +355,22 @@ function install(isGlobal) {
     failures.push('VERSION');
   }
 
-  // Copy hooks
-  const hooksSrc = path.join(src, 'hooks');
+  // Copy hooks from dist/ (bundled with dependencies)
+  const hooksSrc = path.join(src, 'hooks', 'dist');
   if (fs.existsSync(hooksSrc)) {
     const hooksDest = path.join(claudeDir, 'hooks');
     fs.mkdirSync(hooksDest, { recursive: true });
     const hookEntries = fs.readdirSync(hooksSrc);
     for (const entry of hookEntries) {
       const srcFile = path.join(hooksSrc, entry);
-      const destFile = path.join(hooksDest, entry);
-      fs.copyFileSync(srcFile, destFile);
+      // Only copy files, not directories
+      if (fs.statSync(srcFile).isFile()) {
+        const destFile = path.join(hooksDest, entry);
+        fs.copyFileSync(srcFile, destFile);
+      }
     }
     if (verifyInstalled(hooksDest, 'hooks')) {
-      console.log(`  ${green}✓${reset} Installed hooks`);
+      console.log(`  ${green}✓${reset} Installed hooks (bundled)`);
     } else {
       failures.push('hooks');
     }
@@ -382,8 +387,8 @@ function install(isGlobal) {
   const settingsPath = path.join(claudeDir, 'settings.json');
   const settings = cleanupOrphanedHooks(readSettings(settingsPath));
   const statuslineCommand = isGlobal
-    ? 'node "$HOME/.claude/hooks/statusline.js"'
-    : 'node .claude/hooks/statusline.js';
+    ? 'node "$HOME/.claude/hooks/gsd-statusline.js"'
+    : 'node .claude/hooks/gsd-statusline.js';
   const updateCheckCommand = isGlobal
     ? 'node "$HOME/.claude/hooks/gsd-check-update.js"'
     : 'node .claude/hooks/gsd-check-update.js';
@@ -413,6 +418,72 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Configured update check hook`);
   }
 
+  // Register intel hooks for codebase intelligence
+  const intelIndexCommand = isGlobal
+    ? 'node "$HOME/.claude/hooks/gsd-intel-index.js"'
+    : 'node .claude/hooks/gsd-intel-index.js';
+
+  const intelSessionCommand = isGlobal
+    ? 'node "$HOME/.claude/hooks/gsd-intel-session.js"'
+    : 'node .claude/hooks/gsd-intel-session.js';
+
+  // PostToolUse hook for indexing
+  if (!settings.hooks.PostToolUse) {
+    settings.hooks.PostToolUse = [];
+  }
+
+  const hasIntelIndexHook = settings.hooks.PostToolUse.some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-intel-index'))
+  );
+
+  if (!hasIntelIndexHook) {
+    settings.hooks.PostToolUse.push({
+      hooks: [{
+        type: 'command',
+        command: intelIndexCommand
+      }]
+    });
+    console.log(`  ${green}✓${reset} Configured intel indexing hook`);
+  }
+
+  // SessionStart hook for context injection
+  const hasIntelSessionHook = settings.hooks.SessionStart.some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-intel-session'))
+  );
+
+  if (!hasIntelSessionHook) {
+    settings.hooks.SessionStart.push({
+      hooks: [{
+        type: 'command',
+        command: intelSessionCommand
+      }]
+    });
+    console.log(`  ${green}✓${reset} Configured intel session hook`);
+  }
+
+  // Stop hook for pruning deleted files
+  const intelPruneCommand = isGlobal
+    ? 'node "$HOME/.claude/hooks/gsd-intel-prune.js"'
+    : 'node .claude/hooks/gsd-intel-prune.js';
+
+  if (!settings.hooks.Stop) {
+    settings.hooks.Stop = [];
+  }
+
+  const hasIntelPruneHook = settings.hooks.Stop.some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-intel-prune'))
+  );
+
+  if (!hasIntelPruneHook) {
+    settings.hooks.Stop.push({
+      hooks: [{
+        type: 'command',
+        command: intelPruneCommand
+      }]
+    });
+    console.log(`  ${green}✓${reset} Configured intel prune hook`);
+  }
+
   return { settingsPath, settings, statuslineCommand };
 }
 

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>