/flywheel — methodology overview

Forge follows the Agentic Coding Flywheel methodology: plan obsessively in markdown, translate polished plans into self-contained beads, and only then let a swarm execute.

Where you are now

If you are…	Use
starting a new feature / subsystem	/plan → write the initial plan
you have 2+ competing plans from different models	/plan-synthesize → GPT Pro synthesizes hybrid
refining a plan	.flywheel/prompts/plan-refine.md (fresh chats, 4–5×)
plan feels stable and complete	/plan-to-beads → create .beads/beads.jsonl
beads were just created	/polish-beads (run 4–6×)
polishing has flatlined	/fresh-eyes → new session, reload docs
≥ 20 new beads were just batched in	/dedupe-beads
adding features to existing Forge	/idea-wizard (30 → 5 → 15 funnel)
swarm is running, agents finished a bead	self-review inline, then /deep-review every hour
swarm feels busy but directionally off	/reality-check
end of session	/landing → close beads, commit, push
agent confused after compaction	"Reread AGENTS.md, CLAUDE.md, and FLYWHEEL.md"

Layered artifacts (don't confuse them)

• plan space → .flywheel/plans/*.md (where architecture lives)
• bead space → .beads/beads.jsonl (where execution lives)
• code space → src/ + test/ (where implementation lives)
• rules & skills → .claude/, .codex/, .cursor/, .agents/ (how agents behave)

Once polished beads exist, the beads are the source of truth for execution. You don't keep editing the plan while agents implement.

Core invariants (the Kernel)

1. Global reasoning in plan space — the plan must fit in context.
2. Plan must be comprehensive before any code.
3. Plan-to-beads is a distinct translation problem.
4. Beads carry enough context that agents don't need the plan anymore.
5. Convergence matters more than first drafts.
6. Swarm agents are fungible — coordination lives in artifacts.
7. Coordination survives compaction (AGENTS.md re-reads, beads).
8. Session history is part of the system (feed lessons back).
9. Implementation is not the finish line — review/test/harden.

See FLYWHEEL.md at the repo root for the full methodology.