The Core
Flywheel

This document is for a relatively smart software developer who is new to agentic coding and does not want to absorb the entire larger Flywheel guide up front. The goal is narrower: get you to the point where you can coordinate multiple agents without chaos, keep work organized as explicit tasks with dependencies, and keep agents working on the best next unblocked task instead of choosing randomly.

If that works well for you, the larger Flywheel stack becomes much easier to appreciate later.

You do not need to manually manage the coordination between these tools. When your AGENTS.md file is set up correctly, the agents handle the integration automatically: they use bead IDs as thread identifiers in Agent Mail, they announce claims and reserve files before editing, and they update bead status as they work. You configure this once in AGENTS.md and then the agents just do it.

Without Agent Mail, multiple agents constantly collide: two agents edit the same files, nobody knows who is doing what, messages disappear into chat history, and work gets stranded when an agent crashes.

Agent Mail gives agents a shared coordination layer with identities, threads, inboxes, and file reservations. Agents announce what they are doing, reserve edit surfaces, and recover when another agent disappears. All of this happens automatically once your AGENTS.md tells agents to use Agent Mail.

Without br, work collapses into vague conversational intentions: "fix the auth stuff," "clean up the admin area," "someone should improve tests." That kind of tasking is too fuzzy for a swarm.

br turns work into explicit beads with status, priority, and dependencies. Once work is represented that way, multiple agents can make progress without constant human steering.

Even with good beads, agents still need to know what to do next. Without bv, they choose work based on local convenience or whatever they most recently saw in context.

bv reads the bead graph and computes what is most worth doing next. That turns the swarm from "many agents doing work" into "many agents pushing the project forward efficiently."

Plan space is where you decide the workflows, constraints, architecture, and testing expectations. Bead space is where you transform that thinking into executable memory for agents. Code space is where agents implement the local task that a bead defines.

The general rule is simple. Debates belong in plan space. Translation and dependency shaping belong in bead space. Implementation belongs in code space.

A strong plan lets a fresh reader answer five questions without guessing: what are the main workflows? What constraints matter? What architecture are we choosing? How will we know it works? What failure cases must not disappear into hand-waving?

## Upload workflow
- Users drag Markdown files into the upload surface.
- The system parses frontmatter plus body text and stores a normalized note record.
## Constraints
- Unauthorized users must never see note content or note metadata.
- Failed ingestions must be preserved for operator review instead of discarded.
## Architecture choice
- Use a dedicated ingestion pipeline so parse failures can be persisted and retried.
- Keep search indexing separate from upload handling so indexing can be retried independently.
## Tests and failure handling
- Unit coverage for parsing and index mapping.
- E2E coverage for upload, failed-ingestion review, retry, search, and filtering.

It gives a fresh agent workflows, constraints, architecture, testing, and failure handling in one place. Before you turn the plan into beads, check that these five questions are answerable from the plan alone.

When something feels wrong, use the smallest escalation that actually fits the problem:

• Local code confusion — stay in code space and resolve it there
• Weak or underspecified bead — step back into bead space and rewrite the bead
• Wrong graph — fix the dependencies or add the missing bead
• Missing plan work — step back into plan space and revise the markdown plan
• Degraded agent — restart it with a fresh session

The bead is the unit of work agents actually execute. Weak beads force improvisation. Rich beads make execution mechanical. Here is a real bead from the ACFS project:

bd-01s: Add --deep flag to acfs doctor
Context:
Part of EPIC: Enhanced Doctor with Functional Tests.
What to Do:
Add --deep flag to doctor.sh that enables functional tests beyond
binary existence checks:
- Add DEEP_MODE=false global
- Parse --deep flag alongside existing --json
- --deep and --json can be combined
Acceptance Criteria:
- --deep flag parsed correctly
- Default doctor unchanged (fast, existence checks only)
- --deep runs additional functional tests
- Works with --json for structured output
Files to Modify:
- scripts/lib/doctor.sh: Argument parsing

The prose does not need polish. A fresh agent should be able to understand the task, the reason for it, and the acceptance criteria without reopening the whole markdown plan. You can browse real beads from actual Flywheel projects at FrankenEngine, FrankenTUI, and Asupersync.

Quality thresholds get easier to feel when you compare weak and strong versions directly. The weak version names a topic. The strong version scopes the actual requirement, constraint, and testing obligation.

Once you launch agents with good marching orders, they automatically handle the coordination mechanics. A typical bead thread in Agent Mail looks like this — created entirely by agents, not by you:

[br-103] Start: Failed-ingestion admin screen
Claiming br-103. Reserving admin UI files plus retry handler path.
Will send update once list view is working and retry path is wired.
[br-103] Progress: Main path wired
List view and detail view working. Now handling edge cases and tests.
[br-103] Completed
Admin screen done. List view, detail view, and retry action wired.
Auth checks in place. E2E coverage for malformed upload → admin review → retry.

You do not write these messages. The agents create them because your AGENTS.md tells them to coordinate through Agent Mail and use bead IDs as thread anchors. Your job is to monitor these threads to see if work is flowing or stuck.

Before beads or swarms or file reservations, create a serious markdown plan. Do not settle for one quick draft from one model.

At minimum, you want: the user-facing workflows, the important constraints, the major architectural decisions, and the testing expectations.

You do not need to manually create every bead yourself. Tell a coding agent to do the conversion:

Then polish the beads 4-6 times with fresh review passes. Each round catches things the previous round missed. This is the "measure twice, cut once" of the methodology.

Once beads are polished and your AGENTS.md is solid, start up a swarm of agents. Give each one these marching orders:

