pan-flywheel

name	pan-flywheel
description	pan flywheel — start, pause, resume, complete, stop, inspect, emit, and report on the singleton Fix-All Flywheel orchestrator
triggers	["pan flywheel","flywheel orchestrator","fix-all flywheel","start flywheel","pause flywheel","flywheel status"]
allowed-tools	["Bash","Read"]

pan flywheel

Use this skill when operating the singleton Fix-All Flywheel orchestrator.

The Flywheel is not an issue-scoped work agent. It runs as flywheel-orchestrator, reads a brief, emits typed status snapshots to the dashboard, and writes a deterministic end-of-run report.

Commands

pan flywheel start
pan flywheel start --brief docs/flywheel-brief.md
pan flywheel start --orders <book-id>
pan flywheel config --get
pan flywheel config --get flywheel.require_uat_before_merge
pan flywheel config --set flywheel.auto_pickup_backlog=true
pan flywheel config --set flywheel.require_uat_before_merge=false
pan flywheel status
pan flywheel status --json
pan flywheel pause
pan flywheel resume
pan flywheel complete
pan flywheel complete --force
pan flywheel stop
pan flywheel abort
pan flywheel emit-status --file latest.json
pan flywheel report

When to Use Each Subcommand

Start

pan flywheel start
pan flywheel start --brief docs/flywheel-brief.md
pan flywheel start --orders <book-id>

Starts flywheel-orchestrator and opens a new run under ~/.overdeck/flywheel/runs/<runId>/.

Use the default brief unless the user gives a specific markdown brief. The default is docs/flywheel-brief.md. The command validates that the brief path stays inside the project root.

--orders <book-id> validates a ready order book, stamps the book binding into the run launch metadata, and marks the book running only after the Flywheel start gate succeeds. Validation or gate failures leave the book ready.

Config

pan flywheel config --get
pan flywheel config --get flywheel.require_uat_before_merge
pan flywheel config --set flywheel.auto_pickup_backlog=true
pan flywheel config --set flywheel.require_uat_before_merge=false

Reads or writes the two persisted Flywheel autonomy toggles. --get without a key prints both keys as <key>=<bool>; --get <key> prints one key; --set <key>=<bool> writes one key and prints the new value.

Only these keys are accepted: flywheel.auto_pickup_backlog and flywheel.require_uat_before_merge.

Status

pan flywheel status
pan flywheel status --json

Shows the active run's latest FlywheelStatus snapshot. Use --json when another tool or script needs the raw contract payload.

Pause and Resume

pan flywheel pause
pan flywheel resume

pause flips the Flywheel gate and stops active orchestration without clearing the active run id. resume clears the gate and restarts the singleton if needed.

If the Flywheel is already paused or already running, these commands report the current gate state and exit successfully.

Complete

pan flywheel complete
pan flywheel complete --force

Completes an orders-bound run after every book item is closed or parked. The command refuses a non-drained book and names each remaining issue unless --force is passed. It writes report.md, adds ## Retrospective from the run's retro.md when present or the exact no-findings line otherwise, commits any docs/FLYWHEEL-STATE.md change, clears the active-run gate, and marks the book complete.

Continuation is mechanical: the next ready book in queue order starts in-process; when no book is ready and flywheel.auto_pickup_backlog=true, a bookless backlog run starts; otherwise the command stays stopped and emits needs-you: pipeline idle — no order book queued and auto-pickup is off.

Stop

pan flywheel stop

Gracefully stops the active Flywheel run. Kills any live flywheel-orchestrator session (even when the gate is already paused), writes the per-run report.md, commits any orchestrator-authored changes to docs/FLYWHEEL-STATE.md, and clears the SQLite active-run gate so the next pan flywheel start opens a fresh run.

Use this as the normal way to wind down a run and keep its report. Idempotent: a no-op with a clear message when nothing is running and nothing is left to report.

Abort

pan flywheel abort

Discards the active Flywheel run without writing a report. Stops flywheel-orchestrator if it is still attached, writes aborted.json under the run directory, and clears the SQLite gate so the next pan flywheel start can proceed.

Use this when a run is stuck because the orchestrator died (reboot, crash) and there is nothing worth reporting, or when you want a clean slate without ceremony. Idempotent: a no-op when nothing is active.

Emit Status

pan flywheel emit-status --file latest.json

Validates a FlywheelStatus JSON payload and posts it to the local dashboard. The --file value is normally a path; pass a single dash as the value when reading the payload from stdin.

The role prompt should use this helper instead of hand-writing HTTP requests so schema validation stays centralized.

Report

pan flywheel report

Writes the per-run report under the run directory (${OVERDECK_HOME}/flywheel/runs/<runId>/report.md) and commits any orchestrator-authored changes to docs/FLYWHEEL-STATE.md (durable cumulative memory). Produces a docs(flywheel): run N commit when there are changes.

Run this at the end of a Flywheel revolution, not after every status tick.

Guardrails

• Do not start a second Flywheel run while one is active.
• Do not spawn the Flywheel from a workspace devcontainer.
• Do not bypass pan flywheel emit-status with raw HTTP.
• Do not auto-merge or deep-wipe from the Flywheel; keep those as explicit human-controlled actions.

See Also

• roles/flywheel.md — orchestrator role prompt
• docs/flywheel-brief.md — default brief
• docs/FLYWHEEL.md — operator documentation
• docs/FLYWHEEL-STATE.md — durable cumulative memory across all runs (created on first orchestrator write)