msd-core/.planning/phases/05-subagent-codebase-analysis/05-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
05-subagent-codebase-analysis	01	execute	1		agents/gsd-entity-generator.md	true	truths artifacts key_links 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) path provides contains agents/gsd-entity-generator.md Subagent definition for semantic entity generation gsd-entity-generator from to via pattern agents/gsd-entity-generator.md .planning/intel/entities/ Write tool calls 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

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.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:

---
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)

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

After completion, create `.planning/phases/05-subagent-codebase-analysis/05-01-SUMMARY.md`