Skip to content
/
Tier A A11 Governance

AI Flywheel (agent-flywheel-plugin)

ag-coding-flywheel · burningportra/agent-flywheel-plugin · ★ 2 · last commit 2026-05-15

Prevent multi-agent chaos through a structured bead lifecycle with file reservations, typed completion attestations, adversarial duel review, and 36-code structured error contracts.

Best whenA multi-agent system without typed completion attestations and file conflict prevention is not a system — it is a race condition.
Skip ifRaw tmux background shells for multi-agent fan-out, String-parsing error handling
vs seeds
claude-flow(both implement swarm orchestration with file conflict prevention and a completion ledger), but ag-coding-flywheel ships…
Primitive shape 71 total
Commands 24 Skills 40 Subagents 2 Hooks 4 MCP tools 1
00

Summary

AI Flywheel (agent-flywheel-plugin) — Summary

The agent-flywheel-plugin is a multi-agent coding flywheel for Claude Code, at version 3.18.0, shipping as a native Claude Code plugin with 24 commands, 40+ skills, 4 hooks, a bundled MCP server, and the "Bead" state model — tasks represented as atomic units with dependency graphs, reservation tracking, and Zod-validated completion attestations. Its defining features are: (1) adversarial "duel" review — two agents cross-score each other's work; (2) file-reservation conflict prevention via NTM + Agent Mail (no two agents write the same file simultaneously); (3) a 36-code structured error contract (FlywheelErrorCode); and (4) a tender daemon with a 4-minute looper that auto-recovers stalled beads. The six-phase loop is: scan → discover → plan → implement → review → wrap-up, with checkpoints after every step and structured-error routing at every seam.

This framework is best understood as the Claude Code plugin incarnation of Jeffrey Emanuel's "Agentic Coding Flywheel" methodology — the same idea as ACFS (the VPS setup tool also in this batch), but expressed as a prompt/skill/hook plugin rather than an infrastructure bootstrapper.

Compared to seeds, ag-coding-flywheel is most similar to claude-flow (both implement swarm orchestration with file conflict prevention and a completion attestation ledger) but is a Claude Code plugin rather than an npm MCP server, and adds adversarial duel review as a first-class primitive. The multi-model planning (claude-opus + claude-sonnet + codex in parallel) is the most explicit model routing in this batch.

01

Overview

AI Flywheel (agent-flywheel-plugin) — Overview

Origin

Created by burningportra. Version 3.18.0 (highly versioned for a 2-star repo). MIT license. TypeScript + JavaScript. Active: last push May 2026. The plugin is based on and extends Jeffrey Emanuel's (Dicklesworthstone) Agentic Coding Flywheel methodology.

Philosophy

"Multi-agent coding flywheel for Claude Code. Scan → discover → plan → implement → review — with checkpoints, gates, and adversarial review at every seam."

Core problems addressed:

  1. Agents stall halfway → resumable checkpoints with drift-check on resume
  2. Multi-agent agents trample each other's files → file-reservation via NTM + Agent Mail
  3. No audit trail → Completion Evidence attestation (Zod-validated JSON per bead)
  4. No structured errors → 36-code FlywheelErrorCode (vs. string parsing)
  5. No adversarial review → Duel — 2-agent cross-scoring

Key Design Manifesto

From README comparison table:

"Resumable across sessions: ✅ atomic checkpoint (vs. ✗ context-window-bound for raw Claude Code)" "Adversarial review (duels): ✅ 2-agent cross-scoring (vs. ✗ for all alternatives)" "Completion attestation ledger: ✅ Zod-validated JSON (vs. ✗ for all alternatives)" "Structured error contracts: ✅ 36-code FlywheelErrorCode (vs. string parsing)" "Bead-graph dependency view: ✅ bv + Cytoscape viewer"

Bead Model

A "bead" is the atomic unit of work. Beads have:

  • Dependency graph
  • File reservations (prevents concurrent modification)
  • Status lifecycle
  • Completion Evidence (Zod-validated JSON in .pi-flywheel/completion/<beadId>.json)

The bead model is original to this framework — it is not borrowed from any seed.

02

Architecture

AI Flywheel (agent-flywheel-plugin) — Architecture

