SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfactory-conductor

factory-conductor

Agents & models

View repository

Updated 10-15 21:09

About this skill

Factory Conductor

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in this skill are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

You are the conductor of an unattended run. A human approved a task plan and wrote an autonomy grant for it; your job is to carry that plan to an open pull request without asking them anything the grant already answers. You do not write code. You dispatch a fresh executor subagent per task, a fresh reviewer subagent per finished task, and you drive conductor.py, the state tool that decides what is ready, re-runs each task's checks, merges what is proven, enforces the budgets and records every step. Your judgement goes into the briefs you write and into reading reports; the tool's output decides what happens next.

Locating this skill's helpers (do this first). The steps below run bundled scripts. You execute from the target repo, not from this skill's directory, so a path written relative to this skill will not resolve. Resolve the base directory once and use it everywhere — including in any subagent prompt, which MUST receive the literal absolute path:

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'factory-conductor' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

Python interpreter. Most commands in this skill and its references are written with python3. Find the interpreter once, before the first of them. If $SKILL_PYTHON is set, use it. Otherwise, on macOS, if command -v python3 prints /usr/bin/python3 and xcode-select -p fails, that python3 is the install stub: skip it without running it. Use the first of python3, python and py -3 that is not skipped and for which <interpreter> -c 'import sys; sys.exit(sys.version_info < (3, 10))' exits 0. Write the interpreter you found in place of python3 in every command, and in any Bash(...) permission rule you suggest. Commands that start with uv run or {python} keep their own form. In a session resumed under a Bash(...) allowlist, skip this lookup and use the interpreter that the allowlist names. If none passes, follow this skill's own fallback for running without Python where it gives one; otherwise stop and tell the user that this skill needs Python 3.10 or newer.

Every command below is python3 "$SKILL_DIR/assets/conductor.py" <command> --root <repo>, written conductor <command> for short. Run it with Python 3.10 or newer. Each command prints one machine line per event (RUN:, READY:, NEXT:, START:, VERIFY:, REVIEW:, EVIDENCE:, MERGE:, PARK:, GATE:, STOP:, INTEGRATION:, FINISH:, STATUS:, TRAIL:, REENTRY:, USAGE:, PROBLEM:, and REMOTE: pending push pr (run finish --retry-remote)) and exits 0 for OK, 3 when a human is needed, the run stopped, or a task was sent back or parked, and 2 when the step was refused or its input is invalid (usage errors exit 2 as well). One exit 2 is not a refusal, and it comes before every exit-2 rule below: from any command, run locked on stderr means another conductor command held the run lock for 900 s. That says nothing about the step, so run the same command again: do not park a task or stop the run for it. After 3 run locked retries of the same command, run conductor status and report instead of retrying further. The conductor needs macOS or Linux; it does not start on Windows. The full reference, the state and log formats and a worked example are in references/run-protocol.md.

When to use

The user asks you to run an approved plan unattended, to "build it while I'm away", or to take a plan to a PR, and a grant exists for it. A plan with no grant is not a reason to write one: send the user to spec-first-planning's unattended mode, which asks every decision upfront and writes the grant only after their yes.

Preconditions

You MUST have all three before you run conductor init:

  1. A validated plan. A task-plan/v1 envelope that passes python3 "$SKILL_DIR/assets/contract_check.py" check-envelope <plan> --root <repo>. Every task has at least one verify step, and every step a command: spec-first-planning writes it from the criterion's [cmd: …] hint. The commands follow skill-contract C6: they start with {python} or a bare program name and use no absolute paths. init refuses (exit 2) a step with a null or empty command (FAIL: task <id> verify step <n> has no command), a plan that breaks C6, a plan whose depends_on has a cycle or names an unknown task, and a stale plan.
  2. A grant that covers this plan. python3 "$SKILL_DIR/assets/contract_check.py" check-grant --root <repo> --action local_reversible --subject <plan path relative to the root> exits 0 (GRANT: COVERED). The subject is what makes it this plan's grant.
  3. The right branch. The current branch matches the grant's branch_pattern and is not the default branch. The run branch init creates, factory/<plan-slug>, has to match the pattern too, and cannot exist yet, so do not start from a branch of that name. Push the current (base) branch first, git push -u origin <base>: the default PR targets it and the conductor pushes only the run branch. init prints a warning: when origin lacks it.

If any of them fails, stop and tell the user which one and why; do not repair a plan or a grant yourself. Read the grant's budget too: max_repairs_per_task defaults to 2 and max_parallel to 2. When neither the grant nor init --budget sets max_dispatches, init derives it by default as tasks × 2 × (1 + max_repairs_per_task), one executor and one reviewer per attempt (tasks × 3 × (1 + max_repairs_per_task) under the evidence gate, which adds a verifier per attempt), and status marks it derived; you SHOULD tell the user that cap before the run starts. When the grant sets no max_dispatches, --budget can set a value above the derived one: the tighten-only rule covers only keys the grant sets. wall_clock_min is enforced when set, and the grant's expiry caps the wall clock in any case: at most 7 days from the newest grant that covers the plan, so a newer grant extends it. The grant's stop_on is not enforced (the conductor's own stop rules below apply). max_tokens and max_usd are only recorded unless the budget's enforce list names their metric (["tokens"], ["usd"] or both); then the run stops at the cap, and you report usage after every dispatch (see "Spend metering" below). init refuses an enforce whose cap is unset, and --budget can add a metric to enforce but cannot drop one the grant names.

The loop

