get-shit-done-cc 1.9.0 → 1.9.1

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/commands/gsd/analyze-codebase.md

@@ -29,11 +29,13 @@ This command performs bulk codebase scanning to bootstrap the Codebase Intellige
 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)
+- 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>
@@ -265,81 +267,126 @@ Select up to 50 files based on these criteria (in priority order):
 
 From the index.json, identify candidates and limit to 50 files maximum per run.
 
-### 9.3 Generate entities via Task tool batching
+### 9.3 Spawn entity generator subagent
 
-Process selected files in **batches of 10** using the Task tool to spawn subagents.
+Spawn `gsd-entity-generator` with the selected file list.
 
-For each batch, spawn a Task with this instruction:
+**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)
 
-```
-Generate semantic entity files for these source files:
-[list of 10 absolute file paths]
+**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.
 
-For each file:
-1. Read the file content
-2. Write an entity markdown file to .planning/intel/entities/
+You are a GSD entity generator. Read source files and create semantic documentation that captures PURPOSE (what/why), not just syntax.
 
-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
+**Parameters:**
+- Files to process: {len(selected_files)}
+- Output directory: .planning/intel/entities/
+- Date: {today}
 
-Entity template:
+**Slug convention:**
+- Remove leading /
+- Remove file extension
+- Replace / and . with -
+- Lowercase everything
+- Example: src/lib/db.ts -> src-lib-db
+
+**Entity template:**
+```markdown
 ---
-source: [absolute path]
-indexed: [ISO timestamp]
+path: {{absolute_path}}
+type: [module|component|util|config|api|hook|service|model|test]
+updated: {today}
+status: active
 ---
 
-# [filename]
+# {{filename}}
 
 ## Purpose
 
-[1-2 sentences: What does this file DO? Why does it exist? What problem does it solve?]
+[1-3 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] |
+- `functionName(params): ReturnType` - Brief description
+- `ClassName` - What this class represents
+
+If no exports: "None"
 
 ## Dependencies
 
-| Import | Purpose |
-|--------|---------|
-| [import source] | [why this file needs it] |
+- [[internal-file-slug]] - Why needed (for internal deps)
+- external-package - What it provides (for npm packages)
+
+If no dependencies: "None"
 
 ## 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"]
+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
 
-Focus on PURPOSE and semantic understanding, not just listing syntax.
+**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
 
-After all batches complete:
+Confirm entities were written:
 
 ```bash
-ls .planning/intel/entities/*.md | wc -l
+ls .planning/intel/entities/*.md 2>/dev/null | wc -l
 ```
 
-Confirm entity count matches expected file count.
-
 ### 9.5 Report entity statistics
 
 ```
 Entity Generation Complete
 
-Entity files created: [N]
+Entity files created: [N] (from subagent response)
 Location: .planning/intel/entities/
+Graph database: Updated automatically via PostToolUse hook
 
-Batches processed: [N]
-Files per batch: 10
-
-Next: Intel hooks will continue incremental learning as you code.
+Next: Intel hooks will continue incremental updates as you code.
 ```
 
 </process>

package/hooks/dist/gsd-statusline.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Claude Code Statusline - GSD Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = Math.max(0, Math.min(100, 100 - rem));
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs.readdirSync(todosDir)
+        .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+          const inProgress = todos.find(t => t.status === 'in_progress');
+          if (inProgress) task = inProgress.activeForm || '';
+        } catch (e) {}
+      }
+    }
+
+    // GSD update available?
+    let gsdUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'gsd-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          gsdUpdate = '\x1b[33m⬆ /gsd:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"

package/scripts/build-hooks.js

@@ -23,7 +23,7 @@ const HOOKS_TO_COPY = [
   'gsd-intel-session.js',
   'gsd-intel-prune.js',
   'gsd-check-update.js',
-  'statusline.js'
+  'gsd-statusline.js'
 ];
 
 async function build() {