Distribution

  • Type: Claude Code plugin + MCP server
  • Install: /plugin marketplace add burningportra/agent-flywheel-plugin then /plugin install agent-flywheel@agent-flywheel
  • License: MIT
  • Version: 3.18.0
  • Language: TypeScript (MCP server), JavaScript (hooks), Markdown (commands/skills)

Directory Structure

.claude-plugin/           ← Plugin manifest
commands/                 ← 24 slash commands
  start.md, flywheel-setup.md, flywheel-scan.md, flywheel-swarm.md,
  flywheel-duel.md, flywheel-audit.md, flywheel-doctor.md, flywheel-status.md,
  flywheel-drift-check.md, flywheel-fix.md, flywheel-rollback.md,
  flywheel-healthcheck.md, flywheel-stop.md, flywheel-swarm-stop.md,
  flywheel-swarm-status.md, flywheel-bead-viewer.md, flywheel-cleanup.md,
  flywheel-compound-refresh.md, flywheel-reality-check.md, flywheel-refine-skill.md,
  flywheel-refine-skills.md, flywheel-research.md, flywheel-tool-feedback.md,
  memory.md
skills/                   ← 40+ skill directories
  brainstorming/, caam/, cass-memory/, cass/, flywheel-*/,
  idea-wizard/, multi-model-triangulation/, slb/, start/,
  frontend-design/, gdb-for-debugging/, ubs-workflow/, ui-polish/, ...
hooks/
  hooks.json              ← 4 hooks (SessionStart, PreToolUse, Stop, SubagentStop)
  startup.js              ← Session initialization
  agent-mail-guard.js     ← File reservation management
  _run-hook.sh            ← Hook runner
mcp-server/               ← MCP server (TypeScript, compiled to dist/)
  src/                    ← MCP tools for bead management
flywheel.config.yaml      ← Convergence gate configuration
.pi-flywheel/             ← Per-project state (created at runtime)
  beads/                  ← Bead definitions
  completion/             ← Zod-validated completion attestations (<beadId>.json)
  waves/                  ← Wave execution state
.pi/                      ← Project intelligence (scan/discover outputs)
.mcp.json                 ← MCP server configuration
install/                  ← Install scripts
install.sh                ← Linux/macOS installer
install.ps1               ← Windows installer

Required Runtime

  • Claude Code (plugin system)
  • Node.js >= 18.18
  • NTM + Agent Mail (for multi-agent swarm mode)

Target AI Tools

Claude Code (primary, only supported).

03

Components

AI Flywheel (agent-flywheel-plugin) — Components

Commands (24)

Command Purpose
start Smart entry: resume menu (open beads) or fresh-start menu
flywheel-setup Initialize project for flywheel use
flywheel-scan Scan codebase: profile + ranked ideas → .pi/
flywheel-swarm Launch multi-agent swarm for bead execution
flywheel-swarm-stop Stop all swarm agents
flywheel-swarm-status Show swarm agent status
flywheel-duel Adversarial 2-agent ideation cross-scoring
flywheel-audit Audit bead completion evidence
flywheel-doctor 23-check health sweep
flywheel-status Show bead/wave progress
flywheel-drift-check Detect context drift since last checkpoint
flywheel-fix Structured error recovery routing
flywheel-rollback Rollback to last checkpoint
flywheel-healthcheck Quick health verification
flywheel-stop Stop current flywheel session
flywheel-bead-viewer Open Cytoscape bead-graph dependency view (bv)
flywheel-cleanup Clean stale state files
flywheel-compound-refresh Refresh compound bead state
flywheel-reality-check Sanity check on current state
flywheel-refine-skill Iteratively refine a single skill
flywheel-refine-skills Batch skill refinement
flywheel-research Research phase command
flywheel-tool-feedback Collect tool usage feedback
memory Memory management command

Skills (40+ skill directories)

Core flywheel skills:

  • start, brainstorming, idea-wizard — goal/spec ideation
  • flywheel-scan, flywheel-setup, flywheel-status — project intelligence
  • flywheel-swarm, flywheel-duel — multi-agent patterns
  • flywheel-audit, flywheel-doctor, flywheel-healthcheck — observability
  • flywheel-drift-check, flywheel-rollback, flywheel-fix — recovery
  • cass, cass-memory — Code-Aware Session System
  • caam — unknown (context-aware agent management?)
  • multi-model-triangulation — 3-model parallel planning
  • slb — Simple Load Balancer integration
  • frontend-design, ui-polish, ui-ux-polish — UI-specific workflows
  • gdb-for-debugging — debugger-style investigation
  • ubs-workflow — unknown (UBS = user-built-system?)
  • docs-de-slopify — documentation cleanup
  • changelog-md-workmanship — changelog maintenance
  • dsr — unknown (deep-search-review?)
  • memory — session memory management

