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 <noreply@anthropic.com>
2026-01-20 11:44:32 -06:00
parent 701b10d5f9
commit d994732a45
3 changed files with 429 additions and 9 deletions
--- a/.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md
+++ 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"
+---
+
+<objective>
+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`
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/05-subagent-codebase-analysis/05-RESEARCH.md
+@agents/gsd-codebase-mapper.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create gsd-entity-generator agent definition</name>
+  <files>agents/gsd-entity-generator.md</files>
+  <action>
+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)
+  </action>
+  <verify>
+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
+  </verify>
+  <done>
+`agents/gsd-entity-generator.md` exists with complete agent definition following gsd-codebase-mapper pattern. Agent is ready to be spawned by analyze-codebase.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- [ ] 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)
+</verification>
+
+<success_criteria>
+gsd-entity-generator agent definition complete. Agent can be spawned with file paths and will generate semantic entities, writing directly to disk.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-subagent-codebase-analysis/05-01-SUMMARY.md`
+</output>
--- a/.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md
+++ 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"
+---
+
+<objective>
+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`
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.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
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Refactor Step 9 to use subagent delegation</name>
+  <files>commands/gsd/analyze-codebase.md</files>
+  <action>
+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).
+  </action>
+  <verify>
+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
+  </verify>
+  <done>
+analyze-codebase.md Step 9 refactored. Entity generation now delegates to gsd-entity-generator subagent instead of inline Task batching.
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Subagent delegation for entity generation in /gsd:analyze-codebase</what-built>
+  <how-to-verify>
+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)
+  </how-to-verify>
+  <resume-signal>Type "approved" if entity generation works via subagent, or describe issues</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+- [ ] 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
+</verification>
+
+<success_criteria>
+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.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/05-subagent-codebase-analysis/05-02-SUMMARY.md`
+</output>