version: "1.0.2" name: flywheel-operator description: >- Operate the flywheel framework from any role — human or agent. Use when you want to install flywheel into a repo, validate it is healthy, understand its state, or drive the loop (plan/brief/dispatch/review/correct-or-land) as an operator rather than as a worker. The CLI implements the whole loop except creating and resuming tasks: init, config, log, state, run (through the opencode, claude or sim adapter), validate, inspect, verify, factory, staff, cost, stats, next, status, handoff, trace, claim/release/claims, controller, goal, land and lint. Only flywheel plan, retry and artifacts are still planned — until they land, create and resume tasks with brief files and the raw worker commands shown here. license: MIT metadata: version: 0.39.0 # x-release-please-version

Flywheel Operator

Flywheel is a durable orchestrator-to-worker loop. Any agent — or a human — can drive it. The CLI is the deterministic substrate; the skills are the judgment layer. You are the operator: you decide what runs, who runs it, and whether it landed. The command table below implements protocol v1.

What the CLI implements today

The table below lists every command flywheel help prints, kept in sync with the registry (a doc test fails the build if a command is missing here). Only flywheel plan, retry and artifacts are not built yet; the rest of this skill's manual workflow explains what to do until those three land.

Install

# build and validate the CLI
go build ./... && go vet ./... && go test ./...
 
# install the binary
go install ./cmd/flywheel
 
# scaffold state into a repo
flywheel init --dir <target>     # creates flywheel.md + .flywheel/state.json + .flywheel/briefs/

Requires: Go toolchain (to build), the opencode CLI (to dispatch workers), git.

Windows. An existing factory whose .flywheel/.gitattributes predates init (init writes * text eol=lf) should add that line and re-checkout the briefs, so dispatch hashes and brief hashes agree despite CRLF.

Upgrading. Swap the binary — renaming the old executable is safe while a unit runs. Keep symlinked skill installs rather than copies (the skills installer can replace symlinks). Commit skills-lock.json, or any tracked file the skills installer touched, before the next flywheel validate, because files the lead changes after a unit's dispatch count against that unit's owns check. Run flywheel status afterwards.

State model

Everything is files — no database.

Repo is the session. State lives in files, not in any vendor CLI session. That is what makes handoff free: a new head reads the same files and continues. Helper scripts and notes must live in the repo, never in a per-session scratch directory — a session restart loses them. Because handoff is not built yet, transfer is manual — write the current state into flywheel.md and the brief files, and pass the emitted session ID by hand to the next head.

