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

                  
                  goal: Add password recovery
                
                  files:
                
                  - src/auth/service.ts
                
                  edit:
                
                  behavior:
                
                  - expired tokens are rejected
                
                  - valid tokens can only be
                
                  used once

YAMLLn 8, Col 1

maid validate

✓ Approved plan lock
✓ Red-phase evidence
✓ Declared file scope
✓ Structural contract
✓ Behavioral tests
✓ Independent review

HANDOFF READY

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

Machine-checkable contracts

A manifest is a deterministic, AST-level contract for the change — not prose an agent reinterprets.

Tamper-evident planning

Plan locks and genuine red-phase evidence mean an agent can't quietly rewrite the contract or fake a passing test.

Portable across agents

MAID governs the code your agents produce, and runs under Claude, Codex, Cursor, or any harness.

Evidence-backed handoff

Scope, structure, and behavior are verified before handoff — not self-reported as "done".

Proven, not just covered

Deep verification can delete a function's body and require your tests to fail — proof they exercise the code, not just execute a line. (Python, opt-in.)

Why MAID Runner

Plan drift

Agents deviate from the plan and change things you didn't ask for.

MAID's answer: Plan locks and scope enforcement keep work tightly aligned.

Test rewriting

Agents rewrite or delete tests instead of proving the fix.

MAID's answer: Red-phase evidence and behavioral tests prove the change works — and deep verification can knock out the code to confirm a test actually fails without it, so a gutted test can't pass.

Scope expansion

Agents touch extra files or introduce out-of-scope changes.

MAID's answer: Declared file scope and structural contracts prevent creep.

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.

Capabilities

Plan locks

An approved manifest lock becomes the contract for the work.

Red-phase evidence

Require failing tests (or equivalent evidence) before implementation.

Scope enforcement

Only declared files and operations are allowed.

Three-stream validation

Structural, behavioral, and implementation validation.

Independent review

A separate review step ensures quality and alignment.

Outcome learning

Capture results to continuously improve future work.

Works with your existing tools

Claude Code

Codex

Cursor

Windsurf

Generic

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

484 validated manifests

3698 passing tests

218 MAID validation command groups

Strict verification required before handoff

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

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.

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

# Windows PowerShell
> irm https://maidrunner.dev/install.ps1 | iex

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

Alternative installation methods

uv tool install maid-runner

pip install maid-runner

Build boldly. Verify honestly.

Explore MAID Runner