Rewrite /deepen-plan with context-managed map-reduce (v3) by Drewx-Design · Pull Request #178 · EveryInc/compound-engineering-plugin

Drewx-Design · 2026-02-12T19:15:42Z

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)

Context overflow prevention -- v1 pulled all agent output into parent. v3 uses file-based map-reduce.
Skill references/ -- v1 only read SKILL.md. v3 reads full skill tree including references, assets, templates.
kieran-rails-style ghost skill -- v1 referenced a skill that doesn't exist. v3 maps to actual skill names.
/workflows:review vs /plan_review -- v1 offered code review for plan feedback. v3 correctly offers plan review.
Command name preserved -- Kept deepen-plan (not workflows:deepen-plan) for /lfg//slfg compatibility.
Compound insights schema -- v1 had no compound integration. v3 uses full compound-docs YAML schema.
Windows compatibility -- .deepen/ instead of /tmp/. Node.js instead of Python3. Glob/Read instead of find/head.
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.

…re (v3) Replace unbounded v1 agent output with phased file-based map-reduce pattern that keeps parent context under ~12k tokens. Adds plan manifest analysis, validation, judge phase with source attribution priority, and preservation checking. Aligns with plugin ecosystem conventions.

…mplementing The compound-docs skill already has a validated YAML schema and 7-step process. Instead of reimplementing it inside deepen-plan, offer the user the option to run /workflows:compound themselves.

The deepen-plan command deepens decisions but never challenges them. Real reviewer feedback showed it misses redundant tool params, YAGNI violations built despite being flagged, and misplaced business logic. Adds two new always-run agents: - agent-native-architecture-reviewer: routes to skill checklist, anti-patterns, and reference files (not generic prompt) - project-architecture-challenger: reads CLAUDE.md and challenges every decision against project-specific principles Also injects PROJECT ARCHITECTURE CONTEXT into all review/research agent prompts so they evaluate against project conventions.

…ents Validated across two real-world pipeline runs. Key changes: - Batched agent launches (max 4 pending) to prevent context overflow crashes - 200-char return cap on agent messages (all analysis in JSON files) - Version grounding: lockfile > package.json > plan text priority - Per-section judge parallelization (~21 min -> ~8-10 min) - Two-part output: Decision Record (reviewers) + Implementation Spec (developers) - Quality review phase (CoVe pattern) catches self-contradictions and code gaps - Enhancer resolves conditionals, verifies API versions, checks accessibility - fast_follow classification bucket for ticketable items - Convergence signals with [Strong Signal] markers - Task() failure recovery (retry once on infrastructure errors) - truncated_count field for judge convergence weighting - Pipeline checkpoint logging for diagnostics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Drewx-Design added 3 commits February 12, 2026 14:13

fix: delegate compound insights to /workflows:compound instead of rei…

52c60f3

…mplementing The compound-docs skill already has a validated YAML schema and 7-step process. Instead of reimplementing it inside deepen-plan, offer the user the option to run /workflows:compound themselves.

Drewx-Design marked this pull request as draft February 13, 2026 15:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Rewrite /deepen-plan with context-managed map-reduce (v3)#178
Drewx-Design wants to merge 4 commits intoEveryInc:mainfrom
Drewx-Design:feat/deepen-plan-v3-context-managed

Drewx-Design commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Drewx-Design commented Feb 12, 2026

Summary

Architecture Changes

Alignment Audit: v3 vs Plugin Ecosystem

1. Agent Discovery Completeness -- Aligned

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

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

4. MCP Server Integration -- Aligned

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

6. Philosophy Alignment -- Aligned

7. Edge Cases -- Compatible

Key Fixes Applied (v1 to v3)

Test plan

Breaking Changes Risk

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant