Manifest-driven AI development

Don't just trust AI code. Verify it.

MAID Runner turns an approved plan into a machine-checkable contract, then proves the agent stayed in scope, wrote real failing tests first, and shipped exactly what was validated — under Claude, Codex, Cursor, or any agent.

Install MAID Runner Read the docs

Open source MIT licensed Python, TypeScript, JavaScript, Svelte

manifest.yaml

schema: "2"
goal: Add password recovery
type: feature
files:
  edit:
    - path: src/auth/service.py
      artifacts:
        - kind: function
          name: reset_password
          args:
            - name: email
              type: str
          returns: bool
validate:
  - pytest tests/test_reset.py

YAMLLn 15, Col 1

maid verify

$ maid verify --summary --since main
VERIFY: FAIL (1 blocking, 0 warnings unique / 0 raw, 4 passed, 0 skipped)
BLOCKING (1):
  FAIL file_tracking
    Undeclared (1):
      src/auth/session.py
    Tracked (1):
      src/auth/service.py
PASSED (4): schema, behavioral, implementation, coherence
$ rm src/auth/session.py
$ maid verify --summary --since main
VERIFY: PASS (0 blocking, 0 warnings unique / 0 raw, 8 passed, 0 skipped)
PASSED (8): schema, behavioral, implementation, coherence, file_tracking, worktree_scope, changed_scope, tests

HANDOFF READY

Why MAID Runner

Governs the artifacts your agents produce — not just the prompts they follow.

Plan drift

Agents deviate from the plan and touch files you didn't ask for.

MAID's answer: An approved plan lock becomes the contract an agent can't quietly rewrite; only declared files and operations are allowed.

Test rewriting

Agents rewrite or delete tests instead of proving the fix.

MAID's answer: Tests must fail before the change (or produce equivalent red evidence), and behavioral tests prove it works. Deep verification can delete a function's body and require your tests to fail, so a gutted test can't pass. (Knockout: Python, opt-in.)

Self-reported "done"

Agents say the work is finished without proof.

MAID's answer: Structure, behavior, and scope are verified, then independently reviewed before handoff.

Rules that live in one tool

Prompt rules don't travel between agents.

MAID's answer: The manifest is the contract, so MAID runs the same under Claude Code, Codex, Cursor, Windsurf, or any harness: a deterministic, AST-level contract, not prose an agent reinterprets.

Works with your existing tools

Claude Code

Codex

Cursor

Windsurf

Generic

From plan to evidence

Plan

Write a clear manifest.

Review

Human review for clarity and feasibility.

Lock

Create an approved plan lock.

Prove red

Demonstrate failing tests before changes.

Implement

Make the minimal change to satisfy the plan.

Verify

Validate structure, behavior, and scope.

Learn

Capture outcomes to improve future work.

Quick start

One command installs MAID Runner on macOS, Linux, or Windows—no existing Python setup required.

See the docs for detailed guides

terminal

macOS / Linux

curl -LsSf https://maidrunner.dev/install.sh | sh

Installs uv if it is missing, then MAID Runner as a uv tool, and adds uv's tool directory to your PATH. Read install.sh before you run it.

Pin a release: curl -LsSf https://maidrunner.dev/install.sh | sh -s -- --version <version>

Windows PowerShell

irm https://maidrunner.dev/install.ps1 | iex

Installs uv if it is missing, then MAID Runner as a uv tool, and adds uv's tool directory to your PATH. Read install.ps1 before you run it.

Pin a release: & ([scriptblock]::Create((irm https://maidrunner.dev/install.ps1))) -Version <version>

uv / pip

uv tool install maid-runner

pip install maid-runner

Already manage Python tools? Install the package from PyPI directly.

Then, in your project:

$ maid init
$ maid howto --section quickstart
✓ ready to write a verifiable change

MAID in practice

The tool is developed under the rules it enforces.

MAID Runner is not only a workflow we recommend. It is the workflow used to build and maintain the tools themselves.

Every new change can be planned, reviewed, locked, implemented, independently checked, and preserved with its validation evidence.

MAID Runner

The framework dogfoods itself.

MAID Runner develops through the same manifest-driven process it provides to other repositories. Its feature work, fixes, releases, documentation, and even this website are governed by MAID contracts.

manifest → plan lock → red evidence → implementation → review → outcome

706 validated manifests

5587 passing tests

312 MAID validation command groups

Strict verification required before handoff

Numbers as of October 8, 2026, from maid validate, the test suite, and maid test.

Explore the MAID Runner manifests

MAID Validator for C#

A separate plugin developed under MAID.

The open-source C# validator extends MAID Runner with structural validation for C# code. Its development uses reviewed manifests, plan locks, genuine red-phase evidence, independent implementation review, and recorded Outcomes.

7 published MAID manifests

116 passing tests

Python 3.10–3.14 verified package discovery

Numbers as of August 4, 2026.

View the C# validator on GitHub

Private production projects

Used beyond demonstration repositories.

MAID Runner is also used across active client and internal software projects, including established brownfield systems and newly developed products.

Because those repositories contain private business and client code, their names and implementation details are not published. Their use of MAID includes:

scoped feature and maintenance work;
plan review before implementation;
test-driven changes with red evidence;
independent AI-assisted implementation review;
evidence-backed handoff before merge or release.

Real projects. Real constraints. Private by design.

Build boldly. Verify honestly.

Explore MAID Runner