Auditor/Executor Protocol

A two-role protocol for running multi-phase work through AI agents without the plan drifting into open-ended discussion and without "all tests pass" masquerading as verification.

The Auditor defines what "done" means and proves it independently. The Executor implements one numbered task at a time and logs command output. Neither role crosses into the other.

SKILL.md specifies the protocol core; references/ holds the parts an agent loads only when it reaches that step (task and gate writing, handoff templates, Autonomous mode, failure modes and a worked example). aepkit is a zero-dependency Python CLI that automates scaffolding, drift linting, negative controls, status tallies, and installing the skill into your agent. On Claude Code, the optional aeprogress mod shows a run's progress beside the chat, holds back Executor launches when the machine is busy, and compacts the Auditor's session when a phase closes.

When to Reach for This

Prompting an agent, scanning a diff, and shipping when it looks right works well for exploratory scripts and prototypes.

That approach fails when late mistakes carry real costs:

• Financial calculations and balance transfers
• Authorization, tenant isolation, and permission boundaries
• Destructive database schema migrations
• Automated background workers that run without human supervision

In these environments, plausible diffs are not evidence. Two failure modes break multi-session work:

1. Silent Plan Drift: Implementing agents quietly resolve ambiguities with assumptions instead of stopping to ask.
2. Superficial Verification: Reports like "reviewed and looks correct" mask unexecuted checks. Suites stay green because test fixtures bypass the assertion, not because the boundary holds.

The Auditor/Executor Protocol prevents both using a strict four-document paper trail and mandatory negative controls: a security check is not verified until you watch it fail with the protection removed.

The Two Roles

The Auditor never takes the Executor's word for a result: it re-runs every verify command and gate itself before giving a verdict. That is what stops a pasted "tested and working" from closing a task.

One person can run this workflow alone by switching hats between two isolated agent sessions. Keep them isolated, so the Auditor is never checking its own work.

The owner picks one of two modes at the start of a run. In Guided mode the owner pastes each handoff into a fresh Executor session and sees every verdict. In Autonomous mode the Auditor launches Executors as subagents with an explicit model per task, answers their BLOCKED questions with a decision entry in the log, and reports once per closed phase, interrupting the owner only for a numbered critical-risk list (references/autonomous-mode.md).

The Four-Document Paper Trail

aepkit init generates the first three documents and an empty annexes/ directory for the fourth. Keeping them separate prevents instructions from turning back into a discussion:

1. Plan of Record (plan-of-record.md): Explains the what and the why. Opportunity framing (target outcome, problem/friction, cost of doing nothing), set-based shaping (three evaluated options or an explicit N/A (Deterministic Fix/Compliance) bypass), riskiest-assumption prioritization for the first phase, architecture decisions, explicit non-goals, phase roadmaps, and the deferred items ledger. Nobody implements directly from this file.
2. Execution Guide (execution-guide.md): Explains the how. Numbered tasks (P0-T1) with target files, steps, literal verify commands, and phase gates (P0-G1).
3. Compliance Log (compliance-log.md): Records evidence. Holds a status board and one report entry per task and gate ID; the template starts with P0-T1 and P0-G1, and you add an entry for each task you write. The Executor pastes verbatim command output here.
4. Remediation Annexes (annexes/): When an audit yields CONDITIONAL or REJECTED, the Auditor issues a standalone annex instead of editing tasks in flight. Rapid annex growth signals an under-planned phase.

Quickstart

1. Install aepkit

Requires Python 3.11+ with zero third-party dependencies:

pipx install aepkit

To run the latest main instead, use pipx install git+https://github.com/tBeltty/auditor-executor-protocol.

Or from a clone, for development:

git clone https://github.com/tBeltty/auditor-executor-protocol.git
cd auditor-executor-protocol
pip install -e .

2. Install the Protocol into Your Agent

Provision SKILL.md and its references/ directory into your workspace or global environment. Cursor rules hold a single file, so Cursor receives one bundled .mdc with the references appended:

aepkit install-skill                     # auto-detects Antigravity, Claude Code, or Cursor
aepkit install-skill --agent antigravity # writes to .agents/skills/auditor-executor-protocol/
aepkit install-skill --agent claude      # writes to .claude/skills/auditor-executor-protocol/
aepkit install-skill --agent cursor      # writes to .cursor/rules/auditor-executor-protocol.mdc
aepkit install-skill --global            # user-level install (Antigravity unless --agent is given)
aepkit install-skill --dest <path>       # explicit destination; a non-SKILL.md file name gets one bundled file

Auto-detection checks the target directory for .agents/ or .gemini/, .claude/, and .cursor/, then agent environment variables, and falls back to Antigravity. With --global, the skill goes to ~/.gemini/config/skills/, ~/.claude/skills/, or ~/.cursor/rules/. An existing install is skipped unless you pass --force.

On Claude Code you can install the plugin in section 6 instead: it brings the same skill and the aeprogress pane.

3. Scaffold a Phased Project

aepkit init docs/<task-name> --name "<Task Name>"

Creates plan-of-record.md, execution-guide.md, compliance-log.md, and annexes/. --name defaults to the directory name; existing documents are kept unless you pass --force.

4. Track Status and Lint Drift

Inspect open tasks and tallied verdicts:

aepkit status docs/<task-name>

