pan-flywheel git:20260721.ce35c20A

Immutable. This exact content is served forever at /api/v1/blob/e49ae371f87e34e7.

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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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)