Hooks (4)

Event Matcher Script Purpose
SessionStart * startup.js Load session state, initialize bead tracker
PreToolUse Bash agent-mail-guard.js File reservation check before writes
Stop * agent-mail-guard.js --release-reservations Release file reservations when session stops
SubagentStop * agent-mail-guard.js --release-reservations Release reservations when subagent stops

MCP Server

  • TypeScript MCP server in mcp-server/
  • Provides bead management tools to Claude Code
  • Tools include: flywheel_approve_beads, flywheel_advance_wave, and others
  • Zod schema validation for completion evidence

State Files

  • .pi-flywheel/beads/ — bead definitions and status
  • .pi-flywheel/completion/<beadId>.json — Zod-validated completion attestations
  • .pi-flywheel/waves/ — wave execution state
  • .pi/ — project intelligence (scan/discover outputs)
  • flywheel.config.yaml — convergence gate configuration
05

Prompts

AI Flywheel (agent-flywheel-plugin) — Prompt Excerpts

Excerpt 1: README — Adversarial Duel Pattern

Source: README.md

# Pick "Duel"
# Adversarial 2-agent ideation: two agents independently review, then cross-score.
# Disagreements surface gaps the author's agent would not catch.

/agent-flywheel:flywheel-duel

From the comparison table:

| Adversarial review (duels) | ✅ 2-agent cross-scoring | ✗ | ✗ | ✗ |

Prompting technique: Adversarial subagent — two agents score each other's work, with disagreements treated as signal rather than noise. This is the only framework in this batch with formal adversarial review.

Excerpt 2: README — Error Contracts

| Structured error contracts | ✅ 36-code FlywheelErrorCode | ✗ string parsing | ✗ | ✗ |

"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."

Prompting technique: Machine-readable completion contracts — the Completion Evidence JSON (Zod-validated) is a typed completion certificate rather than a conversational "done" signal.

Excerpt 3: From vnnkl/agentflywheel (related skills bundle) — Multi-Model Planning

Source: vnnkl/agentflywheel README (related project, same methodology)

### `/competing-plans` - Parallel Plan Synthesis
Spawn 3 parallel agents that independently plan the same feature, then synthesize a
"best-of-all-worlds" plan. Each agent has a different persona (Pragmatist, Defender, Architect)
that emphasizes different concerns. The synthesis combines the strongest elements from each.

Prompting technique: Persona differentiation in parallel planning — assigning distinct philosophical stances (Pragmatist, Defender, Architect) to parallel planning agents ensures their outputs actually diverge rather than converging on the same answer.

Excerpt 4: From vnnkl/agentflywheel — Deep Planning First

### `/deep-planning` - 85% Planning First
Enforce comprehensive upfront planning before any implementation. Produces a markdown plan
covering architecture, data flow, error handling, edge cases, and security. Based on the
principle that plan mistakes cost 1x to fix, while code mistakes cost 25x.

Prompting technique: Cost-ratio framing — "plan mistakes cost 1x, code mistakes cost 25x" is a concrete economic argument embedded in the prompt rationale, making the planning requirement feel grounded rather than arbitrary.

09

Uniqueness

AI Flywheel (agent-flywheel-plugin) — Uniqueness

Differs From Seeds

The ag-coding-flywheel is most similar to claude-flow (both implement swarm orchestration with file conflict prevention and a completion ledger). However, it differs in three ways: (1) it ships as a Claude Code plugin rather than an npm MCP server, making it zero-infrastructure-install for Claude Code users; (2) its adversarial "duel" review — two agents cross-scoring each other — is more formalized than claude-flow's hive-mind; and (3) the 36-code FlywheelErrorCode provides machine-readable structured error routing absent from all seeds.

The multi-model triangulation (claude-opus + claude-sonnet + codex in parallel for planning) is the most explicit programmatic model routing in the entire batch-19 corpus, and likely in the broader seed+batch corpus.

