flywheel

Flywheel

Zero-cost session handoffs for long-running AI coding agents.

Flywheel is a Claude Code plugin that breaks large projects into one-feature-per-session cycles. Each session picks up where the last left off, implements one feature, reviews it through a 4-layer pipeline, verifies it on target platforms, and commits merge-ready code with a machine-readable handoff for the next session.

Session 1                    Session 2                    Session 3
┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
│ Read handoff     │───────▶│ Read handoff     │───────▶│ Read handoff     │
│ Pick feat-001    │        │ Pick feat-002    │        │ Pick feat-003    │
│ Implement        │        │ Implement        │        │ Implement        │
│ Review (4-layer) │        │ Review (4-layer) │        │ Review (4-layer) │
│ Verify (platform)│        │ Verify (platform)│        │ Verify (platform)│
│ Commit + handoff │───────▶│ Commit + handoff │───────▶│ Commit + handoff │
└──────────────────┘        └──────────────────┘        └──────────────────┘
     feat-001 ✅                 feat-002 ✅                 feat-003 ✅

Why

AI coding agents burn through their context window on large projects. The usual result: half-finished features, skipped tests, lost context between sessions. Flywheel fixes this with three rules:

1. One feature per session. No scope creep. Context stays focused.
2. Merge-ready or revert. No WIP commits. Every session leaves the codebase clean.
3. Machine-readable handoff. The next session knows exactly what happened and what's next.

Benefits

• Zero-context-loss handoffs. Session dies mid-project? No problem. The machine-readable handoff log tells the next session exactly what was done, what failed, and what's next. No manual briefing needed.
• Stateless sessions, persistent progress. Once the feature checklist exists, every session is disposable. Open, close, crash — it doesn't matter. The next session reads the checklist, picks up the next pending feature, and keeps going.
• Scope discipline prevents context blowout. One feature per session. AI agents love to scope-creep until they burn through the context window and produce half-finished work. Flywheel enforces focus: implement one thing, review it, commit merge-ready code, move on.
• 4-layer review catches what single-model can't. Cleanup (author proofreads) → Peer review (fresh agent) → Cross-model (different AI catches blind spots) → E2E (real verification). Each layer catches what the previous one misses.
• Platform verification before handoff. Step 9 verifies the feature works on target platforms (web, iOS, Android, Electron, etc.) using real tools — not just test suites.
• User verification checkpoint. After commit, the flow summary shows the feature title, description, and acceptance criteria so you can verify before marking it done.
• Dynamic feature management between sessions. Add, revise, reprioritize, split, or remove features at any time with /flywheel:features. The project plan evolves with you — no need to re-initialize or restart.
• Pluggable, not locked-in. Every spoke (planning, multi-agent, review) has a zero-dependency built-in default. Install superpowers, codex, playwright as you need them. Works with one tool or all four.
• Auditable by design. Every session ends with a compliance table showing exactly what ran, what was skipped, and why. The handoff log is a complete audit trail of every feature implemented across the project.

Quick start

Install

Add the marketplace and install the plugin:

/plugin marketplace add romanticamaj/flywheel
/plugin install flywheel@flywheel-marketplace

For development / testing (temporary, current session only):

git clone https://github.com/romanticamaj/flywheel.git ~/.claude/plugins/flywheel
claude --plugin-dir ~/.claude/plugins/flywheel

Initialize (once per project)

/flywheel:init

Flywheel detects your installed tools and project platforms, lets you choose per spoke, and creates .flywheel/ with:

.flywheel/
├── flywheel-config.json      # Tool choices + verification platforms + rules
├── feature-checklist.json    # Prioritized features with acceptance criteria
├── init.sh / init.ps1        # Auto-detected bootstrap scripts
└── claude-progress.jsonl     # Handoff log (grows each session)

Run (each session)

/flywheel:relay

The agent follows a 10-step loop: