skills.rest
burningportra
burningportraCOMMUNITY
Explore all skills by this author →
GitHub

flywheel-doctor

Diagnose flywheel toolchain dependencies and render a per-check health report with inline remediation.

3|1|Updated Apr 15, 2026
Search Tags:#remediation#multi-agent#mcp#health check#diagnostics#toolchain#ci gate
One-click install
npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill flywheel-doctor-burningportra
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: flywheel-doctor
Source: https://github.com/burningportra/agent-flywheel-plugin/tree/main/skills/flywheel-doctor
Command: npx skills add https://github.com/burningportra/agent-flywheel-plugin --skill flywheel-doctor-burningportra

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Multi-agent coding setups fail in confusing ways when a binary is missing, the MCP server is unregistered, or the Agent Mail service is down. This Skill runs a single read-only diagnostic sweep across every flywheel dependency so toolchain problems surface as one clear report instead of cryptic downstream failures. ## Core Features & Use Cases - Parallel health checks: Runs 11 bounded checks covering MCP connectivity, Agent Mail liveness, br/bv/ntm/cm binaries, node version, git status, dist drift, orphaned worktrees, and checkpoint validity, each with per-check timeouts and a global sweep budget. - Inline remediation: For each failing check, prompts the user with dry-run or execute options via the flywheel_remediate tool, including service-aware Agent Mail repair and canonical CLI installers. - CI and onboarding gates: Use it before starting a new session, after cleanup, or as a CI gate so toolchain regressions appear as a red line rather than a confusing test failure. - Use Case: Before running /start on a fresh clone, invoke the doctor to confirm every binary resolves and MCP is registered; if dist drift is detected, apply the automated fix and re-verify in one pass. ## Quick Start Ask the agent to run flywheel doctor on the current repository and fix any failing checks it finds.

Frequently Asked Questions about flywheel-doctor

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

FAQPage Schema
How do I check if my flywheel toolchain is set up correctly?▼

Run the flywheel doctor command, which executes 11 parallel checks covering MCP connectivity, Agent Mail liveness, required binaries, node version, git status, and checkpoint validity. Each check reports green, yellow, or red with a one-line detail.

What does the flywheel doctor diagnostic check?▼

It verifies MCP server connectivity, Agent Mail health endpoint, br/bv/ntm/cm binary resolution, node version against the minimum, git repo status, dist drift between src and build output, orphaned worktrees, and checkpoint SHA validity.

Can flywheel doctor fix failing checks automatically?▼

Yes, 10 checks have automated remediation through the flywheel_remediate tool with dry-run and execute modes. Checks like node_version and git_status require manual fixes, and the report shows the manual hint for those.

Is flywheel doctor safe to run while other agents are working?▼

Yes, doctor is read-only and never mutates checkpoints, spool files, or worktrees. It is safe to run concurrently with an active session, and remediation steps are always gated behind an explicit user prompt unless --auto is passed.

Why does the Agent Mail liveness check fail with a lock error?▼

The mailbox activity lock becomes busy when the Agent Mail service is in a bad state. The remediation handler stops the supervised service, runs am doctor repair and archive-normalize, restarts it, and re-verifies the liveness endpoint.

When should I run flywheel doctor versus flywheel healthcheck?▼

Run doctor first as a fast read-only snapshot for setup and toolchain issues, typically under two seconds. Healthcheck is a deeper periodic audit of the codebase, bead graph, and dependencies, run on a cadence rather than to fix setup problems.

Related Skills

Explore More Software Engineering Skills→
DicklesworthstoneDicklesworthstone
70

agent-swarm-workflow

Coordinate parallel software tasks across multiple agents using Agent Mail and BV prompts.

Community
Advanced
mthangtrmthangtr

worker

Execute beads autonomously within a track while maintaining context via Agent Mail.

Community
Advanced
justin-delanojustin-delano
1

beads-audit

Run Beads toolkit health checks to detect orphaned issues and circular dependencies.

Community
Intermediate
rohitg00rohitg00
944

k8s-cli

Discover and invoke kubectl-mcp-server tools from a CLI.

Community
Intermediate