Skip to main content

MAID Runner

PyPI version Python Version License: MIT

A tool-agnostic validation framework and Python library for the Manifest-driven AI Development (MAID) methodology. MAID Runner validates that code artifacts align with declarative YAML manifests, ensuring architectural integrity in AI-assisted development. Integrates with ArchSpec for spec-to-code pipelines.

Watch the introductory video

Full AI Compiler workflow guide

Why MAID Runner?

LLMs generate code based on statistical likelihood, optimizing for "plausibility" rather than architectural soundness. Without intervention, this leads to "AI Slop" -- code that is syntactically valid but architecturally chaotic.

MAID Runner enforces three-stream validation:

  • Acceptance (WHAT): Immutable tests from specifications define system behavior
  • Structural (SKELETON): AST-level verification that code matches manifest contracts
  • Unit (HOW): Implementation-level tests verify internal correctness

This transforms AI from a "Junior Developer" requiring reactive code review into a "Stochastic Compiler" that translates rigid specifications into implementation details.

Full philosophy documentation

Supported Languages

Language Extensions Parser Key Features
Python .py AST (built-in) Classes, functions, methods, attributes, type hints, async/await, decorators
TypeScript/JS .ts, .tsx, .js, .jsx tree-sitter Classes, interfaces, type aliases, enums, namespaces, generics, JSX/TSX
Svelte .svelte tree-sitter Components, props, exports, script blocks, reactive statements

Quick Start

# Install
pip install maid-runner  # or: uv pip install maid-runner

# Initialize MAID in your project
maid init

# Interactive guide
maid howto --section quickstart

Installation

/plugin marketplace add aidrivencoder/claude-plugins
/plugin install maid-runner@aidrivencoder

From PyPI

pip install maid-runner              # Python only (core — no tree-sitter)
pip install maid-runner[all]         # All language support (TypeScript, Svelte)
pip install maid-runner[typescript]  # TypeScript/JS only
pip install maid-runner[watch]       # File watching for TDD mode

Multi-Tool Support

maid init                        # Claude Code (default)
maid init --tool cursor          # Cursor IDE
maid init --tool windsurf        # Windsurf IDE
maid init --tool generic         # Generic MAID.md

CLI Reference

Command Purpose Key Options
maid validate [manifest] Validate manifest against code --mode behavioral|implementation, --no-chain, --coherence, --json, --watch, --watch-all
maid test Run validation commands from manifests --manifest <path>, --watch, --watch-all, --fail-fast, --json
maid snapshot <file> Generate manifest from existing code --output-dir, --force
maid snapshot-system Aggregate all active manifests --output, --manifest-dir
maid manifests <file> List manifests referencing a file --manifest-dir, --quiet
maid files Show file tracking status --manifest-dir, --quiet
maid graph Knowledge graph operations query, export, analyze
maid coherence Run coherence checks --checks, --exclude, --json
maid schema Display manifest JSON Schema
maid init Initialize MAID in project --tool claude|cursor|windsurf|generic|auto
maid howto Interactive methodology guide --section intro|principles|workflow|quickstart|patterns|commands|troubleshooting
maid manifest create <file> Create manifest for a file --goal, --artifacts, --dry-run
maid chain log Show manifest event log --until-seq N, --version-tag TAG, --active, --json
maid chain replay Preview effective artifacts at a point in time --until-seq N, --version-tag TAG, --json

Exit codes: 0 = success, 1 = validation failure, 2 = usage error. Use --quiet for automation.

Run maid howto --section commands for detailed usage and examples.

Common Workflows

# Validate all manifests (chains enabled by default)
maid validate

# Validate a single manifest
maid validate manifests/add-auth.manifest.yaml

# Validate without chain merging
maid validate manifests/add-auth.manifest.yaml --no-chain

# Validate behavioral tests
maid validate manifests/add-auth.manifest.yaml --mode behavioral

# Validate with coherence checks
maid validate --coherence

# TDD watch mode (single manifest)
maid test --manifest manifests/add-auth.manifest.yaml --watch

# Multi-manifest watch (entire codebase)
maid test --watch-all

# Run all validation commands
maid test

# JSON output for CI/CD
maid validate --json

