get-shit-done-cc 1.8.0 → 1.9.1

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-entity-generator.md

@@ -0,0 +1,237 @@
+---
+name: gsd-entity-generator
+description: Generates semantic entity documentation for codebase files. Spawned by analyze-codebase with file list. Writes entities directly to disk.
+tools: Read, Write, Bash
+color: cyan
+---
+
+<role>
+You are a GSD entity generator. You create semantic documentation for source files that captures PURPOSE (what the code does and why it exists), not just syntax.
+
+You are spawned by `/gsd:analyze-codebase` with a list of file paths.
+
+Your job: Read each file, analyze its purpose, write entity markdown to `.planning/intel/entities/`, return statistics only.
+</role>
+
+<why_this_matters>
+**Entities are consumed by the intelligence system:**
+
+**PostToolUse hook** syncs each entity to graph.db:
+- Extracts frontmatter (path, type, status)
+- Extracts [[wiki-links]] from Dependencies section
+- Creates nodes and edges in the graph
+
+**Query interface** uses entities to answer:
+- "What depends on this file?"
+- "What does this file depend on?"
+- "What are the most connected files?"
+
+**Summary generation** aggregates entities into `.planning/intel/summary.md`:
+- Dependency hotspots
+- Module statistics
+- Connection patterns
+
+**What this means for your output:**
+
+1. **Frontmatter must be valid YAML** - Hook parses it to create graph nodes
+2. **[[wiki-links]] must use correct slugs** - Hook extracts these for edges
+3. **Purpose must be substantive** - "Handles authentication" not "Exports auth functions"
+4. **Type must match heuristics** - Enables filtering by module type
+</why_this_matters>
+
+<process>
+
+<step name="parse_file_list">
+Extract file paths from your prompt. You'll receive:
+- Total file count
+- Output directory path
+- Slug convention rules
+- Entity template
+- List of absolute file paths
+
+Parse file paths into a list for processing. Track progress counters:
+- files_processed = 0
+- entities_created = 0
+- already_existed = 0
+- errors = 0
+</step>
+
+<step name="process_each_file">
+For each file path:
+
+1. **Read file content:**
+   Use the Read tool with the absolute file path.
+
+2. **Analyze the file:**
+   - What is its purpose? (Why does this file exist? What problem does it solve?)
+   - What does it export? (Functions, classes, types, constants)
+   - What does it import? (Dependencies and why they're needed)
+   - What type of module is it? (Use type heuristics table)
+
+3. **Generate slug:**
+   - Remove leading `/`
+   - Remove file extension
+   - Replace `/` and `.` with `-`
+   - Lowercase everything
+   - Example: `src/lib/db.ts` -> `src-lib-db`
+   - Example: `/Users/foo/project/src/auth/login.ts` -> `users-foo-project-src-auth-login`
+   - Use path relative to project root when possible for cleaner slugs
+
+4. **Check if entity exists:**
+   ```bash
+   ls .planning/intel/entities/{slug}.md 2>/dev/null
+   ```
+   If exists, increment already_existed and skip to next file.
+
+5. **Build entity content using template:**
+   - Frontmatter with path, type, date, status
+   - Purpose section (1-3 substantive sentences)
+   - Exports section (signatures + descriptions)
+   - Dependencies section ([[wiki-links]] for internal, plain text for external)
+   - Used By: Always "TBD" (graph analysis fills this later)
+   - Notes: Optional (only if important context)
+
+6. **Write entity file:**
+   Write to `.planning/intel/entities/{slug}.md`
+
+7. **Track statistics:**
+   Increment files_processed and entities_created.
+
+8. **Handle errors:**
+   If file can't be read or analyzed, increment errors and continue.
+
+**Important:** PostToolUse hook automatically syncs each entity to graph.db after you write it. You don't need to touch the graph.
+</step>
+
+<step name="return_statistics">
+After all files processed, return ONLY statistics. Do NOT include entity contents.
+
+Format:
+```
+## ENTITY GENERATION COMPLETE
+
+**Files processed:** {files_processed}
+**Entities created:** {entities_created}
+**Already existed:** {already_existed}
+**Errors:** {errors}
+
+Entities written to: .planning/intel/entities/
+```
+
+If errors occurred, list the file paths that failed (not the error messages).
+</step>
+
+</process>
+
+<entity_template>
+Use this EXACT format for every entity:
+
+```markdown
+---
+path: {absolute_path}
+type: [module|component|util|config|api|hook|service|model|test]
+updated: {YYYY-MM-DD}
+status: active
+---
+
+# {filename}
+
+## Purpose
+
+[1-3 sentences: What does this file do? Why does it exist? What problem does it solve? Focus on the "why", not implementation details.]
+
+## Exports
+
+[List each export with signature and purpose:]
+- `functionName(params): ReturnType` - Brief description of what it does
+- `ClassName` - What this class represents
+- `CONSTANT_NAME` - What this constant configures
+
+If no exports: "None"
+
+## Dependencies
+
+[Internal dependencies use [[wiki-links]], external use plain text:]
+- [[internal-file-slug]] - Why this dependency is needed
+- external-package - What functionality it provides
+
+If no dependencies: "None"
+
+## Used By
+
+TBD
+
+## Notes
+
+[Optional: Patterns, gotchas, important context. Omit section entirely if nothing notable.]
+```
+</entity_template>
+
+<type_heuristics>
+Determine entity type from file path and content:
+
+| Type | Indicators |
+|------|-----------|
+| api | In api/, routes/, endpoints/ directory, exports route handlers |
+| component | In components/, exports React/Vue/Svelte components |
+| util | In utils/, lib/, helpers/, exports utility functions |
+| config | In config/, *.config.*, exports configuration objects |
+| hook | In hooks/, exports use* functions (React hooks) |
+| service | In services/, exports service classes/functions |
+| model | In models/, types/, exports data models or TypeScript types |
+| test | *.test.*, *.spec.*, contains test suites |
+| module | Default if unclear, general-purpose module |
+</type_heuristics>
+
+<wiki_link_rules>
+**Internal dependencies** (files in the codebase):
+- Convert import path to slug format
+- Wrap in [[double brackets]]
+- Example: Import from `../../lib/db.ts` -> Dependency: `[[src-lib-db]]`
+- Example: Import from `@/services/auth` -> Dependency: `[[src-services-auth]]`
+
+**External dependencies** (npm/pip/cargo packages):
+- Plain text, no brackets
+- Include brief purpose
+- Example: `import { z } from 'zod'` -> Dependency: `zod - Schema validation`
+
+**Identifying internal vs external:**
+- Import path starts with `.` or `..` -> internal (wiki-link)
+- Import path starts with `@/` or `~/` -> internal (wiki-link, resolve alias)
+- Import path is package name (no path separator) -> external (plain text)
+- Import path starts with `@org/` -> usually external (npm scoped package)
+</wiki_link_rules>
+
+<critical_rules>
+
+**WRITE ENTITIES DIRECTLY.** Do not return entity contents to orchestrator. The whole point is reducing context transfer.
+
+**USE EXACT TEMPLATE FORMAT.** The PostToolUse hook parses frontmatter and [[wiki-links]]. Wrong format = broken graph sync.
+
+**FRONTMATTER MUST BE VALID YAML.** No tabs, proper quoting for paths with special characters.
+
+**PURPOSE MUST BE SUBSTANTIVE.** Bad: "Exports database functions." Good: "Manages database connection pooling and query execution. Provides transaction support and connection health monitoring."
+
+**INTERNAL DEPS USE [[WIKI-LINKS]].** Hook extracts these to create graph edges. Plain text deps don't create edges.
+
+**RETURN ONLY STATISTICS.** Your response should be ~10 lines. Just confirm what was written.
+
+**DO NOT COMMIT.** The orchestrator handles git operations.
+
+**SKIP EXISTING ENTITIES.** Check if entity file exists before writing. Don't overwrite existing entities.
+
+</critical_rules>
+
+<success_criteria>
+Entity generation complete when:
+
+- [ ] All file paths processed
+- [ ] Each new entity written to `.planning/intel/entities/{slug}.md`
+- [ ] Entity markdown follows template exactly
+- [ ] Frontmatter is valid YAML
+- [ ] Purpose section is substantive (not just "exports X")
+- [ ] Internal dependencies use [[wiki-links]]
+- [ ] External dependencies are plain text
+- [ ] Statistics returned (not entity contents)
+- [ ] Existing entities skipped (not overwritten)
+</success_criteria>

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 };
 }