Rewrite /deepen-plan with context-managed map-reduce (v3)

[Drewx-Design]

Summary

• Replaces v1 /deepen-plan with a phased file-based map-reduce architecture (same pattern as the review command v2 in Rewrite workflows:review with context-managed map-reduce architecture #157)
• Sub-agents write full analysis JSON to .deepen/ on disk and return only ~100 token summaries to parent
• Parent context stays under ~12k tokens regardless of agent count (13-26 agents), vs unbounded in v1
• Adds 5 new phases: Plan Manifest, Validation, Judge, Preservation Check, Compound Insights
• Cross-platform safe: project-relative .deepen/ instead of /tmp/

Architecture Changes

Phase	v1 (current)	v3 (this PR)
Analyze	Inline parsing in parent	Dedicated agent writes structured manifest JSON
Discover	find + head (bash, Windows-broken)	Glob/Read native tools (cross-platform)
Research	Agents return full output to parent	Agents write JSON to .deepen/, return 1 sentence
Validate	None	Schema validation + hallucination flagging
Judge	None (dedup in parent)	Dedicated judge with source attribution priority
Enhance	Parent synthesizes (context overflow)	Dedicated enhancer reads disk, writes disk
Verify	Basic quality checks	Section preservation verification
Compound	Not supported	Creates validated docs/solutions/ files via compound-docs skill

Alignment Audit: v3 vs Plugin Ecosystem

Performed a full audit of v3 against the compound-engineering plugin (v2.33.0) -- all agents, skills, commands, MCP servers, and conventions.

1. Agent Discovery Completeness -- Aligned

Check	Status	Evidence
Glob reaches plugin agents	OK	~/.claude/plugins/cache/**/agents/**/*.md matches every-marketplace/compound-engineering/2.33.0/agents/
Category filtering correct	OK	USE: review/ (14), research/ (4), design/ (3), docs/ (1). SKIP: workflow/ (5 orchestrators)
Always-run agents exist	OK	security-sentinel.md, architecture-strategist.md, performance-oracle.md all verified
No valuable agents excluded	OK	v3 includes manifest-matched agents: code-simplicity-reviewer, agent-native-reviewer, pattern-recognition-specialist, language-specific reviewers

Fixed from v1: v1 said "run ALL agents" (40+ parallel). v3 uses intelligent selection: 3 always-run + manifest-matched, reducing from ~30 agents to 10-15 targeted ones.

2. Skill Discovery -- Aligned (with fixes applied)

Check	Status	Evidence
Glob reaches plugin skills	OK	~/.claude/plugins/cache/**/skills/*/SKILL.md matches all 14 skills
Skill-to-domain mappings correct	OK	Fixed: removed kieran-rails-style (doesn't exist as a skill -- it's an agent). Added: andrew-kane-gem-writer, dspy-ruby, every-style-editor, create-agent-skills
Skills with references/ handled	OK	v3 skill agent prompt now globs references/, assets/, templates/ subdirectories

Fixed from v1: v1 only read SKILL.md. v3 agents also read references/*.md, assets/*, templates/* -- critical for skills like agent-native-architecture (14 reference files) and create-agent-skills (11 references + templates + workflows).

3. Command Pipeline -- Aligned (with fixes applied)

Pipeline	Status	Notes
/workflows:plan to /deepen-plan	OK	Plan analyzer handles any markdown format. Plans output to plans/ directory.
/deepen-plan to /workflows:work	OK	Enhanced plan is valid markdown with Research Insights blocks and // ENHANCED: comments. Work command reads it fine.
/deepen-plan to /plan_review	OK	Fixed: v1 offered /workflows:review (code review, not plan review). v3 correctly offers /plan_review.
/lfg chain	OK	Fixed: Kept name: deepen-plan (not workflows:deepen-plan) so /lfg and /slfg references to /compound-engineering:deepen-plan still work.
Compound insights	OK	Fixed: v3 now references compound-docs skill and its YAML schema for properly validated learning files.

4. MCP Server Integration -- Aligned

Check	Status	Evidence
Context7 tool names	OK	resolve-library-id and query-docs verified against plugin.json mcpServers config
No browser automation needed	OK	Research-only command, agent-browser not applicable
No missing MCP servers	OK	Context7 is the only MCP server in the plugin

5. Naming and Convention Alignment -- Aligned (with fixes applied)

Check	Status	Notes
Command name	OK	Fixed: Kept name: deepen-plan (in commands/ not commands/workflows/). Matches existing plugin structure and /lfg//slfg references.
Output paths	OK	Plans: original location preserved. Learnings: docs/solutions/[category]/ with compound-docs schema.
Frontmatter format	OK	Fixed: Compound insights now use full compound-docs YAML schema (13 fields) instead of simplified 6-field format.

6. Philosophy Alignment -- Aligned

Principle	Status	Evidence
Compounding	OK	Option 6 creates learnings; Step 3b discovers them in future runs
80/20 plan vs execution	OK	Command is entirely research/planning, never writes code
Source priority	OK	skill > documented-learning > official-docs > community-web matches best-practices-researcher Phase 1-2-3 order
Agent specialization	OK	Each agent focuses on its domain, returns structured JSON
Parallel-first	OK	All matched agents launch in single parallel batch

7. Edge Cases -- Compatible

Scenario	Status	Notes
No plugin installed	OK	Glob returns empty, "Handling Sparse Discovery" section acknowledges
Custom project agents	OK	.claude/agents/*.md glob catches project-local agents
Skills with scripts/	OK	v3 agent prompt globs references/, assets/, templates/
Multiple plugins	OK	~/.claude/plugins/cache/**/agents/**/*.md catches all
Plan with no frontmatter	OK	Manifest analyzer parses markdown sections, doesn't require frontmatter
Windows paths	OK	Uses project-relative .deepen/, Node.js for validation (no Python/bash dependency)

Key Fixes Applied (v1 to v3)

1. Context overflow prevention -- v1 pulled all agent output into parent. v3 uses file-based map-reduce.
2. Skill references/ -- v1 only read SKILL.md. v3 reads full skill tree including references, assets, templates.
3. kieran-rails-style ghost skill -- v1 referenced a skill that doesn't exist. v3 maps to actual skill names.
4. /workflows:review vs /plan_review -- v1 offered code review for plan feedback. v3 correctly offers plan review.
5. Command name preserved -- Kept deepen-plan (not workflows:deepen-plan) for /lfg//slfg compatibility.
6. Compound insights schema -- v1 had no compound integration. v3 uses full compound-docs YAML schema.
7. Windows compatibility -- .deepen/ instead of /tmp/. Node.js instead of Python3. Glob/Read instead of find/head.
8. Hallucination detection -- Agents with empty tools_used flagged, judge downweights confidence by 0.2.

Test plan

• Run /deepen-plan plans/test-plan.md on a Rails plan -- verify .deepen/ directory created with expected JSON files
• Verify parent context stays under ~14k tokens of agent output
• Run /lfg end-to-end to confirm /compound-engineering:deepen-plan still resolves correctly
• Test compound insights option (Step 9d, option 6) creates files matching compound-docs YAML schema
• Test on Windows to verify .deepen/ path and Node.js validation work cross-platform
• Verify judge removes duplicate recommendations and resolves conflicts with source priority
• Run on a plan with no docs/solutions/ to confirm sparse discovery handles gracefully

Breaking Changes Risk

If the plugin updates these, v3 would need updating:

• Agent renames -- v3 references agents by filename (e.g., security-sentinel). If agents are renamed, the always-run tier and manifest-matched lists need updating.
• compound-docs YAML schema changes -- v3's compound insights option references the schema. If fields are added/removed, the instructions need updating.
• Context7 tool name changes -- v3 hardcodes MCP tool names. If Context7 changes its API, the docs-researcher prompts need updating.

These are the same risks the existing /workflows:review and /workflows:plan commands face -- nothing unique to /deepen-plan.

---