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.
+
+
+
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.
+
+
+