# Compound Engineering

Compound engineering emerged from building [**Cora**](https://cora.computer/), an AI chief of staff for your inbox, from scratch. As we battle-tested every pattern, agent, and workflow across many pull requests, we developed personal productivity hacks to make the work go faster. This, in turn, evolved into a systematic approach to AI-assisted development. We're sharing the details of this philosophy because we believe compound engineering will become the default way software is built.

## The Philosophy

The core philosophy of compound engineering is that each unit of engineering work should make subsequent units easier—not harder.

Most codebases get harder to work with over time because each feature you add injects more complexity. After 10 years, teams spend more time fighting their system than building on it because each new feature is a negotiation with the old ones. Over time, the codebase becomes harder to understand, harder to modify, and harder to trust.

Compound engineering flips this on its head. Instead of features adding complexity and fragility, they teach the system new capabilities. Bug fixes eliminate entire categories of future bugs. When they are codified, patterns become tools for future work. Over time, the codebase becomes easier to understand, easier to modify, and easier to trust.

## The Main Loop

Every runs five products— [**Cora**](https://cora.computer/), [**Monologue**](https://www.monologue.to/), [**Sparkle**](https://makeitsparkle.co/), [**Spiral**](https://writewithspiral.com/), and our website [**Every.to**](/content/site-root.html)—with primarily single-person engineering teams. The system that makes this possible is a four-step loop that forms the basis of compound engineering:

**Plan → Work → Review → Compound → Repeat**

The first three steps—plan, work, and review—should be familiar to any developer. It's the fourth step that separates compound engineering from other engineering. This is where the gains accumulate. Skip it, and you've done traditional engineering with AI assistance.

The loop works the same whether you are fixing a bug in five minutes or building a feature over several days. You just spend more or less time on each step.

### 1. Plan

Planning transforms an idea into a blueprint, and better plans produce better results. Here are the actions to take and questions to ask yourself at this step:

- **Understand the requirement.** What's being built? Why? What constraints exist?
- **Research the codebase.** How does similar functionality work? What patterns exist?
- **Research externally.** What do the framework docs say? What are the established best practices?
- **Design the solution.** What's the approach? Which files need changes?
- **Validate the plan.** Does this hold together? Is it complete?

### 2. Work

Execution follows the plan. The agent implements while the developer monitors. Within this step, there are a few smaller tasks:

- **Set up isolation.** Git worktrees (isolated copies of your repository) or branches keep work separate.
- **Execute the plan.** The agent implements step by step.
- **Run validations.** Run tests, linting (automated code checking), and type checking after each change.
- **Track progress.** Check what work has been done, and what remains.
- **Handle issues.** When something breaks, adapt the plan.

If you trust the plan, there's no need to watch every line of code.

### 3. Review (assess)

This step catches issues before they ship. More importantly, it captures learnings for the next cycle, which becomes the basis for compound engineering. Here are the actions that happen during review:

- **Have multiple agents review the output.** Multiple specialized reviewers examine the code in parallel.
- **Prioritize findings.** Mark findings as P1 (must fix), P2 (should fix), or P3 (nice to fix).
- **Resolve findings.** The agent fixes issues based on review feedback.
- **Validate fixes.** Confirm fixes are correct and complete.
- **Capture patterns.** Document what went wrong to prevent recurrence.

### 4. Compound (the most important step)

Traditional development stops at step three, but the compound step is where the gains are to be made. The first three steps (plan, work, review) produce a feature. The fourth step produces a system that builds features better each time.

In this final step, these are the actions you should take:

- **Capture the solution.** Ask yourself: What worked? What didn't? What's the reusable insight?
- **Make it findable.** Add YAML frontmatter to make sure it is tagged with the right metadata, tags, and categories for retrieval.
- **Update the system.** Add new patterns into CLAUDE.md, the file the agent reads at the start of every session. Create new agents when warranted.
- **Verify the learning.** Ask yourself: Would the system catch this automatically next time?

## The Plugin

The compound engineering workflow ships as a plugin. Install it, and the full system is ready to use.

#### What's in the Box

- **[26 specialized agents.](https://github.com/EveryInc/compound-engineering-plugin/tree/main/agents)** Each agent is trained for a specific job.
- **[23 workflow commands.](https://github.com/EveryInc/compound-engineering-plugin/tree/main/commands)** These include the main loop plus utilities.
- **[13 skills.](https://github.com/EveryInc/compound-engineering-plugin/tree/main/skills)** These provide domain expertise, such as our agent-native architecture skill and style guide skill, on tap.

### Installation

Below are instructions for adding the plugin to some of the most common AI coding tools. Zero configuration is required.

#### Claude Code

```
claude /plugin marketplace add https://github.com/EveryInc/every-marketplace

claude /plugin install compound-engineering
```

#### OpenCode (experimental)

```
bunx @every-env/compound-plugin install compound-engineering --to opencode
```

#### Codex (experimental)

```
bunx @every-env/compound-plugin install compound-engineering --to codex
```

### Where Things Live

```
your-project/
├── CLAUDE.md              # Agent instructions, preferences, and patterns
├── docs/
│   ├── brainstorms/       # /workflows:brainstorm output
│   ├── solutions/         # /workflows:compound output (categorized)
│   └── plans/             # /workflows:plan output
└── todos/                 # /triage and review findings
    ├── 001-ready-p1-fix-auth.md
    └── 002-pending-p2-add-tests.md
```

**CLAUDE.md** is the most important file that the agent reads every session. Put your preferences, patterns, and project context here. When something goes wrong, add a note so the agent learns.

**docs/solutions/** builds your institutional knowledge because each solved problem becomes searchable documentation. Future sessions will find past solutions automatically.

**todos/** tracks work items with priority and status. When the review step turns up issues, use them to decide what's worth fixing, and then use resolution commands to work through them.

### Core Commands

#### [/workflows:brainstorm](https://github.com/EveryInc/compound-engineering-plugin/blob/main/commands/workflows/brainstorm.md)

When you're not sure what to build, start here.

```
/workflows:brainstorm Add user notifications
```

This command helps you brainstorm answers about what to build and plan answers for how to build them. Use this when requirements are fuzzy. The command runs lightweight repo research, then asks questions one at a time to clarify purpose, users, constraints, and edge cases. The AI then proposes approaches, and decisions are captured in `docs/brainstorms/` for handoff to `/workflows:plan`.

#### [/workflows:plan](https://github.com/EveryInc/compound-engineering-plugin/blob/main/commands/workflows/plan.md)

Describe what you want and get back a plan for how to build it.

```
/workflows:plan Add email notifications when users receive new comments
```

This command spawns three parallel research agents: repo-research-analyst (codebase patterns), framework-docs-researcher (documentation), and best-practices-researcher (industry standards). Then the spec-flow-analyzer agent analyzes user flows and edge cases. Results are merged into a structured plan with affected files and implementation steps.

#### [/workflows:work](https://github.com/EveryInc/compound-engineering-plugin/blob/main/commands/workflows/work.md)

This is where the agent actually writes the code.

```
/workflows:work
```

Runs in four phases: quick start (creates a git worktree—an isolated copy of your repo for parallel work—and sets up branch), execute (implements each task with progress tracking), quality check (optionally spawns over five reviewer agents—Rails, TypeScript, security, performance), and ship it (runs linting, creates PR). Each phase has clear entry and exit criteria.

#### [/workflows:review](https://github.com/EveryInc/compound-engineering-plugin/blob/main/commands/workflows/review.md)

Get your PR reviewed by a dozen specialized agents at once.

```
/workflows:review PR#123
```

Spawns more than 14 specialized agents in parallel that run simultaneously: security-sentinel, performance-oracle, data-integrity-guardian, architecture-strategist, pattern-recognition-specialist, code-simplicity-reviewer, and framework-specific reviewers (DHH-rails, Kieran-rails, TypeScript, Python). Everything gets combined into a single, prioritized list.

## Beliefs to Let Go

We have all been trained to believe certain things about software development. With improvements in AI tools, some of those beliefs are now obstacles. Here are eight of them to unlearn:

- **'The code must be written by hand'**  
The actual requirement for you to do your job well as a software engineer is simply to write good code, which can be defined as maintainable code that solves the right problem. Who types—a human or an agent—doesn't matter.
- **'Every line must be manually reviewed'**  
Again, a core requirement to be a good engineer is to write quality code. Manual line-by-line review is one method to get there, but so are automated systems that catch the same issues.
- **'Solutions must originate from the engineer'**  
When AI can research approaches, analyze tradeoffs, and recommend options, the engineer's job becomes to add taste—knowing which solution fits this codebase, this team, and this context.
- **'Code is the primary artifact'**  
A system that produces code is more valuable than any individual piece of code. A single brilliant implementation matters less than a process that consistently produces good implementations.
- **'Writing code is the core job function'**  
A developer's job is to ship value. Code is just one input in that job—planning, reviewing, and teaching the system all count too. Effective compound engineers write less code than before and ship more.
- **'First attempts should be good'**  
In our experience, first attempts have a 95 percent garbage rate. Second attempts are still 50 percent. This isn't failure—it's the process.
- **'Code is self-expression'**  
Developers subconsciously see AI-assisted development as an attack on their identity. It feels like a blow to the ego.
- **'More typing equals more learning'**  
Many developers fear that by not typing it, they are not learning it. However, the reality is that understanding matters more than muscle memory today.

## Getting Started

The compound engineering loop—plan, work, review, compound—is the process. But how much of that process you allow the AI to own depends on where you are in your familiarity and aptitude with AI. There are five stages against which developers can plot themselves to understand where they sit:

#### Stage 0: Manual Development
At this stage, you are writing code line by line without any AI. You perform research via documentation and Stack Overflow. Your debugging process happens through code reading and print statements.

#### Stage 1: Chat-based Assistance
At this stage, you are using AI as a smart reference tool, querying ChatGPT, Claude, or Cursor, receiving code snippets, and copy-pasting what's useful.

#### Stage 2: Agentic Tools with Line-by-Line Review
At this stage, agentic tools—AI assistants that can read files and make changes directly—enter the workflow. You allow the AI to read files and make changes directly in the codebase based on the context you have provided.

#### Stage 3: Plan-First, PR-Only Review
This is the stage where everything changes. You and AI collaborate on a detailed plan including requirements, approach, and edge cases.

#### Stage 4: Idea to PR (Single Machine)
You provide an idea, and the agent handles everything: codebase research, planning, implementation, test execution, self-review, issue resolution, and PR creation.

#### Stage 5: Parallel Cloud Execution (Multiple Devices)
This is the final stage. You move execution to the cloud and run things in parallel.

## Summary

- **Every unit of work makes subsequent work easier.** Code, documentation, and tooling should build on each other and make future work faster, not slower.
- **Taste belongs in systems, not in review.** Bake your judgment into configuration, schemas, and automated checks. If you don't you'll be spending time manually checking, which does not scale.
- **Teach the system, don't do the work yourself.** Time spent giving agents more context pays exponential dividends, but time spent typing code only solves the task in front of you.
- **Build safety nets, not review processes.** The way to build trust in building with AI is by building verification infrastructure, not by gatekeeping manually at every step.
- **Make environments agent-native.** Structure projects so AI agents can navigate and modify them autonomously.
- **Apply compound thinking everywhere.** Every artifact—code, docs, tests, prompts—should enable the next iteration to move faster.
- **Embrace the discomfort of letting go.** When you delegate to AI tools, you have to be okay with imperfect results that scale, rather than perfect results that don't.
- **Ship more value. Type less code.** Your output should be measured by the number of problems solved, not the number of keystrokes you logged.