MAID Runner

Manifest-driven AI development

Make AI coding follow the plan.

MAID Runner is a deterministic CLI and workflow for Manifest-driven AI Development. Give coding agents an approved contract, then verify scope, red evidence, structure, behavior, and implementation before handoff.

Install MAID Runner Read the docs

Open source MIT licensed Python, TypeScript, JavaScript, Svelte

manifest.yaml
1 goal: Add password recovery
2 files:
3 - src/auth/service.ts
4 edit:
5 behavior:
6 - expired tokens are rejected
7 - valid tokens can only be
8 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

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.

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

1

Plan

Write a clear manifest.

2

Review

Human review for clarity and feasibility.

3

Lock

Create an approved plan lock.

4

Prove red

Demonstrate failing tests before changes.

5

Implement

Make the minimal change to satisfy the plan.

6

Verify

Validate structure, behavior, and scope.

7

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

Quick start

Get MAID Runner up and running in minutes. Works on macOS, Linux, and Windows.

See the docs for detailed guides
terminal 
$ pip install maid-runner
$ maid init
$ maid howto --section quickstart
✓ ready to write a verifiable change

Build boldly. Verify honestly.

Explore MAID Runner