From 31844bb6268fb21c4aadb0284d974272f975668e Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 15:36:16 +0000 Subject: [PATCH] feat(library): add compound_engineering job example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a DeepWork implementation inspired by Every Inc's Compound Engineering Plugin (https://github.com/EveryInc/compound-engineering-plugin). The job implements the core methodology: "Each unit of engineering work should make subsequent units easier—not harder." Includes 4 steps: - plan: Transform ideas into detailed implementation plans with research - work: Execute plans with task tracking and incremental commits - review: Multi-perspective code review before merging - compound: Document solutions and learnings for future reuse The README documents: - What DeepWork does automatically (8 features not needing re-implementation) - What the original plugin supports that this version does not (12 gaps) - Suggestions for improving DeepWork based on the gaps (10 recommendations) https://claude.ai/code/session_01EKw7Tc1vwYAH96kaDfq8xY --- library/jobs/compound_engineering/job.yml | 143 +++++++ library/jobs/compound_engineering/readme.md | 347 +++++++++++++++++ .../compound_engineering/steps/compound.md | 245 ++++++++++++ .../jobs/compound_engineering/steps/plan.md | 249 ++++++++++++ .../jobs/compound_engineering/steps/review.md | 359 ++++++++++++++++++ .../jobs/compound_engineering/steps/work.md | 234 ++++++++++++ 6 files changed, 1577 insertions(+) create mode 100644 library/jobs/compound_engineering/job.yml create mode 100644 library/jobs/compound_engineering/readme.md create mode 100644 library/jobs/compound_engineering/steps/compound.md create mode 100644 library/jobs/compound_engineering/steps/plan.md create mode 100644 library/jobs/compound_engineering/steps/review.md create mode 100644 library/jobs/compound_engineering/steps/work.md diff --git a/library/jobs/compound_engineering/job.yml b/library/jobs/compound_engineering/job.yml new file mode 100644 index 00000000..3e3de85f --- /dev/null +++ b/library/jobs/compound_engineering/job.yml @@ -0,0 +1,143 @@ +name: compound_engineering +version: "1.0.0" +summary: "Engineering workflow where each unit of work makes subsequent work easier through systematic planning, execution, review, and learning." +description: | + A DeepWork implementation inspired by Every Inc's Compound Engineering methodology. + The core philosophy: "Each unit of engineering work should make subsequent units easier—not harder." + + This workflow inverts traditional development: 80% planning and review, 20% execution. + By frontloading quality checks and systematically capturing learnings, technical debt + decreases over time instead of accumulating. + + The workflow operates in a continuous cycle: + 1. **Plan**: Convert feature ideas into detailed implementation plans with research + 2. **Work**: Execute plans systematically with task tracking and incremental commits + 3. **Review**: Multi-perspective code review before merging + 4. **Compound**: Document solutions and learnings for future reuse + + Each cycle compounds knowledge: plans inform future plans, reviews catch patterns, + solutions get documented, and quality stays high. + + Ideal for: + - Teams wanting to reduce technical debt over time + - Projects requiring high-quality, well-documented code + - Engineers who want their work to compound rather than accumulate complexity + - Organizations building institutional knowledge + + Based on: https://github.com/EveryInc/compound-engineering-plugin + +changelog: + - version: "1.0.0" + changes: "Initial DeepWork port of Compound Engineering methodology" + +workflows: + - name: full_cycle + summary: "Complete cycle: plan -> work -> review -> compound" + steps: + - plan + - work + - review + - compound + + - name: plan_and_work + summary: "Plan a feature and implement it" + steps: + - plan + - work + + - name: review_only + summary: "Review existing changes" + steps: + - review + +steps: + - id: plan + name: "Create Implementation Plan" + description: "Transforms feature ideas into detailed implementation plans through interactive refinement, local codebase research, and optional external research. Use when starting a new feature or task." + instructions_file: steps/plan.md + inputs: + - name: feature_description + description: "High-level description of the feature or task to plan" + - name: existing_learnings + description: "Path to docs/solutions/ if prior learnings exist" + file: "docs/solutions/" + outputs: + - file: "docs/plans/[date]-[type]-[name]-plan.md" + description: "Implementation plan with research, approach, and checklist" + dependencies: [] + quality_criteria: + - "**Idea Refined**: Did the agent ask clarifying questions to fully understand the requirement?" + - "**Codebase Researched**: Were existing patterns and conventions identified from the codebase?" + - "**Approach Defined**: Is the implementation approach clear with specific files/components to modify?" + - "**Checklist Created**: Is there a concrete checklist of tasks to complete?" + - "**Risks Identified**: Are potential risks and edge cases documented?" + - "**Plan File Created**: Has the plan been saved to docs/plans/?" + + - id: work + name: "Execute Implementation" + description: "Executes implementation plans systematically with task tracking, continuous testing, and incremental commits. Use after planning is complete." + instructions_file: steps/work.md + inputs: + - name: plan_file + description: "Path to the implementation plan" + file: "docs/plans/[plan-file].md" + from_step: plan + outputs: + - directory: "src/" + description: "Implementation source files" + - directory: "tests/" + description: "Test files" + - file: "docs/plans/[plan-file].md" + description: "Plan with completed task checkboxes" + dependencies: + - plan + quality_criteria: + - "**Plan Loaded**: Was the implementation plan read and understood?" + - "**Tasks Tracked**: Were tasks tracked using TodoWrite throughout execution?" + - "**Tests Run Continuously**: Were tests run after each logical change, not batched at end?" + - "**Commits Incremental**: Were changes committed incrementally after each completed task?" + - "**Plan Updated**: Were completed tasks checked off in the plan file?" + - "**All Tasks Complete**: Have all tasks in the plan been completed?" + + - id: review + name: "Multi-Perspective Code Review" + description: "Comprehensive code review using multiple specialized review perspectives. Use before merging changes." + instructions_file: steps/review.md + inputs: + - name: review_target + description: "Branch name, PR number, or files to review" + - name: code_review_standards + description: "Project-specific code review standards" + file: "[code_review_standards_path]" + outputs: + - file: "review-findings.md" + description: "Categorized review findings by severity (P1/P2/P3)" + dependencies: [] + quality_criteria: + - "**Target Identified**: Was the code to review clearly identified?" + - "**Multiple Perspectives**: Were at least 3 different review perspectives applied?" + - "**Findings Categorized**: Are findings categorized by severity (P1=critical, P2=important, P3=nice-to-have)?" + - "**P1 Issues Flagged**: Are any merge-blocking issues clearly marked?" + - "**Actionable Feedback**: Is each finding actionable with clear remediation?" + - "**Summary Provided**: Is there a summary of the overall code quality?" + + - id: compound + name: "Document Learnings" + description: "Captures solutions and learnings while context is fresh. Creates searchable documentation for future reference. Use after solving problems or completing features." + instructions_file: steps/compound.md + inputs: + - name: problem_context + description: "The problem that was solved or feature that was completed" + - name: solution_details + description: "What worked and why" + outputs: + - file: "docs/solutions/[category]/[filename].md" + description: "Documented solution with problem, symptoms, root cause, and fix" + dependencies: [] + quality_criteria: + - "**Problem Captured**: Is the problem clearly described with symptoms?" + - "**Root Cause Documented**: Is the root cause identified and explained?" + - "**Solution Clear**: Is the solution documented step-by-step?" + - "**Category Assigned**: Is the documentation filed in the appropriate category?" + - "**Searchable**: Does the documentation include keywords for future searchability?" + - "**Prevention Noted**: Are prevention strategies documented to avoid recurrence?" diff --git a/library/jobs/compound_engineering/readme.md b/library/jobs/compound_engineering/readme.md new file mode 100644 index 00000000..f52ff8f8 --- /dev/null +++ b/library/jobs/compound_engineering/readme.md @@ -0,0 +1,347 @@ +# Compound Engineering Job + +A DeepWork implementation inspired by [Every Inc's Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin). + +## Overview + +This job implements the core Compound Engineering methodology: **"Each unit of engineering work should make subsequent units easier—not harder."** + +The workflow inverts traditional development ratios: +- **80% planning and review** (frontloading quality) +- **20% execution** (following the plan) + +By systematically capturing learnings and maintaining quality gates, technical debt decreases over time instead of accumulating. + +## The Four Steps + +| Step | Purpose | Time Investment | +|------|---------|-----------------| +| **Plan** | Transform ideas into detailed implementation plans with research | 40% | +| **Work** | Execute plans with task tracking and incremental commits | 20% | +| **Review** | Multi-perspective code review before merging | 30% | +| **Compound** | Document solutions and learnings for future reuse | 10% | + +## Installation + +1. Copy this job to your project: + ```bash + cp -r library/jobs/compound_engineering .deepwork/jobs/ + ``` + +2. Sync to generate slash commands: + ```bash + deepwork sync + ``` + +3. Reload Claude Code to see the new commands. + +## Usage + +### Full Cycle +``` +/compound_engineering +``` +Select the `full_cycle` workflow to run all steps in sequence. + +### Individual Steps +``` +/compound_engineering.plan # Create an implementation plan +/compound_engineering.work # Execute a plan +/compound_engineering.review # Review code changes +/compound_engineering.compound # Document learnings +``` + +## Customization + +Before using, you may want to customize: + +| Placeholder | Location | Purpose | +|-------------|----------|---------| +| `[test_command]` | steps/work.md | Your test runner command | +| `[lint_command]` | steps/work.md | Your linting command | +| `[code_review_standards_path]` | job.yml | Path to your review standards | + +--- + +## What DeepWork Does Automatically + +The following features from the original Compound Engineering plugin **did not need to be re-implemented** because DeepWork provides them automatically: + +### 1. Slash Command Generation +- **Original**: Plugin manually defines `/workflows:plan`, `/workflows:work`, etc. +- **DeepWork**: Automatically generates slash commands from job.yml steps + +### 2. Step-by-Step Workflow Execution +- **Original**: Plugin implements workflow orchestration logic +- **DeepWork**: Handles step sequencing, dependencies, and execution automatically + +### 3. Quality Hooks and Validation +- **Original**: Plugin implements pre/post hooks for quality checks +- **DeepWork**: Provides hook system via `deepwork hook` command + +### 4. Platform Integration (Claude Code) +- **Original**: Plugin packages commands for Claude Code marketplace +- **DeepWork**: Syncs jobs to `.claude/commands/` automatically + +### 5. Multi-Platform Support +- **Original**: Plugin has separate converters for OpenCode, Codex +- **DeepWork**: Supports Claude Code and Gemini CLI natively + +### 6. Workflow State Management +- **Original**: Plugin tracks workflow progress +- **DeepWork**: Maintains state through step dependencies and outputs + +### 7. Rules System +- **Original**: Plugin has rules for file monitoring +- **DeepWork**: Provides `.deepwork/rules/` for file-based rules + +### 8. Sub-agent Coordination +- **Original**: Plugin spawns specialized agents +- **DeepWork**: Agents can use Task tool with guidance from step instructions + +--- + +## What This Version Does NOT Support + +The following features from the original Compound Engineering plugin are **not implemented** in this DeepWork version: + +### 1. Specialized Review Agents (28 agents in original) +**Original**: 14+ specialized review agents including: +- `kieran-rails-reviewer`, `dhh-rails-reviewer` (framework-specific) +- `security-sentinel`, `performance-oracle` (domain-specific) +- `code-simplicity-reviewer`, `pattern-recognition-specialist` + +**This Version**: Uses general-purpose sub-agents with prompts that guide review perspective. Less specialized but more flexible. + +**Impact**: Reviews may miss framework-specific nuances that dedicated agents would catch. + +### 2. Git Worktree Integration +**Original**: `/workflows:work` and `/workflows:review` offer to create git worktrees for isolated development/review environments. + +**This Version**: Does not manage git worktrees. Users work on regular branches. + +**Impact**: Can't do parallel development in isolated environments as easily. + +### 3. File-Based Todo Tracking (`todos/` directory) +**Original**: Creates markdown todo files in `todos/` directory with YAML frontmatter, status tracking (pending/ready/complete), and priority levels. + +**This Version**: Uses TodoWrite tool for in-session tracking. No persistent todo files. + +**Impact**: Task state doesn't persist between sessions. Can't triage todos across team. + +### 4. Screenshot Capture and Upload +**Original**: `/workflows:work` captures screenshots for UI changes and uploads to image hosts for PR documentation. + +**This Version**: Does not automate screenshot capture or upload. + +**Impact**: Visual documentation must be done manually. + +### 5. MCP Server Integration (context7) +**Original**: Integrates with context7 MCP server for framework documentation lookup (100+ frameworks). + +**This Version**: Uses WebSearch for external research. No MCP integration. + +**Impact**: Framework-specific documentation lookup is less reliable. + +### 6. Figma Design Sync +**Original**: `figma-design-sync` agent synchronizes web implementations with Figma designs. + +**This Version**: No Figma integration. + +**Impact**: Design-to-code verification is manual. + +### 7. Browser Automation (`agent-browser`) +**Original**: Provides CLI-based browser automation for testing and screenshots. + +**This Version**: No browser automation. + +**Impact**: Can't automate browser-based testing or capture. + +### 8. Image Generation (`gemini-imagegen`) +**Original**: Generates and edits images using Google's Gemini API. + +**This Version**: No image generation capability. + +**Impact**: Can't generate documentation images or diagrams. + +### 9. PR Comment Resolution +**Original**: `/resolve_pr_parallel` resolves GitHub PR comments in parallel. + +**This Version**: No dedicated PR comment resolution. + +**Impact**: PR feedback must be addressed manually. + +### 10. Automatic Trigger Phrases +**Original**: `/workflows:compound` auto-triggers on phrases like "that worked!", "it's fixed". + +**This Version**: Must be invoked explicitly. + +**Impact**: Users may forget to document learnings. + +### 11. Language/Framework-Specific Skills +**Original**: 15 skills including `dhh-rails-style`, `andrew-kane-gem-writer`, `dspy-ruby`, `frontend-design`. + +**This Version**: No framework-specific skills included. + +**Impact**: Must prompt for framework conventions manually. + +### 12. Changelogs and Release Management +**Original**: `/changelog` generates changelogs, `/release-docs` manages documentation. + +**This Version**: No changelog or release automation. + +**Impact**: Release documentation is manual. + +--- + +## Suggestions for Improving DeepWork + +Based on the gaps above and analysis of how Compound Engineering works, here are suggestions for DeepWork: + +### High Priority + +#### 1. Persistent Todo Files +**Gap**: TodoWrite is session-scoped; Compound Engineering persists todos to files. + +**Suggestion**: Add a `todo_persistence` option to jobs that writes TodoWrite state to markdown files in a `todos/` directory. This enables: +- Task state persistence between sessions +- Team-wide task visibility +- Triage workflows across multiple contributors + +#### 2. Agent Persona System +**Gap**: Can't define specialized agent personas that bring domain expertise. + +**Suggestion**: Add an `agents/` directory to jobs where users can define personas: +```yaml +# .deepwork/jobs/my_job/agents/security-reviewer.yml +name: security-reviewer +persona: | + You are a security-focused code reviewer. You look for: + - Input validation gaps + - Authentication/authorization issues + - Data exposure risks + ... +``` + +These could be referenced in steps: `use_agent: security-reviewer` + +#### 3. Parallel Sub-agent Execution +**Gap**: Review step must spawn sub-agents sequentially or rely on Task tool parallelism. + +**Suggestion**: Add explicit parallel execution syntax in steps: +```yaml +parallel_agents: + - security-reviewer + - performance-reviewer + - pattern-reviewer +aggregate_results: true +``` + +### Medium Priority + +#### 4. External Tool Integration (MCP) +**Gap**: No way to integrate with MCP servers like context7. + +**Suggestion**: Add `mcp_servers` configuration to job.yml or project config: +```yaml +mcp_servers: + - name: context7 + url: https://context7.com/mcp +``` + +#### 5. Trigger Phrases / Auto-invocation +**Gap**: Jobs must be explicitly invoked. + +**Suggestion**: Add `triggers` to job.yml: +```yaml +triggers: + phrases: + - "that worked" + - "finally fixed" + - "problem solved" + action: suggest # or auto-run +``` + +#### 6. Git Worktree Support +**Gap**: No built-in worktree management. + +**Suggestion**: Add worktree helpers: +```bash +deepwork worktree create feature-x +deepwork worktree list +deepwork worktree cleanup +``` + +Or document a pattern for managing worktrees in jobs. + +#### 7. Screenshot/Image Capture +**Gap**: No visual documentation automation. + +**Suggestion**: Add image capture to the tool set or document integration with existing screenshot tools. Could be a skill in the library. + +### Lower Priority + +#### 8. Framework Detection and Adaptation +**Gap**: Jobs don't adapt based on detected frameworks. + +**Suggestion**: Add framework detection: +```yaml +framework_adaptations: + rails: + review_agents: [rails-reviewer] + test_command: bundle exec rspec + nextjs: + review_agents: [react-reviewer] + test_command: npm test +``` + +#### 9. PR Integration +**Gap**: No direct GitHub/GitLab PR integration. + +**Suggestion**: Add PR utilities: +```bash +deepwork pr create --from-plan docs/plans/feature-plan.md +deepwork pr review 123 +``` + +#### 10. Learning Aggregation +**Gap**: Solutions accumulate but aren't automatically aggregated into patterns. + +**Suggestion**: Add a `deepwork learn analyze` command that: +- Scans `docs/solutions/` +- Identifies recurring themes +- Suggests pattern documentation +- Detects critical issues that should be in required reading + +--- + +## The Compound Engineering Philosophy + +This job embodies a specific philosophy about engineering work: + +1. **Planning Pays Dividends**: Time invested in planning reduces time spent on rework, debugging, and reviews. The 80/20 split (planning/execution) may seem extreme but yields higher quality. + +2. **Quality is a Multiplier**: Every quality check now prevents multiple issues later. Technical debt compounds negatively; quality compounds positively. + +3. **Knowledge Should Accumulate**: Solutions captured today accelerate work tomorrow. The `docs/solutions/` directory becomes an ever-growing knowledge base. + +4. **Multiple Perspectives Catch More**: A single reviewer misses things. Multiple specialized perspectives (security, performance, patterns) catch a broader range of issues. + +5. **Small Commits, Continuous Testing**: Large batched commits are harder to review and debug. Small incremental commits with continuous testing maintain quality. + +## Credits + +This job is inspired by and based on [Every Inc's Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) (MIT License). + +The original plugin provides: +- 28 specialized agents +- 24 slash commands +- 15 skills +- MCP server integration +- Multi-platform support + +This DeepWork version captures the core methodology in a simpler, more portable format while identifying gaps that could improve DeepWork's capabilities. + +--- + +*This example demonstrates how DeepWork can replicate sophisticated AI engineering workflows while highlighting areas for platform improvement.* diff --git a/library/jobs/compound_engineering/steps/compound.md b/library/jobs/compound_engineering/steps/compound.md new file mode 100644 index 00000000..6dbbbb97 --- /dev/null +++ b/library/jobs/compound_engineering/steps/compound.md @@ -0,0 +1,245 @@ +# Document Learnings + +## Objective + +Capture solutions and learnings while context is fresh, creating searchable documentation for future reference. + +## Task + +Document a recently solved problem or completed feature in a structured format that makes it easy for future engineers (including AI assistants) to find and apply the solution. + +**Philosophy**: Knowledge compounds when captured. A problem solved once should never need to be solved from scratch again. This step converts ephemeral context into permanent institutional knowledge. + +### When to Use This Step + +Run this step when: +- You just fixed a tricky bug +- You solved a problem after significant debugging +- You discovered a non-obvious solution +- You learned something that would help others +- A feature implementation had unexpected challenges +- You found a pattern worth documenting + +**Trigger phrases** (if you hear these, suggest this step): +- "That worked!" +- "Finally fixed it" +- "The problem was..." +- "Turns out the issue was..." +- "I wish I'd known..." + +### Phase 1: Capture Context + +While the context is fresh, gather: + +1. **Problem Description** + - What was the symptom observed? + - What was the expected vs actual behavior? + - When/where did it occur? + +2. **Investigation Path** + - What did you try that didn't work? + - What led you to the solution? + - What was the debugging process? + +3. **Root Cause** + - What was actually wrong? + - Why did it happen? + - What made it non-obvious? + +4. **Solution** + - What fixed it? + - Why does this fix work? + - Are there alternative solutions? + +5. **Prevention** + - How can this be prevented in the future? + - Should there be a test for this? + - Should there be a lint rule or guard? + +### Phase 2: Categorize the Learning + +Assign the documentation to an appropriate category: + +| Category | Use For | +|----------|---------| +| `build-errors` | Compilation, bundling, dependency issues | +| `test-failures` | Test flakiness, mocking issues, test setup | +| `runtime-errors` | Exceptions, crashes, unexpected behavior | +| `performance-issues` | Slow queries, memory leaks, bottlenecks | +| `database-issues` | Migrations, queries, data integrity | +| `security-issues` | Vulnerabilities, auth problems, data exposure | +| `ui-bugs` | Visual issues, interaction problems, layout | +| `integration-issues` | API problems, service communication | +| `logic-errors` | Business logic bugs, edge cases | +| `configuration` | Environment, settings, deployment | +| `patterns` | Useful patterns, best practices | +| `anti-patterns` | Things to avoid, common mistakes | + +### Phase 3: Create Documentation + +Create a markdown file in `docs/solutions/[category]/`: + +```markdown +--- +title: [Brief descriptive title] +category: [category from above] +date: YYYY-MM-DD +tags: [relevant, searchable, keywords] +related: [links to related solutions if any] +--- + +# [Title] + +## Problem + +### Symptoms +[What was observed - error messages, unexpected behavior] + +### Context +[When/where this occurred - specific conditions] + +### Expected Behavior +[What should have happened] + +### Actual Behavior +[What actually happened] + +## Investigation + +### What Didn't Work +1. [Approach tried and why it failed] +2. [Another approach and why it failed] + +### What Led to the Solution +[The debugging process, the "aha" moment] + +## Root Cause + +[Clear explanation of why this happened] + +## Solution + +### The Fix +[Step-by-step solution] + +```[language] +// Code example if applicable +``` + +### Why This Works +[Explanation of why the solution addresses the root cause] + +### Alternative Solutions +[Other approaches that could work, with trade-offs] + +## Prevention + +### How to Avoid This +- [Preventive measure 1] +- [Preventive measure 2] + +### Suggested Tests/Guards +```[language] +// Test or guard code if applicable +``` + +## Related Resources +- [Link to relevant documentation] +- [Link to related issue or PR] + +--- +*Documented via Compound Engineering methodology* +``` + +### Phase 4: File the Documentation + +1. **Create the Directory** (if needed) + ```bash + mkdir -p docs/solutions/[category] + ``` + +2. **Choose a Filename** + - Use kebab-case: `descriptive-name.md` + - Be specific: `postgres-connection-pool-exhaustion.md` not `db-issue.md` + +3. **Save the File** + - Path: `docs/solutions/[category]/[filename].md` + +### Phase 5: Cross-Reference + +1. **Check for Related Issues** + - Search for similar problems in `docs/solutions/` + - Link to related solutions in the "related" frontmatter + +2. **Pattern Detection** + - If this is the 3rd+ similar issue, consider adding to a `patterns` or `anti-patterns` doc + - Escalate recurring issues to project documentation + +3. **Notify if Critical** + - If this is a critical pattern everyone should know, mention it to the user + - Suggest adding to onboarding docs or required reading + +## Example Dialog + +``` +User: Finally fixed that notification bug! The WebSocket was disconnecting because we weren't handling reconnection properly. + +Claude: Great! Let's capture this learning while the context is fresh. I'll document this solution. + +[Asks clarifying questions to fill gaps] + +What were the symptoms you observed? + +User: Notifications would stop working after about 30 minutes. Users had to refresh to get them again. + +Claude: And what led you to discover it was a reconnection issue? + +User: I noticed in the network tab that the WebSocket was closing with code 1006, which is an abnormal closure. Then I saw we had no reconnection logic. + +Claude: Got it. Let me create the documentation. + +[Creates file] + +# Documentation Created + +**File**: docs/solutions/integration-issues/websocket-reconnection-notifications.md + +**Summary**: +- Problem: Notifications stop after ~30 minutes +- Root Cause: WebSocket abnormal closure (1006) with no reconnection logic +- Solution: Added exponential backoff reconnection with max retries +- Prevention: Added automated test that simulates connection drop + +**Tags**: websocket, notifications, reconnection, real-time + +I've also linked this to a related solution: +- `docs/solutions/integration-issues/websocket-heartbeat-timeout.md` (related connection issue) + +This is the second WebSocket-related issue this month. Would you like me to: +1. Create a general "WebSocket Best Practices" pattern document? +2. Add this to the team's required reading? +3. Just keep this individual solution? + +User: Create the best practices doc + +Claude: [Creates docs/solutions/patterns/websocket-best-practices.md] + +Created! This consolidates learnings from both WebSocket issues into a reusable reference. +``` + +## Quality Criteria + +- Problem is clearly described with symptoms +- Root cause is identified and explained +- Solution is documented step-by-step +- Documentation is filed in the appropriate category +- Tags make the documentation searchable +- Prevention strategies are documented + +## Context + +This is the knowledge-capture step in the Compound Engineering cycle. It transforms temporary debugging context into permanent searchable documentation. + +The compounding effect: Every documented solution makes the next similar problem faster to solve. Over time, the `docs/solutions/` directory becomes a powerful institutional knowledge base. + +This step works best when done immediately after solving a problem, while all the context is still in memory. Waiting even a day causes important details to be lost. diff --git a/library/jobs/compound_engineering/steps/plan.md b/library/jobs/compound_engineering/steps/plan.md new file mode 100644 index 00000000..d70ac825 --- /dev/null +++ b/library/jobs/compound_engineering/steps/plan.md @@ -0,0 +1,249 @@ +# Create Implementation Plan + +## Objective + +Transform a feature idea or task description into a detailed, research-backed implementation plan that will guide systematic execution. + +## Task + +Work interactively with the user to refine their idea, research existing codebase patterns, optionally research external best practices, and produce a comprehensive implementation plan document. + +**Philosophy**: Spend 80% of effort on planning to make the 20% execution smooth. A well-planned feature is easier to implement, review, and maintain. + +### Phase 1: Idea Refinement + +Start by understanding what the user wants to build. Ask clarifying questions to fill gaps in the requirement: + +1. **Understand the Goal** + - What problem does this solve? + - Who is the user/customer? + - What does success look like? + +2. **Scope Definition** + - What's in scope vs out of scope? + - Are there related features that should be considered? + - What are the constraints (time, technology, etc.)? + +3. **Acceptance Criteria** + - How will we know when it's done? + - What are the must-have vs nice-to-have requirements? + +Use the AskUserQuestion tool to gather this information interactively. Don't proceed until you have clear answers. + +### Phase 2: Local Codebase Research + +Before designing a solution, understand what already exists: + +1. **Pattern Discovery** + - Search for similar features in the codebase + - Identify existing conventions (naming, structure, patterns) + - Find reusable components or utilities + +2. **Architecture Understanding** + - Where does this feature fit in the existing architecture? + - What components will need to be modified? + - Are there existing abstractions to leverage? + +3. **Test Pattern Analysis** + - How are similar features tested? + - What test utilities exist? + - What's the expected test coverage? + +**Use the Task tool** with `subagent_type: Explore` to research the codebase: + +``` +Prompt: "Search this codebase for patterns related to [feature]. Find: +1. Similar implementations we can learn from +2. Existing utilities or helpers we should reuse +3. Naming conventions and code structure patterns +4. Testing patterns used for similar features" +``` + +### Phase 3: Prior Learnings Check + +Check if relevant learnings exist from previous work: + +1. **Search docs/solutions/** + - Look for related problem categories + - Find solutions that might apply + - Note any patterns or anti-patterns documented + +2. **Incorporate Learnings** + - Reference relevant prior solutions in the plan + - Avoid previously-documented pitfalls + - Reuse successful approaches + +### Phase 4: External Research (Optional) + +For complex or unfamiliar features, research best practices: + +1. **Determine if Research is Needed** + - Is this a well-understood pattern in the codebase? (Skip research) + - Is this new territory involving security, performance, or complex integrations? (Do research) + - Ask the user if uncertain + +2. **Research Topics** + - Best practices for this type of feature + - Security considerations + - Performance implications + - Common pitfalls to avoid + +**Use WebSearch** for external research when needed: + +``` +Query: "[framework] [feature type] best practices 2025" +``` + +### Phase 5: Create Implementation Plan + +Produce a plan document with the following structure: + +```markdown +# [Feature Name] Implementation Plan + +**Date**: YYYY-MM-DD +**Type**: feature | bugfix | refactor | chore +**Status**: planned + +## Summary +[One paragraph describing what this plan accomplishes] + +## Background +[Context on why this feature is needed] + +## Research Findings + +### Codebase Patterns +- [Pattern 1]: [Where found and how to apply] +- [Pattern 2]: [Where found and how to apply] + +### Prior Learnings Applied +- [Reference to docs/solutions/ if applicable] + +### External Research (if performed) +- [Key findings and sources] + +## Approach + +### High-Level Design +[Description of the overall approach] + +### Components to Modify +1. **[File/Component]**: [What changes needed] +2. **[File/Component]**: [What changes needed] + +### New Components to Create +1. **[File/Component]**: [Purpose and location] + +## Implementation Checklist + +### Setup +- [ ] Create feature branch +- [ ] [Other setup tasks] + +### Core Implementation +- [ ] [Task 1 - specific and actionable] +- [ ] [Task 2 - specific and actionable] +- [ ] [Task 3 - specific and actionable] + +### Testing +- [ ] [Test task 1] +- [ ] [Test task 2] + +### Documentation +- [ ] Update relevant documentation +- [ ] [Other doc tasks] + +## Risks and Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| [Risk 1] | Low/Med/High | Low/Med/High | [How to mitigate] | + +## Edge Cases +- [Edge case 1 and how to handle] +- [Edge case 2 and how to handle] + +## Open Questions +- [ ] [Question 1 - resolve before implementing] +- [ ] [Question 2 - resolve before implementing] + +--- +*Plan created with Compound Engineering methodology* +``` + +### Phase 6: Save the Plan + +1. **Create the plan file** + - Path: `docs/plans/YYYY-MM-DD-[type]-[feature-name]-plan.md` + - Ensure the `docs/plans/` directory exists + +2. **Summarize for the user** + - List the key decisions made + - Highlight any open questions to resolve + - Tell them to run `/compound_engineering.work` when ready to implement + +## Example Dialog + +``` +User: I want to add a notification system for when users get new messages + +Claude: I'll help you create an implementation plan for a notification system. +Let me ask a few clarifying questions first: + +[Uses AskUserQuestion] +1. What types of notifications? (In-app, email, push, or combination?) +2. Should notifications be real-time or can they be slightly delayed? +3. Do users need to be able to configure their notification preferences? + +User: In-app and email. Real-time for in-app, email can be batched. Yes, users should control preferences. + +Claude: Got it. Let me research your codebase for existing patterns... + +[Uses Task tool with Explore agent to research codebase] + +I found some relevant patterns: +- You have an existing `EmailService` in `src/services/email.ts` we can extend +- WebSocket setup exists in `src/realtime/` for real-time features +- User preferences are stored in `users.preferences` JSON column + +Let me check if there are any prior learnings... + +[Reads docs/solutions/ directory] + +Found a relevant solution: `docs/solutions/performance-issues/batch-email-processing.md` +documents a pattern for batching emails efficiently. + +Based on this research, here's the implementation plan: + +[Creates plan file] + +Plan saved to: docs/plans/2025-01-29-feature-notification-system-plan.md + +Key decisions: +- Extend existing EmailService for email notifications +- Use existing WebSocket infrastructure for real-time +- Follow the batch processing pattern from prior learnings +- Add new UserNotificationPreferences table + +Open questions to resolve: +- [ ] What's the email batch interval? (suggested: every 15 minutes) + +When you're ready, run `/compound_engineering.work` to start implementation. +``` + +## Quality Criteria + +- Idea was refined through interactive questioning +- Codebase patterns were researched and documented +- Prior learnings were checked and incorporated if relevant +- Implementation approach is clear and specific +- Checklist contains concrete, actionable tasks +- Risks and edge cases are identified +- Plan file is saved to docs/plans/ + +## Context + +This is the first step in the Compound Engineering cycle. A thorough plan makes the work step smoother and the review step faster. The plan also serves as documentation for future reference. + +By researching the codebase and prior learnings before designing, we ensure consistency and avoid reinventing solutions to already-solved problems. diff --git a/library/jobs/compound_engineering/steps/review.md b/library/jobs/compound_engineering/steps/review.md new file mode 100644 index 00000000..bbaff89c --- /dev/null +++ b/library/jobs/compound_engineering/steps/review.md @@ -0,0 +1,359 @@ +# Multi-Perspective Code Review + +## Objective + +Perform a comprehensive code review using multiple specialized perspectives to catch issues before merging. + +## Task + +Review code changes from multiple angles, categorize findings by severity, and provide actionable feedback. + +**Philosophy**: Reviews are 80% of quality assurance. Multiple perspectives catch what single-focus reviews miss. A thorough review now prevents bugs, tech debt, and rework later. + +### Phase 1: Identify Review Target + +Determine what code to review: + +1. **Ask for the Target** + - Branch name (review all changes on that branch) + - PR number (if using GitHub) + - Specific files (for focused review) + - "Current changes" (review uncommitted or recent commits) + +2. **Get the Diff** + ```bash + # For branch comparison + git diff main...[branch-name] + + # For recent changes + git diff HEAD~5..HEAD + + # For uncommitted changes + git diff + ``` + +3. **Identify Changed Files** + ```bash + git diff --name-only main...[branch-name] + ``` + +### Phase 2: Setup for Review + +1. **Understand the Context** + - What feature or fix are these changes for? + - Is there an implementation plan to reference? + - What are the acceptance criteria? + +2. **Load Review Standards** + - Read the project's code review standards if they exist + - Note any project-specific conventions + +### Phase 3: Multi-Perspective Review + +Run reviews from multiple specialized perspectives. Use sub-agents (Task tool) to keep context clean. + +**IMPORTANT**: Run at least 3 perspectives. Choose based on what the changes touch. + +#### Core Perspectives (Always Run) + +1. **Code Quality Reviewer** + Focus: Clarity, simplicity, maintainability + + ``` + Review these changes for code quality: + - Is the code simple and readable? + - Are names clear and descriptive? + - Is there unnecessary complexity? + - Are there DRY violations? + - Is the code well-organized? + ``` + +2. **Pattern Compliance Reviewer** + Focus: Consistency with existing codebase + + ``` + Review these changes for pattern compliance: + - Do they follow existing codebase conventions? + - Are there new patterns introduced unnecessarily? + - Is the code structure consistent with similar features? + - Are naming conventions followed? + ``` + +3. **Test Coverage Reviewer** + Focus: Test adequacy + + ``` + Review the tests for these changes: + - Are all new code paths tested? + - Are edge cases covered? + - Are the tests meaningful (not just for coverage)? + - Do tests follow existing patterns? + ``` + +#### Conditional Perspectives (Run When Relevant) + +4. **Security Reviewer** (run for: auth, input handling, data access) + Focus: Security vulnerabilities + + ``` + Review these changes for security issues: + - Input validation and sanitization + - Authentication and authorization + - Data exposure risks + - SQL injection, XSS, CSRF vulnerabilities + - Secrets handling + ``` + +5. **Performance Reviewer** (run for: data processing, queries, loops) + Focus: Performance implications + + ``` + Review these changes for performance: + - N+1 queries + - Unnecessary database calls + - Inefficient algorithms + - Memory usage concerns + - Caching opportunities + ``` + +6. **Database Reviewer** (run for: migrations, schema changes) + Focus: Data integrity and migrations + + ``` + Review these database changes: + - Is the migration reversible? + - Are there data integrity risks? + - Are indexes appropriate? + - Is the migration safe for production? + ``` + +7. **API Reviewer** (run for: endpoint changes, contracts) + Focus: API design and compatibility + + ``` + Review these API changes: + - Is the API intuitive and consistent? + - Are breaking changes identified? + - Is error handling appropriate? + - Is the documentation updated? + ``` + +8. **Accessibility Reviewer** (run for: UI changes) + Focus: Accessibility compliance + + ``` + Review these UI changes for accessibility: + - Keyboard navigation + - Screen reader compatibility + - Color contrast + - ARIA labels and roles + ``` + +### Phase 4: Run the Reviews + +For each perspective: + +1. **Spawn a Sub-Agent** + Use Task tool with `subagent_type: general-purpose` + + ``` + Prompt: "You are a [Perspective] reviewer. Review these code changes: + + [Include the diff or file contents] + + [Include perspective-specific questions from above] + + For each issue found, provide: + - File and line number + - Issue description + - Severity: P1 (critical/blocks merge), P2 (important), P3 (nice-to-have) + - Suggested fix" + ``` + +2. **Collect Findings** + - Gather all issues identified + - Note the perspective that found each issue + +### Phase 5: Synthesize Findings + +After all reviews complete: + +1. **Deduplicate** + - Multiple perspectives may find the same issue + - Combine duplicate findings + +2. **Categorize by Severity** + + **P1 - Critical (Blocks Merge)** + - Security vulnerabilities + - Data integrity risks + - Breaking changes without migration + - Failing tests + + **P2 - Important (Should Fix)** + - Performance issues + - Missing test coverage + - Code quality concerns + - Pattern violations + + **P3 - Nice-to-Have (Optional)** + - Style preferences + - Minor optimizations + - Documentation improvements + +3. **Create Findings Document** + + ```markdown + # Code Review Findings + + **Target**: [branch/PR/files reviewed] + **Date**: YYYY-MM-DD + **Perspectives Applied**: [list of perspectives] + + ## Summary + - P1 (Critical): [count] + - P2 (Important): [count] + - P3 (Nice-to-have): [count] + + **Merge Status**: [BLOCKED if any P1s, else APPROVED with conditions] + + ## P1 - Critical Issues + + ### [Issue Title] + - **File**: [path:line] + - **Found by**: [perspective] + - **Issue**: [description] + - **Fix**: [suggested remediation] + + ## P2 - Important Issues + + ### [Issue Title] + ... + + ## P3 - Nice-to-Have + + ### [Issue Title] + ... + + ## Positive Observations + - [What was done well] + ``` + +### Phase 6: Present Findings + +1. **Summarize for the User** + - Total findings by severity + - Whether merge is blocked (any P1s) + - Key issues to address + +2. **Provide Clear Next Steps** + - If P1s exist: Must fix before merge + - If only P2s: Strongly recommend fixing + - If only P3s: Optional, approve merge + +3. **Offer Follow-up** + - Re-review after fixes + - Run `/compound_engineering.compound` to document learnings + +## Example Dialog + +``` +User: /compound_engineering.review + +Claude: I'll perform a multi-perspective code review. What should I review? + +1. A specific branch +2. A PR number +3. Current uncommitted changes +4. Specific files + +User: Branch feature/notification-system + +Claude: Reviewing changes on feature/notification-system compared to main... + +[Gets diff and file list] + +I see changes to: +- src/services/email.ts (modified) +- src/realtime/notifications.ts (new) +- src/db/migrations/add_notification_prefs.ts (new) +- tests/notifications.test.ts (new) + +Based on these changes, I'll apply 6 review perspectives: +1. Code Quality (core) +2. Pattern Compliance (core) +3. Test Coverage (core) +4. Security (auth/data handling) +5. Performance (email batching) +6. Database (migration) + +Running reviews in parallel... + +[Spawns 6 sub-agents with Task tool] + +Synthesizing findings... + +# Review Summary + +**Perspectives Applied**: 6 +**Findings**: 0 P1, 3 P2, 2 P3 +**Merge Status**: APPROVED with conditions + +## P2 - Important Issues (3) + +### Missing Rate Limiting on Notification Endpoint +- **File**: src/realtime/notifications.ts:45 +- **Found by**: Security Reviewer +- **Issue**: The WebSocket notification endpoint doesn't rate limit, allowing potential spam +- **Fix**: Add rate limiting middleware, suggest 10 notifications/second per user + +### No Index on notification_preferences.user_id +- **File**: src/db/migrations/add_notification_prefs.ts:12 +- **Found by**: Database Reviewer +- **Issue**: The user_id foreign key should have an index for query performance +- **Fix**: Add index in migration + +### Batch Email Query Could Be Optimized +- **File**: src/services/email.ts:78 +- **Found by**: Performance Reviewer +- **Issue**: The batch query fetches all columns when only email is needed +- **Fix**: Select only required columns + +## P3 - Nice-to-Have (2) + +### Consider Extracting Notification Types to Enum +- **File**: src/realtime/notifications.ts:15 +- **Found by**: Pattern Compliance +- **Issue**: Notification types are string literals, enum would be safer +- **Fix**: Extract to NotificationType enum + +### Add JSDoc to New Public Functions +- **File**: src/services/email.ts:60 +- **Found by**: Code Quality +- **Issue**: New public functions lack documentation +- **Fix**: Add JSDoc comments + +## Positive Observations +- Good test coverage for the new functionality +- Migration is properly reversible +- Follows existing service patterns well + +**Recommendation**: Fix the 3 P2 issues before merging. The P3s are optional. + +Would you like me to help fix these issues, or should I re-review after you make changes? +``` + +## Quality Criteria + +- Review target was clearly identified +- At least 3 review perspectives were applied +- Findings were categorized by severity (P1/P2/P3) +- Any merge-blocking issues are clearly marked as P1 +- Each finding includes actionable remediation +- A summary of overall code quality was provided + +## Context + +This is the quality assurance step in the Compound Engineering cycle. Multiple perspectives catch different types of issues that a single-focus review would miss. + +The severity categorization (P1/P2/P3) helps prioritize: P1s must be fixed, P2s should be fixed, P3s are optional. This prevents bikeshedding on minor issues while ensuring critical issues are addressed. diff --git a/library/jobs/compound_engineering/steps/work.md b/library/jobs/compound_engineering/steps/work.md new file mode 100644 index 00000000..dd389392 --- /dev/null +++ b/library/jobs/compound_engineering/steps/work.md @@ -0,0 +1,234 @@ +# Execute Implementation + +## Objective + +Execute an implementation plan systematically with continuous testing, incremental commits, and real-time task tracking. + +## Task + +Follow the implementation plan step-by-step, maintaining quality throughout execution by testing continuously and committing incrementally. + +**Philosophy**: Execution is only 20% of the effort because the plan did the heavy lifting. Focus on following the plan, maintaining quality, and avoiding scope creep. + +### Phase 1: Quick Start + +1. **Load the Plan** + - Ask the user which plan to execute, or use the most recent one + - Read the plan file from `docs/plans/` + - Verify all open questions have been resolved (if not, resolve them first) + +2. **Clarify Any Ambiguities** + - If anything in the plan is unclear, ask before starting + - Don't make assumptions that could lead to rework + +3. **Setup the Environment** + - Create a feature branch if not already on one + - Ensure the development environment is ready + - Pull latest changes from the base branch + + ```bash + git checkout -b feature/[feature-name] + # or verify current branch + git branch --show-current + ``` + +### Phase 2: Task Tracking Setup + +**IMPORTANT**: Use the TodoWrite tool throughout execution to track progress. + +1. **Import Tasks from Plan** + - Extract all checklist items from the plan's "Implementation Checklist" section + - Add them to TodoWrite as pending tasks + +2. **Task Management Rules** + - Only ONE task should be `in_progress` at a time + - Mark tasks `completed` immediately when done (don't batch) + - Add new tasks if you discover additional work needed + +### Phase 3: Task Execution Loop + +For each task in the checklist: + +1. **Mark Task In Progress** + - Use TodoWrite to mark the current task as `in_progress` + - Update the plan file: change `- [ ]` to `- [x]` for this task + +2. **Implement Following Patterns** + - Reference the codebase patterns identified in the plan + - Follow existing conventions (naming, structure, style) + - Avoid introducing new patterns unless necessary + +3. **Write Tests** + - Write or update tests for the change + - Follow the test patterns documented in the plan + - Don't skip tests to "save time" + +4. **Run Tests Immediately** + - Run tests after implementing each task + - Don't batch test runs to the end + - Fix failures before moving to the next task + + ```bash + [test_command] + ``` + +5. **Commit Incrementally** + - After each completed task, consider if it's a logical commit point + - Use conventional commit messages: `feat(scope): description` + - Small, focused commits are easier to review and revert + + ```bash + git add [specific files] + git commit -m "feat([scope]): [what this commit does]" + ``` + +6. **Mark Task Complete** + - Use TodoWrite to mark the task as `completed` + - Verify the checkbox is checked in the plan file + +7. **Repeat** + - Move to the next task + - Continue until all tasks are complete + +### Phase 4: Quality Checkpoints + +At natural breakpoints (end of a section, major feature complete): + +1. **Run Full Test Suite** + ```bash + [test_command] + ``` + +2. **Run Linting** + ```bash + [lint_command] + ``` + +3. **Self-Review** + - Does the code follow the patterns identified in the plan? + - Is the code simpler than necessary? (prefer simplicity) + - Are there any obvious issues? + +### Phase 5: Completion + +When all tasks are done: + +1. **Final Verification** + - All tests pass + - All checklist items in the plan are checked + - No uncommitted changes + +2. **Summary** + - Summarize what was implemented + - Note any deviations from the plan (and why) + - List any follow-up tasks discovered + +3. **Next Steps** + - Tell the user to run `/compound_engineering.review` for code review + - Or if they discovered issues worth documenting, suggest `/compound_engineering.compound` + +## Example Dialog + +``` +User: /compound_engineering.work + +Claude: I'll execute an implementation plan. Which plan should I work on? + +[Lists recent plans from docs/plans/] + +1. 2025-01-29-feature-notification-system-plan.md +2. 2025-01-28-bugfix-login-timeout-plan.md + +User: 1 + +Claude: Loading the notification system plan... + +[Reads docs/plans/2025-01-29-feature-notification-system-plan.md] + +I see 8 tasks in the checklist. Let me set up task tracking: + +[Uses TodoWrite to add all tasks] + +Open questions status: +- [x] Email batch interval resolved (15 minutes) + +All questions resolved. Setting up the environment: + +[Creates feature branch] + +Starting implementation. Task 1 of 8: Create UserNotificationPreferences table + +[Marks task as in_progress in TodoWrite] + +Creating the migration... + +[Implements migration] + +Running tests... + +[Runs test command] + +Tests pass. Committing... + +[Commits with message: feat(notifications): add user notification preferences table] + +[Marks task as completed, updates plan checkbox] + +Moving to Task 2: Add preference columns... + +[Continues through all tasks] + +... + +All 8 tasks complete! + +Summary: +- Added UserNotificationPreferences table with 3 preference columns +- Extended EmailService with batch notification support +- Added WebSocket notification channel +- Created notification preference UI component +- Added 12 new tests (all passing) + +Deviations from plan: +- Added a `notification_count` denormalized column for performance (documented in commit) + +Ready for review. Run `/compound_engineering.review` to start multi-perspective code review. +``` + +## Handling Issues + +### Tests Fail +- Fix the failure before moving to the next task +- Don't accumulate failures +- If the fix is complex, consider if the plan needs revision + +### Scope Creep +- If you discover additional work needed, add it to TodoWrite +- If it's substantial, pause and discuss with the user +- Don't silently expand scope + +### Plan Seems Wrong +- Stop and discuss with the user +- It's better to revise the plan than to implement something incorrect +- Update the plan file with changes agreed upon + +### Unexpected Complexity +- Break down the complex task into smaller subtasks +- Add subtasks to TodoWrite +- Consider if this should be documented as a learning later + +## Quality Criteria + +- Plan was loaded and understood before starting +- TodoWrite was used to track all tasks throughout execution +- Tests were run after each task, not batched at the end +- Changes were committed incrementally with clear messages +- Plan checkboxes were updated as tasks completed +- All tasks from the plan were completed +- Final test suite passes + +## Context + +This is the execution step in the Compound Engineering cycle. By this point, the heavy thinking is done in the plan. This step is about disciplined execution: follow the plan, test continuously, commit incrementally. + +The continuous testing and incremental commits make the review step easier (smaller changes to understand) and provide natural rollback points if issues are discovered later.