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>
This commit is contained in:
Lex Christopherson
@@ -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*
|
||||
|
||||
164
.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md
Normal file
164
.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md
Normal file
@@ -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>
|
||||
219
.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md
Normal file
219
.planning/phases/05-subagent-codebase-analysis/05-02-PLAN.md
Normal file
@@ -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>
|
||||
Reference in New Issue
Block a user