From d994732a45c47615f533f643afbf07be44f9d79a Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 20 Jan 2026 11:44:32 -0600 Subject: [PATCH] docs(05): create phase plan for subagent codebase analysis Phase 05: Subagent Codebase Analysis - 2 plans in 2 waves - Plan 05-01: Create gsd-entity-generator subagent (Wave 1) - Plan 05-02: Refactor analyze-codebase to use subagent (Wave 2) - Ready for execution Co-Authored-By: Claude Opus 4.5 --- .planning/ROADMAP.md | 55 ++++- .../05-01-PLAN.md | 164 +++++++++++++ .../05-02-PLAN.md | 219 ++++++++++++++++++ 3 files changed, 429 insertions(+), 9 deletions(-) create mode 100644 .planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md create mode 100644 .planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index c915bf269..f546baca2 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -2,7 +2,7 @@ **Goal:** Make GSD feel intelligent and automagical in how it navigates and understands both greenfield and brownfield projects. -**Phases:** 4 (3 complete, 1 remaining) +**Phases:** 5 (4 complete) --- @@ -23,22 +23,22 @@ **Status:** Complete **Plans:** 3/3 -### Phase 4: Semantic Intelligence & Scale +### Phase 4: Semantic Intelligence & Scale ✓ **Goal:** Transform syntax-only indexing into semantic understanding with graph-based relationships - -**Depends on:** Phase 3 -**Plans:** 4 plans (3 core + 1 gap closure) +**Status:** Complete +**Plans:** 5/5 Plans: - [x] 04-01-PLAN.md — SQLite graph layer with sql.js (Wave 1) - [x] 04-02-PLAN.md — Graph-backed rich summary generation (Wave 2) - [x] 04-03-PLAN.md — Semantic entity generation via Claude API (Wave 2) -- [ ] 04-04-PLAN.md — CLI query interface for getDependents (Gap closure) +- [x] 04-04-PLAN.md — CLI query interface for getDependents (Wave 3) +- [x] 04-05-PLAN.md — Wire plan-phase.md to inject intel into planner (Wave 3) **Wave Structure:** - Wave 1: 04-01 (SQLite foundation) - Wave 2: 04-02, 04-03 (parallel - both depend only on 04-01) -- Gap closure: 04-04 (expose orphaned getDependents function) +- Wave 3: 04-04, 04-05 (parallel - consumption layer) **Why this phase:** - Current system provides "2-3 ls commands worth of information" (Claude's own assessment) @@ -64,6 +64,40 @@ Plans: 3. Transitive dependency queries work (blast radius) 4. Works at scale (500+ file codebases) +### Phase 5: Subagent Codebase Analysis +**Goal:** Prevent context exhaustion on large codebases by delegating analysis to subagents +**Depends on:** Phase 4 +**Plans:** 2 plans + +Plans: +- [ ] 05-01-PLAN.md — Create gsd-entity-generator subagent (Wave 1) +- [ ] 05-02-PLAN.md — Refactor analyze-codebase to use subagent delegation (Wave 2) + +**Wave Structure:** +- Wave 1: 05-01 (agent definition) +- Wave 2: 05-02 (command refactor + verification) + +**Why this phase:** +- Current entity generation loads file contents in orchestrator context +- On large codebases (500+ files), orchestrator exhausts context during file selection and batching +- Subagent delegation gives fresh 200k context for entity generation + +**Delivers:** +- `gsd-entity-generator` subagent following gsd-codebase-mapper pattern +- Refactored `/gsd:analyze-codebase` that spawns subagent instead of inline batching +- Preserved orchestrator context for large codebase analysis + +**Requirements:** +- INTEL-08: Entity generation delegated to subagent (not inline) +- INTEL-09: Subagent writes entities directly, returns statistics only +- INTEL-10: Orchestrator passes file paths, not file contents + +**Success Criteria:** +1. Entity generation works via subagent spawn +2. Orchestrator context preserved (no file contents loaded) +3. Entities correctly formatted and graph.db updated +4. Works on 500+ file codebases without context exhaustion + --- ## Traceability @@ -74,10 +108,13 @@ Plans: | INTEL-02 | Phase 2 | ✓ Complete | | INTEL-03 | Phase 3 | ✓ Complete | | INTEL-04 | Phase 4 | ✓ Complete (04-03) | -| INTEL-05 | Phase 4 | Gap closure (04-04) | +| INTEL-05 | Phase 4 | ✓ Complete (04-04) | | INTEL-06 | Phase 4 | ✓ Complete (04-03) | | INTEL-07 | Phase 4 | ✓ Complete (04-02) | +| INTEL-08 | Phase 5 | Planned (05-01, 05-02) | +| INTEL-09 | Phase 5 | Planned (05-01) | +| INTEL-10 | Phase 5 | Planned (05-02) | --- *Created: 2026-01-19* -*Updated: 2026-01-20 — Added 04-04 gap closure plan for CLI query interface* +*Updated: 2026-01-20 — Phase 5 planned with 2 plans in 2 waves* diff --git a/.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md b/.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md new file mode 100644 index 000000000..68fa465bc --- /dev/null +++ b/.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md @@ -0,0 +1,164 @@ +--- +phase: 05-subagent-codebase-analysis +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - agents/gsd-entity-generator.md +autonomous: true + +must_haves: + truths: + - "Entity generator agent definition exists following gsd-codebase-mapper pattern" + - "Agent reads files, generates semantic entities, writes directly to disk" + - "Agent returns statistics only (not entity contents)" + artifacts: + - path: "agents/gsd-entity-generator.md" + provides: "Subagent definition for semantic entity generation" + contains: "gsd-entity-generator" + key_links: + - from: "agents/gsd-entity-generator.md" + to: ".planning/intel/entities/" + via: "Write tool calls" + pattern: "Write.*entities" +--- + + +Create gsd-entity-generator subagent definition. + +Purpose: Define the subagent that generates semantic entity documentation for codebase files. This agent is spawned by `/gsd:analyze-codebase` with a list of file paths, reads each file, creates entity markdown, and writes directly to `.planning/intel/entities/`. + +Output: `agents/gsd-entity-generator.md` + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-subagent-codebase-analysis/05-RESEARCH.md +@agents/gsd-codebase-mapper.md + + + + + + Task 1: Create gsd-entity-generator agent definition + agents/gsd-entity-generator.md + +Create agent definition following gsd-codebase-mapper.md structure: + +**Frontmatter:** +```yaml +--- +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 section:** +- Spawned by `/gsd:analyze-codebase` with file paths +- Reads source files, analyzes purpose/exports/dependencies +- Writes entity markdown to `.planning/intel/entities/{slug}.md` +- Returns statistics only (NOT entity contents) + +**Process sections:** + +1. `parse_file_list` - Extract file paths from prompt + - Expect: total count, output directory, slug convention, template, file list + +2. `process_each_file` - For each file path: + - Read file using Read tool + - Analyze: purpose (why exists), exports (signatures), dependencies (internal [[wiki-links]], external plain text), module type + - Generate slug: `src/lib/db.ts` -> `src-lib-db` (replace / and . with -, remove extension, lowercase) + - Write entity to `.planning/intel/entities/{slug}.md` + - Track statistics (created, skipped, errors) + +3. `return_statistics` - Return ONLY: + ``` + ## ENTITY GENERATION COMPLETE + + **Files processed:** {N} + **Entities created:** {M} + **Already existed:** {K} + **Errors:** {E} + + Entities written to: .planning/intel/entities/ + ``` + +**Entity template section:** +Include the full entity template from 05-RESEARCH.md (frontmatter with path/type/updated/status, Purpose, Exports, Dependencies with [[wiki-links]], Used By = TBD, Notes optional). + +**Type heuristics table:** +| Type | Indicators | +|------|-----------| +| api | api/, routes/, endpoints/, route handlers | +| component | components/, React/Vue exports | +| util | utils/, lib/, helpers/ | +| config | config/, *.config.* | +| hook | hooks/, use* functions | +| service | services/ | +| model | models/, types/ | +| test | *.test.*, *.spec.* | +| module | default | + +**Wiki-link rules:** +- Internal (starts with `.` or `@/`): convert to slug, wrap in [[brackets]] +- External (package name): plain text, no brackets + +**Critical rules:** +- WRITE entities directly (never return contents) +- PostToolUse hook syncs to graph.db automatically +- Use EXACT template format (hook parses frontmatter + [[links]]) + +**Success criteria checklist** (from research): +- All file paths processed +- Each entity written to correct path +- Frontmatter is valid YAML +- Purpose section is substantive (not "exports X") +- Internal deps use [[wiki-links]] +- Statistics returned (not entity contents) + + +File exists and contains: +- Frontmatter with name, description, tools, color +- Role section explaining spawn context +- Process steps (parse, process, return) +- Entity template +- Type heuristics +- Wiki-link rules +- Critical rules matching gsd-codebase-mapper pattern + + +`agents/gsd-entity-generator.md` exists with complete agent definition following gsd-codebase-mapper pattern. Agent is ready to be spawned by analyze-codebase. + + + + + + +- [ ] File exists at `agents/gsd-entity-generator.md` +- [ ] Frontmatter valid YAML +- [ ] Role section explains subagent purpose +- [ ] Process has 3 steps: parse, process, return +- [ ] Entity template included in full +- [ ] Type heuristics table present +- [ ] Wiki-link rules specified +- [ ] Critical rules section matches gsd-codebase-mapper style +- [ ] Returns statistics only (not entity contents) + + + +gsd-entity-generator agent definition complete. Agent can be spawned with file paths and will generate semantic entities, writing directly to disk. + + + +After completion, create `.planning/phases/05-subagent-codebase-analysis/05-01-SUMMARY.md` + diff --git a/.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md b/.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md new file mode 100644 index 000000000..cecfd2222 --- /dev/null +++ b/.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md @@ -0,0 +1,219 @@ +--- +phase: 05-subagent-codebase-analysis +plan: 02 +type: execute +wave: 2 +depends_on: ["05-01"] +files_modified: + - commands/gsd/analyze-codebase.md +autonomous: false + +must_haves: + truths: + - "analyze-codebase Step 9 spawns gsd-entity-generator subagent" + - "Subagent receives file list (paths only, not contents)" + - "Orchestrator context is preserved (no file contents loaded)" + - "Entity generation completes and returns statistics" + artifacts: + - path: "commands/gsd/analyze-codebase.md" + provides: "Refactored command with subagent delegation" + contains: "gsd-entity-generator" + key_links: + - from: "commands/gsd/analyze-codebase.md" + to: "agents/gsd-entity-generator.md" + via: "Task tool spawn" + pattern: "Task.*gsd-entity-generator" +--- + + +Refactor analyze-codebase Step 9 to spawn subagent instead of inline batching. + +Purpose: Replace the current "batches of 10 via Task tool" approach with a single subagent spawn. The orchestrator selects files (Step 9.2) then spawns `gsd-entity-generator` with the file list. Subagent reads files, generates entities, writes to disk. This preserves orchestrator context for large codebases. + +Output: Updated `commands/gsd/analyze-codebase.md` + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-subagent-codebase-analysis/05-RESEARCH.md +@.planning/phases/05-subagent-codebase-analysis/05-01-SUMMARY.md +@commands/gsd/analyze-codebase.md +@agents/gsd-entity-generator.md + + + + + + Task 1: Refactor Step 9 to use subagent delegation + commands/gsd/analyze-codebase.md + +Modify Step 9 of analyze-codebase.md. Keep Steps 9.1 (create directory) and 9.2 (select files) unchanged. Replace Steps 9.3-9.5 with subagent spawn. + +**Remove:** Step 9.3 "Generate entities via Task tool batching" (the batch-of-10 pattern) + +**Replace with:** Step 9.3 "Spawn entity generator subagent" + +New Step 9.3 content: + +```markdown +### 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) +- List of absolute file paths (one per line) + +**Task tool invocation:** + +```python +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:** +- src/lib/db.ts -> src-lib-db +- Replace / with -, remove extension, lowercase + +**Entity template:** +[Include full template from gsd-entity-generator.md] + +**Process:** +For each file path below: +1. Read file content using Read tool +2. Analyze purpose, exports, dependencies +3. Write entity to .planning/intel/entities/{{slug}}.md +4. 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. +``` + +**Update Step 9.4:** Rename from "Verify entity generation" to just verify count: +```markdown +### 9.4 Verify entity generation + +Confirm entities written: + +```bash +ls .planning/intel/entities/*.md 2>/dev/null | wc -l +``` +``` + +**Update Step 9.5:** Keep "Report entity statistics" but update text: +```markdown +### 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. +``` +``` + +**Update context section** (line ~32) - add subagent reference: +```markdown +**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) +``` + +**Important:** Do NOT pass file contents to subagent. Pass file PATHS only. Subagent reads files itself (fresh context). + + +Read updated commands/gsd/analyze-codebase.md and confirm: +- Step 9.3 spawns gsd-entity-generator via Task tool +- No batch-of-10 pattern remains +- File paths passed, not file contents +- Context section mentions subagent delegation +- Steps 9.4-9.5 updated for new flow + + +analyze-codebase.md Step 9 refactored. Entity generation now delegates to gsd-entity-generator subagent instead of inline Task batching. + + + + + Subagent delegation for entity generation in /gsd:analyze-codebase + +1. Navigate to a test project (not this repo) +2. Run `/gsd:analyze-codebase` +3. Observe: + - Steps 1-8 complete (index, conventions, summary) + - Step 9.2 selects files (should see file list) + - Step 9.3 spawns subagent (Task tool call with "gsd-entity-generator") + - Subagent generates entities (should see Read/Write calls in subagent) + - Subagent returns statistics only (not entity contents) +4. Verify `.planning/intel/entities/` contains entity files +5. Verify entity files follow template (frontmatter, Purpose, Exports, Dependencies with [[links]]) +6. Verify graph.db was updated (entities appear in summary.md) + + Type "approved" if entity generation works via subagent, or describe issues + + + + + +- [ ] Step 9.3 spawns gsd-entity-generator subagent +- [ ] File paths passed to subagent (not file contents) +- [ ] No batch-of-10 pattern in command +- [ ] Context section documents subagent model +- [ ] Entity files created in test project +- [ ] Entities follow template format +- [ ] Graph database updated (via hook) +- [ ] User verification checkpoint passed + + + +analyze-codebase refactored to use subagent delegation. Entity generation works end-to-end on a test project, with orchestrator context preserved and entities written correctly. + + + +After completion, create `.planning/phases/05-subagent-codebase-analysis/05-02-SUMMARY.md` +