deepen-plan

Original：🇺🇸 English

Translated

Enhance a plan with parallel research agents for each section to add depth, best practices, and implementation details

2installs

Sourceeveryinc/compound-engineering-plugin

Added on2026-03-13

NPX Install

npx skill4agent add everyinc/compound-engineering-plugin deepen-plan

SKILL.md Content

View Translation Comparison →

Deepen Plan - Power Enhancement Mode

Introduction

Note: The current year is 2026. Use this when searching for recent documentation and best practices.

This command takes an existing plan (from

/ce:plan

) and enhances each section with parallel research agents. Each major element gets its own dedicated research sub-agent to find:

Best practices and industry patterns
Performance optimizations
UI/UX improvements (if applicable)
Quality enhancements and edge cases
Real-world implementation examples

The result is a deeply grounded, production-ready plan with concrete implementation details.

Plan File

<plan_path> #$ARGUMENTS </plan_path>

If the plan path above is empty:

Check for recent plans:
```
ls -la docs/plans/
```
Ask the user: "Which plan would you like to deepen? Please provide the path (e.g.,
```
docs/plans/2026-01-15-feat-my-feature-plan.md
```
)."

Do not proceed until you have a valid plan file path.

Main Tasks

1. Parse and Analyze Plan Structure

<thinking> First, read and parse the plan to identify each major section that can be enhanced with research. </thinking>

Read the plan file and extract:

Overview/Problem Statement
Proposed Solution sections
Technical Approach/Architecture
Implementation phases/steps
Code examples and file references
Acceptance criteria
Any UI/UX components mentioned
Technologies/frameworks mentioned (Rails, React, Python, TypeScript, etc.)
Domain areas (data models, APIs, UI, security, performance, etc.)

Create a section manifest:

Section 1: [Title] - [Brief description of what to research]
Section 2: [Title] - [Brief description of what to research]
...

2. Discover and Apply Available Skills

<thinking> Dynamically discover all available skills and match them to plan sections. Don't assume what skills exist - discover them at runtime. </thinking>

Step 1: Discover ALL available skills from ALL sources

bash

# 1. Project-local skills (highest priority - project-specific)
ls .claude/skills/

# 2. User's global skills (~/.claude/)
ls ~/.claude/skills/

# 3. compound-engineering plugin skills
ls ~/.claude/plugins/cache/*/compound-engineering/*/skills/

# 4. ALL other installed plugins - check every plugin for skills
find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null

# 5. Also check installed_plugins.json for all plugin locations
cat ~/.claude/plugins/installed_plugins.json

Important: Check EVERY source. Don't assume compound-engineering is the only plugin. Use skills from ANY installed plugin that's relevant.

Step 2: For each discovered skill, read its SKILL.md to understand what it does

bash

# For each skill directory found, read its documentation
cat [skill-path]/SKILL.md

Step 3: Match skills to plan content

For each skill discovered:

Read its SKILL.md description
Check if any plan sections match the skill's domain
If there's a match, spawn a sub-agent to apply that skill's knowledge

Step 4: Spawn a sub-agent for EVERY matched skill

CRITICAL: For EACH skill that matches, spawn a separate sub-agent and instruct it to USE that skill.

For each matched skill:

Task general-purpose: "You have the [skill-name] skill available at [skill-path].

YOUR JOB: Use this skill on the plan.

1. Read the skill: cat [skill-path]/SKILL.md
2. Follow the skill's instructions exactly
3. Apply the skill to this content:

[relevant plan section or full plan]

4. Return the skill's full output

The skill tells you what to do - follow it. Execute the skill completely."

Spawn ALL skill sub-agents in PARALLEL:

1 sub-agent per matched skill
Each sub-agent reads and uses its assigned skill
All run simultaneously
10, 20, 30 skill sub-agents is fine

Each sub-agent:

Reads its skill's SKILL.md
Follows the skill's workflow/instructions
Applies the skill to the plan
Returns whatever the skill produces (code, recommendations, patterns, reviews, etc.)

Example spawns:

Task general-purpose: "Use the dhh-rails-style skill at ~/.claude/plugins/.../dhh-rails-style. Read SKILL.md and apply it to: [Rails sections of plan]"