Positioning

  • Most operationally complex Claude Code plugin in this batch
  • "Production engineering" mindset: structured errors, typed attestations, conflict prevention, 23-check doctor
  • Built on the Dicklesworthstone flywheel methodology (same ecosystem as ACFS in this batch)
  • Very low public profile (2 stars) despite v3.18.0 version number — likely used internally

Notable Patterns

  1. Zod-validated completion attestations: The completion evidence must pass a Zod schema — typed completion certificates are unusual in the prompt framework ecosystem
  2. 36-code FlywheelErrorCode: Structured error taxonomy is engineering-level rigor
  3. Persona-differentiated parallel planning: Pragmatist, Defender, Architect agents produce genuinely different plans because they're given different optimization objectives
  4. 4-minute tender daemon: Auto-recovery via a looping watcher is production-infra thinking applied to AI agent management

Observable Failure Modes

  1. NTM + Agent Mail dependency: Swarm mode requires external tooling (NTM, Agent Mail) not bundled with the plugin
  2. Very low adoption: 2 stars despite rich features — discoverability problem
  3. Version inflation: v3.18.0 for a 2-star repo suggests private/internal development; external stability not validated
  4. No worktree isolation: File reservations prevent conflicts but don't prevent partial writes if an agent crashes mid-bead

Cross-References

  • Built on the Dicklesworthstone/Jeffrey Emanuel Agentic Coding Flywheel methodology
  • Related to ACFS (also in this batch) — same methodology, different layer (plugin vs. infrastructure)
  • Related to vnnkl/agentflywheel — a skills bundle extracting the same methodology into standalone skills
  • Related to burningportra/pi-agent-flywheel — a pi-agent variant of the same plugin
04

Workflow

AI Flywheel (agent-flywheel-plugin) — Workflow

Six-Phase Loop

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

Phase Details

Phase Command Output Gate
Scan /flywheel-scan .pi/ profile + ranked ideas No
Discover (via start menu) Goal + brainstorming output User selects
Plan (brainstorming skill) Bead dependency graph User approves beads
Implement /flywheel-swarm Code changes per bead Completion Evidence per bead
Review /flywheel-audit + duel Cross-scored review Score gate (gate_advance_wave)
Wrap-up (implicit) Cleanup + final state Completion

Bead Lifecycle

pending → reserved → in_progress → completed (with Evidence) | failed → rollback

Bead completion requires:

  1. Agent writes completion evidence JSON to .pi-flywheel/completion/<beadId>.json
  2. Evidence passes Zod schema validation
  3. Coordinator validates before advancing the wave

Multi-Model Planning

From README:

"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."

The multi-model-triangulation skill manages this parallel planning pass.

Duel (Adversarial Review)

  1. Two agents independently review the same bead/implementation
  2. Each agent scores the other's work
  3. Scores are compared; disagreements surface gaps
  4. The duel output feeds back into the bead quality gate

Recovery Mechanisms

  • Drift check: Before resume, checks if codebase has changed since last checkpoint
  • Tender daemon: 4-minute looper that auto-recovers stalled beads
  • Rollback: /flywheel-rollback reverts to last clean checkpoint
  • Doctor: 23-check health sweep (/flywheel-doctor) identifies environment issues
  • Fix: Structured error routing with 36-code FlywheelErrorCode

Convergence Gate

From flywheel.config.yaml:

convergence:
  gate_advance_wave: true  # kill-switch: set false to disable auto-approve on score

When gate_advance_wave: true, the coordinator auto-advances waves when convergence scores pass. When false, human must manually advance.

06

Memory Context

AI Flywheel (agent-flywheel-plugin) — Memory & Context

State Storage

File-based, per-project, in .pi-flywheel/ and .pi/.

Bead State (.pi-flywheel/beads/)

  • One JSON file per bead
  • Fields: id, description, dependencies, status, file reservations, assignedAgent

Completion Evidence (.pi-flywheel/completion/<beadId>.json)

  • Zod-validated JSON attestation per completed bead
  • Versioned: the schema version is tracked
  • Coordinator reads these before advancing to next wave

Wave State (.pi-flywheel/waves/)

  • Current wave number, bead assignments, completion scores

Project Intelligence (.pi/)

  • Scan output: codebase profile, ranked ideas, discovery data

Persistence

  • Scope: project-level, on-disk
  • Checkpoint after every step — crashes are recoverable
  • Drift check on resume: verifies codebase has not changed unexpectedly since last checkpoint

