flywheel-swarm

Launch parallel NTM-managed agents to implement multiple beads simultaneously.

3|1|Updated Apr 15, 2026
One-click install
npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill flywheel-swarm-burningportra
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: flywheel-swarm
Source: https://github.com/burningportra/agent-flywheel-plugin/tree/main/skills/flywheel-swarm
Command: npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill flywheel-swarm-burningportra

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Implementing multiple planned work items (beads) one at a time is slow, and naive multi-agent fan-out causes agents to trample each other's files, lose track of in-flight work, and skip review. This Skill coordinates a parallel swarm of implementation agents with file reservations, completion attestations, and a mandatory review gate. ## Core Features & Use Cases - NTM-first agent fan-out: Spawns implementation agents via ntm spawn and ntm --robot-send with marching-orders prompts, falling back to Agent() only when NTM is unavailable and the user approves. - Coordination and conflict prevention: Bootstraps Agent Mail sessions, team creation, and file reservations so parallel agents do not edit the same files. - Pre-completion quality gate: Requires each agent to run UBS checks, repo verify commands, self-review, and write a .pi-flywheel/completion/<bead-id>.json attestation before reporting done. - Wave-completion review gate: After all agents finish, routes the user through a consolidated review prompt (looks good, self review, fresh-eyes, or duel review) instead of ending the turn. - Use Case: After planning produces five ready beads, launch three parallel agents to implement them concurrently, monitor progress via the tending loop, and run the review gate once the wave completes. ## Quick Start Ask the agent to launch a swarm to implement all ready beads in parallel and choose how many agents should run.

Frequently Asked Questions about flywheel-swarm

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run multiple coding agents in parallel on planned tasks?

Invoke the swarm skill after planning: it lists ready beads via flywheel_approve_beads, asks how many agents to run, then spawns NTM panes with marching-orders prompts for each bead. Each agent claims files, implements, and reports completion through Agent Mail.

How do parallel agents avoid editing the same files?

Each agent calls file_reservation_paths before editing and releases reservations when done. The pre-commit guard blocks conflicting edits, so concurrent agents cannot trample each other's files.

What happens if the ntm CLI is not installed?

The skill checks `which ntm` and `ntm deps -v` first. If NTM is unavailable, it warns the user, asks for confirmation, and only then falls back to a single Agent()-based implementation path.

Why does the swarm require a completion attestation file?

Each agent must write .pi-flywheel/completion/<bead-id>.json matching CompletionReportSchemaV1, recording UBS results, verify commands, and self-review. The coordinator validates this ledger before advancing the wave, preventing unverified work from passing.

What should I do when a swarm agent becomes unresponsive?

Follow the stuck-pane ladder: nudge the agent via SendMessage, then use ntm --robot-smart-restart or --robot-restart-pane to recycle the pane while preserving bead state. TaskStop is the last resort after the ladder is exhausted.