Task general-purpose: "Use the frontend-design skill at ~/.claude/plugins/.../frontend-design. Read SKILL.md and apply it to: [UI sections of plan]"

Task general-purpose: "Use the agent-native-architecture skill at ~/.claude/plugins/.../agent-native-architecture. Read SKILL.md and apply it to: [agent/tool sections of plan]"

Task general-purpose: "Use the security-patterns skill at ~/.claude/skills/security-patterns. Read SKILL.md and apply it to: [full plan]"

No limit on skill sub-agents. Spawn one for every skill that could possibly be relevant.

3. Discover and Apply Learnings/Solutions

<thinking> Check for documented learnings from /ce:compound. These are solved problems stored as markdown files. Spawn a sub-agent for each learning to check if it's relevant. </thinking>

LEARNINGS LOCATION - Check these exact folders:

docs/solutions/           <-- PRIMARY: Project-level learnings (created by /ce:compound)
├── performance-issues/
│   └── *.md
├── debugging-patterns/
│   └── *.md
├── configuration-fixes/
│   └── *.md
├── integration-issues/
│   └── *.md
├── deployment-issues/
│   └── *.md
└── [other-categories]/
    └── *.md

Step 1: Find ALL learning markdown files

Run these commands to get every learning file:

bash

# PRIMARY LOCATION - Project learnings
find docs/solutions -name "*.md" -type f 2>/dev/null

# If docs/solutions doesn't exist, check alternate locations:
find .claude/docs -name "*.md" -type f 2>/dev/null
find ~/.claude/docs -name "*.md" -type f 2>/dev/null

Step 2: Read frontmatter of each learning to filter

Each learning file has YAML frontmatter with metadata. Read the first ~20 lines of each file to get:

yaml

---
title: "N+1 Query Fix for Briefs"
category: performance-issues
tags: [activerecord, n-plus-one, includes, eager-loading]
module: Briefs
symptom: "Slow page load, multiple queries in logs"
root_cause: "Missing includes on association"
---

For each .md file, quickly scan its frontmatter:

bash

# Read first 20 lines of each learning (frontmatter + summary)
head -20 docs/solutions/**/*.md

Step 3: Filter - only spawn sub-agents for LIKELY relevant learnings

Compare each learning's frontmatter against the plan:

```
tags:
```
- Do any tags match technologies/patterns in the plan?
```
category:
```
- Is this category relevant? (e.g., skip deployment-issues if plan is UI-only)
```
module:
```
- Does the plan touch this module?
```
symptom:
```
/
```
root_cause:
```
- Could this problem occur with the plan?

SKIP learnings that are clearly not applicable:

Plan is frontend-only → skip
```
database-migrations/
```
learnings
Plan is Python → skip
```
rails-specific/
```
learnings
Plan has no auth → skip
```
authentication-issues/
```
learnings

SPAWN sub-agents for learnings that MIGHT apply:

Any tag overlap with plan technologies
Same category as plan domain
Similar patterns or concerns

Step 4: Spawn sub-agents for filtered learnings

For each learning that passes the filter:

Task general-purpose: "
LEARNING FILE: [full path to .md file]

1. Read this learning file completely
2. This learning documents a previously solved problem

Check if this learning applies to this plan:

---
[full plan content]
---

If relevant:
- Explain specifically how it applies
- Quote the key insight or solution
- Suggest where/how to incorporate it

If NOT relevant after deeper analysis:
- Say 'Not applicable: [reason]'
"

Example filtering:

# Found 15 learning files, plan is about "Rails API caching"

# SPAWN (likely relevant):
docs/solutions/performance-issues/n-plus-one-queries.md      # tags: [activerecord] ✓
docs/solutions/performance-issues/redis-cache-stampede.md    # tags: [caching, redis] ✓
docs/solutions/configuration-fixes/redis-connection-pool.md  # tags: [redis] ✓

# SKIP (clearly not applicable):
docs/solutions/deployment-issues/heroku-memory-quota.md      # not about caching
docs/solutions/frontend-issues/stimulus-race-condition.md    # plan is API, not frontend
docs/solutions/authentication-issues/jwt-expiry.md           # plan has no auth

Spawn sub-agents in PARALLEL for all filtered learnings.

These learnings are institutional knowledge - applying them prevents repeating past mistakes.