Stagger agent starts by at least 30 seconds to avoid the "thundering herd" problem where all agents grab the same bead. Start smaller than your ego wants to: 1 agent to learn, 2 to feel coordination, 4 for real swarm behavior.

Now you are the operator. On roughly a 10-15 minute cadence, check on the swarm:

1. 1Run bv --robot-triage and check whether the top recommendation still makes sense.
2. 2Glance through Agent Mail threads — are agents making progress or stuck?
3. 3Look for beads stuck in in_progress without movement.
4. 4If an agent seems confused after compaction, send: "Reread AGENTS.md so it's still fresh in your mind."
5. 5If an agent is truly degraded, kill it and start a fresh one.

That is usually enough to keep the loop healthy without turning the human into a full-time traffic cop.

After agents finish each bead, have them review their own work:

Then they move to the next bead using bv to find the most impactful one. The cycle repeats until the graph is done.

• Create the plan and beads — this is where most of your time and thinking goes
• Write a good AGENTS.md — this is the operating manual that makes everything else work
• Launch agents with marching orders — the same generic prompt every time
• Keep the bead graph honest — notice when a missing task or dependency must be added
• Restart or redirect agents when they drift, get loopy, or lose context
• Ask the hard question periodically (see below)

• Register with Agent Mail and discover other active agents
• Claim beads and announce what they are working on
• Reserve files before editing to prevent conflicts
• Update bead status (in_progress, closed) as they work
• Use bv to find the next best bead when they finish one
• Send progress updates and completion messages in Agent Mail threads

All of this is configured once in your AGENTS.md. You do not need to manually invoke Agent Mail calls, update bead statuses, or thread bead IDs into messages. The agents do it because the operating manual tells them to.

When the swarm looks active but you suspect it is not actually closing the real gap, stop and ask:

If the answer is "no," the fix is usually not more implementation effort. Revise the bead graph, add missing work, or step back into planning.

Even in the smaller core-loop version, you still need a minimal AGENTS.md. It does not have to be a giant doctrine document, but it should say:

• What the repo is for
• What the stack is
• Any non-negotiable safety or style rules
• How to use Agent Mail, br, and bv (include the prepared blurbs from each tool's docs)

When an agent vanishes mid-bead, the recovery path should be boring:

1. 1Check the Agent Mail thread for the last meaningful progress update.
2. 2Launch a fresh agent with the standard marching orders.
3. 3The new agent will read AGENTS.md, discover the abandoned bead via bv, and pick it up.
4. 4If the bead was partially completed, the new agent can continue from the code state plus the thread history.

People often assume the magic of the Flywheel comes from the total number of tools. It does not. Most of the value comes from three things:

1. 1Work is explicit instead of implicit
2. 2Coordination is externalized instead of living in human memory
3. 3Task choice is graph-aware instead of random

Those three properties are already present in the core loop. That is why the smaller system gets you surprisingly far.

You probably do not need it for a tiny one-file change with no real dependency structure, a purely local experiment, or a quick one-agent cleanup that does not need externalized coordination.

The loop earns its keep when work has enough structure, enough ambiguity, or enough parallelism that explicit planning, explicit tasks, and explicit coordination start paying for themselves.

If you are just getting started, you do not need to master all of this immediately:

• Large-scale session memory systems like CASS and CM
• Big prompt libraries
• Advanced launch tooling like ntm
• The full exhaustive planning doctrine
• Every supporting tool in ACFS

Those things help. Some help a lot. But they are multipliers on top of the core loop, not prerequisites. You can run the core loop with separate terminal tabs and no special session manager.

Even in the smaller version, a few principles still matter a lot:

• Do not start a swarm with only vague goals — make a real plan first
• Do not treat beads as tiny throwaway todo lines — they need rich context
• Do not skip the bead polishing rounds — single-pass beads are never optimal
• Do not rely on chat scrollback as your coordination system — that is what Agent Mail is for

If you violate those, the workflow quickly degrades back into ordinary multi-agent chaos.

1. 1Pick one real project, not a toy.
2. 2Ask multiple frontier models for competing markdown plans.
3. 3Synthesize them into one strong plan.
4. 4Tell an agent to create beads from the plan with dependencies.
5. 5Polish the beads 4-6 times with fresh review passes.
6. 6Run bv --robot-triage to verify the graph makes sense.
7. 7Launch 2-4 agents with the standard marching orders.
8. 8Tend the swarm. Check every 10-15 minutes.

Start smaller than your ego wants to:

If you want to feel the method instead of only reading about it:

1. 1Pick one real repo
2. 2Write one serious markdown plan
3. 3Tell an agent to create two real beads with one dependency
4. 4Run bv --robot-next and check that the recommendation makes sense
5. 5Launch a second agent with the marching orders and watch them coordinate

Those five steps are enough to make the core loop stop feeling theoretical.

If you want the loop on one screen, keep this:

1. 1Plan with multiple models
2. 2Synthesize into one markdown plan
3. 3Tell an agent to create beads
4. 4Polish beads 4-6 times
5. 5Write a good AGENTS.md
6. 6Launch agents with marching orders
7. 7Tend the swarm every 10-15 minutes
8. 8Have agents do fresh-eyes review after each bead
9. 9Repeat until the graph is done

Move up to the full guide when one or more of these becomes true:

• Your projects are large enough that you want much richer planning workflows
• You want stronger AGENTS.md operating manuals with comprehensive tool documentation
• You want repeatable prompt libraries and skills
• You want better recovery from compaction and session loss
• You want memory systems (CASS, CM) that improve the workflow over time

At that point, the bigger document stops feeling like overhead and starts feeling like leverage.