flywheel.md

# FLYWHEEL.md

> Your project's loop for shipping and improving software, with humans in the loop where it matters.

FLYWHEEL.md is a single Markdown file you drop in your repo root, next to AGENTS.md. It defines the loop your AI coding agents follow to ship a change, prove it works in production, learn from it, and improve. It is a companion to AGENTS.md: AGENTS.md says what to do, SOUL.md (if you use one) says who to be, FLYWHEEL.md says how a change travels from idea to shipped to improved, turn after turn.

## What a flywheel is

A flywheel is a loop a change travels again and again. Each turn it moves through your stages, pauses where a human needs to weigh in, ships, and feeds what it learned into the next turn. The point is momentum that compounds: every turn makes the next one faster and safer.

This file is where you define that loop, so an agent follows your process, not just your goal. It is not a "definition of done" checklist. It is the shape of how you build, release, and evolve.

Why now: when agents write the code, coding stops being the bottleneck. Verification, review, and ownership become it, and the processes built to protect scarce engineering time quietly stop working. This file is where you rewrite them.

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.

## The stages

A change flows through four stages, the same four the wheel turns. The set below is the default. Split a stage (Ship is really plan, build, and review), add, remove, or reorder to match how your project actually ships and evolves. For each stage, write two things:

- Done when: the exit criteria, so the agent knows when to move on.
- Gate: does the agent proceed on its own, or stop and wait for a human?

1. Ship. Plan the approach and name the blast radius, build in small reversible steps, review your own diff, tests, and data flow, then merge, release, and deploy. Land the whole chain, not just the merge.
   - Done when: the change is live where users are.
   - Gate (human): sign off before anything risky or irreversible, and optionally review before merge.
2. Verify. Prove it works in production, by you, with evidence: a real request, a screenshot, real output. Your evidence is your eval, the one you trust for your product, not a generic leaderboard.
   - Done when: you have seen it work for real. A passing test is not proof.
3. Learn. Capture what actually happened: cost, regressions, the surprise, user feedback.
   - Gate (often): wait for real-world signal before starting the next turn.
4. Improve. Feed it back: fix the cause, raise the bar, delete the toil.
   - Done when: the next turn starts smarter than this one did.

## Humans stay in the loop

A flywheel is not "let the agent run unattended forever." It makes explicit where a human stays in the loop: which stages need a sign-off, and where the agent pauses for feedback and resumes when you reply. Mark those gates. Put them where human judgment still wins: risk and trust boundaries, irreversible changes, legal, and product taste. 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. Everything between them, the agent turns on its own. Loosen the gates as trust grows; tighten them for risky surfaces.

## What makes it compound

The difference between a flywheel and a checklist: Learn feeds the next turn. Cost data, regressions, and feedback become the context that makes the next change faster and safer. Leave a trail so the wheel comes around heavier each turn.

## The bar (holds at every stage)

A few rules that do not change between stages, whatever stages you choose:

- Done means deployed and verified, with evidence.
- Every iteration costs money.
- Know your data flow.
- Fix the cause, never the symptom.
- Leave a trail, in the codebase, where it stays in the loop. A doc outside the loop rots.
- Audit the loop itself. Processes pile up and nobody deletes them; every few turns, ask of each stage and gate whether it still earns its place, and cut what does not.

## The agent-file canon

- AGENTS.md: what to do (the project's instructions). See https://agents.md
- SOUL.md: who to be (the agent's identity).
- FLYWHEEL.md: how to ship, and how to know you did.

## Make it yours

Copy FLYWHEEL.md into your repo root, next to AGENTS.md and SOUL.md, then rewrite the stages and gates for your project. A CLI, a model, and a web service have different loops and different human gates. The point is a shared, explicit process your agents and your team can both follow, not these exact words.

Per-stack starting points:

- CLI tool: https://flywheel.md/examples/cli-tool.md
- Library: https://flywheel.md/examples/library.md
- Web service: https://flywheel.md/examples/web-service.md
- Frontend app: https://flywheel.md/examples/frontend-app.md
- ML project: https://flywheel.md/examples/ml-project.md

## How agents load it

No coding tool reads a file named FLYWHEEL.md on its own. Tools load AGENTS.md (or their own CLAUDE.md, .cursor/rules, GEMINI.md). So you do not wire up a new file per tool. You point the file they already read at this one, with a single line:

## 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 loads. 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. This is one mechanism, not a per-tool config matrix that rots as tool formats change. Claude Code can also import the whole file by writing @FLYWHEEL.md in CLAUDE.md. To make a gate actually block, wire the same rule into CI: the file states the intent, the pipeline makes it binding.

## License

MIT. The text is free to copy and adapt. No attribution needed.

A loop you cannot see is a liability. FLYWHEEL.md grew out of running real agents in production; pair it with observability that shows every turn.

Source and home page: https://flywheel.md and https://github.com/vivekchand/flywheel.md