A specification is useful because it defines what a system should mean and how its pieces should fit together.

But a specification by itself does not give an AI a repository-level operating model.

That is the purpose of the AI Flywheel Framework.

The framework is the installable layer that turns the AI Flywheel methodology into a concrete .flywheel structure inside a repository.

Why the framework exists

The AI Flywheel specification defines the lifecycle, governance model, learning model, and boundaries.

The framework answers a different question:

What does an AI need inside a real repository to operate that model consistently?

Without a framework, every repository could invent its own file structure, startup procedure, state representation, evidence records, mission format, and lifecycle semantics.

That would make the methodology difficult to operate, test, or evolve.

The framework provides a canonical starting point.

The manifest is the boundary

One of the most important design decisions is that an AI operator does not begin by wandering through the repository trying to infer how the Flywheel works.

It starts with:

.flywheel/manifest.yaml

The manifest defines the authoritative operating-model boundary.

It identifies canonical locations, required files, and the exact entrypoint the AI must follow.

That makes startup deterministic.

The operator should not substitute its own traversal order, guess at an entrypoint, or search for an alternative if the manifest is invalid. A missing or broken manifest is an operating-model defect.

That might sound strict, but the strictness is intentional. Agentic systems become difficult to reason about when discovery behavior is implicit.

State is explicit

The framework also keeps operating state explicit in:

.flywheel/state.yaml

That state identifies things such as the active mission, active goal, active execution, current lifecycle stage, blockers, and readiness.

This is important because an AI workflow should not depend on conversational memory to know what it is doing.

If the repository is the durable operating environment, the current operating state should live in the repository too.

Bootstrap before self-hosting

The framework begins in a manually operable state.

Its default first mission is designed to onboard the repository, capture human decisions, populate the operating model, and then design the repository-specific tools that will support future Flywheel execution.

That sequence matters.

It avoids a common failure mode in AI tooling: assuming the implementation language, architecture, commands, and automation model before the repository owner has actually made those decisions.

The framework deliberately does not prescribe a programming language, runtime, testing framework, or CLI.

Those are implementation choices.

The framework provides the operating contract within which those choices are made.

What gets installed

The canonical framework installs under .flywheel/.

A successful initial installation is intentionally narrow: it changes the operating-model directory and does not automatically start onboarding or execute a mission.

That separation between installation and operation is useful because writing files into a repository is itself a governed action.

An installer should establish the framework faithfully. It should not silently begin doing repository work simply because installation succeeded.

Installation is treated as a supply-chain operation

The framework installer follows a verification-first model.

For a published release, it resolves a specific package, verifies its SHA-256 checksum, validates archive paths, checks the framework version in the package manifest, stages the files, verifies the staged content, and only then publishes the installation into the repository.

It also records installation provenance in:

.flywheel/installation.yaml

That record provides evidence about what version was installed and from which artifact.

This is the kind of detail that becomes increasingly important when AI systems can modify repository state. Convenience cannot be the only design goal.

A practical workflow

A repository adopting the framework might follow this path:

  1. Install the canonical .flywheel structure.
  2. Read .flywheel/manifest.yaml.
  3. Follow the manifest-defined entrypoint.
  4. Start the bootstrap mission.
  5. Capture repository-owner decisions and constraints.
  6. Create goals for building repository-specific Flywheel capabilities.
  7. Execute those goals through the lifecycle.
  8. Persist evidence and validated learning.
  9. Eventually operate the framework with repository-specific tooling instead of manual steps.

The important point is that the framework supports the transition from manually guided operation to self-hosted operation without changing the underlying methodology.

Framework versus CLI

The framework is intentionally implementation-neutral.

A CLI may install, inspect, validate, or operate the framework, but the CLI is not the framework itself.

That distinction keeps the architecture clean:

  • the specification defines the methodology;
  • the framework provides the canonical installed operating model;
  • a CLI or language-specific implementation provides tooling for operating it;
  • repository-specific capabilities perform the actual work.

Keeping those responsibilities separate prevents one implementation from accidentally becoming the definition of the methodology.

Why the framework is useful

The framework makes several things explicit that are often implicit in AI-assisted development:

  • where operational state lives;
  • how an AI starts work;
  • which files are authoritative;
  • how missions and goals are represented;
  • where evidence and learning are persisted;
  • how governance and lifecycle behavior are communicated;
  • what minimum behavior repository-specific tools must preserve.

That explicitness is valuable because autonomous execution magnifies ambiguity.

A human can often work around a vague process by relying on experience. An AI will also work around ambiguity—but it may do so differently every time.

The framework reduces that freedom where consistency is more valuable than improvisation.

The larger goal

The framework is not intended to be a giant universal automation system.

Its job is smaller and more foundational: provide enough structure for an AI to understand its operating model, onboard a repository, execute governed work, capture evidence, and improve the reusable system around that work.

The specification defines the Flywheel.

The framework gives it somewhere concrete to run.