4. Launch Per-Section Research Agents

<thinking> For each major section in the plan, spawn dedicated sub-agents to research improvements. Use the Explore agent type for open-ended research. </thinking>

For each identified section, launch parallel research:

Task Explore: "Research best practices, patterns, and real-world examples for: [section topic].
Find:
- Industry standards and conventions
- Performance considerations
- Common pitfalls and how to avoid them
- Documentation and tutorials
Return concrete, actionable recommendations."

Also use Context7 MCP for framework documentation:

For any technologies/frameworks mentioned in the plan, query Context7:

mcp__plugin_compound-engineering_context7__resolve-library-id: Find library ID for [framework]
mcp__plugin_compound-engineering_context7__query-docs: Query documentation for specific patterns

Use WebSearch for current best practices:

Search for recent (2024-2026) articles, blog posts, and documentation on topics in the plan.

5. Discover and Run ALL Review Agents

<thinking> Dynamically discover every available agent and run them ALL against the plan. Don't filter, don't skip, don't assume relevance. 40+ parallel agents is fine. Use everything available. </thinking>

Step 1: Discover ALL available agents from ALL sources

bash

# 1. Project-local agents (highest priority - project-specific)
find .claude/agents -name "*.md" 2>/dev/null

# 2. User's global agents (~/.claude/)
find ~/.claude/agents -name "*.md" 2>/dev/null

# 3. compound-engineering plugin agents (all subdirectories)
find ~/.claude/plugins/cache/*/compound-engineering/*/agents -name "*.md" 2>/dev/null

# 4. ALL other installed plugins - check every plugin for agents
find ~/.claude/plugins/cache -path "*/agents/*.md" 2>/dev/null

# 5. Check installed_plugins.json to find all plugin locations
cat ~/.claude/plugins/installed_plugins.json

# 6. For local plugins (isLocal: true), check their source directories
# Parse installed_plugins.json and find local plugin paths

Important: Check EVERY source. Include agents from:

Project
```
.claude/agents/
```
User's
```
~/.claude/agents/
```
compound-engineering plugin (but SKIP workflow/ agents - only use review/, research/, design/, docs/)
ALL other installed plugins (agent-sdk-dev, frontend-design, etc.)
Any local plugins

For compound-engineering plugin specifically:

USE:
```
agents/review/*
```
(all reviewers)
USE:
```
agents/research/*
```
(all researchers)
USE:
```
agents/design/*
```
(design agents)
USE:
```
agents/docs/*
```
(documentation agents)
SKIP:
```
agents/workflow/*
```
(these are workflow orchestrators, not reviewers)

Step 2: For each discovered agent, read its description

Read the first few lines of each agent file to understand what it reviews/analyzes.

Step 3: Launch ALL agents in parallel

For EVERY agent discovered, launch a Task in parallel:

Task [agent-name]: "Review this plan using your expertise. Apply all your checks and patterns. Plan content: [full plan content]"

CRITICAL RULES:

Do NOT filter agents by "relevance" - run them ALL
Do NOT skip agents because they "might not apply" - let them decide
Launch ALL agents in a SINGLE message with multiple Task tool calls
20, 30, 40 parallel agents is fine - use everything
Each agent may catch something others miss
The goal is MAXIMUM coverage, not efficiency

Step 4: Also discover and run research agents

Research agents (like

best-practices-researcher

framework-docs-researcher

git-history-analyzer

repo-research-analyst

) should also be run for relevant plan sections.

6. Wait for ALL Agents and Synthesize Everything

<thinking> Wait for ALL parallel agents to complete - skills, research agents, review agents, everything. Then synthesize all findings into a comprehensive enhancement. </thinking>

Collect outputs from ALL sources:

Skill-based sub-agents - Each skill's full output (code examples, patterns, recommendations)
Learnings/Solutions sub-agents - Relevant documented learnings from /ce:compound
Research agents - Best practices, documentation, real-world examples
Review agents - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
Context7 queries - Framework documentation and patterns
Web searches - Current best practices and articles

For each agent's findings, extract:

Concrete recommendations (actionable items)
Code patterns and examples (copy-paste ready)
Anti-patterns to avoid (warnings)
Performance considerations (metrics, benchmarks)
Security considerations (vulnerabilities, mitigations)
Edge cases discovered (handling strategies)
Documentation links (references)
Skill-specific patterns (from matched skills)
Relevant learnings (past solutions that apply - prevent repeating mistakes)

