hoangsonww /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)
- Global reasoning in plan space — the plan must fit in context.
- Plan must be comprehensive before any code.
- Plan-to-beads is a distinct translation problem.
- Beads carry enough context that agents don't need the plan anymore.
- Convergence matters more than first drafts.
- Swarm agents are fungible — coordination lives in artifacts.
- Coordination survives compaction (
AGENTS.mdre-reads, beads). - Session history is part of the system (feed lessons back).
- Implementation is not the finish line — review/test/harden.
See FLYWHEEL.md at the repo root for the full methodology.