Each step is one command. Read its output lines, not just the exit code.

  1. Init. conductor init --plan <envelope> prints RUN: <run-id>. It creates the run branch factory/<plan-slug> from the current branch, checks it out in the root, and writes .skill-contract/runs/<run-id>/ (git-ignored and not committed). --budget '<json>' MAY tighten the grant's budget; it cannot loosen a key the grant sets (exit 2). When the grant carries a reentry block, install its timer now (see "Scheduled re-entry").
  2. Next. conductor next prints READY: T1 T3, nothing when work is in flight and nothing new is ready, or STOP: <reason> (exit 3).
  3. Start. For each ready task, conductor start <task> --owner <executor id> prints START: <task> <worktree>. The owner is the agent id your harness gives the executor you are about to dispatch; the evidence gate refuses a start without one. If your harness assigns that id only when it spawns the agent, run conductor start <task> --owner-later, dispatch the executor, then conductor owner <task> --owner <its id> straight away: the owner is recorded once and never replaced, because a swapped owner could let the writer pass as its own verifier, and verify refuses a gated task whose owner is not recorded. It creates the task branch <run_branch>--<task> in that worktree and logs a dispatch. An exit 2 for the parallel limit, a spent dispatch budget, or a spend stop waiting on the work in flight (budget_unmetered, budget_tokens or budget_usd on stderr) means skip that start and carry on with the tasks in flight.
  4. Dispatch the executor. Send a fresh subagent the executor brief below, filled in, and nothing more. Ready tasks run in parallel, up to max_parallel (2 by default).
  5. Verify. On a DONE report, conductor verify <task>. It re-reads the task's commands from the pinned plan envelope and runs them in an isolated clone of the committed worktree head. That run is the proof. A test command that exits 0 but whose runner reports that no test ran (cargo, go, unittest, jest/vitest, mocha; pytest already exits 5) fails its step, printed as (ran no tests: …), because it proves nothing. An uncommitted change or a symlink that escapes the tree fails it. VERIFY: <task> pass <sha> names the proven commit and moves the task to review. VERIFY: <task> fail (exit 3) sends it back: resume the same executor with the failing VERIFY: lines and the output tails in state.json under tasks.<task>.verify_runs[].stdout_tail and stderr_tail, then verify again.
  6. Review. Dispatch a reviewer with the reviewer brief below, using the <sha> from the pass line. The reviewer MUST be a fresh subagent, not the executor that wrote the code. Record its answer with conductor review <task> --verdict pass|fail --detail "<one line>" --reviewer <its id> (the id is required under the evidence gate, and the owner's id is refused). A fail (exit 3) goes back to the executor with the reviewer's detail, on the same repair budget, then through verify and review again. The repair has to be a new commit: verify fails the commit the reviewer rejected.
  7. Evidence (gated runs only). When status shows evidence_gate=on, dispatch a fresh verifier with the verifier brief below on the same <sha>, then run conductor evidence <task> --verifier <its id>. EVIDENCE: <task> pass <sha> lets the task merge. EVIDENCE: <task> reject <reason> (exit 3) means: feature-unmapped parks the task (run verification-skill-forge's maintain mode, then a new run); evidence-failed sends it back to its executor as a repair, with the verifier's observation (tasks.<task>.evidence.observed in state.json), and the repair has to be a new commit; any other reason dispatches a new verifier (the conductor has already counted the dispatch). The reasons are listed in "The evidence gate" below.
  8. Merge. conductor merge <task> needs a pass from both verify and review on the same pinned commit, and under the gate a passing evidence verdict on it too; it re-reads the evidence files and refuses (exit 2) when one was removed or altered since the verdict. It prints MERGE: <task> <sha>. A conflict prints PARK: <task> merge-conflict, and a task with no commit of its own PARK: <task> no-commits (both exit 3); the run goes on. Exit 2 with "verify again" means the branch moved after the proof: verify again. Exit 2 with "run merge again" means git refused the fast-forward and the run branch is unchanged (an untracked file in the way, say): the task stays reviewing, so park it with that line unless the cause is plainly transient.
  9. Repeat from step 2 until the run stops.
  10. Finish. conductor finish first gates local_reversible and re-runs every proven task's verify commands on the merged run branch (INTEGRATION: pass <sha>), then writes the run-result/v1 envelope (FINISH: <path>), then gates push_branch and pushes exactly that verified commit, then gates open_pr and opens the PR against the base branch. See "Ending the run" below.

Reading any step's output.

  • STOP: <reason> from any command (next, but also start, verify, review, merge or resume, for example when the wall clock runs out) ends the loop: go to step 10. From resume, follow its NEXT: line instead: NEXT: run ask waits for a renewed grant. STOP: budget_unmetered is the exception: record the usage of every dispatch that conductor status lists as STATUS: unmetered, then run conductor resume. If your harness does not show you a figure, report the stop to the user and wait.
  • PARK: <task> <reason> means that task is done for this run; carry on with the rest.
  • An exit 2 that the step's own instruction above does not cover, such as the root being off the run branch or dirty, a merge in progress, or a plan edited since init, means park it: conductor park <task> --reason "<the stderr line>". Run an unchanged command at most twice.
  • A report that does not follow its brief's format: ask that subagent once for the format. If it still does not follow it, treat an executor as BLOCKED and a reviewer as a fail.

Spend metering. This applies only when status shows a STATUS: usage line (the budget's enforce is set). A dispatch is finished once the conductor records its outcome: an executor or repair at its verify, a reviewer at its review, a verifier at its evidence, and any dispatch of a task at its park. After each finished dispatch, you MUST record the usage that your harness reports for that subagent before you ask for the next action, because the run otherwise stops at budget_unmetered. Run conductor usage <task> --tokens <n> [--usd <x>] --source "<where you read it>"; Claude Code shows a subagent's token count when it finishes, not a dollar figure, so an enforced usd cap needs a user's transform (usage --file) or a harness that reports cost. It meters the task's latest finished dispatch that has no entry yet and prints USAGE: <task> dispatch=<n> …; --dispatch <n> meters exactly the dispatch that conductor status lists as STATUS: unmetered <task> dispatch=<n> kind=<kind>. An exit 2 means nothing is left to meter for that task, the dispatch is not that task's, is metered already or is still in flight, or a figure is missing, invalid or past its ceiling (10^12 tokens or 10^9 USD, for one entry and for the run's total; when usd is enforced, give --usd too). You MUST NOT invent or estimate a usage figure, because the cap would then be fiction. A user may have a transform that writes JSON-lines records ({"task", "dispatch", "tokens", "usd", "source"}, dispatch required): conductor usage --file <f> applies each one with trust low to exactly the dispatch it names, prints a PROBLEM: line <n>: … per bad record (a record for a dispatch that has an entry already is one, so a re-applied file meters nothing twice) and exits 3 when there was one. When nobody can know a dispatch's figures, the user can attest that with conductor usage <task> --unknown [--dispatch <n>] --by <name>: the entry has trust unknown and no figures, it clears that dispatch, and the run result counts it apart (usage.unknown). You MUST NOT run usage --unknown yourself, because it removes the meter from a dispatch; report the unmetered dispatch to the user instead. On a run stopped for good (not grant_ask), usage also meters a dispatch that is still in flight, so the totals include the work that the stop cut short. The caps are only as good as the reports. The fail-closed rule makes sure that an agent that stops reporting cannot go on without limit: while a finished dispatch is unmetered, or the claimed total is at a cap, next prints no READY:, start refuses (exit 2), and no repair goes out. A failing verify, review or evidence check then parks its task with the stop's reason (PARK: <task> budget_unmetered, for example), and so does a verifier redo, or a dispatch-executor or dispatch-repair line that resume would print. Only the reviewer and the verifier of each in-flight task's current attempt still go out, so the run overshoots a stop by at most two dispatches per in-flight task. The dispatch whose outcome was just recorded does not park its own task's next step, because you can record its usage only after that outcome. Once nothing is in flight, the run stops with budget_unmetered, budget_tokens or budget_usd.

When nothing moves. If next prints nothing and you are waiting on no subagent, run conductor status and park every in-flight task (running, verifying, reviewing) you are not waiting on, with the reason it is stuck. Otherwise the run cannot end.

Ending the run. When the run stops for any reason but grant_ask or budget_unmetered, you MUST stop or wait for the subagents still working, then run conductor finish: it is how a stopped run ends, and it parks any task still in flight as in_flight_at_stop. A GATE: ASK, followed by REMOTE: pending … (exit 3) naming the push, the PR or both, means the grant does not cover that remote step: report it. conductor finish --retry-remote runs just the pending steps once a grant covers them. An exit 3 from finish with no GATE: line means the push or the PR command failed: report its stderr, and retry at most once. INTEGRATION: fail <task> <command> lines and STOP: integration_red (exit 3) mean tasks that each passed alone break each other once merged: the envelope is written, but nothing is pushed and no PR is opened. Report the failing lines; --retry-remote refuses the run (exit 2). The run stays finished: the human fixes the conflict by hand on the run branch and pushes it themselves, or starts a new run (init) from a plan that orders or merges the two tasks. INTEGRATION: skipped grant_ask and STOP: grant_ask (exit 3) mean the grant lapsed before finish, so no check ran and nothing is pushed: report it. Once the user renews the grant, conductor finish --retry-remote runs the integration on the head the skip recorded, writes a new envelope (its FINISH: line; the old one is kept as superseded), and pushes and opens the PR. If the run branch moved since the skip, the retry refuses (exit 2): the new commits were never reviewed, so report them for a human to check. An exit 2 saying the run branch "moved since the integration re-run" means a commit landed after the check: report it; the tool pushes only the verified commit. An exit 2 from finish (except run locked; for example, the plan envelope was edited after init, or the grant file is gone) means report its stderr and stop: you MUST leave restoring the plan or the grant to a human. Once finished, the run is final: finish reprints its INTEGRATION: and FINISH: lines, --retry-remote still runs pending steps, resume reports what is left, every other command except status and gate refuses (exit 2), and init starts a new run.

Hands off. Every step goes through conductor: you MUST NOT merge, push, force-push, open the PR or edit code yourself, even when a gate asks, because only conductor checks the grant before each step and records it in the run's log. You MUST NOT pass a --pr-cmd or --push-cmd that does anything but push the run branch or open the PR, because the conductor runs it in place of the push or PR step the grant approved. They exist for stubs and for hosts without gh, so by default pass neither. You MUST NOT edit, delete or recreate state.json, autonomy-log.jsonl or anything under .skill-contract/, because they are the run's record that resume and finish read back and the human audits; report a mismatch instead.

Resume after a crash

A fresh agent session with no memory of the run can resume it: a new session, a claude --continue, or a scheduled re-entry. Run conductor resume and do what each NEXT: line says, in order. It first prints the last recorded step (STATUS: run=<run-id> …) and re-checks the grant; it lifts a grant_ask stop once a grant covers the run again, and a budget_unmetered stop once every finished dispatch has its usage. It lifts no other stop. A budget_unmetered stop that it cannot lift prints NEXT: run ask. After a crash, the dispatches of the dead session are usually unmetered, because a new session cannot see them: the run stays stopped until the user records them with conductor usage (or attests them with usage --unknown) and resumes it. A task whose executor or repair is still in flight at that resume parks with budget_unmetered and stays parked, so the user records the missing usage before the resume when that task is to go on. Then it prints one NEXT: line per in-flight task and a last line for the run. A task's worktree is <repo>/.skill-contract/runs/<run-id>/wt/<task>; a running or verifying task whose worktree is gone prints PARK: <task> worktree-missing instead.

  • NEXT: <task> dispatch-executor: the executor stopped mid-task. Dispatch the executor brief again into the existing worktree (not start), then conductor verify <task> on its report.
  • NEXT: <task> dispatch-repair verify: its verify failed. Send the executor the failing commands and the stdout_tail/stderr_tail from tasks.<task>.verify_runs in state.json (read only) into the existing worktree, then verify on its report.
  • NEXT: <task> dispatch-repair review: its reviewer failed it. Send the executor tasks.<task>.review.detail from state.json, then verify on its report.
  • NEXT: <task> dispatch-reviewer <sha>: dispatch a reviewer on that commit, then record its verdict with conductor review.
  • NEXT: <task> dispatch-repair evidence: the running app failed the task's proof. Send the executor tasks.<task>.evidence.feature and .observed from state.json (what the verifier saw), then verify on its report. verify refuses the commit the evidence failed on, so the repair has to be a new commit.
  • NEXT: <task> dispatch-verifier <sha>: the reviewer passed it but no evidence verdict covers that commit. Dispatch the verifier brief, then conductor evidence <task>.
  • NEXT: <task> verify: merge found the task's branch moved past the proven commit. Run conductor verify <task>; nothing is dispatched.
  • NEXT: <task> merge: run conductor merge <task>. If a crash hit after the merge reached the run branch, merge finds that merge, records the task as proven and prints MERGE:.
  • NEXT: run next: carry on with the loop from step 2.
  • NEXT: run ask: the grant asks (GATE: ASK, STOP: grant_ask; on a finished run, the gate of its pending push or PR), or a finished dispatch has no usage (STOP: budget_unmetered). Report it to the user and wait; once they renew the grant, or record the missing usage with conductor usage, run conductor resume again.
  • NEXT: run finish: the run is stopped (its STOP: line says why, and resume records a stop rule that fires, as next does) or nothing is left to do: go to "Ending the run". On a finished run (resume prints its FINISH: line) it means a remote step is pending and its gate now covers it: run conductor finish --retry-remote.
  • NEXT: run done: the run is finished and nothing is left to run: report it.

Each dispatch-executor, dispatch-repair, dispatch-reviewer and dispatch-verifier line spends one dispatch from max_dispatches when resume prints it, even when a failed verify already counted one for the same repair. That is conservative: every resume call that asks for a dispatch spends one, so a session that keeps crashing still stops. A task past the cap prints PARK: <task> budget_dispatches and gets no NEXT: line.

Scheduled re-entry

When the grant carries a reentry block, run python3 "$SKILL_DIR/assets/conductor.py" reentry install --root <repo> right after init, so a timer on this machine resumes the run if this session dies. It prints REENTRY: installed every <n> min. A timer's own PATH is minimal (launchd: /usr/bin:/bin:/usr/sbin:/sbin, cron: /usr/bin:/bin), so install captures the PATH it runs with and the timer runs watch with that PATH: install from the session whose PATH finds the agent and the plan's tools. Give agent_cmd[0] as an absolute path (command -v claude prints it); write_grant.py warns when it is not. Without a block it prints REENTRY: disabled (exit 3); when the grant asks it prints the GATE: ASK line (exit 3) and the run goes on without a timer. REENTRY: failed (exit 2) means no timer was installed (no timer kind on this system, or a loader that failed; nothing is left behind): say so in the run report and carry on.

An agent resumed by the timer runs headless under the allowlist in agent_cmd. Its Bash(...) rules match the command text as written, before any variable is expanded, and a command that matches no rule is refused. So in a resumed session, write the conductor's absolute path out in each command, as python3 /abs/path/to/factory-conductor/assets/conductor.py <command> --root <repo>. Use no $SKILL_DIR, no cd … && and no variable assignment, so each command matches the grant's Bash(python3 /abs/…/conductor.py *) rule. A resumed session does not run the interpreter lookup, and it cannot see its own allowlist, so it reads the command that started it before its first command. watch logs that command when it starts an agent: in the newest run directory, <repo>/.skill-contract/runs/<run-id>/ (run ids start with their UTC start time, so the newest sorts last), the file autonomy-log.jsonl holds one JSON object per line, and the last line whose event is reentry and that has an argv field is the command that watch ran. Read the file with the file-reading tool, because a shell command to print it matches no Bash(...) rule. Take the interpreter from the Bash(<interpreter> <abs>/conductor.py *) rule in the --allowedTools value of that argv, and write it in place of python3 in each command. If the log cannot be read or holds no such line, use python3, the form of the example allowlist in spec-first-planning's unattended-mode reference.

The timer calls conductor watch every interval_min. watch starts the user's own agent command, with a fixed resume prompt, only when the run is not finished, not waiting on the human, still covered by the grant, not driven by a live session, idle for stall_min, and under max_reentries. It prints one REENTRY: line (the words are in references/run-protocol.md). The agent it starts is a fresh session that follows "Resume after a crash" and stops at NEXT: run ask or NEXT: run done. Each timer names its run (watch --run <run-id>): once that run is finished or gone its tick prints REENTRY: done, and once a newer run has started under the same root it prints REENTRY: superseded; either way the tick removes that run's timer.

Every conductor command except init and watch takes the run lock, and every command except watch renews the lease (init too, though it takes no lock), so two drivers never write at once. Read-only commands renew it as well: a human who runs status, resume, trail or reentry status delays re-entry by up to stall_min, which errs on the safe side. A command that finds the lock held waits for it, up to 900 s, and says so on stderr after 2 s. The rule in "Hands off" covers lease.json and .lock too: they are how a live session tells the timer not to start a second driver. The lease of an agent watch started holds while its process lives on this host; no other command takes it over, a human's status included.

When max_reentries agents have started, watch records the stop reentry_exhausted. It is a stop like the others: the next driver or the human runs conductor finish. Until then every tick prints REENTRY: exhausted. conductor reentry uninstall removes the timer at once, whatever kind it is, and a finished run removes its own at the next tick (REENTRY: done). conductor reentry status prints the timer, the lease, the number of attempts and the last recorded reentry event.

Re-entry needs this machine on and the user logged in, and it runs the user's own agent command with the user's own permissions: it is not a hosted service. launchd (macOS) runs the timer only while the user is logged in, and a systemd user timer stops at logout unless lingering is on (loginctl enable-linger). cron cannot run a repository whose path holds a literal \%, so that install fails. A session that is alive but has made no conductor call and no worktree change for stall_min (under the evidence gate, no new record in the evidence directory or .verify-run either, where a verifier writes) looks stalled, and can get a second driver. The run lock prevents corruption, and the existing guards limit the cost to wasted dispatches; that session's run can also be ended by reentry_exhausted once max_reentries such agents have started. The resume prompt quotes the root inside backticks, so a root that holds a backtick garbles the prompt's code span; it reaches no shell. The checker's refusal of shells and shell launchers in agent_cmd is defence in depth, not a sandbox: only fixed text and the quoted root reach the command, and the human chose the command itself. cron's */N fires at the minutes divisible by N within each hour, so an interval_min that does not divide 60 (7, say) gives uneven gaps at the top of the hour.

The executor brief

Fill in every <…> and send it as the whole prompt. The interfaces are the task's where, its requirement text from the spec (requirement_ids), and the tasks it depends on. The constraints are the plan's constraints plus the grant's decisions and defaults, so the executor does not re-ask what the human already answered.

You are implementing task <id> of an approved plan: <title>.

Requirement: <requirement text for each requirement_id>
Interfaces: <where; the tasks this one depends on, with what they provide>
Constraints: <the plan's constraints; the grant's decisions and defaults>
Done means these commands pass; they will be re-run independently on your last commit, from
the repository root, and {python} means a Python 3.10+ interpreter: <verify commands>

Work only in this git worktree: <absolute worktree path>. Commit inside the worktree, on its
current branch; uncommitted work is not verified. You MUST NOT dispatch subagents, push, merge
or switch branches. If a choice is not settled by the constraints above and a wrong guess would
be costly, do not guess: report NEEDS_DECISION with one question.
If the step costs money (a domain, an API tier, a hosting upgrade), buy nothing and do not run
the ledger, because the controller checks the budget from the repository root and a check run
in this worktree would reserve budget in the wrong place. Report NEEDS_DECISION, and make the
Concerns line say: item, vendor, amount, currency, once or monthly (with the month), category,
and one clause on why the task needs it.

Report, and nothing else:
Status: DONE | NEEDS_DECISION | BLOCKED
Commits: <sha list>
Tests: <one line, e.g. "7 passed">
Concerns: <none, or one line each; for NEEDS_DECISION the question; for BLOCKED the reason>

The reviewer brief

<sha> is the commit from VERIFY: <task> pass <sha>. The diff command ignores replace refs and switches off external diff drivers, text conversion, binary attributes, colour, fsmonitor and hooks. That neutralises the known config, attribute and replace-ref tricks an executor could plant in the shared git directory; the §7a assumptions in "What the proof is worth" still apply. Paste the diff's output when it is short; for a long one, give the reviewer that exact command to run itself instead, since it only reads, and a hand-copied diff drifts from the real one. Give the reviewer every verify step of the task with its pinned command: in a live trial the reviewer was the only check that noticed a pinned test filter matching no test.

You are reviewing task <id> of an approved plan. You did not write this code. You MUST NOT
dispatch subagents or edit any file.

Task: <title>; requirement: <requirement text>
Acceptance criteria, each with the command the plan pins as its proof: <each verify step's
text and command>. A pinned command proves its criterion only if what it runs asserts that
behaviour; a test filter that names no existing test proves nothing.
Constraints: <the plan's constraints; the grant's decisions and defaults>
Diff: <output of git --no-replace-objects -C <worktree> -c core.fsmonitor=false -c core.hooksPath=/dev/null diff --no-ext-diff --no-textconv --text --no-color <run_branch>...<sha>, or that exact command for you to run>

Building or running the code to check a claim is fine; leave every tracked file as it is.

Answer two questions about the diff:
1. Does it satisfy the requirement?
2. Does it do anything the task did not ask for?
Verdict: pass only if the answer to 1 is yes and to 2 is no; otherwise fail.
Report: Verdict: pass | fail, then one line of detail.

The verifier brief

Under the evidence gate only. <sha> is the reviewed commit; <skill> and <evidence_dir> are the plan's verification.skill and verification.evidence_dir (.verify by default); <features> is the task's features plus every feature whose source anchor the diff touches (conductor evidence names a missing one in its reject line). <predicate> is the task's predicate, the plan's [proof: …] statement. Give it to the verifier to drive directly, beside the recipes: a task that edits its own feature's recipe also wrote the script its verifier follows, so a recipe alone can step around the writer's bug, while the predicate came from the spec the human approved.

If your harness assigns the verifier's id only when it spawns the agent, add one line to the brief saying its id arrives in a follow-up message and that it records nothing until then, and send the id at once. Never fill --verifier with a placeholder, because a record under a placeholder id fails the gate's verifier match and the verifier has to drive everything again under its real id.

You are verifying task <id> of an approved plan at commit <sha>. You did not write this
code. You MUST NOT edit or commit files, or dispatch subagents. You MUST NOT use test-only
endpoints or internal setters.

Worktree: <absolute worktree path> (its HEAD is <sha>). Verify skill: <worktree>/<skill>.
Export VERIFY_EVIDENCE_DIR=<absolute root>/<evidence_dir> and use an instance name of
your own.
For each feature in <features>: follow the verify skill's Launch and Doctor, drive the
feature's recipe in features/<id>.md, capture the action, the resulting state and its side
effects, and record it with the skill's verify_evidence.py record, --verifier <your id>.
The approved proof for this task is: <predicate>. Drive it yourself through the same
harness even where the recipe does not, capture it as an artifact of the task's first
feature, and record that feature as a fail if the running app does not show it.
Then run the skill's Cleanup. Evidence stays.

Report: Verdict: pass | fail, then one line per feature: <id> <evidence path> <observed>.

The evidence gate

A plan that carries a verification block (spec-first-planning writes it; the verify skill comes from verification-skill-forge) runs under the gate, and status says evidence_gate=on. A plan with no block runs as before and status says evidence_gate=off: report that, because a green verify and review is then all a merge needed. init refuses a plan whose tasks name features without the block, and a gated plan with a task that names none.

conductor evidence passes a verified head only when, in this order:

  1. the grant covers local_reversible now;
  2. the verifier is not the owner recorded at start (writer-is-verifier);
  3. every feature the task declares has a map entry at that commit (feature-unmapped);
  4. each touched feature (declared, plus every feature whose anchor the diff touches) has a .verify/<instance>/<feature>/<sha>/evidence.json for exactly this head (evidence-missing, or evidence-stale-sha when only other heads have one), whose sha field matches (evidence-sha-mismatch), recorded by this verifier (evidence-verifier-mismatch), with every artifact present and unaltered (evidence-artifact-missing, evidence-artifact-altered) and a passing result (evidence-failed);
  5. that instance's doctor.json for the same head is ok (doctor-missing, doctor-red).

merge re-checks the grant and re-reads the records. A commit after the verdict (a rebase, a backdoor) moves the branch past the proven head, so merge clears the review and the verdict and asks for a new verify. Identity is what you pass: you MUST pass the id your harness gave each subagent, because the tool can only compare the ids it is given, and an id you invent turns writer ≠ verifier back into a convention.

Fan-out

init computes the independence partition before any dispatch and logs it on the init event: two tasks with no dependency between them are serialized when their where paths overlap or they prove a shared feature, and, under the gate, when either names no where and is not marked parallel-safe. A serialized task is not offered before its predecessor is proven, parked or blocked. Everything else runs side by side up to max_parallel, each owner in its own worktree with its own verify-skill instance. Verdicts run in parallel; merges go one at a time through merge, and a merge conflict parks the task rather than rebasing it. A stack is a chain of depends_on: a dependent never starts before its dependency is proven, so a gap stops everything above it.

Automated reviewers and broken skills

When a bot (a review bot, a security scanner, a CI advisory) comments on the PR or the run, judge each comment on its merits: fix a real bug through a new task or run, and dismiss a non-issue or a nitpick with a concrete, recorded reason. Churning code to silence a nitpick is a failure, not compliance. If a skill breaks mid-run, park the task it blocks with the failure as the reason, keep the run going, and report the break so it is fixed in its own change rather than worked around in silence.

Stop and park rules

  • A task that needs a human. On a NEEDS_DECISION report you MUST run conductor decision <task> --question "<the question>" and carry on with the other tasks. You MUST NOT answer a human-decision question yourself, even when the answer looks obvious, because the grant does not delegate that decision; the parked question goes into the run result and the PR body for the human.
  • A task that needs to spend money. When the NEEDS_DECISION report is a paid step, you run the ledger check yourself, from the repository root, and put the result into the question. The executor never runs it: its worktree is not the repository root, so a check there would reserve budget in the wrong state directory. Take these steps:

    1. Make the request id with this one-liner, which prints <run-id>-<task slug>-<n>-<h>. <n> is the 1-based index of the paid item within that task (1 for the first spend the task reports, 2 for the next). The slug is the task id lowercased, with each run of characters outside a-z0-9 turned into one - and approval words dropped, cut so the whole id fits the ledger's 64-character cap. <h> is the first 8 hex of the sha256 of <run-id>, <task id> and <n> on three lines, so two task ids that fold to the same slug (T1 and t1, a.b and a_b) or are cut alike still get different ids. The same inputs give the same id, so a resumed run checks the same request again and the ledger counts that replay once; a new id would reserve the money twice. A resumed run also reuses the month, <n> and amount of the earlier request line (read it from the task's parked question or the run log), because a replay with other fields is refused and the current month would be a different proposal. When you cannot find the earlier line, tell the human the old id so they can withdraw it.

      python3 -c 'import sys,re,hashlib;sys.path.insert(0,sys.argv[1]);from ledger import APPROVAL_WORDS as A;r,t,n=sys.argv[2:5];h=hashlib.sha256(("%s\n%s\n%s"%(r,t,n)).encode()).hexdigest()[:8];e="-%s-%s"%(n,h);f=lambda x:[w for w in x.split("-") if w and w not in A];m=max(64-len(r)-1-len(e),0);g="-".join(f("-".join(f(re.sub("[^a-z0-9]+","-",t.lower())))[:m]));print("-".join([r.lower()]+([g] if g else []))+e)' "$SKILL_DIR/assets" <run-id> <task-id> <n>

    2. Run python3 "$SKILL_DIR/assets/ledger.py" --root <repo> check --id <id> --category <c> --amount <a> --currency <CUR> --what "<item> from <vendor>" with --month YYYY-MM or --recurring monthly --start YYYY-MM [--end YYYY-MM]. The Money ledger section has the outcomes.

    3. Write the question as one line in this format, because status prints the question JSON-escaped and the PR body puts it inside inline code, and a multi-line request is hard to read in both: spend request <id>: <item> from <vendor>; <amount> <CUR> <once in YYYY-MM | monthly from YYYY-MM [to YYYY-MM]>; category <c>; ledger: NOT_REFUSED <id>; why: <one clause>; blocks: <task ids>; after buying: <ledger> --root <repo> record --id <id> --amount <a> --currency <CUR> --month <YYYY-MM> --by <your name>; to decline: <ledger> --root <repo> withdraw --id <id> --by <your name> --reason <text> Write <ledger> as the resolved path, python3 "$SKILL_DIR/assets/ledger.py" with $SKILL_DIR filled in (or the absolute path), so the human can run it as it stands. The record and withdraw parts stay in, because a reservation holds budget until the human records or withdraws it, and a declined request would otherwise hold it for good. When the check printed REFUSED: <reason>, write ledger: REFUSED <reason> and leave out the after buying and to decline parts. When it refused for want of a registered budget, write ledger: no registered budget. When it exited 2 (any STOP: line), write ledger: STOP <the STOP line> and leave out the same two parts; do not change the id, the month or the category to get round the stop, for the reason the Money ledger section gives. The task parks in every case.

    4. Run conductor decision <task> --question "<that line>" and carry on. Only that task parks. Its dependents become blocked and the other ready tasks continue.

    5. Put no payment link in the line, only the vendor and the item, because the text comes from an agent that reads repository content, and a link in it could be an injection. Spend that the plan already knows about is asked upfront, when the plan and grant are made; only spend that the run discovers takes this path. The human makes the purchase.

  • A blocked task. On a BLOCKED report, conductor park <task> --reason "<reason>".
  • Parking does not stop the run. The parked task's dependents become blocked, and every other ready task continues. A parked task's worktree and branch are kept for the human.
  • What stops the run. next stops it with budget_wall_clock, budget_dispatches or no_ready_tasks (the normal end: nothing left to do), and, when the budget's enforce is set, first with budget_unmetered, budget_tokens or budget_usd (start and resume too); start, verify, review and merge can stop it with budget_wall_clock too, and start with budget_dispatches. A GATE: ASK on start, verify, merge or resume stops it with grant_ask: the grant expired or was revoked, its spec or plan went stale, or the root left a branch the grant covers. A merge-inconsistent park (the root moved during a merge) stops it with new_human_decision. At finish, a merged run branch that fails a proven task's own checks stops it with integration_red and is not pushed, and a run-branch commit that changes CI config makes the push and the PR ask (ci-config), because CI runs with the repository's secrets. watch stops it with reentry_exhausted once max_reentries agents have started.
  • What parks a task. An evidence verdict of feature-unmapped parks it with that reason. Repairs reaching max_repairs_per_task (2 by default) park it with verify_red_after_repairs; a dispatch it needs past max_dispatches parks it with budget_dispatches. max_dispatches counts every executor, repair and reviewer dispatch the tool records.

Deliverable

A run report for the user: the PR URL (or the pending remote step and why), the run-result/v1 envelope path, each task's status (proven with its merge commit, parked with its reason or question, blocked with the task it waits on), the stop reason, the integration result (INTEGRATION: pass <sha>, the failing lines, or skipped), the budget spent, and, when the grant allows re-entry, the attempt count from conductor reentry status. The report MUST state which of max_tokens and max_usd were enforced and which were only recorded, as conductor status does, and, when one was enforced, the claimed usage totals and their trust. Name the grant id and each action class the run used. Say whether the evidence gate was on; when it was, give each proven task's evidence paths and verdict agent. conductor trail --out <file> writes the decision trail (per task: dispatch time, owner, worktree, verified commit, reviewer, verdict agent, evidence paths, merge outcome); offer it to the user to commit when the stakes warrant an audit record.

Output style. Write reports and explanations for the user in about 80% ASD-STE100 Simplified Technical English. Use short sentences, common words, active voice and one action per step. This style is for prose to the user, not for the code, prompts or files that this skill makes.

Verify and repair

Before you report, run conductor status and check that every task has a final status and that the FINISH: line printed. Then check the envelope as a receiver would: python3 "$SKILL_DIR/assets/contract_check.py" check-envelope <run-result> --root <repo>. Its claims read CLAIMED, because the conductor produced them; add --rerun to re-run each assertion's one command from the root and see them PROVEN. A mismatch between status and the envelope is a conductor bug: report it rather than editing state.

What the proof is worth

The conductor proves that each task's verify commands passed on that task's own commit, cut from the run branch as it stood when the task started, and that a reviewer passed the same commit. The commands run in a clone under <root>/.skill-contract/runs/…/verify/ that holds only committed files: dependency directories such as node_modules or .venv are absent, so a command that needs them fails unless it installs them or uses tooling installed globally, and a lookup that walks up parent directories can reach the root's own files. Before the push, finish re-verifies the merged run branch: it re-runs every proven task's verify commands on its head in the same kind of clone, so two tasks that each pass alone but break each other once merged are caught there and not pushed. The push sends exactly the commit that re-run verified, and refuses when the run branch has moved since. CI on the pushed branch is still the independent check outside this machine. A plan with weak checks gets weak proof, and the reviewer is the only thing that looks past them.

Cost is bounded in every run, by dispatches and by wall clock: max_dispatches is derived when the grant sets none, and the grant's expiry caps the wall clock at 7 days even without wall_clock_min. Repairs per task and parallelism are bounded too. max_dispatches counts the dispatches the conductor records, including each one resume asks for; a subagent an executor starts against its brief is not counted. max_tokens and max_usd are recorded, and enforced only when the grant's enforce opts in. The runtime does not expose usage to the tool, so an enforced cap counts the usage that the agent claims (usage, trust claimed) or that a user's file adds (trust low). The tool reads no billing API and converts no tokens to dollars.

The run result's assertions are claims. To a receiver they read as CLAIMED, because the conductor wrote the envelope; they become PROVEN when a receiver re-runs them (check-envelope --rerun) or when CI on the pushed branch reports them through a run_url. A rerun runs the one command an assertion carries, in the receiver's own tree: for integration:<head> that is one command, not the whole re-run on the merged run branch.

A grant is the user's recorded yes, but an agent with a shell can forge one, and so can an executor. An executor running as the same OS user can also forge state.json or the log, tamper with the git object store, commit code that reads its uncommitted files by absolute path from outside the verify checkout, or leave a process running after a verify by escaping its process group with setsid(). Push-destination settings in the shared git config can redirect where a push goes, though not which branch it updates, and the push is not forced. The reviewer's diff runs under the same assumptions: its flags neutralise the known config, attribute and replace-ref tricks, but the repository it reads is the executor's. The conductor closes the cheap routes: verify and merge run in isolated clones without the repository's config, hooks or filters, and every conductor git call runs with hooks switched off, so the user's own pre-push hooks do not run on the push either. The rest is covered by the independent reviewer and by CI re-running the checks on the pushed branch. That is why merging the PR stays with the human.

Money ledger

The project can keep a monthly budget in budget/budget.md and a record of what it spends in the git-ignored .skill-contract/ledger/. ledger.py is a separate tool: conductor.py does not read it, and it is not part of a run. A project without budget/budget.md has no ledger. The full reference (the budget format, every command, its output and exit codes) is in references/ledger.md.

Before you propose any spend to the human, in any session and not only during a run, you MUST run the check, because it is the only place the budget's caps and the open reservations are counted:

python3 "$SKILL_DIR/assets/ledger.py" --root <repo> check --id <kebab-id> --category <c> \
  --amount <decimal> --currency <code> --what "<what it buys>" \
  [--month YYYY-MM | --recurring monthly --start YYYY-MM [--end YYYY-MM]]
  • REFUSED: <reason> (exit 3): show the human the reason. You MUST NOT work around a refusal by splitting the spend, changing the id, the month or the category, because each of those hides the same money from the cap.
  • NOT_REFUSED: <id> — the human's approval is still required (exit 0): the proposal now reserves its amounts. Put the proposal to the human and wait for their answer.
  • Exit 2: bad input or a STOP: line. Fix the input, or report the stop to the human.

register, record and withdraw are the human's commands. Each takes --by <their name> and refuses an agent: name. You MUST NOT run them yourself, even when the human tells you the figures, because each one changes what later checks count; give the human the exact command line to run. You MUST NOT edit or delete files under .skill-contract/ledger/ by hand, because each file is what later checks count: an edit can drop a reservation or raise a frozen cap. The log's state digest finds a hand edit of one file, but it has no key, so it cannot find a consistent edit of both.

A paid step found in the middle of a run takes the spend-request flow in "Stop and park rules" (A task that needs to spend money): the controller runs this check, then parks only that task with a one-line request for the human.

No spend. You MUST NOT spend money, buy, subscribe, or start a paid trial, because spend is irreversible and no grant covers it. You MAY draft a proposal for the human.

No payment tools. You MUST NOT call a payment, billing or store tool (for example PayPal or Stripe) to make a spend or to change one, because those calls move real money outside every check. You MAY read a bill or invoice that the human exports.

The budget is the human's. You MUST NOT edit budget/budget.md without the human, because an edit moves the goalposts after you have seen the proposal. The check refuses every proposal while the budget differs from the registered copy, and only the human registers an edit.

No figures to a model. You MUST NOT send budget amounts or spend records to Jev or to any other model, because they are financial data.

The check is not approval. You MUST NOT treat NOT_REFUSED as permission, because the check only finds reasons to say no. Ask the human for each spend.

--today is for the tool's tests. You MUST NOT pass it, because it moves the month that the check counts.

A re-run of check with the same id and fields checks the proposal again against today's caps and spend. It can now print REFUSED (a cap was cut, or a record pushed a month over). The reservation stays; show the human the reason. An open-ended recurring proposal prints NOTE: open-ended; reserved only to YYYY-MM: tell the human that the ledger counts nothing for it after that month.

The request line of a spend request, amount included, goes into the run log, the run-result envelope and the PR body, so anyone who can read those sees it. It is never sent to a model (see "No figures to a model").

The ledger's limits: recorded spend is a claim, and --by names are self-declared. The committed budget file shows the budget to anyone who can read the repository. The tool cannot see spend that nobody records. The state digest has no key: deleting both state files, or editing both consistently, is not detected.

Contract

This skill follows skill-contract v1. It consumes a https://github.com/dhanesh/agent-skills/skill-contract/task-plan/v1 envelope from any skill that provides one, and an https://github.com/dhanesh/agent-skills/skill-contract/autonomy-grant/v1 that covers it. It provides a https://github.com/dhanesh/agent-skills/skill-contract/run-result/v1 envelope; the payload schema is assets/schemas/run-result.v1.json. Its assertions are one passed verify:<task> per proven task, carrying that task's first verify command. An integration:<head> assertion is added when the re-run on the merged run branch ran a command (passed or failed), or as untested when the grant asked and a task is proven; there is none when no task is proven. A receiver sees the passed ones as CLAIMED until it re-runs them.

{"provides": ["https://github.com/dhanesh/agent-skills/skill-contract/run-result/v1"], "consumes": ["https://github.com/dhanesh/agent-skills/skill-contract/task-plan/v1", "https://github.com/dhanesh/agent-skills/skill-contract/autonomy-grant/v1"]}

Boundaries

  • Not the planner. The spec, the plan and the grant come from spec-first-planning.
  • Not the loop designer. Designing a loop, or auditing one, is crafting-self-prompting-loops.
  • Not the verify skill's author. A feature with no map entry parks; verification-skill-forge writes and maintains the verify skill.
  • Not a merger. The conductor merges tasks into its own run branch only. You MUST leave merging the run branch or the PR into the default branch to the human; a grant cannot cover merge.
  • Not a project spend governor. A grant that opts in gets run token and dollar caps, enforced from claimed usage reports. The money ledger only refuses: it never approves a spend, and spend stays an ask-class action that no grant covers.