Deduplicate and prioritize:

Merge similar recommendations from multiple agents
Prioritize by impact (high-value improvements first)
Flag conflicting advice for human review
Group by plan section

7. Enhance Plan Sections

<thinking> Merge research findings back into the plan, adding depth without changing the original structure. </thinking>

Enhancement format for each section:

markdown

## [Original Section Title]

[Original content preserved]

### Research Insights

**Best Practices:**
- [Concrete recommendation 1]
- [Concrete recommendation 2]

**Performance Considerations:**
- [Optimization opportunity]
- [Benchmark or metric to target]

**Implementation Details:**
```[language]
// Concrete code example from research

Edge Cases:

[Edge case 1 and how to handle]
[Edge case 2 and how to handle]

References:

[Documentation URL 1]
[Documentation URL 2]


### 8. Add Enhancement Summary

At the top of the plan, add a summary section:

```markdown
## Enhancement Summary

**Deepened on:** [Date]
**Sections enhanced:** [Count]
**Research agents used:** [List]

### Key Improvements
1. [Major improvement 1]
2. [Major improvement 2]
3. [Major improvement 3]

### New Considerations Discovered
- [Important finding 1]
- [Important finding 2]

9. Update Plan File

Write the enhanced plan:

Preserve original filename
Add
```
-deepened
```
suffix if user prefers a new file
Update any timestamps or metadata

Output Format

Update the plan file in place (or if user requests a separate file, append

-deepened

after

-plan

, e.g.,

2026-01-15-feat-auth-plan-deepened.md

Quality Checks

Before finalizing:

All original content preserved
Research insights clearly marked and attributed
Code examples are syntactically correct
Links are valid and relevant
No contradictions between sections
Enhancement summary accurately reflects changes

Post-Enhancement Options

After writing the enhanced plan, use the AskUserQuestion tool to present these options:

Question: "Plan deepened at

[plan_path]

. What would you like to do next?"

Options:

View diff - Show what was added/changed
Run
/technical_review
- Get feedback from reviewers on enhanced plan
Start
/ce:work
- Begin implementing this enhanced plan
Deepen further - Run another round of research on specific sections
Revert - Restore original plan (if backup exists)

Based on selection:

View diff → Run
```
git diff [plan_path]
```
or show before/after
/technical_review
→ Call the /technical_review command with the plan file path
/ce:work
→ Call the /ce:work command with the plan file path
Deepen further → Ask which sections need more research, then re-run those agents
Revert → Restore from git or backup

Example Enhancement

Before (from /workflows:plan):

markdown

## Technical Approach

Use React Query for data fetching with optimistic updates.

After (from /workflows:deepen-plan):

markdown

## Technical Approach

Use React Query for data fetching with optimistic updates.

### Research Insights

**Best Practices:**
- Configure `staleTime` and `cacheTime` based on data freshness requirements
- Use `queryKey` factories for consistent cache invalidation
- Implement error boundaries around query-dependent components

**Performance Considerations:**
- Enable `refetchOnWindowFocus: false` for stable data to reduce unnecessary requests
- Use `select` option to transform and memoize data at query level
- Consider `placeholderData` for instant perceived loading

**Implementation Details:**
```typescript
// Recommended query configuration
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: 2,
      refetchOnWindowFocus: false,
    },
  },
});

Edge Cases:

Handle race conditions with
```
cancelQueries
```
on component unmount
Implement retry logic for transient network failures
Consider offline support with
```
persistQueryClient
```

References:


NEVER CODE! Just research and enhance the plan.

deepen-plan

NPX Install

Tags

SKILL.md Content

Deepen Plan - Power Enhancement Mode

Introduction

Plan File

Main Tasks

1. Parse and Analyze Plan Structure

2. Discover and Apply Available Skills

3. Discover and Apply Learnings/Solutions

4. Launch Per-Section Research Agents

5. Discover and Run ALL Review Agents

6. Wait for ALL Agents and Synthesize Everything

7. Enhance Plan Sections

9. Update Plan File

Output Format

Quality Checks

Post-Enhancement Options

Example Enhancement