--- name: compound-engineering description: "Compound Engineering workflow for AI-assisted development. Use when planning features, executing work, reviewing code, or codifying learnings. Follows the Plan → Work → Review → Compound loop where each unit of engineering makes subsequent work easier. Triggers on: plan this feature, implement this, review this code, compound learnings, create implementation plan, systematic development." --- This skill implements Compound Engineering—a development methodology where each unit of work makes subsequent work easier, not harder. Inspired by Every.to's engineering approach. ## Core Philosophy **Each unit of engineering work should make subsequent units of work easier—not harder.** Traditional development accumulates technical debt. Every feature adds complexity. Every change increases maintenance burden. Compound engineering inverts this by creating a learning loop where each bug, failed test, or problem-solving insight gets documented and used by future work. ## The Compound Engineering Loop ``` Plan → Work → Review → Compound → (repeat) ``` 1. **Plan (40%)**: Research approaches, synthesize information into detailed implementation plans 2. **Work (20%)**: Execute the plan systematically with continuous validation 3. **Review (20%)**: Evaluate output quality and identify learnings 4. **Compound (20%)**: Feed results back into the system to make the next loop better 80% of compound engineering is in planning and review. 20% is in execution. ## Step 1: Plan Before writing any code, create a comprehensive plan. Good plans start with research: ### Research Phase 1. **Codebase Analysis**: Search for similar patterns, conventions, and prior art in the codebase 2. **Commit History**: Use `git log` to understand how related features were built 3. **Documentation**: Check README, AGENTS.md, and inline documentation 4. **External Research**: Search for best practices relevant to the problem ### Plan Document Structure Create a plan document (markdown) with: ```markdown # Feature: [Name] ## Context - What problem does this solve? - Who is affected? - What's the current behavior vs desired behavior? ## Research Findings - Similar patterns found in codebase: [list with file links] - Relevant prior implementations: [commit references] - Best practices discovered: [external references] ## Acceptance Criteria - [ ] Criterion 1 (testable) - [ ] Criterion 2 (testable) - [ ] Criterion 3 (testable) ## Technical Approach 1. Step 1: [specific action] 2. Step 2: [specific action] 3. Step 3: [specific action] ## Code Examples [Include code snippets that follow existing patterns] ## Testing Strategy - Unit tests: [what to test] - Integration tests: [what to test] - Manual verification: [steps] ## Risks & Mitigations - Risk 1: [mitigation] - Risk 2: [mitigation] ``` ### Detail Levels - **Minimal**: Quick issues for simple features (1-2 hours work) - **Standard**: Issues with technical considerations (1-2 days work) - **Comprehensive**: Major features requiring architecture decisions (multi-day work) ## Step 2: Work Execute the plan systematically: ### Execution Workflow 1. **Create isolated environment**: Use feature branch or git worktree 2. **Break down into tasks**: Create TODO list from plan 3. **Execute systematically**: One task at a time 4. **Validate continuously**: Run tests after each change 5. **Commit incrementally**: Small, focused commits with clear messages ### Working Principles - Follow existing patterns discovered in research - Run tests after every meaningful change - If something fails, understand why before proceeding - Keep changes focused—don't scope creep ### Quality Checks During Work ```bash # After each change, verify: npm run typecheck # or equivalent npm test # run affected tests npm run lint # check code quality ``` ## Step 3: Review Before merging, perform comprehensive review: ### Review Checklist **Code Quality** - [ ] Follows existing codebase patterns and conventions - [ ] No unnecessary complexity—prefer duplication over wrong abstraction - [ ] Clear naming that matches project conventions - [ ] No debug code or console.logs left behind **Security** - [ ] No secrets or sensitive data exposed - [ ] Input validation where needed - [ ] Safe handling of user data **Performance** - [ ] No obvious performance regressions - [ ] Database queries are efficient (no N+1) - [ ] Appropriate caching if applicable **Testing** - [ ] Tests cover acceptance criteria - [ ] Edge cases considered - [ ] Tests are maintainable, not brittle **Architecture** - [ ] Change is consistent with system design - [ ] No unnecessary coupling introduced - [ ] Follows separation of concerns ### Multi-Perspective Review Consider the code from different angles: - **Maintainer perspective**: Will this be easy to modify in 6 months? - **Performance perspective**: Any bottlenecks? - **Security perspective**: Any vulnerabilities? - **Simplicity perspective**: Can this be simpler? ## Step 4: Compound This is where the magic happens—capture learnings to make future work easier: ### What to Compound **Patterns**: Document new patterns discovered or created ```markdown ## Pattern: [Name] When to use: [context] Implementation: [example code] See: [file reference] ``` **Decisions**: Record why certain approaches were chosen ```markdown ## Decision: [Choice Made] Context: [situation] Options considered: [alternatives] Rationale: [why this choice] Consequences: [trade-offs] ``` **Failures**: Turn every bug into a lesson ```markdown ## Lesson: [What Went Wrong] Symptom: [what was observed] Root cause: [actual problem] Fix: [solution] Prevention: [how to avoid in future] ``` ### Where to Codify Learnings 1. **AGENTS.md**: Project-wide guidance that applies everywhere 2. **Subdirectory AGENTS.md**: Specific guidance for subsystems 3. **Inline comments**: Only when the code isn't self-explanatory 4. **Test cases**: Turn bugs into regression tests ### Compounding in Practice After completing work, ask: - What did I learn that others should know? - What mistake did I make that can be prevented? - What pattern did I discover or create? - What decision was made and why? Document these in the appropriate location so future agents (and humans) benefit. ## Practical Commands ### Planning a Feature ``` Plan implementation for: [describe feature] - Research the codebase for similar patterns - Check git history for related changes - Create a detailed plan with acceptance criteria - Include code examples that match existing patterns ``` ### Executing Work ``` Execute this plan: [plan reference] - Create feature branch - Break into TODO list - Work through systematically - Run tests after each change - Create PR when complete ``` ### Reviewing Code ``` Review this change: [PR/diff reference] - Check for code quality issues - Look for security concerns - Evaluate performance implications - Verify test coverage - Suggest improvements ``` ### Compounding Learnings ``` Compound learnings from: [work just completed] - What patterns were used or created? - What decisions were made and why? - What failures occurred and how to prevent them? - Update AGENTS.md with relevant guidance ``` ## Key Principles 1. **Prefer duplication over wrong abstraction**: Simple, clear code beats complex abstractions 2. **Document as you go**: Every command generates documentation that makes future work easier 3. **Quality compounds**: High-quality code is easier to modify 4. **Systematic beats heroic**: Consistent processes beat individual heroics 5. **Knowledge should be codified**: Learnings should be captured and reused ## Success Metrics You're doing compound engineering well when: - Each feature takes less effort than the last similar feature - Bugs become one-time events (documented and prevented) - New team members can be productive quickly (institutional knowledge is accessible) - Code reviews surface fewer issues (patterns are established and followed) - Technical debt decreases over time (learnings compound) Remember: You're not just building features—you're building a development system that gets better with each use.