maid-runner 2.1.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 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

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 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

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

Claude Code Plugin (Recommended)

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

From PyPI

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

Multi-Tool Support

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

CLI Reference

Command	Purpose	Key Options
maid validate <manifest>	Validate manifest against code	--validation-mode behavioral|implementation, --use-manifest-chain, --watch, --watch-all
maid test	Run validation commands from manifests	--manifest <path>, --watch, --watch-all, --fail-fast
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 init	Initialize MAID in project	--claude, --cursor, --windsurf, --generic, --all
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

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

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

Common Workflows

# 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

File Tracking

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

Manifest Structure

{
  "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"]
}

Validation Modes

Mode	Files	Behavior
Strict	creatableFiles	Implementation must EXACTLY match expectedArtifacts
Permissive	editableFiles	Implementation must CONTAIN expectedArtifacts

Artifact Types

Common: class, function, attribute

TypeScript-specific: interface, type, enum, namespace

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/test_task_XXX_*.py
3. Validate: maid validate <manifest> --validation-mode behavioral
4. Iterate until validation passes

Phase 3: Implementation Loop

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

Phase 4: Integration

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

Library API (v2)

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)

V2 Manifest Format (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.

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

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 (chronological)
├── tests/                   # Test suite
├── maid_runner/
│   ├── cli/                 # CLI modules
│   └── validators/          # Core validation logic
├── examples/                # Example scripts
└── .claude/                 # Claude Code configuration

Testing

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

Requirements

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

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.