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
316
plugins/compound-engineering/skills/ce-compound/SKILL.md
Normal file
316
plugins/compound-engineering/skills/ce-compound/SKILL.md
Normal file
@@ -0,0 +1,316 @@
|
||||
---
|
||||
name: ce:compound
|
||||
description: Document a recently solved problem to compound your team's knowledge
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
---
|
||||
|
||||
# /compound
|
||||
|
||||
Coordinate multiple subagents working in parallel to document a recently solved problem.
|
||||
|
||||
## Purpose
|
||||
|
||||
Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
|
||||
|
||||
**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/ce:compound # Document the most recent fix
|
||||
/ce:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Context-Aware Orchestration
|
||||
|
||||
### Phase 0: Context Budget Check
|
||||
|
||||
<critical_requirement>
|
||||
**Run this check BEFORE launching any subagents.**
|
||||
|
||||
The /compound command is token-heavy - it launches 5 parallel subagents that collectively consume ~10k tokens of context. Running near context limits risks compaction mid-compound, which degrades output quality significantly.
|
||||
</critical_requirement>
|
||||
|
||||
Before proceeding, the orchestrator MUST:
|
||||
|
||||
1. **Assess context usage**: Check how long the current conversation has been running. If there has been significant back-and-forth (many tool calls, large file reads, extensive debugging), context is likely constrained.
|
||||
|
||||
2. **Warn the user**:
|
||||
```
|
||||
⚠️ Context Budget Check
|
||||
|
||||
/compound launches 5 parallel subagents (~10k tokens). Long conversations
|
||||
risk compaction mid-compound, which degrades documentation quality.
|
||||
|
||||
Tip: For best results, run /compound early in a session - right after
|
||||
verifying a fix, before continuing other work.
|
||||
```
|
||||
|
||||
3. **Offer the user a choice**:
|
||||
```
|
||||
How would you like to proceed?
|
||||
|
||||
1. Full compound (5 parallel subagents, ~10k tokens) - best quality
|
||||
2. Compact-safe mode (single pass, ~2k tokens) - safe near context limits
|
||||
```
|
||||
|
||||
4. **If the user picks option 1** (or confirms full mode): proceed to Phase 1 below.
|
||||
5. **If the user picks option 2** (or requests compact-safe): skip to the **Compact-Safe Mode** section below.
|
||||
|
||||
---
|
||||
|
||||
### Full Mode
|
||||
|
||||
<critical_requirement>
|
||||
**Only ONE file gets written - the final documentation.**
|
||||
|
||||
Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
|
||||
</critical_requirement>
|
||||
|
||||
### Phase 1: Parallel Research
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
|
||||
#### 1. **Context Analyzer**
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
#### 3. **Related Docs Finder**
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
#### 4. **Prevention Strategist**
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
#### 5. **Category Classifier**
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
### Phase 2: Assembly & Write
|
||||
|
||||
<sequential_tasks>
|
||||
|
||||
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
||||
|
||||
The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
1. Collect all text results from Phase 1 subagents
|
||||
2. Assemble complete markdown file from the collected pieces
|
||||
3. Validate YAML frontmatter against schema
|
||||
4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 3: Optional Enhancement
|
||||
|
||||
**WAIT for Phase 2 to complete before proceeding.**
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Based on problem type, optionally invoke specialized agents to review the documentation:
|
||||
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
---
|
||||
|
||||
### Compact-Safe Mode
|
||||
|
||||
<critical_requirement>
|
||||
**Single-pass alternative for context-constrained sessions.**
|
||||
|
||||
When context budget is tight, this mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing a minimal but complete solution document.
|
||||
</critical_requirement>
|
||||
|
||||
The orchestrator (main conversation) performs ALL of the following in one sequential pass:
|
||||
|
||||
1. **Extract from conversation**: Identify the problem, root cause, and solution from conversation history
|
||||
2. **Classify**: Determine category and filename (same categories as full mode)
|
||||
3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` with:
|
||||
- YAML frontmatter (title, category, date, tags)
|
||||
- Problem description (1-2 sentences)
|
||||
- Root cause (1-2 sentences)
|
||||
- Solution with key code snippets
|
||||
- One prevention tip
|
||||
4. **Skip specialized agent reviews** (Phase 3) to conserve context
|
||||
|
||||
**Compact-safe output:**
|
||||
```
|
||||
✓ Documentation complete (compact-safe mode)
|
||||
|
||||
File created:
|
||||
- docs/solutions/[category]/[filename].md
|
||||
|
||||
Note: This was created in compact-safe mode. For richer documentation
|
||||
(cross-references, detailed prevention strategies, specialized reviews),
|
||||
re-run /compound in a fresh session.
|
||||
```
|
||||
|
||||
**No subagents are launched. No parallel tasks. One file written.**
|
||||
|
||||
---
|
||||
|
||||
## What It Captures
|
||||
|
||||
- **Problem symptom**: Exact error messages, observable behavior
|
||||
- **Investigation steps tried**: What didn't work and why
|
||||
- **Root cause analysis**: Technical explanation
|
||||
- **Working solution**: Step-by-step fix with code examples
|
||||
- **Prevention strategies**: How to avoid in future
|
||||
- **Cross-references**: Links to related issues and docs
|
||||
|
||||
## Preconditions
|
||||
|
||||
<preconditions enforcement="advisory">
|
||||
<check condition="problem_solved">
|
||||
Problem has been solved (not in-progress)
|
||||
</check>
|
||||
<check condition="solution_verified">
|
||||
Solution has been verified working
|
||||
</check>
|
||||
<check condition="non_trivial">
|
||||
Non-trivial problem (not simple typo or obvious error)
|
||||
</check>
|
||||
</preconditions>
|
||||
|
||||
## What It Creates
|
||||
|
||||
**Organized documentation:**
|
||||
|
||||
- File: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
**Categories auto-detected from problem:**
|
||||
|
||||
- build-errors/
|
||||
- test-failures/
|
||||
- runtime-errors/
|
||||
- performance-issues/
|
||||
- database-issues/
|
||||
- security-issues/
|
||||
- ui-bugs/
|
||||
- integration-issues/
|
||||
- logic-errors/
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| ❌ Wrong | ✅ Correct |
|
||||
|----------|-----------|
|
||||
| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
|
||||
| Research and assembly run in parallel | Research completes → then assembly runs |
|
||||
| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Documentation complete
|
||||
|
||||
Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: 3 code fixes
|
||||
✓ Related Docs Finder: 2 related issues
|
||||
✓ Prevention Strategist: Prevention strategies, test suggestions
|
||||
✓ Category Classifier: `performance-issues`
|
||||
|
||||
Specialized Agent Reviews (Auto-Triggered):
|
||||
✓ performance-oracle: Validated query optimization approach
|
||||
✓ kieran-rails-reviewer: Code examples meet Rails standards
|
||||
✓ code-simplicity-reviewer: Solution is appropriately minimal
|
||||
✓ every-style-editor: Documentation style verified
|
||||
|
||||
File created:
|
||||
- docs/solutions/performance-issues/n-plus-one-brief-generation.md
|
||||
|
||||
This documentation will be searchable for future reference when similar
|
||||
issues occur in the Email Processing or Brief System modules.
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Link related documentation
|
||||
3. Update other references
|
||||
4. View documentation
|
||||
5. Other
|
||||
```
|
||||
|
||||
## The Compounding Philosophy
|
||||
|
||||
This creates a compounding knowledge system:
|
||||
|
||||
1. First time you solve "N+1 query in brief generation" → Research (30 min)
|
||||
2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
|
||||
3. Next time similar issue occurs → Quick lookup (2 min)
|
||||
4. Knowledge compounds → Team gets smarter
|
||||
|
||||
The feedback loop:
|
||||
|
||||
```
|
||||
Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
|
||||
↑ ↓
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Each unit of engineering work should make subsequent units of work easier—not harder.**
|
||||
|
||||
## Auto-Invoke
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /ce:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## Routes To
|
||||
|
||||
`compound-docs` skill
|
||||
|
||||
## Applicable Specialized Agents
|
||||
|
||||
Based on problem type, these agents can enhance documentation:
|
||||
|
||||
### Code Quality & Review
|
||||
- **kieran-rails-reviewer**: Reviews code examples for Rails best practices
|
||||
- **code-simplicity-reviewer**: Ensures solution code is minimal and clear
|
||||
- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues
|
||||
|
||||
### Specific Domain Experts
|
||||
- **performance-oracle**: Analyzes performance_issue category solutions
|
||||
- **security-sentinel**: Reviews security_issue solutions for vulnerabilities
|
||||
- **cora-test-reviewer**: Creates test cases for prevention strategies
|
||||
- **data-integrity-guardian**: Reviews database_issue migrations and queries
|
||||
|
||||
### Enhancement & Documentation
|
||||
- **best-practices-researcher**: Enriches solution with industry best practices
|
||||
- **every-style-editor**: Reviews documentation style and clarity
|
||||
- **framework-docs-researcher**: Links to Rails/gem documentation references
|
||||
|
||||
### When to Invoke
|
||||
- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
|
||||
- **Manual trigger**: User can invoke agents after /ce:compound completes for deeper review
|
||||
- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/ce:plan` - Planning workflow (references documented solutions)
|
||||
Reference in New Issue
Block a user