maid-runner 2.13.0

Tool-agnostic validation framework for the Manifest-driven AI Development (MAID) methodology. Validates that code artifacts align with declarative manifests.

MAID Runner

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; React and Angular through TypeScript-backed parsing
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

Claude Code Plugin (Recommended)

/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

Repo-Level Claude Install

Use maid init --tool claude inside shared repositories as a repo-level Claude install for the MAID-only Claude skills, implementation-review agent, and marked CLAUDE.md guidance. The .claude/skills source payload includes the current MAID workflow skills for planning, plan review, implementation, implementation review, evolution, auditing, and incident logging.

CLI Reference

Command	Purpose	Key Options
maid validate [manifest]	Validate manifest against code	--mode schema|behavioral|implementation, --no-chain, --coherence, --file-tracking, --worktree-scope, --changed-scope, --json, --watch, --watch-all
maid test	Run validation commands from manifests	--manifest <path>, --watch, --watch-all, --fail-fast, --json
maid verify	Run the combined done gate	--strict, --advisory, --worktree-scope, --changed-scope, --no-changed-scope, --since, --base-ref, --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 audit supersessions	Audit supersession artifact preservation	--manifest-dir, --seal, --unseal, --lock, --json, --quiet
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
maid serve	Run a long-lived validator daemon over a Unix socket	--socket, --pidfile, --project-root, --client-timeout

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

# Branch handoff gate for humans, CI, and AI agents
maid verify --base-ref <parent-branch>

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

# Audit supersession drops and seal current legacy drops
maid audit supersessions --manifest-dir manifests --json
maid audit supersessions --manifest-dir manifests --seal

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

Changed-Scope Handoff Gate

maid verify runs changed-scope by default. Use it at branch handoff, review, and CI boundaries to close the loophole where a file changed during the task is listed only under files.read after the edit has already been committed. Callers must opt out explicitly with --no-changed-scope.

Recommended branch review command:

maid verify --base-ref <parent-branch>

Use --base-ref for stacked branches because MAID compares from git merge-base <parent-branch> HEAD to the current working tree. Use --since <commit-ish> when the exact task baseline is known:

maid validate --changed-scope --since <task-start-commit>
maid verify --since <task-start-commit>

The baseline can also be recorded in active manifests:

metadata:
  maid_task_base: <task-start-commit>

When maid verify runs without --since, --base-ref, or an unambiguous metadata.maid_task_base, MAID fails closed with E115 instead of guessing main, master, dev, development, or a remote branch. Git does not retain a reliable branch-origin fact after rebases and merges, and a default commit count can miss task changes, so the baseline must be real evidence supplied by the caller or manifest. files.read never grants write permission; changed source files must be declared in files.create, files.edit, or files.delete. Use --include-tests when the handoff should also enforce changed test files.

Use --worktree-scope for fast live checks of uncommitted local changes. Use maid verify for branch handoff because changed-scope checks committed, staged, unstaged, and untracked files since the task baseline by default. Use maid validate --changed-scope only when you want the lower-level validate command to run the same gate explicitly.

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

Angular TypeScript Boundary

Angular source files are supported as TypeScript files. MAID Runner collects decorated classes, fields, methods, and signal-style input() / output() fields through TypeScriptValidator; Angular decorator names and decorator metadata are not public MAID artifacts.

Required-import validation uses the same TypeScript import scanner for Angular standalone component imports and lazy import() route modules. Third-party imports such as @angular/core remain package imports and do not satisfy project-local required imports.

maid snapshot tracks literal Angular templateUrl, styleUrl, and styleUrls companion files in files.read when those files exist. Template HTML and CSS/SCSS contents are tracked as file boundaries, not parsed into Angular artifacts.

React TypeScript Boundary

React .tsx and .jsx files are supported through TypeScriptValidator. MAID Runner collects ordinary TypeScript artifacts such as function components, typed const components, custom hooks, provider functions, props interfaces, and props type aliases. It also recognizes common inline wrapper exports using memo, React.memo, forwardRef, React.forwardRef, and anonymous default-exported arrow components as function artifacts.