aepkit status --json docs/<task-name> prints the same reading as JSON, with each ID's phase, effective state and executor, and the phases with their titles from execution-guide.md (and weights from an optional Weight column in the plan's phase table), for scripts and tools to use instead of parsing the log.

Cross-check document consistency:

aepkit lint docs/<task-name>

aepkit lint catches an empty guide, tasks without a report line, missing report entries, log entries with no matching task, DONE reports whose verify output is not pasted in a code block, gates without a stated negative control (hypothetical or waived ones do not count), work reported in a phase before every earlier phase is APPROVED, unfilled opportunity/shaping/non-goal fields in plan-of-record.md once work is reported DONE or audited, open rows in the deferred items ledger for a phase being closed, duplicated log paragraphs, and annex buildup past --annex-threshold (default 6 in total, with a per-phase breakdown). It checks that evidence is present and in the right form, not that it is genuine; the Auditor's re-run does that.

5. Run a Negative Control

When validating an authorization, tenant, or schema boundary:

aepkit negcontrol \
  --file server/middleware/auth.js \
  --break-cmd "sed -i '' 's/requireAuth/\/\/requireAuth/' server/middleware/auth.js" \
  --test-cmd "npm test -- auth.test.js" \
  --expect "401|Unauthorized"

The sed -i '' form above is BSD/macOS sed; on GNU/Linux use sed -i 's/.../.../' file.

negcontrol backs up the target file, applies the break mutation, confirms the test fails, restores the file with byte-level verification, confirms the test passes, and outputs a transcript ready for compliance-log.md. Without --file, pass --restore-cmd to undo the break yourself; with both, the backup still wins if the file is not byte-identical afterwards. --file needs --break-cmd, because the backup must be taken before the break. --timeout limits each command in seconds, and a test that times out instead of failing fails the control: a hang is not a caught break.

A failure only proves something if it is the failure you meant. A syntax error, a missing import or a mistyped test command also makes the test exit non-zero. --expect takes a regular expression that the failing run's output must match, and the control fails if it does not. Without --expect, output that looks like a syntax, import, collection or command-not-found error is flagged with a WARNING next to the OK, and you need to read the transcript to confirm the reason.

6. Optional: the Claude Code plugin

On Claude Code, one plugin, auditor-executor-protocol, brings the protocol as a skill (the same SKILL.md and references/ that aepkit install-skill --agent claude installs) together with aeprogress, a mod for runs where the Auditor launches Executors as subagents or as workers of a harness such as Orca. The protocol does not depend on the mod. The mod reads a run made with the protocol, only through aepkit status --json, so it needs aepkit and a run (sections 1 and 3); without one it shows nothing.

The mod does three things:

1. A pane beside the chat with the overall percentage, one bar per phase (weighted by an optional Weight column in the plan), who is working on which task ID (Claude Code subagents, Orca workers, or any harness through a command of your own), what awaits audit, what needs attention, and the machine's load. It refreshes after each turn, and every 20 seconds while it is open.

2. A launch limit. While a run is found, it refuses to launch another Executor past 2 live workers, 1 building worker, or a machine more than 75% busy for a build, and the refusal says which limit was hit. A handoff that builds nothing carries the line Load: docs-only (references/handoffs.md) and only answers to the worker count. On macOS it also recommends excluding the project from Spotlight when indexing keeps the machine busy.

   

3. Compaction when a phase closes. In Autonomous mode, once a gate is APPROVED and the Auditor brief is up to date on disk, the Auditor calls the mod's compact_and_resume tool. After its turn, a 40-second countdown lets you cancel; then the session is compacted and the Auditor resumes from its own message. Typing a prompt, pressing Esc or running /compact yourself takes over.

   

Install the plugin at the prompt of a Claude Code terminal session, then open the pane on a run:

/plugin install auditor-executor-protocol --marketplace tBeltty/auditor-executor-protocol
/aeprogress docs/<task-name>

It works in the terminal and in the desktop app's local sessions (in the app: + next to the prompt, Plugins, Add marketplace). Every limit and feature is an option in /config. It needs Claude Code 2.1.287 or later and sends no data about you anywhere (its one network request, a daily version check, can be turned off); its README lists every process it starts and everything it can refuse. To get new versions on their own, turn on auto-update once: /plugin, Marketplaces, auditor-executor-protocol, Enable auto-update. Setup, options and how each number is computed: integrations/claude-code/aeprogress.

CLI Reference

python -m aepkit works the same as aepkit. Errors go to stderr.

Exit codes: lint and negcontrol return 0 when clean, 1 when they find a problem, and 2 on a usage error or missing document, so both can gate CI. status is informational and returns 0 whenever the compliance log exists.

aepkit reads and writes local Markdown files only: no external databases, daemons, or network calls. negcontrol runs the shell commands you pass it.

Running Tests

Run the test suite using the standard library runner:

python3 tests/run.py

Or run with pytest by installing test extras:

pip install -e ".[test]"
pytest

Contributing

Contributions are welcome. CONTRIBUTING.md covers the development setup, the quality gates, and the PR checklist; participation follows the CODE_OF_CONDUCT.md. Report vulnerabilities privately as described in SECURITY.md. Changes are listed in CHANGELOG.md.

License

MIT (see LICENSE).

Made with ♥️ by tBelt.