get-shit-done-cc 1.9.1 → 1.9.2

package/agents/gsd-entity-generator.md

@@ -1,237 +0,0 @@
----
-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

@@ -1,410 +0,0 @@
----
-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>