The problem
AI-assisted work can repeat tasks without accumulating verified learning or clearly governing what happens next.
Generating a sequence of AI-assisted deliverables does not by itself demonstrate improvement. Without preserved evidence, teams cannot reliably distinguish a successful adaptation from a repeated assumption.
The challenge is to make learning reviewable and cumulative while retaining control over decisions that affect future executions.
The solution
Establish a governed operating model in which AI-assisted work produces accountable decisions, measurable outcomes, and reusable learning rather than isolated outputs.
The specification defines the responsibilities and records required at each stage of the Flywheel, including the evidence needed to assess outcomes before changing the way work is performed.
Governance provides the decision boundaries: what can proceed, what requires review, and what must be validated before an improvement becomes part of future execution.
Who it's for
Teams designing evidence-driven, repeatable AI-assisted engineering processes.
It is intended for engineering teams, repository owners, and AI operators who need a repeatable process with explicit accountability.
It can also serve as a reference for evaluating whether an existing AI-assisted workflow captures trustworthy evidence, incorporates human decisions, and improves over time.
How it works
Key capabilities and concepts. See the project documentation or source code for implementation details.
Defines an execution-to-evidence-to-improvement lifecycle
Start with a defined mission and goal so each execution has an explicit purpose and expected outcome.
Observe what happened and capture durable evidence that later evaluation can inspect.
Distinguishes validated learning from unverified observations
Evaluate outcomes, classify the observations, and decide whether an adjustment is justified.
An observed result is not automatically a validated improvement; the model requires a separate assessment before reuse.
Establishes governance and traceability for continued operation
Record decisions, approvals, and the evidence supporting the selected change.
Only validated learning should influence later work, keeping the process auditable and avoiding unexamined repetition.
Design decisions that matter
- Treat evidence as distinct from assumption.
An observation can suggest a problem or improvement, but it does not prove the proposed change is effective.
Validation creates a deliberate boundary between collecting evidence and adopting new behavior.
- Make governance and traceability part of the operating model.
Lifecycle transitions and changes need traceable reasons, evidence, and appropriate human authority.
This helps reviewers understand not just what changed, but why a particular change was allowed.
- Define the normative rules separately from implementation.
The specification establishes the contract; the framework and CLIs provide ways to operate against it.
Separating rules from tooling allows different implementations to share the same expectations without prescribing one runtime or interface.
Explore the implementation
The specification repository and its published documentation are authoritative for current requirements and revisions.
The specification is the reference for the operating model; implementation details and command behavior belong to the associated Framework and CLI repositories.
Review the published specification for the current lifecycle rules, governance requirements, and revision history.
Related articles
Engineering context and lessons behind this project.
AI Flywheel Spec – From Agent Loop to Compounding System ↗
Why evidence-driven validation and reusable learning distinguish the Flywheel from a repeating agent loop.
From Specification to System: How the AI Flywheel Became Four Projects ↗
How the Specification, Framework, Testing, and CLI responsibilities evolved into separate projects.