Roles with boundaries
flywheel/stage_contracts.yaml defines checklists, exit gates, lanes,
and forbidden actions for each stage.
Free · Local-first · Built from Flywheel
A workflow harness for human + agent software delivery.
Base Protocol gives Flywheel a public front door: configured lanes, stage contracts, role files, local commands, and durable records for teams that want AI work to stay inspectable.
flywheel — zsh
Not another app. Not another subscription. Flywheel is a repo-shaped operating model: markdown for humans, YAML and JSON for tools, and shell commands for state you can inspect.
The Point
AI work gets better when the operating model is visible.
Chat is good for momentum. Repositories are good for memory. Flywheel puts the
repeatable parts of delivery in files: flywheel.yaml, stage prompts, role
contracts, process docs, backlog lanes, planning notes, approvals, observer reports,
and experience indexes.
The result is not a synthetic company or a productivity cult. It is a small local harness that makes stage ownership, evidence, forbidden actions, and next-state recommendations visible.
The Model
The folder is the source of truth.
Queues you can inspect
Engineering and architecture items move through intake,
ready, active, qa, done,
blocked, and archive.
Artifacts over transcripts
Plans, handoffs, observer notes, approvals, release records, and experience summaries land as markdown, YAML, and JSON.
Tool-agnostic by default
The human-facing ./fw router wraps stable shell tools while JSON output
gives agents a clean integration surface.
Inside The Harness
Plain files plus narrow commands.
Host paths are mapped in flywheel.yaml.
Use the default self-contained layout or remap backlog and artifact paths into an existing repository.
Stages launch from explicit rules.
stage_contracts.yaml records stage prompts, input and output lanes,
checklists, exit gates, and forbidden actions.
Backlog lanes are reviewable markdown.
./fw lanes reads configured domains and lane counts without mutating
state. ./fw move synchronizes file location, metadata, and history.
Cycle memory is written twice.
Observer closure produces a human markdown report and a structured JSON sidecar for experience indexing.
Risky work gets explicit approval records.
Approval, hook, plugin, validation, and doctor commands make local enforcement visible before the next move.
Context can project into other tools.
Export planning shows how Flywheel context would map into Codex, Claude, Cursor, or every configured target.
The Workflow
Six stages, one local memory.
Each stage launches from its own contract, reads explicit input lanes, and writes artifacts plus a next-state recommendation back to disk.
flywheel — stage: planning
// start with intent
Planning turns loose work into shaped backlog items.
The system captures goals, constraints, risks, and readiness signals before work enters a delivery lane.
$
./fw launch planning
Staff Directory
Names route work to real role contracts.
The names are lightweight handles over files in flywheel/roles. They
improve routing and handoff quality without overriding the stage contracts, process
docs, or local tools.
// principles
01
Local files first. Services are optional.
02
State movement should use local tools when practical, so lane placement and metadata stay synchronized.
03
Every handoff should carry evidence, risks, and a next-state recommendation.
04
Each completed cycle should leave observer records and experience data the next cycle can use.
The Artifact
Base Protocol is the front. Flywheel is the working system.
The repo contains prompts, role files, process docs, templates, lane validators, state movement tools, approval records, hook and plugin surfaces, observer traces, and export planning.
start here
$
git clone https://github.com/MattMatheus/Flywheel.git
$
cd Flywheel
$
./fw doctor
$
./fw lanes
$
./fw launch engineering
$
./fw move STORY-example active qa --reason "handoff ready"
$
./fw experience summarize
$
./fw export plan all
Read the Flywheel README →