maid-runner

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

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.

Bring the current repository up to full MAID adoption, or refresh a repo that was onboarded before plan-lock/verify existed. Detects how the repo invokes maid-runner (a scripts/maid wrapper, uvx, or a project dependency), runs `maid init` for the agents in use (Claude and/or Codex) so skills/agents/config are installed as repo-local files, reconciles stale hand-written MAID guidance in CLAUDE.md/AGENTS.md, verifies the payload is clean, and stops for explicit commit approval. Use when asked to "set up MAID here", "onboard this repo to MAID", "bring this repo up to full MAID", "refresh MAID tooling", "fix stale MAID setup", or "the repo isn't running maid verify / plan lock".

Generate optional advisory MAID run reviews outside maid-runner with cloud privacy disclosure.

Bring the current repository up to full MAID adoption, or refresh a repo that was onboarded before plan-lock/verify existed. Detects how the repo invokes maid-runner (a scripts/maid wrapper, uvx, or a project dependency), runs `maid init` for the agents in use (Claude and/or Codex) so skills/agents/config are installed as repo-local files, reconciles stale hand-written MAID guidance in CLAUDE.md/AGENTS.md, verifies the payload is clean, and stops for explicit commit approval. Use when asked to "set up MAID here", "onboard this repo to MAID", "bring this repo up to full MAID", "refresh MAID tooling", "fix stale MAID setup", or "the repo isn't running maid verify / plan lock".

Generate optional advisory MAID run reviews outside maid-runner with cloud privacy disclosure.

Use in maid-runner when asked to improve MAID runner as a whole system, synthesize lessons from bug reports, review findings, insights, failed MAID loops, release friction, user feedback, or recurring workflow pain, and route confirmed opportunities into cleanup/refactor, performance, validation hardening, documentation, developer-experience, release, or MAID workflow draft queues. Produces a prioritized self-improvement backlog and scoped draft-manifest candidates; delegates deep specialist audits to the existing maid-runner cleanup/refactor, performance optimization, validation hardening, draft implementation, and implementation review skills instead of replacing them.

Use in maid-runner when asked to improve MAID runner as a whole system, synthesize lessons from bug reports, review findings, insights, failed MAID loops, release friction, user feedback, or recurring workflow pain, and route confirmed opportunities into cleanup/refactor, performance, validation hardening, documentation, developer-experience, release, or MAID workflow draft queues. Produces a prioritized self-improvement backlog and scoped draft-manifest candidates; delegates deep specialist audits to the existing maid-runner cleanup/refactor, performance optimization, validation hardening, draft implementation, and implementation review skills instead of replacing them.

Use in maid-runner when asked to analyze `maid validate`, `maid test`, and `maid verify` for performance and efficiency opportunities, profile hot paths, capture confirmed findings, and create a draft-manifest queue of speedups for the Codex MAID loop to implement. Covers benchmarking, caching boundaries, parser reuse, parallel execution, MAID draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Use in maid-runner when asked to analyze `maid validate`, `maid test`, and `maid verify` for performance and efficiency opportunities, profile hot paths, capture confirmed findings, and create a draft-manifest queue of speedups for the Codex MAID loop to implement. Covers benchmarking, caching boundaries, parser reuse, parallel execution, MAID draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Review a MAID manifest and its behavioral tests before implementation. Verifies the plan is complete, scoped correctly, and the tests form a genuine behavioral contract. Use after maid-planner produces a manifest and before implementation starts. Triggers: review the manifest, review the plan, check the manifest, is this plan ready, maid plan review.

Generate optional advisory Outcome enrichment outside maid-runner by orchestrating maid enrich prompt, agent-available model generation, maid enrich validate, and maid enrich render with cloud privacy disclosure.

Generate optional advisory Outcome enrichment outside maid-runner by orchestrating maid enrich prompt, agent-available model generation, maid enrich validate, and maid enrich render with cloud privacy disclosure.

Review a MAID manifest and its behavioral tests before implementation. Verifies the plan is complete, scoped correctly, and the tests form a genuine behavioral contract. Use after maid-planner produces a manifest and before implementation starts. Triggers: review the manifest, review the plan, check the manifest, is this plan ready, maid plan review.

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.

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.

Record curated MAID gaming or implementation-drift incidents as chosen/rejected examples for future review, hooks, or DPO datasets. Use when the user asks to log a MAID incident, capture a model gaming pattern, save a chosen/rejected pair, or prepare DPO training material.

Use in maid-runner when asked to audit `maid validate` / `maid verify` for anti-gaming loopholes, evaluate validator-hardening design, save confirmed findings, or create draft-manifest queues. Emphasizes evidence-backed closure through schema, VCS/worktree scope, test-runner output, compiler/parser services, bounded syntax checks, reference documentation, MAID draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Use in maid-runner when asked to audit `maid validate` / `maid verify` for anti-gaming loopholes, evaluate validator-hardening design, save confirmed findings, or create draft-manifest queues. Emphasizes evidence-backed closure through schema, VCS/worktree scope, test-runner output, compiler/parser services, bounded syntax checks, reference documentation, MAID draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Use in maid-runner when asked to audit the codebase for cleanup and refactor opportunities (dead code, duplication, long functions, weak abstractions, stale TODOs, orphaned manifests), capture confirmed findings, and create a draft-manifest queue of safe-refactor work for the Codex MAID loop to implement. Anchored on Feathers' Working Effectively With Legacy Code (characterization, seams, sprout method) and Fowler's Refactoring (named maneuvers and code-smell vocabulary). Covers characterization, behavior preservation, manifest evolution via maid-evolver, draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Use in maid-runner when asked to audit the codebase for cleanup and refactor opportunities (dead code, duplication, long functions, weak abstractions, stale TODOs, orphaned manifests), capture confirmed findings, and create a draft-manifest queue of safe-refactor work for the Codex MAID loop to implement. Anchored on Feathers' Working Effectively With Legacy Code (characterization, seams, sprout method) and Fowler's Refactoring (named maneuvers and code-smell vocabulary). Covers characterization, behavior preservation, manifest evolution via maid-evolver, draft planning, plan self-review, schema validation, and optional branch/commit handoff.

Evolve an existing MAID manifest contract intentionally. Handles signature changes, renames, removals, and splits. Determines whether chain merging suffices or superseding is required. Use when you need to change something that a prior manifest already declared.