A tool-agnostic validation framework for the Manifest-driven AI Development (MAID) methodology. MAID Runner validates that code artifacts align with their declarative manifests, ensuring architectural integrity in AI-assisted development.

📹 Watch the introductory video

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 dual-constraint validation:

• Behavioral (Coordinate A): Code must pass the test suite
• Structural (Coordinate B): Code must adhere to a pre-designed JSON manifest

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

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

# Initialize MAID in your project
maid init

# Interactive guide
maid howto --section quickstart

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

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

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

Exit codes: 0 = success, 1 = failure. Use --quiet for automation.

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

# Validate implementation (default mode)
maid validate manifests/task-013.manifest.json --use-manifest-chain

# Validate behavioral tests
maid validate manifests/task-013.manifest.json --validation-mode behavioral

# TDD watch mode (single manifest)
maid test --manifest manifests/task-013.manifest.json --watch

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

# Run all validation commands
maid test

When using --use-manifest-chain, 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

{
  "goal": "Implement email validation",
  "taskType": "create",
  "supersedes": [],
  "creatableFiles": ["validators/email_validator.py"],
  "editableFiles": [],
  "readonlyFiles": ["tests/test_email_validation.py"],
  "expectedArtifacts": {
    "file": "validators/email_validator.py",
    "contains": [
      {"type": "class", "name": "EmailValidator"},
      {
        "type": "function",
        "name": "validate",
        "class": "EmailValidator",
        "parameters": [{"name": "email", "type": "str"}],
        "returns": "bool"
      }
    ]
  },
  "validationCommand": ["pytest", "tests/test_email_validation.py", "-v"]
}

Common: class, function, attribute

TypeScript-specific: interface, type, enum, namespace

Define the high-level feature or bug fix.

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

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

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

from maid_runner import (
    validate_schema,
    validate_with_ast,
    discover_related_manifests,
    generate_snapshot,
    AlignmentError,
)

# Validate a manifest
validate_schema(manifest_data, schema_path)
validate_with_ast(manifest_data, file_path, use_manifest_chain=True)

# Generate snapshot manifest
generate_snapshot("path/to/file.py", output_dir="manifests")

# 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

maid-runner/
├── docs/                    # Documentation
├── manifests/               # Task manifests (chronological)
├── tests/                   # Test suite
├── maid_runner/
│   ├── cli/                 # CLI modules
│   └── validators/          # Core validation logic
├── examples/                # Example scripts
└── .claude/                 # Claude Code configuration

uv run python -m pytest tests/ -v                    # All tests
uv run python -m pytest tests/test_task_*.py -v      # Task-specific tests
maid test                                            # MAID validation commands

• Python 3.10+
• Core: jsonschema, pytest, tree-sitter, tree-sitter-typescript
• Dev: black, ruff, mypy

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.

MIT License. See LICENSE for details.