菜单
Audit the codebase against all existing MAID manifests to detect regressions, broken contracts, and architectural drift. Validates that past manifests still hold true against current code. Use before releases, after large changes, or periodically as a health check.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | maid-auditor |
| description | Audit the codebase against all existing MAID manifests to detect regressions, broken contracts, and architectural drift. Validates that past manifests still hold true against current code. Use before releases, after large changes, or periodically as a health check. |
MAID manifests are durable contracts. Unlike markdown plans that are disposable, a manifest declared last week should still validate against today's code. If it doesn't, something has drifted.
This skill checks the entire codebase against every active manifest and reports:
| Status | Meaning |
|---|---|
| ✅ TRACKED | Manifest validates, tests pass — contract is healthy |
| ❌ REGRESSION | Manifest was valid before, now fails — code broke a past contract |
| ⏳ PENDING | Manifest exists but implementation is incomplete — not yet done |
| ⚠️ DRIFT | Code changed in a tracked file but manifest wasn't updated — gap detected |
| 📦 SUPERSEDED | Manifest is archived — not active, not checked |
Run the complete validation suite:
# 1. Structural validation: do all manifests still match the code?
maid validate --json > /tmp/maid-audit-structural.json 2>&1
# 2. Behavioral validation: do all tests still pass?
maid test --json > /tmp/maid-audit-behavioral.json 2>&1
# 3. Coherence checks: any architectural violations?
maid validate --coherence --json > /tmp/maid-audit-coherence.json 2>&1
# 4. File tracking: any undeclared or partially compliant files?
maid validate --json > /tmp/maid-audit-tracking.json 2>&1
For each manifest, determine status:
maid validate 2>&1
| Output | Interpretation |
|---|---|
Passed: N | N manifests have code that matches their contracts — TRACKED |
Failed: N | N manifests have code that doesn't match — investigate each |
Skipped: N (superseded) | N manifests are archived — SUPERSEDED, no action needed |
For each failed manifest, identify the specific failure:
maid validate manifests/<slug>.manifest.yaml --mode implementation
maid test
| Output | Interpretation |
|---|---|
| All commands pass | Behavioral contracts intact — TRACKED |
| Specific test fails | Behavior changed without intent — REGRESSION |
| Test file missing | Test was deleted — REGRESSION |
maid coherence
| Check | What It Catches |
|---|---|
naming | Artifacts that violate naming conventions |
duplicate | Same artifact declared in multiple manifests |
boundary | Cross-layer dependencies that violate architecture |
signature | Signature inconsistencies across manifests |
dependency | Circular or invalid manifest dependencies |
The file tracking analysis identifies files that exist in the codebase but are not fully covered by manifests:
| Status | Meaning | Action |
|---|---|---|
| UNDECLARED | File exists but not in any manifest | Add to a manifest |
| REGISTERED | File in manifest but incomplete (no artifacts, no tests) | Add artifacts and tests |
| TRACKED | File has full compliance (artifacts + tests) | No action needed |
Present findings to the user in a clear summary:
## MAID Audit Report — <date>
### Overview
- Total manifests: <N>
- Active (non-superseded): <N>
- Superseded (archived): <N>
### Health Summary
✅ TRACKED: <N> manifests — contracts healthy, tests passing
❌ REGRESSION: <N> manifests — code broke a past contract
⏳ PENDING: <N> manifests — implementation not yet complete
⚠️ DRIFT: <N> manifests — code changed without manifest update
📦 SUPERSEDED: <N> manifests — archived, not checked
### File Coverage
- TRACKED files: <N> (full compliance)
- REGISTERED files: <N> (partial compliance)
- UNDECLARED files: <N> (no manifest coverage)
### Regressions (if any)
1. manifests/<slug>.manifest.yaml
- Artifact 'X' missing from file Y
- Likely cause: <refactor/change>
- Action: Update manifest or restore artifact
### Drift (if any)
1. manifests/<slug>.manifest.yaml
- Extra public artifact 'Z' in strict file Y
- Action: Add to manifest or make private (_prefix)
### Coherence Issues (if any)
1. <check name>: <description>
- Action: <recommendation>
### Recommendations
- <prioritized list of actions>
Based on findings, recommend prioritized actions:
User: "Are we clean for release?"
AI: [runs maid-auditor]
Report: ✅ 47 tracked, ❌ 0 regressions, ⏳ 2 pending
Result: Ship with confidence (pending items are known backlog)
User: "I just refactored the auth module, check for regressions."
AI: [runs maid-auditor, filters for affected manifests]
Report: ❌ 1 regression — auth-service manifest broken
Result: Manifest updated to reflect new structure
User: "How's the MAID health of this project?"
AI: [runs maid-auditor]
Report: Full audit with coverage metrics
Result: Trend data — improving or declining coverage over time
For release audits, periodic health checks, and other portfolio-level cadence
reviews, run maid insights after the validation sweep when an Outcome index is
available:
maid insights --limit 10
Use the report as advisory aggregate evidence only. It can reveal recurring patterns across tags, paths, artifacts, validation status, and review findings, but it must never gate or change the audit verdict. The auditor remains read-only and verdict-neutral: validation results determine contract health; insights inform recommended-actions follow-up candidates.
If the Outcome index is stale, the stale index fails by default. To recover,
run maid learn to refresh the index, or pass --allow-stale-index only when a
stale advisory read is acceptable for the audit cadence. Valid maid insights
options are --index, --manifest-dir, --project-root,
--allow-stale-index, --limit, and --json.
User: "How much of this brownfield project is MAID-covered?"
AI: [runs maid-auditor, focuses on file tracking]
Report: 30 TRACKED, 15 REGISTERED, 45 UNDECLARED
Result: Clear picture of onboarding progress
This is what makes MAID different from traditional testing:
| Traditional Approach | MAID Approach |
|---|---|
| Tests verify behavior | Tests verify behavior AND manifests verify structure |
| Test decay over time (flaky tests) | Manifests are stable contracts (don't decay) |
| Regression caught by failing tests | Regression caught by both failing tests AND failing validation |
| Plan is disposable (markdown) | Plan is durable (manifest) — checked forever |
| No audit trail of intentional changes | Every change has a timestamped contract |
The manifest is a regression detector that doesn't need to run. It sits in the repository as a declarative statement: "this file MUST contain these artifacts." Every future maid validate checks that statement against reality.
# Full audit (all in one)
maid validate # Structural: all manifests
maid test # Behavioral: all tests
maid validate --coherence # Architectural: coherence checks
# JSON output (for automation)
maid validate --json
maid test --json
# Single manifest check
maid validate manifests/<slug>.manifest.yaml --mode implementation
maid-implementer instead)maid-planner instead)Review an implementation produced from an approved MAID manifest. Confirms changed files stay within manifest scope, declared artifacts exist, validations pass, and the behavior matches the contract. Use after maid-implementer or after any MAID-backed code change before merge.
Implement code against an approved MAID manifest. Loads only the declared files, writes code to pass behavioral tests, validates with `maid validate --mode implementation`, and iterates until all checks pass. Use after a manifest is approved by maid-planner (or manually).
Plan a coding task as a machine-checkable MAID manifest instead of free-form markdown. Analyzes the project, asks clarifying questions, drafts or refines a manifest, and for implementation-ready plans adds behavioral tests, validates with `maid validate --mode behavioral`, and gets user approval. The promoted manifest becomes the implementation contract. Use at the start of every new feature, bug fix, or refactor.
Use when implementing maid-runner MAID draft manifests from manifests/drafts, promoting them into manifests, and validating implementation batches with review before handoff in Claude Code.
Review an implementation produced from an approved MAID manifest. Confirms changed files stay within manifest scope, declared artifacts exist, validations pass, and the behavior matches the contract. Use after maid-implementer or after any MAID-backed code change before merge.
Implement code against an approved MAID manifest. Loads only the declared files, writes code to pass behavioral tests, validates with `maid validate --mode implementation`, and iterates until all checks pass. Use after a manifest is approved by maid-planner (or manually).