FLYWHEEL.md

It's just a Markdown file.

Here is the whole thing. Drop it in your repo root, next to your AGENTS.md, and your agents read it before they touch anything. Copy this starter, then make it yours.

# FLYWHEEL.md

How an agent ships and improves this project, turn by turn.
`AGENTS.md` = what to do. `SOUL.md` = who to be. `FLYWHEEL.md` = how to ship.

## The loop
Ship, verify, learn, improve. Each turn compounds.

## The stages (the four the wheel turns, split or rename to fit)
1. Ship. Plan the approach and blast radius, build in small reversible steps, review diff/tests/data flow, then merge, release, deploy. Gate: a human signs off on anything risky or irreversible.
2. Verify. Prove it in production, with evidence. A passing test is not proof.
3. Learn. Cost, regressions, feedback. Gate (often): wait for real-world signal.
4. Improve. Fix the cause, raise the bar, delete the toil.

## The bar (holds every stage)
- Done means deployed and verified, with evidence.
- Every iteration costs money.
- Know your data flow.
- Fix the cause, never the symptom.
- Leave a trail.

New to it? Browse example flywheels for CLIs, libraries, services, frontends, and ML projects. Steal it, fork it, no attribution needed.

Not a poster. Context your agent reads.

FLYWHEEL.md is not a wall poster or a checklist humans nod at. It is context your coding agent loads before it acts, the same way it reads AGENTS.md, and it changes what the agent does at every step.

• Your agent reads it first.

  Drop it in your repo root, then point the file your agent already loads, AGENTS.md or CLAUDE.md, at it with one line (how). Claude Code, Cursor, or Codex then reads the loop as instructions. No runtime, no plugin, no lock-in.

• Gates pause the run for you.

  At each stage you mark with a gate, the agent stops and waits for a human, then resumes when you reply. The human-in-the-loop, written down so the agent honors it.

• "Done" demands evidence, not a claim.

  The agent can't close a stage by asserting success. It has to show proof, and proof is domain-specific: a real request plus an error-rate graph for a service; a screenshot, a Playwright run, or a Lighthouse score for a frontend; an eval on held-out data against the prod baseline for a model. See the per-stack examples.

• It's instructions, not magic.

  An agent follows FLYWHEEL.md like any other guidance. It isn't hard enforcement. Want a gate to actually block? Wire the same rule into CI. The file makes the intent explicit; your pipeline makes it binding.

So why a file at all? You already have these steps. What's new is that an autonomous agent now runs them at machine speed. The gates and the evidence bar are what keep a closed loop from shipping confident, untested change while you sleep.

How agents actually load it.

No tool reads a file named FLYWHEEL.md on its own. But every coding agent already loads AGENTS.md (or its own CLAUDE.md, .cursor/rules, GEMINI.md). So you don't wire up a new file per tool. You point the file they already read at this one. One line, and the loop rides in with it.

## Process
Follow the loop in ./FLYWHEEL.md for every change.
Don't mark a stage done without the evidence it requires.
Stop at any gate marked (human) and wait for a person.

Paste that into the context file your agent already reads. Because that file is auto-loaded, FLYWHEEL.md travels with it, for Claude Code, Cursor, Codex, Gemini CLI, and anything else that honors AGENTS.md. No plugin, no per-tool config to keep current.

• One mechanism, not a matrix.

  Skip the per-tool setup table. The agent loads AGENTS.md or CLAUDE.md by default, and the one line above carries the loop with it. Tool config formats churn; a reference from the file they already read does not.

• Claude Code can pull it in whole.

  In CLAUDE.md, write @FLYWHEEL.md to import the entire file into context, not just a pointer to it.

• Want a gate to actually block? Wire it into CI.

  The reference makes the agent follow the loop. Your pipeline makes a gate binding. The file states the intent, CI enforces it.

Writing code was never the hard part.

Agents can write code all day. The hard part is everything after: does it actually work, in production, for a real person? And can you prove it?

That's the loop: ship → verify → learn → improve. Run it with discipline and software starts improving itself, safely. Run it without and you get confident, untested, unobservable change, at machine speed. The question under every autonomous codebase: what happens when the loop closes without a human in it?

This isn't theoretical. When agentic coding became the default inside Anthropic's own Claude Code org, the bottleneck moved: coding stopped being the slow part, and verification, review, and ownership became it. The old norms quietly stopped working and had to be rewritten to keep shipping (Fiona Fung, Code w/ Claude 2026). FLYWHEEL.md is where you write the new ones down.

Another way to see it: a company without this loop is an open-loop control system. Decisions go out, signal comes back lossy and late, error compounds, the system drifts. With agents in the work, the drift is at machine speed. A flywheel is the closed loop: tight feedback into the next turn, so error stays in check (Diana Hu, YC, Stanford CS 153).

The stages a change travels.

This is what's inside FLYWHEEL.md: the four stages a change moves through, the same four the wheel turns. Each stage has a finish line, and some have a gate, a point where the agent stops and waits for a human before going on. Four is the default. Split Ship into plan, build, and review, or add stages, to match how your team works.

Three things to read here: the stages (the steps a change travels), the gates (where a human stays in control), and the bar (the rules that hold at every stage).

Read the full FLYWHEEL.md on GitHub →

Humans stay in the loop. A flywheel is not "run unattended forever." It says exactly where a human gates a stage and the agent pauses for feedback, then resumes when you reply. Put the gates where human judgment still wins: risk and trust boundaries, irreversible changes, legal, and product taste. And keep the gates themselves deterministic, written as code your CI runs, not as instructions the agent grades itself on. The agent's work between gates is latent; the gates and the evidence are not. A CLI, a model, and a web service each get a different loop and different gates.

A few rules that hold every turn.

The loop is the shape of your process. These don't change between stages, whatever stages you choose.

• Done means deployed and verified, with evidence.

  A diagnosis is not a fix. A merge is not a deploy. A deploy is not a verification. Land the whole chain, then say done.

• Every iteration costs money.

  Each poll, each fetch, each run is spend. Treat request volume like a budget you can blow, because you can.

• Know your data flow.

  "Works on my machine" is the most expensive lie an agent tells. Trace the path from source to screen before you trust it.

• Fix the cause, never the symptom.

  No skipping a check to go green. No bypassing the guard to make the error disappear. Find the root, or you'll meet it again.

• Leave a trail, in the codebase.

  The next turn shouldn't relearn what this one did. Write down the non-obvious: the gotcha, the constraint, the why. Keep it in the repo, next to the code, where it stays in the loop. A doc that lives outside the loop rots.

• Audit the loop. Kill what stopped serving its purpose.

  Processes pile up; nobody deletes them. Every few turns, ask of each stage and gate: is it still earning its place? Building is cheap now, so prune hard. A loop you never trim becomes the bottleneck it was meant to remove.

The questions people actually ask.