Metadata-Version: 2.4
Name: maid-runner
Version: 2.8.1
Summary: Tool-agnostic validation framework for the Manifest-driven AI Development (MAID) methodology. Validates that code artifacts align with declarative manifests.
Author-email: "Mamerto Fabian Jr." <mamerto@codefrost.com>
License: MIT
Project-URL: Homepage, https://github.com/mamertofabian/maid-runner
Project-URL: Repository, https://github.com/mamertofabian/maid-runner
Project-URL: Issues, https://github.com/mamertofabian/maid-runner/issues
Project-URL: Documentation, https://github.com/mamertofabian/maid-runner#readme
Keywords: maid,validation,ai,development,manifest,tdd,architecture
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.25.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: typescript
Requires-Dist: tree-sitter>=0.23.2; extra == "typescript"
Requires-Dist: tree-sitter-typescript>=0.23.2; extra == "typescript"
Provides-Extra: svelte
Requires-Dist: tree-sitter>=0.23.2; extra == "svelte"
Requires-Dist: tree-sitter-svelte>=1.0.2; extra == "svelte"
Requires-Dist: tree-sitter-typescript>=0.23.2; extra == "svelte"
Provides-Extra: all
Requires-Dist: tree-sitter>=0.23.2; extra == "all"
Requires-Dist: tree-sitter-typescript>=0.23.2; extra == "all"
Requires-Dist: tree-sitter-svelte>=1.0.2; extra == "all"
Provides-Extra: watch
Requires-Dist: watchdog>=6.0.0; extra == "watch"
Dynamic: license-file

# MAID Runner

[![PyPI version](https://badge.fury.io/py/maid-runner.svg)](https://badge.fury.io/py/maid-runner)
[![Python Version](https://img.shields.io/pypi/pyversions/maid-runner.svg)](https://pypi.org/project/maid-runner/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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](https://archspec.dev) for spec-to-code pipelines.

**[Watch the introductory video](https://youtu.be/0a9ys-F63fQ)**

> [Full AI Compiler workflow guide](docs/ai-compiler-workflow.md)

## 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](docs/maid-philosophy-and-vision.md)

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

```bash
# 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)

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

### From PyPI

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

```bash
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`, `--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

```bash
# 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)

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

```yaml
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:**
```bash
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:**
```bash
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

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](docs/draft-manifest-workflow.md).

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

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

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

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

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

```python
from maid_runner import validate

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

### Custom Validator Registration

```python
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](https://github.com/mamertofabian/maid-agents)** | Automated workflow orchestration using Claude Code agents |
| **[MAID Runner MCP](https://github.com/mamertofabian/maid-runner-mcp)** | MCP server exposing validation to AI agents |
| **[MAID LSP](https://github.com/mamertofabian/maid-lsp)** | Language Server Protocol for real-time IDE validation |
| **[MAID for VS Code](https://github.com/mamertofabian/vscode-maid)** | VS Code/Cursor extension with manifest explorer and diagnostics |
| **[Claude Plugins](https://github.com/aidrivencoder/claude-plugins)** | Plugin marketplace including MAID Runner |
| **[ArchSpec](https://archspec.dev)** | AI-powered spec generation with MAID manifest export |

## Development Setup

```bash
# 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

```bash
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](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md) for guidelines.

## License

MIT License. See [LICENSE](LICENSE) for details.