File Tracking

When validating with manifest chains (default), MAID Runner reports file compliance status:

  • UNDECLARED: Files not in any manifest (no audit trail)
  • REGISTERED: Files tracked but incomplete (missing artifacts/tests)
  • TRACKED: Files with full MAID compliance

Manifest Structure (v2 YAML)

schema: "2"
goal: "Implement email validation"
type: feature
files:
  create:
    - path: validators/email_validator.py
      artifacts:
        - kind: class
          name: EmailValidator
        - kind: method
          name: validate
          of: EmailValidator
          args:
            - name: email
              type: str
          returns: bool
  read:
    - tests/test_email_validation.py
validate:
  - pytest tests/test_email_validation.py -v

V1 JSON manifests are auto-converted when loaded.

Validation Modes

Mode Files Behavior
Strict files.create Implementation must EXACTLY match declared artifacts
Permissive files.edit Implementation must CONTAIN declared artifacts

Artifact Kinds

Common: class, function, method, attribute

TypeScript-specific: interface, type, enum, namespace

Manifest Event Log

MAID Runner v2.4.0 introduces an event-log system for tracking manifest history:

schema: "2"
goal: "Add user authentication"
type: feature
sequence_number: 42         # optional — deterministic ordering
version_tag: "v2.4.0"       # optional — release label

Inspect the event log:

maid chain log                    # Full history (includes superseded)
maid chain log --until-seq 10     # Up to sequence 10
maid chain log --version-tag v2.4.0 --json
maid chain log --active           # Active manifests only

Preview artifact state at a point in time:

maid chain replay --until-seq 10 --json
maid chain replay --version-tag v2.4.0

The event log provides deterministic ordering via sequence_number (falls back to created), includes superseded manifests in the historical record, and supports point-in-time queries through event_log_until() and replay_until() APIs.

Development Workflow

Phase 1: Goal Definition

Define the high-level feature or bug fix.

Phase 2: Planning Loop

  1. Create manifest: maid manifest create <file> --goal "Description"
  2. Create behavioral tests in tests/
  3. Validate: maid validate <manifest> --mode behavioral
  4. Iterate until validation passes

Phase 3: Implementation Loop

  1. Implement code per manifest
  2. Validate: maid validate <manifest>
  3. Run tests: maid test --manifest <manifest>
  4. Iterate until all tests pass

Phase 4: Integration

Verify complete chain: maid validate and maid test pass for all active manifests.

Library API

MAID Runner provides a Python library API for direct integration with tools, CI/CD, and custom scripts.

Basic Validation

from maid_runner import validate, validate_all

# Validate a single manifest
result = validate("manifests/add-auth.manifest.yaml")
if result.success:
    print("All checks passed")
else:
    for error in result.errors:
        print(f"{error.code.value}: {error.message}")

# Validate all manifests in directory
batch = validate_all("manifests/")
print(f"{batch.passed}/{batch.total_manifests} passed")

Manifest Chain Operations

from maid_runner import ManifestChain

chain = ManifestChain("manifests/")

for m in chain.active_manifests():
    print(f"{m.slug}: {m.goal}")

artifacts = chain.merged_artifacts_for("src/auth/service.py")

Loading and Saving Manifests

from maid_runner import load_manifest, save_manifest

manifest = load_manifest("manifests/add-auth.manifest.yaml")  # YAML v2 or JSON v1
print(manifest.goal)
save_manifest(manifest, "manifests/copy.manifest.yaml")

Snapshot Generation

from maid_runner import generate_snapshot

manifest = generate_snapshot("src/auth/service.py")
print(f"Found {len(manifest.all_file_specs[0].artifacts)} artifacts")

JSON Output for Tool Integration

from maid_runner import validate

result = validate("manifests/add-auth.manifest.yaml")
print(result.to_json())  # Structured JSON output

Custom Validator Registration

from maid_runner import ValidatorRegistry, BaseValidator, CollectionResult

class GoValidator(BaseValidator):
    @classmethod
    def supported_extensions(cls):
        return (".go",)

    def collect_implementation_artifacts(self, source, file_path):
        return CollectionResult(artifacts=[], language="go", file_path=str(file_path))

    def collect_behavioral_artifacts(self, source, file_path):
        return CollectionResult(artifacts=[], language="go", file_path=str(file_path))