In a consumer repo. Commit the state: flywheel.md, .flywheel/state.json, .flywheel/briefs/, .flywheel/plans/, .flywheel/learnings.md, .flywheel/scripts/ (and .flywheel/events.jsonl once the event log lands, issue #11); ignore .flywheel/runs/ and any local cache. This framework repo ignores its own .flywheel/ only because its dogfood state is scratch — consumer repos commit theirs.

Config

.flywheel/config.json is the project configuration, created by flywheel init:

Read and set it with the CLI:

flywheel config get model                    # bare keys use the default worker
flywheel config set variant low              # or model, adapter, max_parallel
flywheel config set workers.<name>.<key> <v> # any worker by name
flywheel config set workers.<name>.permission_mode bypassPermissions  # claude workers; empty = acceptEdits
flywheel config set workers.<name>.max_turns 400    # claude --max-turns; 0 = limits.max_turns, else 200
flywheel config set limits.unit_cost_usd 5          # per-unit cost cap in USD; 0 = none (workers.<name>.unit_cost_usd overrides)
flywheel config set review.panel_min_lines 40       # review --panel: a diff under 40 changed lines gets one reviewer; 0 = off
flywheel config set feedback.upstream <owner/repo>
flywheel config set feedback.submit ask|never
flywheel config set limits.per_host <n>
flywheel config show                        # effective config as JSON
flywheel config validate                    # check the config, list every problem

Settable keys: model, variant, adapter, max_parallel (bare = the default worker, or workers.<name>.<key>), max_turns and unit_cost_usd (the same), feedback.upstream, feedback.submit, limits.per_host, limits.max_turns, limits.unit_cost_usd, staffing.lead.adapter, staffing.lead.model, staffing.lead.session, staffing.inspector.adapter, staffing.inspector.model, staffing.inspector.session, staffing.auditor.adapter, staffing.auditor.model, staffing.auditor.session, staffing.reviewer.adapter, staffing.reviewer.model, staffing.reviewer.session. fallbacks is not settable — edit .flywheel/config.json for it. flywheel init --model <m> --variant <v> seeds a fresh config at setup.

Operating the loop

The CLI has no plan/retry/handoff commands yet, so those steps are done with files and raw commands. flywheel init only scaffolds; the loop below is the manual fallback and runs on the same state files the planned subcommands will automate. $MODEL comes from .flywheel/config.json — flywheel config get model (see Config below).

1. Plan — decompose into bounded single-purpose tasks; each gets a brief file:

cat > .flywheel/briefs/<id>.txt with goal, exact change, don't-touch list, required gates, report contract.

1. Brief — the brief file from step 1 is the brief: goal, exact change, don't-touch list,

required gates, report contract.

1. Dispatch — first choice is flywheel log --task <id> --kind planned --brief <path> then

flywheel run <task>. Manual fallback (e.g. one increment of a brief) — fresh run with --variant low, capture rc and sessionID: ``bash mkdir -p .flywheel/runs OPENCODE_CONFIG=skills/flywheel/references/worker-permissions.json \ opencode run --pure -m "$MODEL" --auto --format json --title "<id>-r1" --variant low \ "Follow the attached brief exactly." --file .flywheel/briefs/<id>.txt < /dev/null > .flywheel/runs/<id>.r1.jsonl; rc=$? ` Every dispatch sets OPENCODE_CONFIG to the worker permission policy, which denies tree-rewriting git commands (ordering and --auto behaviour: [../flywheel/references/worker-brief.md#2-dispatch-canonical-flywheel-run-the-worker-adapters-own-cli-as-fallback](../flywheel/references/worker-brief.md#2-dispatch-canonical-flywheel-run-the-worker-adapters-own-cli-as-fallback)). Session id (every JSONL event carries it): `bash grep -o '"sessionID":"[^"]*"' .flywheel/runs/<id>.r1.jsonl | head -1 ` Record the exit code and the emitted session ID in flywheel.md — flywheel run` will do this when it lands.

1. Review — judge the actual exit status and git diff, never self-report. Run `flywheel

validate <task> then flywheel inspect <task> --verdict ... --session <your own session>` from your own session — a worker's report is never evidence. Re-run gates independently on sensitive changes.

1. Correct or land (manual fallback) — resume the emitted session ID with a delta brief for

corrections. Pass the session ID by hand; there is no automatic handoff: ``bash OPENCODE_CONFIG=skills/flywheel/references/worker-permissions.json \ opencode run --pure -m "$MODEL" --auto --format json --title "<id>-c<n>" --variant low --session "<emitted-sessionID>" \ "Apply the attached correction to the same task." --file .flywheel/briefs/<id>.delta.txt < /dev/null > .flywheel/runs/<id>.c<n>.jsonl; rc=$? ` Give each correction its own delta. flywheel run <id> --delta <file> snapshots it to .flywheel/briefs/<id>.c<n>.delta.txt and records that path on dispatched, so reusing the file never breaks an earlier correction's T1. For an older ledger where a later delta overwrote an earlier one, acknowledge the loss with flywheel log --task <id> --kind amended --attempt c<n> --note "<why>"`; T1 passes that correction with the note as its reason and waives nothing else.

Validating while other units run

When parallel units run on one checkout, repo-wide gates fail with each other's half-written code, triggering the T3 refusal (exit 6, "no passing supervisor validated reading on tree"). To avoid this, use separate worktrees: for each unit, reset a verify worktree to main's HEAD, clean it, and copy only that unit's owned files. Then:

1. Run flywheel validate <task> --workdir <tree> to measure the gates on the stable worktree.
2. Run flywheel inspect <task> --verdict pass --workdir <tree> using the same worktree (T3 will find the passing supervisor reading on that tree hash).
3. Commit only the unit's owned files.

When CI already measured the merged commit (its gates passed on the PR before the squash merge), record that evidence instead of landing on --exception: flywheel attest <task> --commit <sha> --evidence <CI run URL> --session <your own session>, then flywheel inspect <task> --verdict pass --commit <sha> --session <your own session>, then flywheel land <task> --commit <sha>.

A unit's gates may depend on machine state outside the repo — a database, a local stack, or git-ignored env files. A fresh worktree holds only the unit's files, so that state must be carried in before the gates run, or the gate result is meaningless: a red gate that looks like a defect in the unit.

Control plane vs data plane

Both are reachable by anyone (agent or human) — the judgment layer differs, the substrate doesn't. flywheel plan, retry and artifacts are still planned; everything else in this table is built and safe to invoke.

Role economy

• Planner/validator (frontier model: Claude Code / Codex) — decomposes, briefs, judges.
• Worker (cheap disposable: OpenCode + DeepSeek) — explores, implements, tests, reports.
• Operator (you, or any agent) — decides who plays which role for a given run.

Role ≠ adapter: the role comes first; the cheapest head that can fill it is selected. Run out of tokens on the planner mid-session? The repo is the session — a new head reads the same files and continues. The loop never waits for a vendor.

Assigning personas

Each persona is a skill; any agent (or a human) can load one. To give an agent a role:

1. Load that skill into the agent — copy or install the persona's SKILL.md (and the factory

model it links to, skills/flywheel/references/factory.md).

1. Tell it its persona and session — which role it plays, which repo or worktree is its

session, and who else is on the line (the lead, the foreman, the auditor) so it can find its work and know what it must not do.

The independence rules hold for every assignment: the auditor is never the same session as the lead, planner or inspector, and should be a different model or vendor; the inspector never inspects work from its own session; a worker never records gauge readings, inspections or audits. A session that is two personas at once may do either role's work, but never both on the same unit.

Minimal staffing:

• One frontier lead holding the planner, foreman, inspector and steward roles (the lead plans,

runs the line, inspects and triages learnings — the default at small scale).

• OpenCode workers (the approved model) executing the work orders.
• A different model as auditor — a separate session, ideally a different vendor, that audits

first articles and samples.

Health

go test ./...            # one-command validation
git status               # what's dirty
flywheel factory --once  # status at a glance (use --json for machine use)
cat .flywheel/state.json # machine state
cat .flywheel/learnings.md # what the loop has taught itself (generated by flywheel feedback; not hand-edited)
grep '<sessionID>' ~/.local/share/opencode/log/opencode.log | tail -20   # provider errors (key limits) show up only here

If a dispatch stalls or fails, classify the run first (../flywheel/references/worker-brief.md#3-run-states-and-failures), then report the blocker and halt — never take over the worker's job. Never kill opencode processes by name; on Windows that can kill OpenCode Desktop.

Files to read

• skills/flywheel/SKILL.md — the orchestrator skill (full loop rules)
• skills/flywheel/references/worker-brief.md — brief template + dispatch safety
• skills/flywheel-worker/SKILL.md — the worker's contract
• examples/ — worked briefs