From b3db2ff909eeaeaab74a0cd494474e0bcd22cf64 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 20 Jan 2026 09:57:57 -0600 Subject: [PATCH] feat(04-03): add semantic entity generation to analyze-codebase - Add Step 9 for semantic entity file generation - Task tool batching for 100+ file codebases (10 files per batch) - 50 file limit per run to manage context - File selection criteria: 3+ exports, 5+ dependents, key directories - Entity slug convention: path--segments--filename-ext.md - Entity template with Purpose, Exports, Dependencies, Used By sections - Update objective, output, and success criteria for entities - Add context section explaining execution model Co-Authored-By: Claude Opus 4.5 --- commands/gsd/analyze-codebase.md | 117 +++++++++++++++++++++++++++++-- 1 file changed, 113 insertions(+), 4 deletions(-) diff --git a/commands/gsd/analyze-codebase.md b/commands/gsd/analyze-codebase.md index 34ccd3e6d..6a10da4b0 100644 --- a/commands/gsd/analyze-codebase.md +++ b/commands/gsd/analyze-codebase.md @@ -1,20 +1,21 @@ --- name: gsd:analyze-codebase -description: Scan existing codebase and populate .planning/intel/ with file index and conventions +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 --- -Scan codebase to populate .planning/intel/ with file index and conventions. +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. +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 +Output: .planning/intel/index.json, conventions.json, summary.md, entities/*.md @@ -26,6 +27,13 @@ This command performs bulk codebase scanning to bootstrap the Codebase Intellige - 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) @@ -232,6 +240,104 @@ 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. ``` @@ -242,6 +348,7 @@ Next: Intel hooks will continue incremental learning as you code. - .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) @@ -251,4 +358,6 @@ Next: Intel hooks will continue incremental learning as you code. - [ ] 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