agent-flywheel

░▒▓ CLAUDE // AGENT-FLYWHEEL v3.18.0 ▓▒░

/plugin marketplace add burningportra/agent-flywheel-plugin
/plugin install agent-flywheel@agent-flywheel
/reload-plugins
/agent-flywheel:flywheel-setup

Then /agent-flywheel:start and you're off.

TL;DR

The problem

Coding agents stall halfway. They pick up a task, lose context, hit a rate limit, leave half-finished work, skip the review pass that would catch their own bugs, and cannot resume cleanly across sessions. Multi-agent fan-out is worse — agents trample each other's files, lose track of which work is in flight, and there's no audit trail when something goes wrong.

The solution

A six-phase loop with state on disk, gates between every step, and adversarial review at the risky seams. Every user decision flows through AskUserQuestion (no implicit choices). Every multi-agent fan-out goes through NTM + Agent Mail (no raw tmux, no & background shells). Every closed bead carries a versioned Completion Evidence attestation in .pi-flywheel/completion/<beadId>.json that the coordinator validates before advancing the wave.

scan ──> discover ──> plan ──> implement ──> review ──> wrap-up
  │         │           │          │            │           │
  └─────────┴───── checkpoint after every step ─┴───────────┘
            (drift check on resume; structured-error routing)

Why use it?

Quick example

# In a Claude Code session, in any git repo:
/agent-flywheel:start

# Banner + state detection. If beads are open, you get the resume menu.
# Otherwise you see a fresh-start menu:
#
#   1. Scan & discover  ← profile + ranked ideas
#   2. Set a goal       ← brainstorm + plan + implement
#   3. Deslop pass      ← isomorphism-preserving refactor
#   4. Duel             ← adversarial 2-agent ideation

# Pick "Set a goal". Type the goal. Pick "Full flywheel".
# The flywheel runs /brainstorming, generates a plan via 3 parallel
# models (claude-opus, claude-sonnet, codex), splits it into beads,
# and asks you to approve.

# After approval, the swarm spawns:
ntm spawn agent-flywheel --label impl --pi=4 --cc=2 --stagger-mode=smart

# Each pane gets a marching-orders message via Agent Mail. The
# tender daemon nudges stalled panes. When all beads close,
# `flywheel_review` spawns 5 fresh-eyes reviewers per risky bead
# (or 2-agent adversarial duel for p0 / security-path beads).

# Wrap-up commits CHANGELOG entries, bumps the version, rebuilds
# dist/, and writes a postmortem entry to docs/solutions/.

Design philosophy

1. State lives on disk; the server is stateless. Every phase boundary writes .pi-flywheel/checkpoint.json atomically. The MCP server reads it and writes it; nothing else holds session state. Resume across machines, across /clear, across crashes.

2. One lever per commit. Refactors land as isomorphism-preserving Edits (the simplify-and-refactor-code-isomorphically skill enforces this). Reviewers can bisect.

3. Every decision is a labeled question. AskUserQuestion is the only sanctioned way to ask the user anything. No implicit "shall I proceed?" prose. No silent choices.

4. Multi-agent fan-out is mandatory through NTM. Raw Task/Agent calls for fan-out, backgrounded shells, and tmux split-window are review-bounce conditions. NTM provides the canonical pane registry, Agent Mail integration, stuck-pane detection, and stagger.