Session Initialization

startup.js (SessionStart hook):

  • Loads bead state from .pi-flywheel/
  • Detects open beads → triggers resume menu
  • Loads Agent Mail connections

File Reservation System

agent-mail-guard.js (PreToolUse hook):

  • Before any Bash command, checks if target files are reserved by another agent
  • If reserved: blocks the operation and routes to queue
  • On Stop/SubagentStop: releases all file reservations for that agent

Memory Skill

A dedicated memory command and skill for session memory management (details internal to skill definition).

cass-memory Skill

cass-memory (Code-Aware Session System memory) — a skill for maintaining code-aware context across sessions.

07

Orchestration

AI Flywheel (agent-flywheel-plugin) — Orchestration

Multi-Agent Pattern

Yes — swarm with file conflict prevention.

  • Orchestration pattern: swarm (parallel agents + file reservation coordination)
  • Coordinator: start command + MCP server (flywheel_approve_beads, flywheel_advance_wave)
  • Workers: individual bead-executing agents
  • Conflict prevention: NTM + Agent Mail + agent-mail-guard.js (file reservation system)

Wave-Based Execution

Similar to GSD's wave model: beads within the same dependency level execute in parallel. The convergence gate (gate_advance_wave) controls whether waves auto-advance or require human approval.

Adversarial Review (Duel)

The duel is the most distinctive orchestration feature:

  1. /flywheel-duel spawns two agents
  2. Each independently reviews the same implementation
  3. Each scores the other's review (cross-scoring)
  4. Score disagreements are structured outputs, not conversational
  5. A human decides based on the duel outcome

This is the only formal adversarial multi-agent review protocol in the entire batch-19 corpus.

Multi-Model Planning

From README:

"Generates a plan via 3 parallel models (claude-opus, claude-sonnet, codex)"

The multi-model-triangulation skill manages this:

  • Three agents with different personas (Pragmatist, Defender, Architect)
  • Each produces an independent plan
  • Plans are synthesized into a "best-of-all-worlds" result

This is the most explicit multi-model routing in this batch.

File Reservation (Conflict Prevention)

The agent-mail-guard.js PreToolUse hook:

  • Intercepts Bash commands before execution
  • Checks Agent Mail for file reservations held by other agents
  • Blocks if conflict; releases on Stop/SubagentStop

This prevents "agent trampling" without requiring separate containers.

Tender Daemon

A 4-minute looper that:

  • Monitors for stalled beads (no progress in 4 minutes)
  • Auto-recovers by re-assigning stalled beads

Execution Mode

  • With convergence gate: continuous-ralph (waves advance automatically on score pass)
  • Without convergence gate (gate_advance_wave: false): interactive-loop

Isolation

No container or worktree isolation. File reservation is the only isolation mechanism.

08

Ui Cli Surface

AI Flywheel (agent-flywheel-plugin) — UI / CLI Surface

CLI Binary

No dedicated CLI binary. Interaction is through Claude Code slash commands.

Installer scripts exist:

  • install.sh (Linux/macOS)
  • install.ps1 (Windows)

Local UI

Limited — the flywheel-bead-viewer command opens a Cytoscape.js-based dependency graph viewer (bv):

  • Visual bead dependency graph
  • Node states color-coded
  • Runs in browser

No full web dashboard.

IDE Integration

Claude Code only.

Observability

  • /flywheel-status — current bead/wave progress
  • /flywheel-doctor — 23-check health sweep (environment, NTM, Agent Mail, MCP server)
  • /flywheel-healthcheck — quick health verification
  • /flywheel-swarm-status — swarm agent status
  • /flywheel-drift-check — drift detection
  • /flywheel-audit — bead completion evidence audit
  • Bead-graph viewer (bv) — Cytoscape visual dependency graph

Error Handling Surface

  • 36-code FlywheelErrorCode for structured error routing
  • /flywheel-fix — structured error recovery
  • /flywheel-rollback — checkpoint rollback
  • Tender daemon — auto-recovery for stalled beads

MCP Server

TypeScript MCP server provides:

  • flywheel_approve_beads — approve bead completion
  • flywheel_advance_wave — advance to next execution wave
  • Zod schema validation for all completion evidence

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k
A11 Governance

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k
A11 Governance

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k
A11 Governance

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k
A11 Governance

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k
A11 Governance

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k
A11 Governance

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…