ValidatorRegistry.register(GoValidator)

MAID Ecosystem

Tool Purpose
MAID Agents Automated workflow orchestration using Claude Code agents
MAID Runner MCP MCP server exposing validation to AI agents
MAID LSP Language Server Protocol for real-time IDE validation
MAID for VS Code VS Code/Cursor extension with manifest explorer and diagnostics
Claude Plugins Plugin marketplace including MAID Runner
ArchSpec AI-powered spec generation with MAID manifest export

Development Setup

# Install dependencies
uv sync
uv sync --group dev

# Run tests
uv run python -m pytest tests/ -v

# Code quality
make format      # Auto-fix formatting
make lint        # Check style
make type-check  # Type checking

Project Structure

maid-runner/
├── docs/                    # Documentation
├── manifests/               # Task manifests (YAML v2)
├── tests/
│   ├── core/                # Core module tests
│   ├── validators/          # Validator tests
│   ├── coherence/           # Coherence check tests
│   ├── graph/               # Knowledge graph tests
│   ├── compat/              # Compatibility tests
│   ├── cli/                 # CLI tests
│   ├── integration/         # Integration tests
│   └── e2e/                 # End-to-end tests
├── maid_runner/
│   ├── core/                # Manifest loading, validation, chain, types
│   ├── validators/          # Language-specific artifact collectors
│   ├── graph/               # Knowledge graph (manifest relationships)
│   ├── coherence/           # Architectural coherence checks
│   ├── compat/              # V1 JSON backward compatibility
│   ├── cli/commands/        # CLI command modules
│   └── schemas/             # JSON Schema (v1, v2)
├── examples/                # Example scripts
└── .claude/                 # Claude Code configuration

Testing

uv run python -m pytest tests/ -v                    # All tests
uv run python -m pytest tests/core/ -v               # Core tests
uv run python -m pytest tests/validators/ -v          # Validator tests
maid test                                            # MAID validation commands

Requirements

  • Python 3.10+
  • Core: jsonschema, pyyaml
  • Optional: tree-sitter, tree-sitter-typescript (TypeScript/JS support), tree-sitter-svelte (Svelte support)
  • Dev: black, ruff, mypy, pytest

Contributing

This project dogfoods MAID methodology. All changes require:

  1. A manifest in manifests/
  2. Behavioral tests in tests/
  3. Passing structural validation
  4. Passing behavioral tests

See CONTRIBUTING.md and CLAUDE.md for guidelines.

License

MIT License. See LICENSE for details.

Metadata

Release files for maid-runner 2.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maid-runner 2.5.2
File Size Uploaded Provenance Actions
maid_runner-2.5.2.tar.gz 118.3 kB With provenance Details for maid_runner-2.5.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maid-runner 2.5.2
File Interpreter ABI Platform Actions
maid_runner-2.5.2-py3-none-any.whl Python 3 none any Details for maid_runner-2.5.2-py3-none-any.whl

Total release size: 266.3 kB

Release files / maid_runner-2.5.2.tar.gz

Download URL maid_runner-2.5.2.tar.gz
Size 118.3 kB
Tags Source
SHA-256 checksum
How to use checksums
cd82e3eb6dbf7f0a9ba18ac94657c0e697f8d885614f6a6d11539d88e521f61d
BLAKE2b-256 checksum
How to use checksums
0300579d97d3c052337a1071fdab8f09e2b64eabcce8ae0cc2a290a6cfcddc65
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 6, 2026.

Transparency log

Release files / maid_runner-2.5.2-py3-none-any.whl

Download URL maid_runner-2.5.2-py3-none-any.whl
Size 148.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a8ee649364af29c284a08b0589417e18bb87c59e306d6e8479904b20ddfdd52a
BLAKE2b-256 checksum
How to use checksums
93c38ada63046bad0a454b9663be1220ea2b54badefddc12b8fa2864b8e030e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 6, 2026.

Transparency log

Security for maid-runner 2.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for maid_runner-2.5.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.5.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page