golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

fix(04): revise plans based on checker feedback

Browse Source 
04-02: Added SessionStart hook wiring verification to Task 3 and
key_links. The hook already exists from Phase 2 - plan now verifies
it correctly injects the new graph-backed summary format.

04-03: Removed embedded JavaScript execution pattern. Commands are
instructions Claude follows, not scripts. Entity generation now uses
Task tool to spawn subagents for batch processing instead of pretending
markdown can execute JS.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-20 09:43:37 -06:00
parent e3d39c09e6
commit 3230fdfd2b
2 changed files with 138 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.planning/phases/04-semantic-intelligence/04-02-PLAN.md
View File

@@ -13,6 +13,7 @@ must_haves:
- "Summary includes dependency hotspots queried from SQLite" - "Summary includes dependency hotspots queried from SQLite"
- "Summary shows file purposes, not just file counts" - "Summary shows file purposes, not just file counts"
- "Transitive dependents queryable via recursive CTE" - "Transitive dependents queryable via recursive CTE"
- "SessionStart hook injects graph-backed summary into context"
artifacts: artifacts:
- path: "hooks/gsd-intel-index.js" - path: "hooks/gsd-intel-index.js"
provides: "Graph-backed summary generation" provides: "Graph-backed summary generation"
@@ -24,6 +25,10 @@ must_haves:
to: ".planning/intel/graph.db" to: ".planning/intel/graph.db"
via: "SQL queries for hotspots" via: "SQL queries for hotspots"
pattern: "SELECT.*FROM edges.*GROUP BY" pattern: "SELECT.*FROM edges.*GROUP BY"
- from: "hooks/gsd-intel-session.js"
to: ".planning/intel/summary.md"
via: "fs.readFileSync on startup/resume"
pattern: "readFileSync.*summary\\.md"
--- ---
<objective> <objective>
@@ -52,6 +57,11 @@ Summary generation requirements (from research):
- Group by type from node body - Group by type from node body
- Include file purposes from entity content - Include file purposes from entity content
- Target < 500 tokens for context injection - Target < 500 tokens for context injection
Existing wiring (from Phase 2):
- hooks/gsd-intel-session.js reads summary.md on startup/resume
- Injects content as <codebase-intelligence> tag into Claude's context
- This wiring already exists - we verify it works with new graph format
</context> </context>
<tasks> <tasks>
@@ -269,7 +279,7 @@ Key design notes:
</task> </task>
<task type="auto"> <task type="auto">
<name>Task 3: Integrate graph summary into regeneration flow</name> <name>Task 3: Integrate graph summary into regeneration flow and verify SessionStart wiring</name>
<files>hooks/gsd-intel-index.js</files> <files>hooks/gsd-intel-index.js</files>
<action> <action>
Modify regenerateEntitySummary() to prefer graph summary when available. Modify regenerateEntitySummary() to prefer graph summary when available.
@@ -333,7 +343,7 @@ if (isEntityFile(filePath)) {
Note: regenerateEntitySummary becomes async because it calls generateGraphSummary. Note: regenerateEntitySummary becomes async because it calls generateGraphSummary.
</action> </action>
<verify> <verify>
Test the full flow: Test the full flow including SessionStart injection:
```bash ```bash
cd /Users/lexchristopherson/Developer/claude-code-resources/get-shit-done cd /Users/lexchristopherson/Developer/claude-code-resources/get-shit-done
@@ -393,18 +403,21 @@ done
# Check summary.md has graph-based content # Check summary.md has graph-based content
cat .planning/intel/summary.md cat .planning/intel/summary.md
# Should show: # Should show:
# - "Dependency Hotspots" section # - "Dependency Hotspots" section
# - test-db with 2 dependents (auth and api both depend on it) # - test-db with 2 dependents (auth and api both depend on it)
# Verify SessionStart hook reads new summary format
echo '{"source":"startup"}' | node hooks/gsd-intel-session.js
# Should output <codebase-intelligence>...</codebase-intelligence> with hotspots
# Cleanup # Cleanup
rm .planning/intel/entities/test-*.md rm .planning/intel/entities/test-*.md
rm .planning/intel/graph.db rm .planning/intel/graph.db
rm .planning/intel/summary.md rm .planning/intel/summary.md
``` ```
</verify> </verify>
<done>Summary generation prefers graph when available, falls back to file-based</done> <done>Summary generation prefers graph when available, SessionStart hook confirmed to inject graph-backed summary</done>
</task> </task>
</tasks> </tasks>
@@ -428,6 +441,12 @@ After all tasks complete:
- Simulate entity writes - Simulate entity writes
- Check summary.md has "Dependency Hotspots" section - Check summary.md has "Dependency Hotspots" section
- Hotspot counts are accurate - Hotspot counts are accurate
4. SessionStart wiring verified:
```bash
# Verify SessionStart reads and injects the new format
echo '{"source":"startup"}' | node hooks/gsd-intel-session.js | grep -q "Dependency Hotspots" && echo "PASS: SessionStart injects graph summary"
```
</verification> </verification>
<success_criteria> <success_criteria>
@@ -438,6 +457,7 @@ After all tasks complete:
- [ ] regenerateEntitySummary() prefers graph when graph.db exists - [ ] regenerateEntitySummary() prefers graph when graph.db exists
- [ ] Falls back gracefully to file-based summary - [ ] Falls back gracefully to file-based summary
- [ ] Summary includes dependency hotspots with accurate counts - [ ] Summary includes dependency hotspots with accurate counts
- [ ] SessionStart hook (gsd-intel-session.js) correctly injects graph-backed summary into context
</success_criteria> </success_criteria>
<output> <output>

242
.planning/phases/04-semantic-intelligence/04-03-PLAN.md
View File

@@ -16,24 +16,24 @@ must_haves:
- "Batch processing handles 100+ files efficiently" - "Batch processing handles 100+ files efficiently"
artifacts: artifacts:
- path: "commands/gsd/analyze-codebase.md" - path: "commands/gsd/analyze-codebase.md"
provides: "Semantic entity generation via Claude API" provides: "Semantic entity generation instructions for Claude"
contains: "@anthropic-ai/sdk" contains: "semantic entities"
- path: "package.json" - path: "package.json"
provides: "Anthropic SDK dependency" provides: "Anthropic SDK dependency"
contains: "@anthropic-ai/sdk" contains: "@anthropic-ai/sdk"
key_links: key_links:
- from: "commands/gsd/analyze-codebase.md" - from: "commands/gsd/analyze-codebase.md"
to: "Anthropic Messages API" to: "Task tool"
via: "client.messages.create" via: "Subagent spawning for entity batch processing"
pattern: "messages\\.create" pattern: "Task.*entity"
--- ---
<objective> <objective>
Enhance /gsd:analyze-codebase to create semantic entity files using Claude API. Enhance /gsd:analyze-codebase to create semantic entity files using Claude.
Purpose: Generate entity documentation that captures file PURPOSE (what it does, why it exists), not just syntax (exports/imports). This transforms "2-3 ls commands" of information into genuine semantic understanding. Purpose: Generate entity documentation that captures file PURPOSE (what it does, why it exists), not just syntax (exports/imports). This transforms "2-3 ls commands" of information into genuine semantic understanding.
Output: Updated analyze-codebase.md command with Claude API integration, @anthropic-ai/sdk dependency. Output: Updated analyze-codebase.md command with entity generation instructions, @anthropic-ai/sdk dependency (for future direct API use).
</objective> </objective>
<execution_context> <execution_context>
@@ -60,7 +60,14 @@ Current analyze-codebase.md:
New requirement: New requirement:
- After indexing, optionally create entity .md files - After indexing, optionally create entity .md files
- Use Claude to write semantic purpose, not just regex extraction - Claude (executing the command) reads file content and generates semantic documentation
- No embedded JavaScript in command markdown - Claude IS the executor
Execution model clarification:
- GSD command .md files contain INSTRUCTIONS for Claude to follow
- Claude reads the markdown and executes the instructions using its tools
- Commands cannot contain executable JavaScript - Claude interprets and acts on the instructions
- For batch processing, Claude uses the Task tool to spawn subagents
</context> </context>
<tasks> <tasks>
@@ -78,7 +85,7 @@ Add @anthropic-ai/sdk to package.json dependencies:
} }
``` ```
Note: Version 0.52.0+ includes Messages API with proper TypeScript support. Note: Version 0.52.0+ includes Messages API with proper TypeScript support. This dependency enables future direct API integration (e.g., hooks that call Claude API directly). For the /gsd:analyze-codebase command, Claude itself generates the entity content.
</action> </action>
<verify>`grep -q "@anthropic-ai/sdk" package.json`</verify> <verify>`grep -q "@anthropic-ai/sdk" package.json`</verify>
<done>@anthropic-ai/sdk added to package.json</done> <done>@anthropic-ai/sdk added to package.json</done>
@@ -99,20 +106,28 @@ Works standalone (without /gsd:new-project) for brownfield codebases. Creates:
- index.json for file index - index.json for file index
- conventions.json for naming patterns - conventions.json for naming patterns
- summary.md for context injection - summary.md for context injection
- entities/*.md for semantic file documentation (optional, requires ANTHROPIC_API_KEY) - entities/*.md for semantic file documentation (optional)
Output: .planning/intel/index.json, conventions.json, summary.md, entities/*.md Output: .planning/intel/index.json, conventions.json, summary.md, entities/*.md
</objective> </objective>
``` ```
2. Add allowed-tools: Task (for entity generation subagent) 2. Add Task to allowed-tools (for entity generation via subagent):
```yaml
allowed-tools:
- Read
- Bash
- Glob
- Write
- Task
```
3. Add new Step 9 after Step 8 (before completion report): 3. Add new Step 9 after Step 8 (before completion report). This step provides INSTRUCTIONS for Claude to follow:
```markdown ```markdown
## Step 9: Generate semantic entities (optional) ## Step 9: Generate semantic entities (optional)
If `ANTHROPIC_API_KEY` environment variable is set, generate semantic entity files. After indexing, generate semantic entity files for key codebase files.
### 9a: Select key files for entity generation ### 9a: Select key files for entity generation
@@ -120,7 +135,7 @@ From the index, select files for entity generation using these criteria:
- Files with 3+ exports (significant modules) - Files with 3+ exports (significant modules)
- Files imported by 5+ other files (dependency hotspots) - Files imported by 5+ other files (dependency hotspots)
- Files in key directories: api/, lib/, utils/, services/, models/ - Files in key directories: api/, lib/, utils/, services/, models/
- Limit to 50 files maximum per run (avoid excessive API costs) - Limit to 50 files maximum per run (context management)
Skip: Skip:
- Test files (*.test.*, *.spec.*) - Test files (*.test.*, *.spec.*)
@@ -134,41 +149,30 @@ Skip:
mkdir -p .planning/intel/entities mkdir -p .planning/intel/entities
``` ```
### 9c: Generate entities using Claude API ### 9c: Generate entities in batches
For each selected file, use the Anthropic SDK to generate entity content: For efficient processing, use the Task tool to spawn a subagent for batch entity generation.
```javascript **Subagent prompt template:**
const Anthropic = require('@anthropic-ai/sdk');
const client = new Anthropic(); // Uses ANTHROPIC_API_KEY env var
async function generateEntityContent(filePath, fileContent) { ```
const response = await client.messages.create({ Generate semantic entity documentation for the following files.
model: 'claude-sonnet-4-5-20250929',
max_tokens: 1500,
system: `You are a senior engineer documenting a codebase. Create entity documentation following this exact template format. Be concise - focus on PURPOSE and key relationships.
Output ONLY the markdown content, no explanations or commentary.`, For each file:
messages: [{ 1. Read the file content
role: 'user', 2. Analyze its purpose, exports, and dependencies
content: `Create entity documentation for this file. 3. Write an entity file to .planning/intel/entities/{slug}.md
Path: ${filePath} Entity template (use EXACTLY this format):
Content:
\`\`\`
${fileContent}
\`\`\`
Follow this template EXACTLY:
--- ---
path: ${filePath} path: {file_path}
type: [module|component|util|config|test|api|hook|service|model] type: [module|component|util|config|api|hook|service|model]
updated: ${new Date().toISOString().split('T')[0]} updated: {today's date YYYY-MM-DD}
status: active status: active
--- ---
# [filename] # {filename}
## Purpose ## Purpose
@@ -177,12 +181,12 @@ status: active
## Exports ## Exports
[List each export with signature and brief description] [List each export with signature and brief description]
- \`exportName(args): ReturnType\` - What it does - `exportName(args): ReturnType` - What it does
## Dependencies ## Dependencies
[Internal deps use wiki-links, external use plain text] [Internal deps use wiki-links, external use plain text]
- [[slugified-path]] - Why needed - [[slugified-internal-path]] - Why needed
- external-package - Why needed - external-package - Why needed
## Used By ## Used By
@@ -191,52 +195,40 @@ TBD
## Notes ## Notes
[Optional: patterns, gotchas, or important context]` [Optional: patterns, gotchas, or important context]
}]
});
return response.content[0].text; ---
}
Slug convention: `src/lib/db.ts` -> `src-lib-db` (replace / and . with -, remove extension)
Files to process:
{list of file paths, max 10 per batch}
``` ```
### 9d: Write entity files ### 9d: Process in batches of 10
For each generated entity: For codebases with many key files:
1. Create slug from path: `src/lib/db.ts` -> `src-lib-db` 1. Split the selected files into batches of 10
2. Write to `.planning/intel/entities/{slug}.md` 2. Use Task tool for each batch with the prompt template above
3. The PostToolUse hook will automatically sync to graph.db 3. Wait for each batch to complete before starting the next
4. This prevents context exhaustion and allows progress tracking
### 9e: Process in batches ### 9e: Verify entity creation
Process files in batches of 5 with 1 second delay between batches to respect rate limits. After batch processing:
- Count entities created: `ls .planning/intel/entities/*.md | wc -l`
```javascript - Verify they have semantic content (Purpose section, not just syntax)
async function processEntities(files) { - The PostToolUse hook will automatically sync new entities to graph.db
const batchSize = 5;
for (let i = 0; i < files.length; i += batchSize) {
const batch = files.slice(i, i + batchSize);
await Promise.all(batch.map(async (filePath) => {
const content = fs.readFileSync(filePath, 'utf8');
const entityContent = await generateEntityContent(filePath, content);
const slug = filePath.replace(/^\//, '').replace(/[\/\.]/g, '-').replace(/-[jt]sx?$/, '');
fs.writeFileSync(`.planning/intel/entities/${slug}.md`, entityContent);
}));
if (i + batchSize < files.length) {
await new Promise(r => setTimeout(r, 1000)); // Rate limit
}
}
}
```
``` ```
4. Update Step 10 (completion report) to include entity stats: 4. Update Step 10 (renumber from Step 8) to include entity stats:
```markdown ```markdown
## Step 10: Report completion ## Step 10: Report completion
Display summary statistics: Display summary statistics:
\`\`\` ```
Codebase Analysis Complete Codebase Analysis Complete
Files indexed: [N] Files indexed: [N]
@@ -248,17 +240,17 @@ Conventions detected:
- Directories: [list] - Directories: [list]
- Patterns: [list] - Patterns: [list]
Entities created: [N] (if ANTHROPIC_API_KEY set) Entities created: [N] (if entity generation ran)
- Skipped: [N] (already existed or filtered) - Skipped: [N] (already existed or filtered)
Files created: Files created:
- .planning/intel/index.json - .planning/intel/index.json
- .planning/intel/conventions.json - .planning/intel/conventions.json
- .planning/intel/summary.md - .planning/intel/summary.md
- .planning/intel/entities/*.md (if API key set) - .planning/intel/entities/*.md (if entities generated)
Next: Intel hooks will continue incremental learning as you code. Next: Intel hooks will continue incremental learning as you code.
\`\`\` ```
``` ```
5. Update success criteria to include entity generation: 5. Update success criteria to include entity generation:
@@ -270,7 +262,8 @@ Next: Intel hooks will continue incremental learning as you code.
- [ ] index.json populated with exports and imports for each file - [ ] index.json populated with exports and imports for each file
- [ ] conventions.json has detected patterns (naming, directories, suffixes) - [ ] conventions.json has detected patterns (naming, directories, suffixes)
- [ ] summary.md is concise (< 500 tokens) - [ ] summary.md is concise (< 500 tokens)
- [ ] entities/*.md created for key files (if ANTHROPIC_API_KEY set) - [ ] entities/*.md created for key files (if Step 9 executed)
- [ ] Entity files have semantic Purpose sections (not just syntax extraction)
- [ ] Statistics reported to user - [ ] Statistics reported to user
</success_criteria> </success_criteria>
``` ```
@@ -280,63 +273,55 @@ Next: Intel hooks will continue incremental learning as you code.
# Check command has entity generation step # Check command has entity generation step
grep -q "Generate semantic entities" commands/gsd/analyze-codebase.md && echo "PASS: Step 9 exists" grep -q "Generate semantic entities" commands/gsd/analyze-codebase.md && echo "PASS: Step 9 exists"
# Check mentions Anthropic SDK # Check mentions Task tool for batching
grep -q "@anthropic-ai/sdk" commands/gsd/analyze-codebase.md && echo "PASS: SDK mentioned" grep -q "Task tool" commands/gsd/analyze-codebase.md && echo "PASS: Task batching documented"
# Check has batch processing # Check entity template is present
grep -q "batchSize" commands/gsd/analyze-codebase.md && echo "PASS: Batch processing" grep -q "## Purpose" commands/gsd/analyze-codebase.md && echo "PASS: Entity template included"
# Check batch size documented
grep -q "batches of 10" commands/gsd/analyze-codebase.md && echo "PASS: Batch processing"
``` ```
</verify> </verify>
<done>analyze-codebase.md includes semantic entity generation via Claude API</done> <done>analyze-codebase.md includes semantic entity generation via Claude + Task tool batching</done>
</task> </task>
<task type="auto"> <task type="auto">
<name>Task 3: Add fallback messaging for missing API key</name> <name>Task 3: Add context section explaining execution model</name>
<files>commands/gsd/analyze-codebase.md</files> <files>commands/gsd/analyze-codebase.md</files>
<action> <action>
Add clear messaging when ANTHROPIC_API_KEY is not set. Update the context section to explain how entity generation works.
In the context section, add: In the context section, add:
```markdown ```markdown
**Entity generation (optional):** **Entity generation:**
Requires `ANTHROPIC_API_KEY` environment variable. If not set, only index/conventions/summary are created. Set with: Step 9 generates semantic entity files using Claude's understanding of code purpose. Unlike regex-based extraction (exports/imports), this captures WHY code exists.
```bash
export ANTHROPIC_API_KEY=sk-ant-... For large codebases (50+ key files), entity generation uses the Task tool to spawn subagents that process files in batches of 10. This:
- Prevents context exhaustion
- Allows progress tracking
- Enables parallel processing
Entity files are written to `.planning/intel/entities/` and automatically synced to the graph database by the PostToolUse hook.
**When to skip entity generation:**
- Quick index-only scan: Stop after Step 8
- Already have entities: Existing entities won't be overwritten
- Small codebase: May not need formal entities
``` ```
Entity generation costs approximately $0.01-0.02 per file (using claude-sonnet-4-5-20250929). This clarifies:
``` 1. Claude generates entity content (not embedded JavaScript)
2. Task tool handles batching for large codebases
In Step 9, add at the beginning: 3. Users can skip Step 9 if they just want the index
```markdown
## Step 9: Generate semantic entities (optional)
**Check for API key:**
```javascript
if (!process.env.ANTHROPIC_API_KEY) {
console.log('Skipping entity generation: ANTHROPIC_API_KEY not set');
console.log('To enable, run: export ANTHROPIC_API_KEY=sk-ant-...');
// Skip to Step 10
}
```
If no API key, skip directly to Step 10 with message:
```
Entity generation skipped (no ANTHROPIC_API_KEY).
To enable semantic entities, set ANTHROPIC_API_KEY and re-run.
```
```
This ensures the command still works without API key (backwards compatible) while clearly explaining how to enable entity generation.
</action> </action>
<verify> <verify>
```bash ```bash
grep -q "ANTHROPIC_API_KEY not set" commands/gsd/analyze-codebase.md && echo "PASS: Fallback messaging exists" grep -q "Task tool to spawn subagents" commands/gsd/analyze-codebase.md && echo "PASS: Execution model explained"
``` ```
</verify> </verify>
<done>Command gracefully handles missing API key with clear instructions</done> <done>Command explains entity generation execution model clearly</done>
</task> </task>
</tasks> </tasks>
@@ -352,36 +337,37 @@ After all tasks complete:
2. Command has entity generation: 2. Command has entity generation:
```bash ```bash
grep -q "Step 9" commands/gsd/analyze-codebase.md && echo "PASS" grep -q "Step 9" commands/gsd/analyze-codebase.md && echo "PASS"
grep -q "generateEntityContent" commands/gsd/analyze-codebase.md && echo "PASS" grep -q "semantic entities" commands/gsd/analyze-codebase.md && echo "PASS"
``` ```
3. Fallback works: 3. Task tool batching:
```bash ```bash
grep -q "ANTHROPIC_API_KEY not set" commands/gsd/analyze-codebase.md && echo "PASS" grep -q "Task tool" commands/gsd/analyze-codebase.md && echo "PASS"
grep -q "batches of 10" commands/gsd/analyze-codebase.md && echo "PASS"
``` ```
4. Batch processing: 4. Entity template present:
```bash ```bash
grep -q "batchSize" commands/gsd/analyze-codebase.md && echo "PASS" grep -q "## Purpose" commands/gsd/analyze-codebase.md && echo "PASS"
``` ```
Manual test (requires API key): Manual test:
```bash ```bash
export ANTHROPIC_API_KEY=sk-ant-...
# Run /gsd:analyze-codebase on a test project # Run /gsd:analyze-codebase on a test project
# Verify .planning/intel/entities/*.md created with semantic content # Verify Steps 1-8 produce index.json, conventions.json, summary.md
# If Step 9 runs, verify .planning/intel/entities/*.md created with semantic content
``` ```
</verification> </verification>
<success_criteria> <success_criteria>
- [ ] @anthropic-ai/sdk added to package.json - [ ] @anthropic-ai/sdk added to package.json
- [ ] Step 9 added for entity generation - [ ] Step 9 added for entity generation (instructions for Claude, not embedded JS)
- [ ] Task tool documented for batch processing subagents
- [ ] File selection criteria documented (3+ exports, 5+ dependents, key dirs) - [ ] File selection criteria documented (3+ exports, 5+ dependents, key dirs)
- [ ] 50 file limit per run to control costs - [ ] 50 file limit per run to manage context
- [ ] Batch processing with rate limiting (5 files, 1s delay) - [ ] Batch processing with batches of 10 via Task tool
- [ ] Entity slug convention documented - [ ] Entity slug convention documented
- [ ] Graceful fallback when ANTHROPIC_API_KEY not set - [ ] Execution model explained (Claude generates content, not script execution)
- [ ] Cost estimate included (~$0.01-0.02 per file)
- [ ] Updated success criteria includes entity generation - [ ] Updated success criteria includes entity generation
</success_criteria> </success_criteria>