telescreen

flywheel 🎡

A Claude Code plugin that turns ad-hoc "vibe coding" into a disciplined, self-verifying loop for AI-assisted development. It distills the best practices from obra/superpowers, EveryInc/compound-engineering-plugin, karpathy/autoresearch, addyosmani/agent-skills, and gszhangwei/open-spdd into one coherent system.

This repository is the plugin, served through the xmarks marketplace (.claude-plugin/marketplace.json).

Install (Claude Code)

/plugin marketplace add arazvan-ec/xmarks
/plugin install flywheel@xmarks

Then /reload-plugins and run /flywheel:help. To make flywheel auto-activate in a repo, see docs/add-flywheel-to-a-repo.md.

Claude Code only — the claude.ai chat app uses a different Skills system and does not run Claude Code plugins.

Claude Code web — web sessions do not auto-install marketplace plugins, so neither /plugin install nor the settings.json marketplace keys make /flywheel:* appear there. Instead, vendor flywheel into the target repo once with scripts/install-vendored.sh; the commands then work on every surface as /flywheel-help, /flywheel-loop, … See docs/add-flywheel-to-a-repo.md. The same gap applied to flywheel itself: with no registered agents its own dev loop could not honor the +delegate routes it prescribes. install-vendored.sh --agents-only is the one self-target the guard allows — it registers agents/*.md into .claude/agents/ and nothing else (no skills, no hooks), and scripts/check-agent-parity.sh fails CI if the shipped and registered copies ever disagree in either direction. Its sibling --hooks-only registers this repo's own hooks into .claude/settings.json pointing at scripts/, and scripts/check-hook-parity.sh now also asserts that every hook hooks/hooks.json declares is registered there.

The idea: two nested loops

Outer loop (development cycle) — one unit of work flows through six gated phases:

spec → plan → work → verify → review → compound

Inner loop (inside work) — a tight write failing test → implement → run → observe → fix cycle that never declares "done" until an objective check is green.

Nothing advances on "seems right": verify runs the real app/tests, and every finished cycle deposits reusable knowledge into a ledger that primes the next one.

📚 New to loops as a concept? See docs/getting-started-with-loops.md — the four loop types (turn-based, goal-based, time-based, proactive) and how flywheel maps onto them.

⏱️ Want to run flywheel on a schedule or unattended? See docs/proactive-loops.md — composing /flywheel:verify/review with /loop, /schedule routines, /goal, and workflows.

The second pillar: an agent-native runtime (v0.15.0)

The loop above builds software. The process/run pair lets flywheel also operate it — turning the repo agent-native: Claude is a first-class part of the runtime, not a bolt-on. Instead of writing a static backend function for a recurring domain operation ("analyze a car", "score a lead", "ingest a report"), you define a process contract and let Claude run it.

• /flywheel:process <desc> scaffolds .claude/flywheel/processes/<slug>.md: the fixed rules the operation always follows, its output schema, and where results persist — following the repo's own data strategy declared once in .claude/flywheel/DATA.md (e.g. Postgres via the repo's client), never a datastore flywheel imposes.
• /flywheel:run <slug> [input] executes the contract as the backend: follow the rules, apply judgment only where the contract allows, write the result to the datastore and prove it landed (idempotent, read-back verified), then mature the contract — appending one evidence-based refinement so the next run is sharper. Fixed rules + a self-improving prompt, exactly as asked.

Full vision + the worked car example: docs/research/agent-native-processes.md.

Commands

Agents

• verifier — runs the app/tests and returns an objective PASS/FAIL with evidence.
• reviewer-correctness, reviewer-security, reviewer-performance — adversarial specialist reviewers dispatched in parallel by /flywheel:review. The fan-out itself is untested by the suites (P32, v0.60.0): an eval executor is a subagent, a subagent cannot spawn subagents, so no graded run this repo has ever made dispatched a reviewer-* at all. skills/review/evals/ covers what is left — which reviewers a diff draws (read from an artifact, not from the report's prose) and whether the report says the specialists did not run — and real dispatch has exactly one arm, run by hand from a top-level session, documented in that suite's README.
• evaluator — independent cross-check dispatched by /flywheel:autoloop on ambiguous keep/discard results and before it declares its target met; re-runs the metric command itself instead of trusting the working agent's self-report.
• executor — the cheap tier of stage routing (Haiku, low effort): does one fully-specified mechanical plan task in its own context and returns ESCALATE: <reason> rather than inventing a decision the task left open. Dispatched by /flywheel:work for a task routed haiku/low+delegate.

Model routing by role (v0.9.0): the mechanical verifier runs on Haiku (it runs commands and reports evidence); the judgment-heavy reviewer-* run on Sonnet. Override any agent via its model: frontmatter (e.g. a reviewer → opus for high-stakes reviews), or all at once with CLAUDE_CODE_SUBAGENT_MODEL. Since v0.39.0 each agent also pins its effort: — low for the mechanical verifier/evaluator/executor, high for the adversarial reviewer-*.

A task's check: is executed, not read (v0.70.0): every plan task must carry a - check: — plan-route.sh rejects a plan without one — and until now that field was linted for presence and never run, so "T4 is done" was a model grading its own work over a field that usually already held a runnable command. bash scripts/check-task-closure.sh runs it and prints one row per task: PASS (a command matched the allowlist, ran, exited 0), FAIL (it exited non-zero), UNRUNNABLE (no allowlisted command in the check — named and counted, never executed and never read as green), or PENDING (the cycle keeps a ledger and this task has no transition line in it, so it has not started — the loop commits a plan at its approval gate, before the work, and grading then would report not-started as broken). Rows equal tasks, so a dropped item is visible exactly where the count stops reconciling. What it may execute is pinned by scripts/task-closure-allow.txt — a span carrying a shell operator is refused before the allowlist is consulted, and what survives runs as argv with no shell, so an allowlisted prefix cannot append a second command. That file is a security boundary rather than a convenience list: a plan is repo content any PR can write, so running arbitrary shell out of it would hand /flywheel:verify the exposure gate.sh's trust store exists to close. Plans added before the cutoff are corpus — reported, never failed, never rewritten to buy a green (P18, P48). The gate grades the command's exit code, not the prose around it, so a check: written from here on states the condition that holds at close.

Stage routing: model + effort per plan task (P27, v0.39.0): a plan is not one price. /flywheel:plan routes every task with route: <model>/<effort>[+delegate] from a 3-tier rubric — T1 mechanical and fully specified (haiku/low+delegate, run by the executor agent), T2 ordinary test-first work (sonnet/medium), T3 judgment, and always the riskiest step (opus/high) — and the routing table is part of what the plan gate approves, so a model switch is a decision you signed, not one taken mid-task. /flywheel:work honors the route, escalates one tier on the second red instead of grinding cheap, and records route (plus route_escalated_from on an escalation) on the transition line. bash scripts/plan-route.sh <plan.md> lints the routes and prints the tier summary; it fails a plan whose riskiest step runs below the top tier (scripts/route-tiers.txt holds the tiers, so retuning them is a data edit). The payoff is deliberately not claimed in tokens — the linter counts tasks, and any cost delta rides on the cost proxies below (P18/P23).

Atomic commits inside the loop (P28, v0.40.0): a cycle no longer saves its work for the end. /flywheel:work commits each task the moment its check goes green and pushes it — git commit -m "<subject>" -- <the task's paths> (pathspec, so the commit holds that task and nothing that was already dirty) plus a force-free git push -u origin <branch>; /flywheel:debug does the same for a fix and its regression test. Both forms are exactly what the P21 grant already pre-approves, so the discipline costs no new permission surface. /flywheel:ship then commits only what is left (ledger, spec, docs) and never squashes, rebases or amends the task history — rewriting it is yours to ask for. Committing fails open everywhere: no repo, no remote, nothing to commit, or a rejected push is reported once and the loop carries on; on the default branch it creates a feature branch first rather than committing to main.

Token discipline (v0.12.0): /flywheel:autoloop treats its iteration budget as a hard stop and recommends piloting on a small budget before scaling; /flywheel:help points to /usage, /goal, and /workflows for spend visibility. See skills/autoloop/SKILL.md.

Delegation triggers (v0.13.0): /flywheel:work names advisory thresholds for handing off to a fresh-context subagent — reading 4+ files, touching 2+ non-trivial files, or ~20 tool calls deep without converging — to keep each turn's context lean.

Live progress (v0.16.0, two-tier since v0.30.0): every process run (/flywheel:run) and dev cycle (/flywheel:loop/work) materializes its steps as visible tasks in the host task system — states updated at every transition — and keeps per-execution telemetry at .claude/flywheel/runs/<slug>/<date>.jsonl (one appended JSON line per transition) plus an HTML report at …/<date>.html, rendered from the JSONL only at gates and at close and republished to a stable artifact URL. Output tokens are the expensive ones: a transition costs one line, never a regenerated page. Chat stays reserved for gates, blockers, and the final summary. Fail-open: reporting never blocks execution.

Cycle cost, measured (P23): each transition line carries a cost object — bytes_out, bytes_in, tool_calls, elapsed_s — and the rendered report ends with a cost block. These are proxies, labelled as such everywhere they appear, never token counts: a session cannot observe its own token usage, so recording one would put unverifiable evidence in the ledger (P18) — scripts/run-cost.sh warns if it finds a tokens key. bash scripts/run-cost.sh <run.jsonl> [baseline.jsonl] totals a run and prints the per-field delta against a baseline, so "this made the loop cheaper" becomes a number. Transitions from before the schema are reported as unmeasured, never counted as zero — otherwise every old run would look free. bytes_in (P40a) floors read volume (charged once per read, nothing for conversation) and is reported UNMEASURED, never 0, in old runs to prevent fabricating improvements. bytes_in and tool_calls are recorded as they happen (P44): scripts/read-meter.sh sits on PostToolUse and appends one line per call — the bytes of tool_response that entered context — so a transition line reads bytes_in, tool_calls and elapsed_s with read-meter.sh --since <previous ts> (or --since first on a cycle's opening transition, which has no previous ts — every run before P45 omitted elapsed_s on line 1 because a commit-time delta has no previous commit) instead of recalling a total nothing kept, which is why both fields were absent from every line in the repo's history. A write tool's response echoes the file it changed without that text reaching context, so the call counts and its bytes do not, and no meter at all reports UNMEASURED rather than a zero. bash scripts/check-telemetry.sh gates conformance (every runs JSONL line holds valid proxies) and coverage (every spec slug is instrumented unless exempted with a reason in scripts/telemetry-baseline.txt), failing the build if either rule breaks.

State it keeps (in the project you use it on)

• .claude/flywheel/specs/<slug>.md — REASONS specs and .plan.md plans.
• .claude/flywheel/processes/<slug>.md — agent-native process contracts (fixed rules + output schema + persistence + an append-only improvement log), created by /flywheel:process and matured by /flywheel:run.
• .claude/flywheel/DATA.md — the repo's data-persistence strategy (Store / Access / Schema / Conventions) that every /flywheel:run writes through, so results land the way the repo already stores them.
• .claude/flywheel/LEARNINGS.md — the compounding ledger. Typed entries (## <type>: <title> + a greppable <!-- fw: … --> metadata line; type ∈ decision/gotcha/pattern/bugfix/fixture) let the SessionStart hook inject only a relevance-scored, budgeted subset (branch/files/recency, default top 12, FLYWHEEL_LEARNINGS_INJECT to override) instead of a blind reload; /flywheel:recall <query> reaches the rest on demand. Created by /flywheel:compound. Older free-prose entries still load, as always-eligible low-priority entries.
• fixture entries (v0.21.0) capture how to set up the world — the recipe to build a valid stub for a domain entity, seed the datastore, or stand up a test harness — the costliest thing a session otherwise re-derives. /flywheel:work offers to record one when it spends real effort building test data, and /flywheel:spec + work prime from any that match the task's entities before the rediscovery.
• Evidence-gated (v0.25.0): flywheel gates knowledge the way it gates code. Each entry carries evidence= — what proved it (a test, a run/PR, a command → result). A lesson that can't point to a proof is written evidence=unverified explicitly, and the SessionStart injection + /flywheel:recall flag those so a wrong-but-plausible conclusion can never masquerade as proven context. /flywheel:compound records only what a cycle actually proved.
• .claude/flywheel/runs/<slug>/<date>.jsonl + .html — per-execution telemetry for process runs and dev cycles (v0.16.0): one JSONL line appended per state transition; the HTML report (task ledger + states, gates, unit telemetry, verdict) rendered from the JSONL only at gates and close (v0.30.0).

Read-priming hook (advisory)

Before reading a file, a PreToolUse hook greps the ledger's files= metadata for that path and, if any typed entry names it, injects a short "prior learnings touch this file" note into context via the hook's additionalContext field (v0.18.0 — plain stdout is transcript-only and never reaches the model) — cheap context ahead of an expensive read. A bash pre-filter skips the python parser entirely for the no-match majority. It never blocks the read (unlike claude-mem's File Read Gate) and fails silently (no ledger, no match, or no python3) so it can never slow down or break a read.

Approval-coherent permissions

flywheel has exactly two deliberate approval gates, and both are conversational: the spec sign-off and the plan approval. The harness's tool-permission layer knows nothing about them — so without help it re-asks "allow?" for actions the approval already implied. Two allow-only PreToolUse hooks close the gap; everything they don't match keeps the normal permission flow, and (docs-guaranteed) a hook "allow" can never override a deny/ask rule you wrote yourself. Both are fail-open by contract: they never deny, never ask, never block; malformed input or a missing python3 just falls back to the ordinary prompt.

• State writes (v0.27.0, Write|Edit|MultiEdit|NotebookEdit): a write whose target resolves inside <project>/.claude/flywheel/ is auto-allowed — specs, plans, the ledger, process contracts, run reports. Repo code and .claude/settings.json are out of scope. Paths are realpath-resolved before the containment check, so .. traversal, prefix siblings (.claude/flywheel-evil/) and symlinks planted inside the state dir that point elsewhere get no grant.
• Loop-advancing git (v0.28.0, Bash): one plain git add, git commit, git stash (bare/push/pop/list), or a force-free git push [-u] origin <branch> where <branch> is the current, non-default branch — checked live against the repo. Any shell metacharacter outside single quotes (chaining, pipes, redirects, $(…)/backticks even inside double quotes) disqualifies the whole command, so git commit -m "x" && anything never rides the grant while a quoted -m "fix: A & B" passes. Global git flags (-C, -c, --git-dir), foreign remotes, refspecs, --force*, stash drop/clear and every other verb stay prompted.

The commands the plugin cannot know — your test/metric command, your DATA.md datastore write path — get their grant at the gate that approves them: /flywheel:spec and /flywheel:process offer at sign-off (never write unasked) to append the matching narrow rule (e.g. Bash(npm test:*)) to the project's .claude/settings.json permissions.allow, committed with the spec/contract; /flywheel:sync flags signed pre-v0.28.0 specs/contracts that lack their rule as drift.

Progress toolbar, enforced (P56, v0.74.0)

While a .claude/flywheel/specs/<slug>.plan.md that the current branch touches (vs its base, or uncommitted) still has a task with no transition line, the final reply of each turn must open with <🟢|⏸️|🔴|🏁> <done>/<total> <bar> · ▶ <item> · «<what, in the owner's words>». scripts/toolbar.sh enforces it as two hooks: UserPromptSubmit injects the format and the live count (slug done/total, open task ids) as context every prompt, and Stop blocks (exit 2) a final reply whose first line is not the toolbar or whose total is not the plan's. Mid-turn notes are exempt. stop_hook_active never re-traps, and anything it cannot read is a no-op.

A shipped cycle says what it learned (P69, v0.83.0)

scripts/compound-due.sh is a Stop hook: a runs/<slug>/*.jsonl this branch touches that has a phase: ship line and no phase: compound line blocks the turn (exit 2). /flywheel:compound appends that line with entries: N; a cycle that proved nothing durable records entries: 0 with a reason. Before it, 14 of 16 shipped runs in this repo carried no compound line.

Feedback about flywheel reaches flywheel (P70, v0.83.0)

A lesson about the plugin, learned in a repo that only uses it, used to stay in that repo's ledger. When /flywheel:compound writes one outside this repo, it offers scripts/upstream-issue.sh, which renders the entry as a prefilled flywheel feedback issue URL (label flywheel-feedback) with only flywheel paths kept. Nothing is sent until a human reviews the form and submits it. The same form is open to anyone using the plugin. The flow-audit process reads the open issues as input and gives each one a disposition.

A delegated review says it started (P57, v0.75.0)

A review sent to another session (create_session) that posts nothing reads the same whether it found nothing, could not post, or is still running. skills/review/references/delegated-review.md is the child's prompt template: post a 🔎 Review started … fw-review-start comment on the PR first, through the GitHub MCP tools (the container has no gh), then post the findings as one review with inline comments, or a "no findings" comment. The delegation guard's REVIEW family asks when a delegated review prompt lacks fw-review-start, naming the template.

Mods (P72, v0.84.0+)

Claude Code mods ship from this marketplace as separate, opt-in plugins under mods/<name>/, each with its own version and tests (scripts/check-mods.sh).

Claude Code web (cloud sessions): marketplace plugins are not installed there, mods included. Load mods by folder instead, with CLAUDE_CODE_PLUGIN_DIRS, verified in a cloud container on CLI 2.1.289. In the environment's settings (cloud environment menu → Edit), add to the setup script git clone --depth 1 https://github.com/arazvan-ec/xmarks /opt/xmarks, and set the environment variable CLAUDE_CODE_PLUGIN_DIRS=/opt/xmarks/mods/resource-committee:/opt/xmarks/mods/big-brother-token (absolute paths, :-separated). New sessions load them. A project's own settings.json cannot set this variable. Step by step, and what each mod measures: docs/mods-in-the-cloud.md.

| resource-committee | Assigns every turn its model and effort: sonnet/medium by default, opus/high for judgment, sonnet/low for mechanical work, classified once per prompt by Haiku so the cache survives. /committee shows the decision or pins haiku/sonnet/opus/auto; /committee stats sums each session's tally. Subagents keep their own model.