ninja nerdingCompound Engineering
Compound Engineering
A plugin of 36 skills for Claude Code, Codex, Cursor and eleven other hosts, built at Every while shipping Cora with a one-person engineering team. The idea in one line: each unit of work should make the next one easier, so the loop ends by writing down what it learned where the next plan will read it. About 25k GitHub stars. Free, MIT.
Jump to install, a feature start to finish, which skill to start with, or every skill.
Five things to know
The whole page in five boxes. Each links to the part that explains it.
- 01
One sentence
Each unit of engineering work should make the next one easier, not harder. That is the whole bet.
How - 02
The loop
Brainstorm, plan, work, simplify, review, compound. The last step writes down what you learned where the next plan will read it.
How - 03
80 / 20
Most of your time goes into the plan and the review. Writing the code is the cheap part now.
How - 04
Plans are the new code
The plan file is the artifact you own. Brainstorm fills in what to build, plan fills in the guardrails, work figures out the how.
How - 05
Hands off is a mode
After a brainstorm, lfg runs the rest to an open PR. It never merges. You still read the PR.
How
Where it came from
Kieran Klaassen opened his laptop one morning and found Claude Code had already reviewed his pull requests using three months of his own past review comments, without being asked. He wrote that up as the story behind compounding engineering, then turned the habits into a plugin. Trevin Chow joined as co-maintainer for version 3, which rebuilt it as self-contained skills so the same thing runs on Codex, Cursor and the rest. The quote that sticks: “Every bug fix feels half-done if it doesn't prevent its entire category going forward.”
Words on this page
Thirteen terms, in plain words. Skip this if you already work with coding agents and pull requests.
- Plugin
- A bundle you install into a coding agent to give it new abilities. This one is a set of skills, installed with two lines.
- Skill
- A named set of instructions the agent follows when you call it. You type its ID with a slash in front, like /ce-plan. On Codex it is $ce-plan.
- Host
- The coding agent the plugin runs inside. Claude Code, Codex and Cursor are hosts, and eleven others are supported.
- AGENTS.md and CLAUDE.md
- Instruction files in your repo that the agent reads. You point AGENTS.md at the lessons folder and paste standing rules into it. Adding a note to CLAUDE.md when the agent gets something wrong is the small version of this whole idea.
- Diff
- The lines a change adds, removes or edits. Simplify and review both work on the diff.
- PR (pull request)
- A proposed change, opened for review before it joins the main code. ce-work and lfg open one. Merging it stays your call.
- CI
- Short for continuous integration: the automated checks that run on a PR. lfg watches them and tries up to three rounds of repairs.
- Worktree
- A second working copy of the same repo, so one change stays isolated from another. Handy for starting the next brainstorm while work runs.
- Product Contract
- What a brainstorm settles: what to build, for whom, and what is out of scope. lfg plans better when it has one.
- U-IDs
- Labels for the units of work in a plan: U1, U2 and so on. Each unit lists files and test scenarios, and commits are prefixed with its ID.
- Risk surface
- The parts of a change where mistakes cost most: authentication, payments, migrations, external contracts. These always get the full plan and review, however small the change.
- Review personas
- Reviewer roles ce-code-review picks from the diff, such as correctness, testing, security and performance. Each looks at the change from its own angle.
- Frontmatter
- A short block of labelled fields (YAML) at the top of a lesson doc. It is what lets ce-plan and ce-ideate find the right lesson later.
Two lines, then one command in your repo
Zero config. After installing, run /ce-setup once per project. It reports which optional tools are missing, writes the config file, and offers to point your AGENTS.md at the knowledge store.
Claude Code
/plugin marketplace add EveryInc/compound-engineering-plugin /plugin install compound-engineering
Codex CLI (skills are $ce-plan there)
codex plugin marketplace add EveryInc/compound-engineering-plugin codex plugin add compound-engineering@compound-engineering-plugin
Cursor, in Agent chat
/add-plugin compound-engineering
Then, in any project
/ce-setup
Already installed?
Refresh the marketplace before you update. /plugin update on its own can leave you on the old version. When in doubt, remove and reinstall.
What your repo looks like after a few loops
your-project/
├── AGENTS.md
├── CONCEPTS.md
├── .compound-engineering/
│ └── config.yaml
└── docs/
├── plans/
├── solutions/
├── ideation/
└── pulse-reports/One plan file per feature in docs/plans/. Lessons in docs/solutions/, by category. Ideation output in docs/ideation/. CONCEPTS.md is the shared vocabulary that ce-compound grows. AGENTS.md should name the solutions folder so the agent finds it. config.yaml holds optional defaults such as docs_root, plan_model and output format.
Reading the Feb 2026 guide or watching the videos? Names changed in v3.
- /workflows:brainstorm/ce-brainstorm
- /workflows:plan/ce-plan
- /workflows:work/ce-work
- /workflows:review/ce-code-review
- /workflows:compound/ce-compound
- /resolve_pr_parallel, /triage, todosfolded into ce-code-review and ce-resolve-pr-feedback
- 26 agents + 23 commands + 13 skills36 self-contained skills, no separate agent files
Brainstorm → plan → work → simplify → review → compound
Every iteration, in this order. Skip ahead only when the earlier artifact already exists. A bug starts at ce-debug, not brainstorm. The return arrow is the point: compound writes the lesson, the next plan reads it.
01
ce-brainstorm
You have an idea or problem and need requirements before any plan.
One question at a time until a requirements-only plan exists.
02
ce-plan
Requirements are set. You need an implementation-ready plan.
Turns requirements into WHAT to build: guardrails, tests, confidence check.
03
ce-work
The plan is ready. Time to write the code.
Executes the plan, verifies, commits, and ships through quality gates.
04
ce-simplify-code
The code just landed. Review it before anyone else does.
Refines the fresh change for clarity and reuse. Behavior stays the same.
05
ce-code-review
You are about to merge. Check the diff against the plan.
Report-only multi-agent review. Applying fixes is a separate step.
06
ce-compound
The work is done. Write down what the next run should already know.
Stores the lesson in docs/solutions/ so the next brainstorm and plan read it.
Then back to brainstorm. Run one teaches it. Run two remembers. The plugin's own demo replays a lesson written on day one that a plan picked up, unprompted, eighteen days later on unrelated work.
The standard loop, as typed
/ce-brainstorm make background job retries safer /ce-plan /ce-work /ce-simplify-code /ce-code-review /ce-compound
The hands-off version
/ce-brainstorm describe the feature /lfg
What you type, what it asks, what lands on disk
Same loop, one real feature. Note the shape: one plan file that grows. Brainstorm fills in the what, plan adds the guardrails, work figures out the how with the code in front of it.
- 01
ce-brainstorm
/ce-brainstorm add a way for users to pause notifications
You
Answer one question per turn. It only asks about decisions it cannot look up in the repo. Pick from the 2 or 3 approaches it lays out, or say "your call".
It
Runs a background scout for repo evidence while you talk. Pressure-tests the premise (who are "users", is "pause" already a solution shape). Reads back a synthesis before writing anything.
On disk
A requirements-only plan in docs/plans/. Requirements, actors, flows and acceptance examples each get a stable ID (R1, A1, F1, AE1). Small ideas end in chat with no file.
- 02
ce-plan
/ce-plan
You
Confirm or redirect the scope summary. That is the last cheap moment to change your mind. Then wait.
It
Reads docs/solutions/ and the codebase in parallel. Breaks the work into units (U1, U2, ...) with files and test scenarios, never code. Scores its own weak sections and sends reviewers at them.
On disk
The same plan file, now implementation-ready. Menu: start ce-work, hand it to a /goal, or open the HTML version.
- 03
ce-work
/ce-work
You
Nothing, mostly. It moves to a feature branch on its own. Come back when the PR is up.
It
Executes unit by unit, tests as it goes, simplifies as it goes, runs a self-sized code review, writes an operational note (what to watch, when to roll back) and opens the PR.
On disk
Commits prefixed with U-IDs and an open PR. Progress is read from git, not from the plan.
- 04
ce-simplify-code
/ce-simplify-code
You
Run it before anyone reviews. Skip it for docs-only or tiny diffs.
It
Refines the fresh diff for clarity and reuse. Behavior stays the same. Tests still pass.
On disk
A cleaner diff. No bug hunting here, that is the next step.
- 05
ce-code-review
/ce-code-review
You
Read the findings. Say "apply:local" if you want the verified ones fixed. It never pushes.
It
Picks reviewer personas from the diff (correctness, testing, security, performance, migrations, ...), gates findings at 75% confidence, groups them by theme. A second model tries to break the first one's work.
On disk
A findings report with P0 to P3 severity. Your CODING_STANDARDS.md rules get enforced if the file exists.
- 06
ce-compound
/ce-compound
You
Say "that worked" and let it judge. Or name the lesson: "the email digest race condition we fixed". One lesson per run.
It
Asks three things: is the reasoning non-obvious, durable, and material? If the final code already explains it, it writes nothing. Checks for an existing doc to update instead of duplicating.
On disk
docs/solutions/<category>/<name>.md with frontmatter. The next ce-plan reads it. Run one teaches it, run two remembers.
Ceremony scales with the work. A small, well-bounded idea gets a Lightweight brainstorm that ends in chat with no file, and a Direct plan that answers in a few sentences. Risk surfaces (auth, payments, migrations, external contracts) always get the full treatment. You do not pick the tier. The skill does, and says which.
Where you walk in depends on what you already have
Eight starting situations. The skill names are what you type, with a slash in front.
You do not know what is worth building yet
ce-ideate
Finds grounded directions first. Optional. Its survivor flows into brainstorm.
You have a direction but not the shape
ce-brainstorm
The usual front door. Settles what, for whom, and what is out of scope.
A PRD, a detailed issue, or a clear one-liner exists
ce-plan
Skip brainstorm. Paste the issue URL or the PRD path.
Something is broken
ce-debug
Not brainstorm. Describe what is observably wrong, not the fix you suspect.
The change is already specified down to the file
ce-work
Bare-prompt mode. It triages size itself and sends big things back to plan.
Should we adopt X?
ce-pov
A verdict, not a build. Add "oracle this" for second opinions from other models.
You need to understand code before touching it
ce-explain
Evidence-backed how and why, with file:line pointers.
You want it shipped without you in the loop
lfg
After a brainstorm. Plans, works, reviews, compounds, opens a PR, watches CI.
lfg: the whole loop to an open PR
One skill chains the rest. Use it when the task is bounded and you are fine not inspecting each stage. Trevin reports multi-hour runs on full features, one over six hours, with no human past the plan handoff.
What it does
- Routes the request: a plan goes to ce-work, a bug goes to ce-debug, an unsettled product shape goes to ce-brainstorm first if you are present.
- Implements, simplifies, runs code review and applies the eligible fixes itself.
- Runs ce-compound in non-interactive mode so a qualifying lesson ships inside the PR.
- Runs browser tests, commits, pushes, opens the PR, then watches CI with up to three repair rounds.
- Leaves anything it would not apply as an "Unapplied review findings" checklist in the PR body.
What it will not do
- Merge. CI decided is where it stops. Merging stays yours.
- Pause for approval of the plan or the diff. If you want to approve stages, run the skills one at a time.
- Execute a plan file it found on disk. The plan has to be one the session named.
- Ship without verification evidence. Missing evidence is retried once, then it stops.
After it prints DONE, read the PR. /ce-babysit-pr watches it through review toward merge. On Codex the plan is also /goal-ready: ce-plan offers to hand the file to a goal so you can walk away or start a second agent on something else.
Brain on at the ends, off in the middle
Plan and review are 80 percent of your time. Execution is cheap. That is why the loop front-loads questions and back-loads review.
Before
Answer the brainstorm honestly. Read the plan like a diff. Reading a plan and agreeing with it is a decision. Silence is not approval.
During
Step away. If you trust the plan, you do not need to watch every line. Start the next brainstorm in another worktree.
After
Review for intent, not syntax. Does this match what we agreed to build? The review agents already did security, performance and style. You own the PR regardless of who typed it.
Three questions before you approve anything
- What was the hardest decision you made here?
- What alternatives did you reject, and why?
- What are you least confident about?
The step everyone skips, and why it is the whole thing
Plan, work, review produce a feature. Compound produces a system that builds features better each time. Skip it and you have done ordinary engineering with AI help, and every session starts from zero.
What qualifies
All three, or it writes nothing: non-obvious (the final code does not explain it), durable (an invariant, a root cause, a rejected approach, not a diff narration), material (forgetting it would cause a repeat or a long rediscovery).
The test it applies: if this doc disappeared, would a future engineer reading the final code repeat the mistake? If not, do not compound.
Where a lesson belongs
- Machine-enforceable behaviorA test, a type, or an assertion
- Local non-obvious rationaleA code comment
- Change-specific historyThe commit or PR description
- Shared domain languageCONCEPTS.md
- Durable reasoning that crosses boundariesdocs/solutions/ via ce-compound
What the doc looks like
Bug track: symptoms, what did not work, solution, why it works, prevention. Knowledge track: context, guidance, why it matters, when to apply. YAML frontmatter on top so ce-plan and ce-ideate can find it. If an older doc already covers the problem, it updates that one instead of making a twin.
Maintenance is its own skill: ce-compound-refresh audits docs/solutions/ against current code and keeps, updates, consolidates or deletes. Run it quarterly, or when a lesson contradicts the code.
Compound Packs, for rules that cross repos
A learning says what a past problem taught. A pack says what work in a domain must honor (“Rails owns routes and props, pages do not get a parallel JSON API”). Declare packs in config.yaml as a local folder or a pinned git repo. Planning grounds in them and review enforces them, each use cited back to the rule file. /ce-setup pack:house-rules scaffolds one. Experimental.
Make capture automatic · paste into AGENTS.md (offer-first, verbatim from the docs)
After a solved, verified problem, offer once to invoke the `ce-compound` skill at the completion checkpoint only when the work produced durable project reasoning that is not readily recoverable from the final code, tests, types, comments, or existing documentation, and losing it would plausibly cause recurrence, material risk, or substantial rediscovery. Apply this counterfactual: if the learning document disappeared, would a future engineer reading the final implementation still be likely to repeat the mistake or redo substantial investigation? If not, do not offer. Completion, effort, and diff size alone are not enough. Offer at the checkpoint so a qualifying learning can ship in the PR that produced it, and only where the repository treats captured learnings as tracked, committed knowledge.
Make planning automatic · paste into AGENTS.md (verbatim from the docs)
Before implementing work that spans several files or carries a design decision, invoke the `ce-plan` skill. Skip it for a change already specified down to the files it touches that touches no risk surface (authentication, payments, migrations, external contracts); do that directly or with the `ce-work` skill.
Two phrases carry the weight. “Invoke the skill”, because the slash form is not agent-callable on every host. And the skip clause, because a rule that fires on every typo still pays the skill load. /ce-setup offers to insert either line for you.
Four to let go, four to adopt
The Every guide lists eight of each. These are the ones that change what you do on Monday. The rest are in the guide.
Let go
Every line must be manually reviewed
If you do not trust the output, fix the system that produces it. Add a review agent. Do not compensate by reading everything.
First attempts should be good
Kieran's numbers: first attempts are 95% garbage, second attempts 50%. Iterate fast enough that attempt three lands sooner than attempt one used to.
Code is the primary artifact
A system that produces good code is worth more than any one piece of code.
More typing equals more learning
The developer who reviews ten agent implementations sees more patterns than the one who hand-typed two.
Adopt
Extract your taste into the system
Naming, error handling, test style. Write it into AGENTS.md, review personas and CODING_STANDARDS.md so it stops living in one senior head.
The 50 / 50 rule
Half your time on features, half on the system that builds them. An hour on a review rule saves ten hours of review this year.
Make the environment agent-native
If you can run tests, see logs, take screenshots and open PRs, the agent should be able to too. Anything it cannot do, you do by hand.
Plans are the new code
Fixing an idea on paper is cheaper than fixing code later. Review the plan like you used to review the diff.
Find your rung before you install anything
Skipping rungs does not work. You end up distrusting the tools. The stage is per job, not per person. Kieran runs at different rungs on the same day.
- 0
Manual
No AI. Docs and print statements.
- 1
Chat
Snippets from a chat window. You paste. You review every line.
- 2
Agentic, line by line
Claude Code or Cursor edits files. You approve each action. Most people plateau here.
- 3
Plan first, PR-only review
You and the agent write a plan. It implements alone. You read the PR. Compound engineering starts here.
- 4
Idea to PR
You describe an outcome. The agent plans, builds, reviews itself, opens the PR. That is lfg.
- 5
Parallel, in the cloud
Three features, three agents, review PRs as they land. Agents start proposing fixes unasked.
The 2 to 3 move is the one that matters: invest in the plan, let it run, review at PR level. The compounding move at each rung is the same shape. Keep prompts that worked. Add a note to CLAUDE.md when it gets something wrong. After each implementation, write down what the plan missed.
From the people who built it
Pulled from Kieran and Trevin on X, the skill docs, and Kieran's walkthrough with Peter Yang.
Brainstorm before lfg, every time
lfg on a one-liner plans against weak product context. A brainstorm gives it a Product Contract. The brainstorm wrap-up offers "ship it autonomously" when the plan is ready.
Describe the bug, not the fix
ce-debug validates the causal chain before it changes code. Telling it your suspected fix skips that.
Pick a model for the thinking step
"use fable" on brainstorm or plan sends only approach generation or plan authoring to that model. Set plan_model in config to make it the default.
Add output:html when a human will read it
Markdown is the default because the file is usually going to an agent. HTML adds diagrams and is easier for you to read. Ideation is HTML by default.
Three questions before you approve anything
What was the hardest decision? What alternatives did you reject and why? What are you least confident about?
Keep rules personal
Ten specific patterns you actually follow beat a hundred generic ones. Delete the generic rules.
One lesson per compound run
Grounding and overlap checks assume a single solved problem. Several lessons means several runs.
Reinstall after a marketplace update
Running /plugin update alone can leave you on the old version. Refresh the marketplace first, or remove and reinstall.
Overnight dogfood
Kieran's favourite new habit: set a goal to dogfood a feature overnight. ce-dogfood loads your personas and STRATEGY.md and kicks the tires from every angle.
Watch for the factory trap
The 50/50 rule drifts. If you are building machinery and not shipping product, swing back. The test: did the last feature need fewer review rounds than the one before?
Every skill
36 skills. One line each. IDs are what you type, with a slash in front.
The loop
Every iteration, in this order.
ce-brainstorm
You have an idea or problem and need requirements before any plan.
One question at a time until a requirements-only plan exists.
ce-plan
Requirements are set. You need an implementation-ready plan.
Turns requirements into WHAT to build: guardrails, tests, confidence check.
ce-work
The plan is ready. Time to write the code.
Executes the plan, verifies, commits, and ships through quality gates.
ce-simplify-code
The code just landed. Review it before anyone else does.
Refines the fresh change for clarity and reuse. Behavior stays the same.
ce-code-review
You are about to merge. Check the diff against the plan.
Report-only multi-agent review. Applying fixes is a separate step.
ce-compound
The work is done. Write down what the next run should already know.
Stores the lesson in docs/solutions/ so the next brainstorm and plan read it.
Around the loop
Anchors and feeds that keep the loop grounded.
ce-strategy
The project needs a written north star.
Creates or updates STRATEGY.md that ideate, brainstorm, and plan read first.
ce-product-pulse
You want a time-windowed read on how the product is doing.
Reports usage, performance, errors, and follow-ups into docs/pulse-reports/.
ce-sweep
Inbox noise (Slack, GitHub) should become a rolling plan.
Ingests feedback, acknowledges at source, keeps an /lfg-ready plan.
ce-compound-refresh
docs/solutions/ is getting stale or duplicated.
Keeps, updates, consolidates, replaces, or deletes old learnings.
On demand
Reach for one when a specific need shows up. Not every run.
ce-ideate
You do not know what is worth building yet.
Finds grounded directions before brainstorm. Optional first step.
ce-bakeoff
A costly technical choice is still open.
Develops competing approaches so brainstorm or plan can pick one.
ce-pov
You need a judgment, not a build.
Project-grounded recommendation, with an optional oracle panel.
ce-explain
You need to understand existing behavior before changing it.
Evidence-backed how-and-why of the relevant code.
ce-debug
Something is broken. Start here instead of brainstorm.
Finds the causal chain, then an optional fix and PR handoff.
ce-doc-review
The requirements or plan itself needs review.
Structured findings on a document. Not a ship/no-ship verdict.
ce-optimize
You have a measurable target and need confirmed gains.
Keeps only improvements that move the score or cost.
ce-prototype
Someone needs to feel the product before you plan it.
Throwaway prototype, then writes decisions into a plan.
ce-retune
A skill corpus is tuned for last year’s model.
Baselines, then measured cut passes for a new model.
ce-riffrec-feedback-analysis
You have a Riffrec recording of a session.
Turns the recording into structured feedback or a brainstorm handoff.
Git workflow
Commit, ship, and shepherd PRs.
ce-commit
You only need a local commit.
Convention-aware commit. Named-file staging. No push.
ce-commit-push-pr
Working changes should become an open PR.
Full ship, rewrite a description, or description-only from a URL.
ce-babysit-pr
An open PR needs watching, not merging.
Watches review and CI. Calls resolve-pr-feedback and debug as needed.
ce-resolve-pr-feedback
Review comments are in. One pass to handle them.
Evaluates, fixes, and replies, including nitpicks.
ce-worktree
This change should stay isolated from the current tree.
Puts the work in a git worktree, preferring the host’s native tool.
Autonomous
Hands-off after you set the destination.
lfg
You have a brainstorm (or a bug) and want the whole pipeline run.
Plans if needed, works, simplifies, reviews, compounds, ships, watches CI.
Testing and design
Verify and polish what you built.
ce-test-browser
The current diff needs an end-to-end browser pass.
Runs browser tests on the current diff. Does not check out a PR.
ce-test-xcode
An iOS change needs a simulator check.
Builds and tests on the simulator. Not XCUITest.
ce-polish
The feature works. The UX does not feel finished.
Conversational polish in a live browser. Manual invoke only.
ce-dogfood
You want hands-off browser QA of the branch.
Maps flows, fixes small breakages, writes a report. Manual invoke only.
Collaboration
Share work. Do not post it for you.
ce-proof
Markdown needs to go through Proof.
Publish, view, comment, or pull via Proof. Not a review skill.
ce-handoff
The next person (or session) needs the context.
Writes a session handoff, or orients from a selected source.
ce-promote
A shipped feature needs announcement copy.
Drafts X, changelog, LinkedIn, email, blog, or demo text. Never posts.
Utilities
Setup, writing, and maintenance.
ce-setup
A repo is new to Compound Engineering.
Checks optional tools, writes config.yaml, scaffolds a Compound Pack.
ce-noslop
Prose should read like a person wrote it.
Rewrites or drafts with no AI tells. Every fact stays.
wtf
The last message, a file, or a passage is opaque.
Explains it in plain language. Adds no claims. Manual invoke only.
Who this is for
Install it if
You already let an agent edit files and you keep re-explaining the same things. You have one repo you work in every week. You are willing to read a plan before code exists. That is rung 2 trying to reach rung 3, which is exactly where this plugin earns its keep.
Hold off if
You are still copy-pasting from a chat window. The vocabulary (Product Contract, U-IDs, work source) is a lot on day one. Start with the one-line version of compound: when the agent gets something wrong, add a note to CLAUDE.md. That habit is the plugin in miniature.
The one thing to not skip: run /ce-compound after the first real bug you fix with it, then watch the next /ce-plan cite that doc without being told. That moment is when the name makes sense.
Attribution
- EveryInc/compound-engineering-plugin by Every, maintained by Kieran Klaassen and Trevin Chow. MIT. The skill list, install blocks, version, star count and the feature walkthrough (the docs' own running example) are from the repo, its README and the skill docs, summarized. The two standing instructions for AGENTS.md are quoted verbatim from the ce-compound and ce-plan guides.
- The Every guide (Feb 2026): the beliefs, the 80/20 and 50/50 rules and the adoption ladder, summarized. It uses the older v2 command names; the rename table on this page maps them to v3.
- Kieran's story behind compounding engineering, the source of the origin story and the quoted line about bug fixes.
- Trevin's v3 update on X, posts by Kieran on X and Kieran's walkthrough with Peter Yang: the v3 changes, multi-hour runs and the field notes, summarized.
- The plugin is Every's own product and the guide is published by Every. Claims about what the plugin does are its makers' own.
- The five-box summary, the glossary, the order of the page and the take are FakeNerd's.