refactor(skills): migrate commands to skills directory structure
Move all 27 command .md files from commands/ to skills/*/SKILL.md format. Claude Code 2.1.3+ merged commands and skills - both create slash commands and work identically. Skills add optional features like supporting files and automatic context loading. - commands/ce/*.md -> skills/ce-*/SKILL.md - commands/workflows/*.md -> skills/workflows-*/SKILL.md - commands/*.md -> skills/*/SKILL.md - Update plugin.json and marketplace.json descriptions - Update CLAUDE.md directory structure docs - Update deploy-docs and generate_command references Fixes #116 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Matt Van Horn
committed by
Matt Van Horn
Matt Van Horn
parent
e426799f85
commit
3e99c11c0b
546
plugins/compound-engineering/skills/deepen-plan/SKILL.md
Normal file
546
plugins/compound-engineering/skills/deepen-plan/SKILL.md
Normal file
@@ -0,0 +1,546 @@
|
||||
---
|
||||
name: deepen-plan
|
||||
description: Enhance a plan with parallel research agents for each section to add depth, best practices, and implementation details
|
||||
argument-hint: "[path to plan file]"
|
||||
---
|
||||
|
||||
# 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:**
|
||||
1. Check for recent plans: `ls -la docs/plans/`
|
||||
2. 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:**
|
||||
1. Reads its skill's SKILL.md
|
||||
2. Follows the skill's workflow/instructions
|
||||
3. Applies the skill to the plan
|
||||
4. 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:**
|
||||
|
||||
1. **Skill-based sub-agents** - Each skill's full output (code examples, patterns, recommendations)
|
||||
2. **Learnings/Solutions sub-agents** - Relevant documented learnings from /ce:compound
|
||||
3. **Research agents** - Best practices, documentation, real-world examples
|
||||
4. **Review agents** - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
|
||||
5. **Context7 queries** - Framework documentation and patterns
|
||||
6. **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:**
|
||||
1. **View diff** - Show what was added/changed
|
||||
2. **Run `/technical_review`** - Get feedback from reviewers on enhanced plan
|
||||
3. **Start `/ce:work`** - Begin implementing this enhanced plan
|
||||
4. **Deepen further** - Run another round of research on specific sections
|
||||
5. **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:**
|
||||
- https://tanstack.com/query/latest/docs/react/guides/optimistic-updates
|
||||
- https://tkdodo.eu/blog/practical-react-query
|
||||
```
|
||||
|
||||
NEVER CODE! Just research and enhance the plan.
|
||||
Reference in New Issue
Block a user