Required-import validation uses TypeScript import identity for React tests and components, including Testing Library test files, barrel imports, React.lazy(() => import(...)), path aliases from tsconfig.json, and local CSS module imports. Package imports such as react, react-dom, and @testing-library/* remain external package imports and do not satisfy project-local required imports.

maid snapshot tracks existing relative style and static asset imports from React TSX/JSX files in files.read, including CSS modules, side-effect stylesheets, SVGs, and other non-code assets. MAID Runner does not parse CSS, assets, DOM behavior, React runtime semantics, React Native, Next.js, Remix, Vite, or bundler-specific behavior as MAID artifacts.

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.

Supersession Artifact Preservation

When manifest A supersedes manifest B, MAID Runner audits every public artifact declared by B. Each superseded artifact must be accounted for by A in one of three ways:

• Re-declare the artifact in A for the same file path.
• List the artifact's file under A's files.delete and ensure the file is gone.
• Declare the artifact under A's removed_artifacts and ensure the symbol is absent from the current source file.

If a replacement manifest drops artifacts without one of those structural signals, maid validate reports E110 ARTIFACT_DROPPED_BY_SUPERSESSION. This prevents a supersession from silently shrinking the validation surface.

Use the dedicated audit command to inspect these drops:

maid audit supersessions --manifest-dir manifests
maid audit supersessions --manifest-dir manifests --json

Brownfield repositories can seal existing legacy drops once:

maid audit supersessions --manifest-dir manifests --seal

This writes .maid/legacy-grandfathered.lock. The lock records each legacy drop by superseding slug, superseding manifest content hash, superseded slug, file path, and artifact key. After the lock exists, matching legacy drops are reported as E111 GRANDFATHERED_SUPERSESSION info entries. New drops, or drops from an edited superseding manifest whose content hash changed, are not covered by the lock.

Re-sealing a repository with an existing sealed lock is blocked unless --unseal is passed:

maid audit supersessions --manifest-dir manifests --seal --unseal

Treat --unseal as a deliberate migration action. It should be visible in review because it can add or replace grandfathered drops.

To intentionally remove an artifact while superseding a manifest, declare it in removed_artifacts:

schema: "2"
goal: "Replace old auth helper"
type: refactor
supersedes:
  - add-old-auth-helper
removed_artifacts:
  - kind: function
    name: old_auth_helper
    file: src/auth/helpers.py
    reason: "Replaced by AuthService.authenticate"
files:
  edit:
    - path: src/auth/service.py
      artifacts:
        - kind: class
          name: AuthService
validate:
  - pytest tests/auth/test_service.py -v

removed_artifacts is not trusted as self-attestation. Implementation validation verifies that the named symbol is absent from the referenced file and reports E311 REMOVED_ARTIFACT_STILL_PRESENT if it is still defined, the file cannot be parsed, the path escapes the project root, or no validator can inspect that file type.

Validator Daemon (maid serve)

A long-lived local daemon that exposes the validator over a Unix socket so AI agents, editor integrations, and tight TDD loops can validate manifests without paying Python startup per call. NDJSON protocol, repo-bound project root, locked-down socket permissions.

maid serve --socket .maid/serve.sock --pidfile .maid/serve.pid

See docs/maid-serve.md for protocol, methods, security defaults, and example client.

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

For larger batches, use draft manifests as the planning queue: keep mutable planning inventory in manifests/drafts/, promote one implementation-sized draft into manifests/, then implement and validate the promoted path. See Draft Manifest Workflow.

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/               # Active task manifests (YAML v2)
│   └── drafts/              # Mutable draft manifest queue
├── 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 and Angular .ts 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

Use manifests/drafts/ for mutable planned work that has not been promoted into the active manifest chain yet.

See CONTRIBUTING.md and CLAUDE.md for guidelines.

License

MIT License. See LICENSE for details.