01
Define the contract
Epics map the larger goal. Child manifests declare behavior, files, artifacts, dependencies, and shortcuts the agent must avoid.
Free workflow guide · Open-source MAID Runner
Prepared autonomy for AI coding agents.
Plan work as verifiable contracts, let Codex or Claude keep moving, and require every completed change to prove itself.
Contract → validation gates → verified implementation
Manifest-driven planning
Codex Goal mode
Claude & Cursor compatible
Deterministic done gates
The core idea
Plan now. Execute when capacity is available.
I prepare implementation-sized work before asking an agent to code. When the opportunity arrives, the agent receives a queue of bounded contracts instead of a vague backlog.
02
Keep the work moving
Codex Goal mode can progress through approved child manifests one at a time while preserving the completion criteria.
03
Make “done” prove itself
Red evidence, plan locks, tests, structural validation, scope checks, review, and Outcomes create an auditable finish line.
Codex keeps the work moving. MAID keeps it honest.
From idea to evidence
A development queue made of contracts
An epic is never handed directly to an implementation agent. It is split into small child manifests, and one approved child becomes the active contract.
EpicMap the larger outcome and dependencies
Child draftsBreak the work into implementation-sized units
Red + reviewProve behavior is missing and harden the plan
Active manifestLock, promote, and implement within scope
OutcomeRecord validation, review, and reusable lessons
Three-stream validation
One weak check is easy for an agent to game.
MAID combines complementary forms of evidence. Structural validation alone does not prove correctness, and tests alone may not protect the intended architecture.
WHAT
Behavioral tests describe what users and systems must be able to observe.
SKELETON
Manifest validation checks declared files, components, interfaces, signatures, and architectural shape.
HOW
Unit, integration, type, build, browser, and other project checks protect correctness and regressions.
How I use it
Prepared work meets persistent execution.
1
Prepare ahead
I define epics and child drafts while the product context is fresh.
2
Make children implementation-ready
Behavioral tests, red evidence, plan review, and approval turn planning inventory into executable contracts.
3
Start a persistent goal
Codex processes ready manifests in dependency order, one bounded cycle at a time.
4
Close the evidence loop
Validation, independent review, Outcome capture, and recall improve the next plan.
Reusable Codex goal
/goal Process every approved, implementation-ready MAID child manifest in dependency order, one at a time. For each child: confirm red evidence and plan lock; promote through MAID; implement only within declared scope; run tests and implementation validation; perform review; fix valid findings; capture an evidence-backed Outcome; then continue. Pause for ambiguity, missing authority, security or privacy risk, scope violations, or a failed gate that cannot be resolved honestly. Never weaken tests, hide failures, or commit and push without explicit approval.
Responsible autonomy
What “almost autonomous” actually means
Starting a long-running goal does not broaden an agent’s permissions. It keeps the work progressing inside the same sandbox, scope, and approval boundaries.
The agent can continue
- Selecting the next approved child
- Running tests and validation
- Making in-scope code changes
- Iterating on honest implementation failures
- Reviewing and recording evidence
The agent must pause
- Requirements are materially ambiguous
- The implementation needs undeclared files
- Security or private data may be affected
- The contract itself must legitimately change
- Commit, push, deploy, or new authority is required
Free PDF guide
Prepared Autonomy
Download the complete visual workflow for using MAID Runner with Codex Goals—and optionally Claude Code and Cursor. The guide is freely shareable and does not require an email address.
PDF · No email required · Freely shareable
Want more implementation help?
Join the First-Run Companion early-access list.
The guide explains the system. I’m building a guided companion for the reader who wants help crossing from “this makes sense” to completing a first bounded MAID change.
- A first-run roadmap
- Task-selection worksheet
- Copy-ready prompts for Codex, Claude, and Cursor
- An annotated manifest lifecycle
- Promotion and completion checklists
- Practical failure diagnostics
By subscribing, you agree to receive MAID implementation guidance and product updates. Unsubscribe anytime. See the Privacy Policy.
Questions
Before you try MAID
Start with one bounded feature or bug fix. Let the first run teach you where contracts help most in your codebase.
Is MAID a coding agent?
No. MAID Runner is tool-agnostic validation infrastructure. Codex, Claude Code, Cursor, Windsurf, or another agent can work against the same manifest contract.
Does passing MAID validation prove the code is correct?
No single gate can do that. MAID combines behavioral tests, structural validation, implementation checks, scope enforcement, and review to create stronger evidence.
Do I have to automate an entire backlog?
No. Begin with one implementation-sized child manifest. Prepared queues become useful only after the individual contract cycle is trustworthy.
Is the PDF really ungated?
Yes. The workflow guide is freely downloadable. Email is optional and only for First-Run Companion early access and future MAID guidance.
Prepared autonomy is not unlimited autonomy.
Give your coding agent a persistent objective, a narrow contract, and a finish line backed by evidence.
MAID Runner is an independent open-source project and is not affiliated with OpenAI, Anthropic, or Cursor.