execute
Run an approved ac plan to completion, wave by wave, with cost-tiered workers, per-wave verification and a final review. Loaded by /ac/execute; the request carries a plan slug or path plus flags.
SKILL.mdopencode/ac/skills/execute/SKILL.md
GitHub<!-- ported-from: plugins/ac/skills/execute/SKILL.md sha256:f804207e82454f6f38991fa849456dfb5fb62f0bc7c81cd8ced9a23593b7e4f9 -->
/ac/execute
Executor that runs an approved plan to completion, wave by wave, and gates the deliver with a final code-review.
Plan: the request this skill was loaded with. /ac/execute passes the user's argument text (a plan slug or path, plus flags); the plan skill's auto chain passes <slug> --auto; the ac/lane agent passes <bundle-id> --lane --max-parallel <N>. Skills take no arguments, so that request text is the whole input.
Standing rules
These hold for the whole run, including after a compaction, which drops the loaded skill body (while you own a live marker the ac plugin re-injects a fixed copy of these bounds into every request and asks you to load this skill again, ../../src/run-guards.ts). Everything below this block is procedure; these are the bounds.
Turn termination. Your turn ends on exactly one of: a question tool call, the Phase 4b execution summary, a named BLOCKER from <auto_mode>, or a one-line wait status while background subagents or shells you started still run (each completion notification starts your next turn; never wait with a sleep or polling loop). Nothing else ends it. Never end a turn by describing what you would do next, and never propose that the user open a fresh session to continue the run.
Under LANE_MODE (set by --lane: this run is an ac/lane session, which has no question tool and whose coordinator sees only its last message of each turn) the legal turn end is the lane status block defined in ../coordinate/references/lane-protocol.md, and every turn ends with one. status: WORKING replaces the one-line wait status while workers run, status: BLOCKED replaces question at every BLOCKER (see <auto_mode>), status: DONE ends Phase 4b, and status: FAILED ends a halt that has no option to offer (plan not found, a truncated plan, a count mismatch). A lane never calls question, never pushes and never loads the qa skill. A PAUSE message can arrive mid-turn: from then on spawn no new worker and launch no new step, let the workers already running report, run Layer A to D on the steps they finished (commit the wave only when all of it verified), leave the rest unchecked, delete nothing, set "paused": true in the marker so a compaction meanwhile does not restart the steps, and end with status: PAUSED; RESUME removes that field and continues from the plan's unchecked steps.
Every branch that terminates the run deletes this run's marker, .ac/state/execute/<slug>.json, first, and leaves every other slug's marker alone: while a marker this session owns exists, no subagent of this session is running, and your turn ends, the ac plugin's stop guard sends a synthetic continuation that names the unchecked steps from the plan file and tells you to continue (../../src/run-guards.ts). It sends at most one per stall (your next tool call ends the stall) and three per user prompt, and a user interrupt silences it. The marker's absence is what lets a terminal stop stay stopped.
A failed subagent moves down its model chain; it is not a question. A subagent call that comes back with a provider failure (Subagent failed (sessionID: ...), a <subagent ... state="error"> message, an error such as provider.invalid-output) or with no answer at all (Subagent completed without a text response., an empty report) failed on its model, not on the work. Recover by continuing the same child, not by a fresh spawn: call the subagent tool again with the same agent, sessionID: "<the sessionID from the failure text>" and the prompt Your last turn stopped on a provider error. Continue the task from where you left off without repeating finished work., so the child keeps everything it already read and wrote (a fresh spawn repeats all of it). When it answered nothing or broke off mid-stream (provider.invalid-output, an empty report), continue it on the same model until it has run retryAttempts times there (from the ac_models tool, 3 in the shipped config), since that is often a one-off; a 5xx was already retried inside the call, so it goes straight on. Then call ac_fallback_next({ tier: "<the agent name without ac/>", tried: [<every model this call ran on>], session_id: "<the sessionID from the failure text>", status: <the HTTP status, when the error carried one> }), with tried starting at the agent's chain head from ac_models unless you set its model yourself, continue the same child with model: "<the returned value>" as well (the child switches to it and keeps its context), and give that model the same number of attempts. A rate limit was retried 10 times inside the call, and the plugin gives one model 30 across continuations: wait:<seconds> means that model has retries left, so wait that long with one shell sleep and continue the child on the same model with tried unchanged. The tool bounds those waits itself. Start a fresh spawn with the full prompt only when the continuation is refused (Subagent session not found, is not a child of the current session) or the child's context overflowed. Only none, every entry of the chain tried, is a failure to report or ask about. Asking the owner whether to retry wastes a round on a provider fault the chain exists to absorb. A plan worker follows 2e, which is this rule plus the tier ladder; this rule covers the reviewer and ac/oracle at Phase 3. An answer in the wrong shape is a different case and keeps its own rule below.
Context. Compaction summarizes older turns and the run continues. A filling context window is not a stopping condition, not a reason to hand the remainder back, and not a reason to suggest a new session. No compaction tool is available to you, so never plan around invoking one. When the procedure you need has been truncated away, load the skill execute again with the skill tool to restore this body, then read PLAN_PATH for the authoritative step state.
A stop needs a name. "I cannot verify this properly in the remaining context" is not a reason. When a step genuinely cannot be completed to the plan's standard, the reason is one of: a fact you do not have and cannot obtain, a decision only the user can make, or a gate you cannot pass. Each maps to a BLOCKER branch (2i, 2j, 3c) that surfaces a question and deletes the marker. Name the class, take the branch, report what did land. Never substitute a capacity limit for the real reason.
No review loop needs bounding. Phase 3 is one reviewer pass and the findings are yours to filter. Five bounded loops remain: at most two retries per step at 2e (a variant rung, then a tier rung), counted in WORKER_RETRY_PER_STEP; at most two briefing-gap re-spawns per step at 2e; the provider-fallback re-spawns at 2e, which end when the tier's model chain does (plus at most ten wait: re-spawns per step), bounded by the tried list you pass to ac_fallback_next; the three-failed-steps-across-two-waves halt at 2j, read from STEP_FAILURES (one entry per step at terminal failure); and the one QA retest that the qa skill runs and counts after its own fixes at 3e, so 3e never re-invokes it.
Progress surface. Two surfaces carry it and neither is a tool. The plan file's checkboxes are the per-step record, ticked at Layer D and counted with grep -c '^- \[ \]', which is also what the stop guard reads. Phase 2h prints the per-step table after each wave. Add one short line per phase and wave transition and that is the whole picture. Do not write a procedure that depends on opencode's todo tool, which is off unless an experimental flag turns it on.
Output length. Per-turn user-facing prose: at most 3 lines. The wave summary at 2f: at most 3 lines. Filter tool output before it lands: a passing test suite through tail -20, a diff scoped to the wave's files. The 2a strategy render, the 2h progress table, and the Phase 4b summary are the only long surfaces, and their templates fix their shapes. Anything a later reader needs goes in wisdom.md or report.md, not into the chat. Every token you write is re-read on every later turn; a file is read on demand.
plan.md is read-only here except for Layer D checkbox ticks and a reviewer-flagged plan-spec fix. If the plan is
wrong, report and stop. Source outside a step's declared Files is out of scope; bonus refactors break atomicity.
</scope>
There is no language server in opencode. Type errors come from the project's typecheck command at Layer A and from
the <diagnostics file="..."> blocks the ac plugin appends to edit, write and patch results for the file types
it has a checker for; callers and duplicates come from grep.
Subagents run in child sessions and inherit none of your context, so every worker gets the full six-section
briefing, its shared blocks in briefing-common.md (2b). Drive every chain from here (the agent reports back and you make the next call): the plan-workers'
permissions deny subagent, and the code reviewer and ac/oracle have it denied.
</capabilities>
| Call site | Class | Under AUTO_MODE = true |
|---|---|---|
| 2i Dep failed? | BLOCKER | surfaces |
| 2j Halted? (3 failures spanning 2+ waves) | BLOCKER | surfaces |
| 3c plan-spec issue | BLOCKER | surfaces |
| Wave checkpoint commit failed | BLOCKER | surfaces |
| Verification failed on a step a later wave needs | BLOCKER | surfaces |
When .ac/state/active-auto.json owned by this session (its session_id is this session's root_session_id) appears mid-run (ac/auto adopted the run), keep running in context with AUTO_MODE true and do not load yourself again. While that marker is live the BLOCKER rows above do not surface either: record the block under ## Blocked in the marker's decisions file, skip the blocked step and the steps that depend on it, and keep every independent wave going. The final commit's --no-push keys on that file (Phase 4a); ac/auto pushes after its gate when the user named the push.
LANE_MODE implies AUTO_MODE. Under LANE_MODE no gate calls question: every BLOCKER row, plus each other site below that names one (the 1g and 2c plan-spec branch, the third briefing gap at 2e, 3c, and the 2f surface-first patch, all class 3c), ends the turn with a status: BLOCKED block. Its blocker carries the class from lane-protocol.md (2i, 2j, 3c or commit), the question, the options the question call would have offered as single-token labels, and the recommended label. The marker stays, because the run resumes rather than ends. A RESOLVE <label> message continues as if the user had chosen that label, including that option's own marker handling: an option that stops the run deletes the marker and ends with status: FAILED.
BLOCKER gates surface whatever the mode,
because each needs judgment auto mode cannot supply. Before surfacing one, emit a line naming which class fired.
Outside an away run, a BLOCKER waits for the user's answer and never picks an option on its own. AUTO_MODE stays set through a BLOCKER
unless the user picks an option that stops the run.
Heartbeat: one short line per phase, wave, and iteration transition. </auto_mode>
<bootstrap> Nothing to load and no task list to register (see Progress surface). Begin at Phase 1a. </bootstrap>Phase 1: Load Plan
1a. Parse arguments
- Strip
--autoif present:AUTO_MODE = true, per the<auto_mode>policy: halt only on BLOCKER classes. - Strip
--laneif present:LANE_MODE = true. Set by theac/laneagent that/ac/coordinatedispatches. ImpliesAUTO_MODE = true,NO_QA = true(parallel lanes would collide on dev-server ports) and no push at 4a. - Strip
--max-parallel Nif present:MAX_PARALLEL = N, the cap on workers running at once within a wave (2c). Without the flag,MAX_PARALLELismaxParallelfrom theac_modelstool (1c), 3 in the shipped config: a conservative default, since the gateway's concurrency limit is unknown and each worker turn spends several requests and a share of the key's balance. - Strip
--no-oracleif present:NO_ORACLE = true. Skips theac/oraclespawn at 3b. - Strip
--no-qaif present:NO_QA = true. Skips the Phase 3e QA pass whatever the plan's**QA**line says. - Strip
--no-checkpoint-commitsif present:NO_CHECKPOINT_COMMITS = true. Disables wave-after commits; Phase 4 final commit still runs. - Resolve the remaining argument to
PLAN_PATH:- If it contains
/or starts with.ac/, use as full path. - Otherwise treat as slug:
.ac/plans/<slug>/plan.md.
- If it contains
- If
PLAN_PATHdoes not exist: printPlan not found at <path>. Run /ac/plan first.and stop. - If
AUTO_MODE = true, emit one user-visible line:Auto mode engaged. Will run end-to-end, halting only on BLOCKER classes (Phase 2i dep-failed, Phase 2j 3-strike, Phase 3c plan-spec issue, error-handling halts).
1b. Read and parse the plan
Read PLAN_PATH in full and hold: the frontmatter (Steps, Waves, Codebase State, Generated, QA), ## Research Summary, ## Codebase Conventions including the TDD field,
## Reuse Map, ## Work Objectives (Core Objective, Concrete Deliverables, Definition of Done, Must Have,
Must NOT Have), ## Execution Strategy with its Dependency Notes, every step in ## Steps with all its fields,
and ## Risks Accepted.
Set QA_ENABLED = true only when the frontmatter carries **QA**: true; an absent line means false. Read the line from
the frontmatter only (the text above the first ## heading), because a step's own **QA**: field can sit at column
zero in flat-style plans.
1c. Tier routing and escalation
| Tier | Subagent | Model chain (from ac_models) |
|---|---|---|
quick |
ac/plan-worker-quick |
tiers.plan-worker-quick |
junior |
ac/plan-worker-junior |
tiers.plan-worker-junior |
junior-high |
ac/plan-worker-junior-high |
tiers.plan-worker-junior-high |
senior |
ac/plan-worker-senior |
tiers.plan-worker-senior |
Call the ac_models tool once here and hold each tier's chain, plus the oracle and plan-code-review chains for
Phase 3, its groups and its maxParallel. Read the routing from the tool, never from config/models.jsonc, which
the plugin options of an install can override.
The head of a chain is the agent's own model, written as provider/model#variant, so an attempt that omits
model runs on it; the entries after it are what ac_fallback_next walks at 2e.
junior-high shares junior's head model and variant in the shipped config, for work at the borderline of coupling
or context depth. The criticality rule never routes there; it escalates to senior.
Pass the subagent tool's model parameter on exactly two spawns, the 2e provider-fallback re-spawn and the 2e
variant retry; this skill is the explicit instruction its description asks for. Every other spawn omits model and
runs on the agent's own.
When the plan's Codebase State is legacy or chaotic, route every quick step to ac/plan-worker-junior
whatever its declared tier: mechanical work in an inconsistent codebase is not mechanical. The plan file is not
modified; this is an in-memory routing decision. Record the count for the Phase 4 report.
1e. Initialize execution state
ACCUMULATED_WISDOM = [] # max 15 items total, max 5 added per wave
MODIFIED_FILES = [] # tracked across waves; passed to Phase 3
STEP_FAILURES = [] # one {step, wave} per step at terminal failure; 2j asks whether they span 2+ waves
WORKER_RETRY_PER_STEP = {} # retries spent per step (variant rung, tier rung), max 2
Then write this run's marker, .ac/state/execute/<slug>.json (the plan slug, characters [A-Za-z0-9._-] only; the
plugin ignores any other name), which the ac plugin's file-scope guard, standing-rules injection, compaction recovery
note and stop guard read, all keyed on harness and root_session_id. Call the ac_session tool first; it returns
session_id and root_session_id as JSON. Each running plan owns its own marker, so another slug's marker is another
run sharing the checkout, not a conflict. When this slug's marker already exists, is owned by another session (a
harness or root_session_id other than yours) and has a started_at under 24 hours old, another session is running
this plan: say so in one line and stop without writing (under LANE_MODE, with status: FAILED), because two runs
ticking one plan's checkboxes corrupt its state. An older one, or one this session owns (a resume), is overwritten.
Fields: slug, session_id and root_session_id (copy exactly what
ac_session returned, never derive or recall them; the root id is what scopes every guard to this run),
harness (exactly "opencode"; without it the plugin reads the marker as Claude Code's and ignores it), lane (only under LANE_MODE: exactly true, so the stop guard leaves the nudge to the coordinator, the lane's supervisor; omit the field otherwise), started_at
(24-hour age bound; take it from date -u +%Y-%m-%dT%H:%M:%SZ, never from your own sense of the time, since a local
time with a Z reads as the future), current_wave, wave_files, note. Schema and per-field reasoning at
references/execution-state.md.
Lifecycle: written here, refreshed at 2c and 2f, deleted at 4a and on every branch that ends the run early. Every read, refresh and delete in this body names this run's own file and never touches another slug's.
Also keep the output of one git status --porcelain taken now as BASELINE_DIRTY: 2d never restores a path that was
already dirty before this run started, since it may belong to another run or to the user.
.ac/state/active-auto.json may coexist beside it. That marker belongs to ac/auto, not to this skill: never
delete it, and read it only at Phase 4a, where it counts only when it names this session.
1f. TDD mode
Read the plan's ## Codebase Conventions for **TDD** and set TDD_MODE: "tdd" directs each worker to write the
failing test first, "tests-after" to write tests after implementation for any behavioral change, "none" to write
tests only when a step's Done when demands testable behavior. A missing field defaults to "none" and gets noted
in the Phase 4 report. The value is injected into every worker briefing.
Read project CLAUDE.md and CLAUDE.local.md for typecheck, build, test, and lint commands as RUNTIME_CONTEXT.
Workers receive the project instructions (AGENTS.md and the configured instructions files) but never this skill's
workflow rules, so briefings cite those commands explicitly.
1g. Confirm the progress surface
No list to register. Read Waves and Steps from the plan frontmatter and hold both: Steps is what every
Layer D count gets compared against, and WAVES is how many barriers the run will pass. State both in the
Phase 2a render.
Then run the shape gate once:
shell: node "$AC_CLI" plan-check <PLAN_PATH>
AC_CLI is set in every shell by the ac plugin and names the ac CLI installed with it; never substitute a path of your own, since a pinned install and the repository's working tree can differ. It prints the step counts on every exit and, when the plan deviates from what the rest of this body parses, one
line per deviation. Route by what it reports, taking the first route below that matches, except that a BLOCKER route
always wins over a continue route on the same step:
- Exit 2: the plan file is not where you looked. Re-derive
PLAN_PATHfrom the argument and try once; if it still fails, say the path you tried and stop. - Exit 0: continue. Hold the step counts it printed for Layer D; on a resume the unchecked number is what is left to run.
All <N> Step N headings are present, so the step lines are missing their prefix: repair, do not stop: only the checkboxes are absent, and without them Layer D and the stop guard have nothing to count. Insert one- [ ] **Step N**: <the heading's own title>line per step withedit, keeping the space after the bracket because the stop guard matches it, then re-runplan-checkand say in one line that you repaired it and how many lines you added.step(s) are absent from the body rather than merely unticked: the plan is truncated, not unticked. Do not invent checkboxes and do not correct the frontmatter down to what survived. Say how many steps are missing and stop.- A worker step with no
Tier, or a verification step with noCommandsorEvidence: a plan-spec defect; do not pick a tier yourself, since that is the planner's cost decision. Take the 3c plan-spec BLOCKER branch, naming the steps and what each is missing. This wins over the next route: routed on its fields, a step with an unrecognisedTypeand noTierreads as a verification step and its code never gets written. - A
Typeoutside the three, on a step this list has not already blocked: route on the step's fields instead of its label, and say in one line which steps you re-read and as what. A step carrying aTieris a worker step; a step carryingCommandsandEvidencewith noTieris a verification step.implementationmaps tocode. - A missing
**QA**:line as the only ERROR (plan-check printsno+ the field +line): the plan predates the field. Continue withQA_ENABLED = false, as 1b already reads an absent line, and say so in one line. - Any other ERROR (a missing
Files,Description,QAorMust NOT, a leftover placeholder, a missingAuto modeline): a plan-spec defect, since the briefing inlines four of those five fields verbatim. Take the 3c plan-spec BLOCKER branch and name the steps and fields. - A count mismatch the ticks do not account for: the frontmatter and the body disagree about how many steps exist. Say which two numbers you got and stop; every later Layer D comparison rests on this one.
WARN lines never gate the run. Say how many there were in one line and continue.
Phase 2: Execute Wave-by-Wave
Goal: run each step to verified completion, wave by wave, on auto-continue. The user does not approve each step.
2a. Present execution strategy
Render the wave breakdown once using the shape at references/wave-orchestration.md under
## Phase 2a execution-strategy render.
Then start Wave 1 in the same turn. There is no confirmation gate: typing /ac/execute is the consent, and the
plan was approved in the plan skill. Auto-continue applies until Phase 4 or a BLOCKER.
2b. Worker briefing template (the 6-section prompt)
Every worker invocation receives the 6-section briefing. For the exact template (with VERBATIM/DERIVED field annotations), read references/worker-briefing-template.md.
The briefing is the worker's whole world. The worker does not read the plan, so Section 6, with briefing-common.md,
carries the step's pattern references, the codebase conventions, the invariants it must preserve and the plan-wide
guardrails. Assemble all four from the plan you are holding.
Write the shared blocks once. Before Wave 1's spawns, write .ac/plans/<slug>/briefing-common.md with the
blocks that are identical for every step, per the template's ## briefing-common.md section: Runtime Commands,
Codebase conventions, the Core Objective and the plan-wide guardrails, all verbatim. Write it once per run (a
resumed run overwrites the previous run's copy, since the plan may have changed) and do not repeat those blocks in
the per-step briefings. Each per-step briefing opens with a line telling the worker to read that file by absolute
path, then carries only the step-specific sections. 20 of 100 measured plans did this unprompted and 206 worker
runs read such a file, so the worker reads it reliably and the orchestrator stops paying for the same blocks once
per step.
Resolve every sibling-step pointer before you send it. Wherever the step's Description, QA or Must NOT
names another step by number ("call Step 4's parser", "same constraint as Step 10"), replace the pointer with what
the worker actually needs: the sibling's Files path and a one-line statement of the contract, or the file:line
the thing will live at. A forward pointer to a step that has not run yet is the dangerous case, because there is no
source to fall back on.
Length rule: a per-step briefing and briefing-common.md together under 30 lines is too short; under-spec'd
briefings produce drift. The contract fields go in verbatim, in the per-step briefing (<constraints>).
2c. Launch workers in parallel within the wave
Refresh this run's marker first: current_wave to this wave's index, wave_files to the union of every absolute path
in this wave's steps' Files. The file-scope guard lets a worker edit exactly that set, so the union has to be
complete before any spawn.
Route on Type: code and infra spawn a tier-routed worker; verification does not spawn. Run its Commands
directly via shell and capture to its Evidence paths. For a verification step Layer A blends with your shell output,
Layer B is largely n/a, Layer C is the evidence file, and Layer D still applies. A Type outside the three was
resolved at Phase 1g by reading the step's fields; use what 1g decided rather than re-deciding per step.
Check invocation reachability before the wave launches. When a step's Description tells you to run a slash
command, remember that no tool of yours types a command: you reach the skill it attaches through the skill tool.
Read that skill's frontmatter (not a grep of the whole file, since several skills discuss the flag without setting
it): disable-model-invocation: true means only the user can trigger it. When nothing you hold reaches it, take the
plan-spec BLOCKER branch in 3c and say which command and which step. Do not quietly substitute executing the
command's body yourself: that tests the procedure, not the dispatch the step claims.
Spawn every code and infra step of the wave in one response, one subagent call each:
subagent({ agent: "ac/plan-worker-<tier>",
description: "Step <N>: <short title>",
prompt: "<the six-section briefing>",
background: true })
Set background: true on every call unless the wave is a single quick or junior step, which may run in the
foreground and return its report in the same response. A background call returns at once with the child's
sessionID. Wait for all of them before verifying any, by ending the turn with a one-line status; when a completion
notification arrives while others still run, end the turn again. Never wait with a sleep or until loop, a
file-stability check, or repeated reads of evidence files; the stop guard stays quiet while a subagent of this
session runs. Do not spawn one step, verify it, and then spawn the next: a wave whose steps share no files has no
reason to serialize. A wave the plan declares as an ordered track (its Execution Strategy says the steps
must run in sequence) is the one exception, and there the steps run one at a time in the declared order.
With MAX_PARALLEL set and fewer slots than steps, the first response spawns that many steps in the wave's declared order, in the background, and each completion notification that arrives spawns the next queued step before the turn ends; verification still waits for every step of the wave.
Name the wave's steps in one line before the spawns.
2d. Wave verification (4-layer, runs once per wave)
Every worker in the wave has returned. Now verify, once, for the whole wave. You are the QA gate. A worker's report is a claim, and automated checks alone do not confirm it.
Confirm no mutation survived. Run git status --porcelain in the same response as the diff and the
Layer A commands; it does not depend on their results and they do not depend on its.
The allowed set is wave_files (this wave's declared union, from 2c) plus MODIFIED_FILES (earlier
waves) plus anything under .ac/, plus the wave_files of every other marker in .ac/state/execute/ and every
path already dirty in the git status --porcelain you took at 1e: another run may share this checkout, and its
files are not yours to restore. A dirty path outside all of these is an unreverted mutation or an
out-of-scope edit, typically through shell, which the file-scope guard cannot see (it gates the edit permission
that edit, write and patch share): restore it from git, and record it as a
[REMEDIATION] Step <N> <tier>: <what you restored> wisdom line. Compare against wave_files, not against
MODIFIED_FILES alone, which is only appended at 2e. A worker's temporary patch inside its own Files passes this
check; the diff shows whether it survived.
Then take the wave diff, which is Layer B's input:
shell: git add -A -- <wave_files> && git diff --cached -U8 -- <wave_files>
Stage first, and diff the index: a plain git diff shows nothing for a file the wave created, because an untracked
path has no committed side, so every created file would be invisible to Layer B and every claim on it a false
"claim with no hunk". Staging does not commit; 2g still decides that.
Who runs what, the per-ecosystem commands and the diagnostics rule are in references/verification.md.
This barrier is mandatory: with no per-step checks, it is the only place a failure surfaces.
Issue the wave's independent actions in one response. The mutation check, the diff, the typecheck, the build, the test run and the linter are one response with six tool calls, not six turns. Same for the wave's checkbox ticks in Layer D, and for the QA scenarios in Layer C that touch different surfaces: only calls issued together cut the turn count. Serialize only where one call's output decides the next one's arguments.
Layer A: Automated
Layer A authority: no language server runs in opencode, so the typecheck is always a command. When the changed
files sit under a sub-project root (its own package.json AND tsconfig.json, and not the orchestrator's cwd), that
sub-project's own commands count for the typecheck, the build and the tests, run inside the sub-project dir
(cd <sub-project-root> && bun run tsc --noEmit, its own typecheck or package.json scripts, or the language
equivalent). A typecheck run from the outer root against those files cannot resolve the sub-project's deps, so what
it reports for them is boundary noise. With no sub-project boundary, the project's typecheck from RUNTIME_CONTEXT
is authoritative.
Run the project-wide static analysis once for the wave (PHPStan,
tsc --noEmitortsc -b,flutter analyze; sub-project local per the authority rule above), and read the<diagnostics file="...">blocks the ac plugin appended to the edit results you and the workers saw (workers quote theirs under Verification). Those blocks carry per-file checkers only (for examplephp -l, the project's PHPStan whenvendor/bin/phpstanexists, andvendor/bin/pint --teston.php,dart analyze --fatal-infoson.dart); a TypeScript typecheck never runs per edit, so the wave typecheck is its only run. It is the one project-wide check a wave keeps, because a per-file analyzer cannot see a caller that a changed signature broke. When the project has no project-wide analyzer (a Laravel app without PHPStan, plain JavaScript), add to item 3 the tests of the callers of every public symbol the wave modified (grep the definition name and every import path, then read each hit), or run the full suite for this wave.A
<diagnostics>block is a hint, not a result: the plugin never hears about changes made byshell, git or a formatter, and withoutvendor/bin/phpstanan absent block means syntax and style are clean, not that types and symbols are. Before you act on one or call it stale, run the file's CLI analyzer (references/verification.md, "Diagnostics are a hint").Classify every diagnostic before acting on it:
- Transient: a
Cannot find modulefor a dependency an install-bearing step of this wave adds, or a forward reference to a symbol a sibling step of the same wave creates. Re-run at the wave barrier; one that survives the install or the producer step is a real error. - Persistent false positive, never blocks: framework globals registered at runtime that a static checker
cannot see (Pest's
it/uses/expect/beforeEach/test, bun-test'sdescribe/it/expect, Cypress'scy, Vitest'sviwith auto-globals, Vue'sdefineProps/defineEmits, Nuxt auto-imports, Rails view helpers); the sub-project boundary noise above; and'await' has no effect on the type of this expressiononawait expect(...).rejects.toX(...)or.resolveschains, which the test runner's exit 0 confirms (never remove theawait: that breaks the async assertion). Note each class once per run in the report, not per step. The plan's false-positive whitelist field in## Codebase Conventions, when present, is the authoritative skip list. - Real error: anything else. It routes to Phase 2e.
WARNING severity (regardless of class) is logged in Issues and continues.
- Transient: a
Run the project's build command (from
RUNTIME_CONTEXTorCLAUDE.md). Exit code 0 required.Run the format check and the linter on the wave's touched files, and the tests related to them (the tests the workers wrote or edited, plus the tests that cover the changed source), once, for the wave, in parallel. The commands per ecosystem are in
references/verification.md. Do not run the full suite or a repo-wide lint here; Phase 3 runs them once. Verify once; do not re-run a check that already passed to build confidence. All selected tests must pass. A failure in a test the wave did not touch counts as pre-existing only after you saw it fail without the wave's change, or the project records it as known; name it under Issues either way.Filter output as the Output length rule says. A pipe hides the runner's exit code behind
tail's, and the agent shell is zsh, where${PIPESTATUS[0]}is empty, so run a judged command asset -o pipefail; <command> 2>&1 | tail -20, or as<command> > "$TMPDIR/run.log" 2>&1; echo "exit=$?"; tail -20 "$TMPDIR/run.log", and judge the exit code, never the last line of output. On failure, admit the failing cases and nothing else. A failure the wave's checks catch that no single step explains is a cross-step interaction, which routes to remediation below rather than to one step's retry.
Layer B: Manual Code Review (read the wave diff, do not skip)
This is the layer you are most tempted to skip. Do not skip it. Review the diff rather than re-reading whole files: against a worker that overstates what it did, the delta itself is the stronger instrument.
Read the wave diff taken above, hunk by hunk. A file this wave created is already in it whole, as added lines, so it needs no
Read. When the diff comes back as a persisted preview (Output too large ... Preview), read the saved file in windows before reviewing; the preview is the first 2KB, not the wave. Read beyond the diff only on one of these three triggers, which are the whole list:- the file is under 150 lines, where reading it whole costs no more than reading its hunks;
- the diff carries deletion hunks, where what was removed matters as much as what replaced it;
- the step declares a contract in its
Referencesthat the hunk appears to change.
Outside the 150-line case, read the region around the hunk with
Readoffsetandlimit(about 60 lines each side), not the whole file: everything you read stays in your context for the rest of the run. "When it looks ambiguous" is not a trigger. If you find yourself opening files outside this list, the plan'sFileswere wrong and that is a finding, not a reason to read more.For each hunk:
- Does the logic actually implement the step Description?
- Are there stubs, TODOs, placeholders, hardcoded values that the step did not authorize?
- Are there logic errors or missed edge cases evident from the data flow?
- Does the change follow the plan's Codebase Conventions and
my-coding? - Are imports correct and unused imports removed?
Attribute every hunk, file first. Attribution is by file: each hunk belongs to the step whose
Filesdeclares that path, which is deterministic from the plan. Fall back to the workers'path:start-endclaims only when two steps of the same wave share a file. Line ranges cannot carry attribution on their own: concurrent workers shift each other's ranges,-U8merges nearby regions into one hunk with two claimants, and nothing bounds a claim's width.Then check the claims against the diff. Three outcomes, and the first two fail the step:
- a hunk in a file no step declares: an out-of-scope write that only this check sees (the file-scope guard gates on the wave's union). Treat as failed and route to 2e.
- a claim the code contradicts: the worker described something it did not do. Treat as failed.
- a claim with no hunk, or a hunk no claim mentions, inside a file the step does own: a reporting gap, not a code defect. Record it and continue; a formatter the worker ran leaves exactly this.
Run the two checks the diff cannot give you, because duplication lives in files you were never going to open: one repo-wide
grepfor the name of each newly exported symbol, which lists its callers and import sites, and one for each new function name. They catch a second definition of something the wave just wrote.If you cannot explain what each hunk does in one sentence, you have not reviewed it. Read again.
Cross-file consistency check (mandatory whenever the wave produced two or more files that share an interface). It also covers the diff's known weakness, that a hunk does not show what the surrounding code now does, so it is not optional just because the diff read quickly. Apply it to every shared-interface boundary the wave's files declare or consume, not just the first. The seven boundaries, each with the concrete failure it catches, are at
references/cross-file-review.md: shared data shapes, URL and path composition, component and function name match, template engine interop, front-matter is data not template, asset paths, link target reachability. Read that file at the first wave where the check applies.
Layer C: Hands-on QA (per step, run here at the barrier)
This layer stays per-step: each step names its own scenario and evidence path. Run every step's scenario here, in one pass over the wave, rather than between spawns.
Skip the scenario for any step Layer B already failed: its code is about to be retried. Run it after the retry instead, alongside that step's re-verification in 2e.
When the step's QA field names a tool, run the scenario and gate it on four checks:
- Reproducer-validity: one command, fails on HEAD before the change (for a fix or regression step), deterministic across 3 runs, no external service that can flip the result. Mark a dimension n/a rather than skipping it.
- Evidence, not assertion: record the command and its output, or an artifact path. A bare "verified" is not evidence.
- Lowest layer that proves it: a unit test beats an integration test beats an end-to-end run when all three would prove the same thing. Escalate only when the lower layer cannot reach the behavior.
- Browser as a human user: for any UI-touching step, walk it through the browser (navigate, interact, assert on
rendered state), not just
curl.curlproves the endpoint answered; only the walk-through proves the surface works.
Capture to .ac/plans/<slug>/evidence/<step-id>-<scenario>.<ext>: .png for a browser screenshot, .json for a
curl body, terminal output for a CLI or test run. Steps with no QA field, or QA: none, skip this layer.
Layer D: Plan state check (per step)
Run each step's provable Done when criterion first: the one command it names, batched into the same
response as the ticks. These are greps and single targeted assertions, not scoped suite runs; running them is
what stops the tick from being a claim.
Tick each verified step's checkbox from - [ ] to - [x] with edit, one edit per step. Confirm the wave's
ticks landed with grep -c '^- \[ \]' <PLAN_PATH> and check the number against what you expect, which is
the plan's total step count minus every step ticked so far. Do not re-read the plan to check: you already hold it
from Phase 1b.
The tick stays per-step rather than one edit per wave: the stop guard's continuation lists every - [ ] line as an
outstanding step (../../src/run-guards.ts), so batched ticks would send you to re-run steps that already finished.
The tick is also the only durable record of which steps inside a wave finished.
2e. Verification outcome routing
Verification runs per wave, so route per step off what Layer B attributed. A wave-suite failure or a Layer B finding belongs to the step whose claimed hunks explain it; a failure no step's hunks explain is a cross-step interaction and goes to 2f remediation, not to a retry.
All four layers pass: append the wave's files to MODIFIED_FILES and continue.
Worker hit a provider error: the subagent call came back with a provider failure instead of a report (a rate
limit, an overloaded or unavailable model, a 5xx, or a child session that failed before it wrote ### Changes Made).
The step did not fail; its model never got to work. Call:
ac_fallback_next({ tier: "plan-worker-<tier>", tried: [<every model this step has run on>], session_id: "<failed worker's sessionID>", status: <error status> })
tried holds each model as provider/model#variant, starting with the agent's own (the head of its chain, 1c) and
adding every fallback you have spawned for the step since. status is the HTTP status the provider error carried
(429 for a rate limit); omit it when the failure named none. Pass it every time: a 429 is a limit that clears on its
own, and only with the status does the tool keep the step on the same model until that model has spent the plugin's
rate-limit schedule. The tool returns the next chain entry that is not tried, not
cooling down after a recent failure and on a provider with a credential, or wait:<seconds>, or none. On a
model, continue the failed worker rather than spawning a new one: the same agent, sessionID: "<its sessionID>",
model: "<the returned value>" and the continue prompt from the failed-subagent rule above, so it keeps the files
it read and the edits it made (a fresh spawn with the full briefing only when the continuation is refused). Add the
model to tried, and take the same route on another provider error. Every entry joins tried, so the loop ends within the chain's
length. These re-spawns are
not retries: they do not count in WORKER_RETRY_PER_STEP and keep the step on its current rung. On none the
tier's chain is exhausted: count it as the step's failure and take the tier rung below directly, because the variant
rung would re-run a model that is not answering; for a senior step it is terminal. The tier-rung spawn starts a fresh
tried on its own tier's chain.
wait:<seconds> comes back only on a 429 while the failed model has not yet spent the rate-limit schedule (30
retries in the shipped config; each call runs 10 inside it, so two waits cover it). The continuation carries the
count on, and once it is spent the tool answers the next chain entry instead. Wait that long in one
shell call (sleep <seconds> with the call's timeout above it), then continue the same worker on the same model
the same way, leaving tried as it is. A wait is not a step failure and not a retry: it adds nothing to
WORKER_RETRY_PER_STEP or STEP_FAILURES and keeps the step on its rung. The tool bounds the waits per model (two
in the shipped config, more when a worker meets a second throttle after a clean stretch), so take its answer each
time; only as a guard against a loop, treat the answer as none once one step has waited ten times. Only none
counts as the step's failure.
Worker reported [BRIEFING GAP]: it could not proceed because something Section 6 should have carried
was missing. Re-assemble the missing block and re-spawn at the same tier. Never escalate for this: the
tier is not what failed.
Bounded at two. The re-spawn does not count against the two-retry budget below, so it has its own bound (when
the plan itself lacks the block, every re-spawn reports the same gap). On the third report for one step, stop
re-spawning and take the plan-spec BLOCKER branch in 3c: name it, then question (Edit plan to fill the gap and re-verify / Accept as Risk and proceed / Stop).
Failures attributed to one step climb two rungs at most, each counted in WORKER_RETRY_PER_STEP:
- Variant rung, first failure of a
quick,juniororjunior-highstep: re-spawn at the same tier withmodelset to the model the failed attempt ran on, one reasoning variant up (#lowto#high,#highto#max). Skip the rung when the variant cannot rise: the model already runs at#max, or it has no variant at all (thesubagenttool rejects a variant the model does not offer and lists the ones it does). Then the first failure goes straight to rung 2. The rung follows the model actually spawned: aquickstep routed toac/plan-worker-juniorby the codebase-state rule in 1c retries on junior's model at#max, and a step that is running on a fallback model raises that model's variant. - Tier rung, second failure (or the first when rung 1 is skipped): re-spawn one tier up (
quicktojunior,juniorandjunior-hightosenior) on the new tier's own model, with nomodelargument.
Record each rung as it fires, as a wisdom line for the current wave: [RETRY] Step <N> <tier>: rung <1|2>, <one-line cause>, with the tier that failed, and nothing when no rung fired. [RETRY] lines do not count toward the five
wisdom items in 2f; ac plan-stats reads them to measure what each tier costs in quality.
senior has no rung 1, because its chain already runs at #max, and no rung 2, because nothing sits above it: a
senior step's first failure is terminal. A failure after rung 2 is terminal too. Record a terminal failure the same
way, [RETRY] Step <N> <tier>: terminal, <one-line cause>.
These re-spawns keep the step's current model and do not advance the ladder: a malformed report with no
### Changes Made or ### Verification (re-spawn at the same tier with a format reminder; a second malformed
report counts as the step's first failure), a [BRIEFING GAP] re-spawn, and a provider-fallback re-spawn, which
changes the model but not the rung.
The retry briefing leads with the failure context, then repeats the original.
Two fast paths skip rung 1: a worker flagging tier mismatch goes straight to rung 2 and the
mis-classification goes in the report, and a worker flagging [CONTRADICTION] does not retry at all,
because the next attempt hits the same structural conflict; mark it pending-remediation for 2f remediation.
A retried worker is not verified until you verify it. 2d ran before the retry spawned. After each retry, variant
rung, tier rung or provider fallback: re-stage and re-diff scoped to that step's Files, re-run Layer A, and re-run
the attribution for that step, before 2g commits.
Terminal failure (the tier rung failed, or a senior step failed first): append exactly one {step, wave} to
STEP_FAILURES for the step, however many retries it spent, and fire 2j at 3. Do not block the
wave on one failure unless 2i says a later wave depends on it.
2f. Remediation and wisdom
Runs after 2e, once every step has a terminal status (verified, failed, or pending-remediation).
- Remediate what the orchestrator owns:
[CONTRADICTION]reports, cross-file findings deferred from Layer B, and plan oversights your review surfaced. Apply the minimal patch to the file that structurally owns the missing piece, updateMODIFIED_FILES, clear anypending-remediationstep whoseDone whennow passes, and record each as a[REMEDIATION] Step <N> <tier>: <what you fixed>wisdom line (Step - -when no step owns it). Surface first when a patch would change a downstream contract; mechanical framework-completeness patches do not need a gate. - Extract wisdom: up to 5 concrete items this wave, 15 total, codified patterns rather than platitudes.
[REMEDIATION]and[RETRY]lines are records, outside the 5 and the 15. Persist all of them towisdom.mdunder## Wave <N>. - Re-ground: emit a 2-3 line wave summary and refresh the marker's
notewith a resume hint, which is what you read back after a compaction. Re-readPLAN_PATHandwisdom.mdonly when a compaction has actually happened since you last held them;grep -c '^- \[ \]'already told you what remains.
2g. Wave checkpoint commit
When the wave changed tracked files and NO_CHECKPOINT_COMMITS is not set, commit after 2f, before the next
wave. git commit -m "<one line naming the wave>" -- <wave_files> .ac/plans/<slug>, not the commit skill: loading
it admits a long body and spends turns on style detection, once per wave, to produce a checkpoint the Phase 4
commit squashes anyway. The final commit at 4a is where the commit skill earns its cost.
Commit the wave's paths explicitly, never git add -A: the parent repo may carry unrelated work, and -A would
snapshot it as this plan's deliverable, once per wave.
The gate is "did this wave change anything", which git status answers; no plan-wide label decides it, the
reviewer tier or the oracle default.
A commit failure here is a BLOCKER: print the git error and take the branch in
references/execution-state.md. Never auto-retry, because a failed commit usually means the
tree is in a state you did not expect.
2h. Progress table
After each wave, render the per-step table using the shape at
references/wave-orchestration.md under ## Phase 2h progress table.
2i. Wave dependency check (before launching the next wave)
Before the next wave's workers launch, check whether any failed step is a hard dependency for it. The three sources,
in order: the plan's ### Dependency Notes, a next-wave step whose Files names a file a failed step was to create,
and a next-wave step whose References point at a failed step's output.
If one failed, this is a BLOCKER even under auto mode. Emit one line naming it, then question (header
Dep failed?, options Stop and investigate (Recommended) / Fix the failed step manually and resume / Skip the dependent steps and continue). The first two delete the marker before halting; the third leaves it in place because
the run continues. Procedure at references/wave-orchestration.md.
If nothing hard failed, the next wave launches automatically. Auto-continue is the default between waves.
2j. 3-strike rule
When STEP_FAILURES holds 3 entries spanning two or more distinct waves, emit one line naming the
BLOCKER and question (header Halted?,
options Accept and continue (Recommended for known-isolated failures) / Fix manually and re-verify / Stop and investigate).
Accept and continue logs the failures, leaves the marker in place, and moves to the next wave; the failures surface
in the Phase 4 report. The other two delete the marker first, then pause or halt. This is a BLOCKER even under auto
mode: three accumulated failures make the (Recommended) qualifier unsafe to assume.
The two-wave span keeps the count meaningful: three failures inside one wave is one bad wave, not a systemic pattern. An entry is one step at terminal failure, so a step that spent both retries before failing counts once.
2k. Loop until all waves complete
Run 2b through 2j for each wave in sequence, auto-continuing between them; only 2i and 2j pause the loop. When the final implementation wave completes, advance to Phase 3.
Phase 3: Final code-review
Goal: gate the deliver with one independent code-review pass on the actual implementation: does the work match the plan and meet quality bars.
Aim for zero CRITICAL findings from Phase 2's verification. The reviewer reports rather than gates, so a CRITICAL finding here costs a fix and a re-verify, not a loop.
3a. Final automated pass
Run the build in the foreground; the reviewer reads code that must at least build. Then start the full test suite
and the repo-wide lint with background: true on the shell call, in the same response that spawns the reviewer in
3b (a project script whose name does not say test or lint, such as make ci or composer qa, goes under timeout 3600 so the stop guard counts it as work that will finish), so the two run side by side. Both must be green before
Phase 4: when the background run notifies you, a failure there is a finding like the reviewer's and goes through 3c.
When the reviewer finishes first, end the turn with a one-line status; the suite's notification starts the next one.
Then open this run's section of the review log, once:
shell: mkdir -p .ac/plans/<slug> && { grep -qx '## Run <marker started_at>' .ac/plans/<slug>/review-log.md 2>/dev/null || printf '
## Run %s
' '<marker started_at>' >> .ac/plans/<slug>/review-log.md; }
The log is append-only across runs and this header scopes this run's entry; a second /ac/execute <slug> writes
its own section rather than reading the previous one, and the grep -qx guard stops a re-entry from opening a
duplicate header.
3b. Spawn the reviewer
subagent({ agent: "ac/plan-code-review",
description: "Final code-review",
prompt: "Plan: <PLAN_PATH>
Modified files: <MODIFIED_FILES, newline-separated>
Wisdom: <wisdom.md path>
<only when signal 1 below fired alone: Criticality surfaces by path: <the surfaces>. Weigh failure scenarios there.>" })
One reviewer, whatever the plan's size.
Spawn ac/oracle alongside it, in the same response, only when the planner judged the change critical. Three
signals: signal 2 or signal 3 fires it, signal 1 alone does not, and --no-oracle forces the skip either way:
MODIFIED_FILESlands on one of the closed six surfaces in../plan/references/model-tiers.mdrule 5: authentication or authorization, payment or billing, cryptographic operations, user-input to SQL or shell or file path, file upload or deserialization, destructive migration.- Any step's
Why this tierbeginsrule-5-criticality, the planner's own judgement written at Stage 5. - The plan carries an
### Oracle Sanity-Check Findingssection, meaning Stage 3.5 already found something worth a second opinion at planning time.
Signal 1 alone is weak, since a file path rarely announces "cryptographic operations" or "destructive migration":
it adds the Criticality surfaces by path line to the reviewer brief above and spawns no oracle. When signal 2 or 3
fired, the oracle runs on its own model.
subagent({ agent: "ac/oracle", description: "Oracle strategic review",
prompt: "Plan: <PLAN_PATH>
Modified files: <MODIFIED_FILES>
Research the plan was built on: <.ac/plans/<slug>/research/>
Wisdom from the run: <.ac/plans/<slug>/wisdom.md>
The change touches <the surfaces that fired>. Review the diff for failure scenarios on those surfaces,
and test the plan's claims about what the code does against the code: they are premises, not findings.
Plan compliance, reuse and caller impact are the code reviewer's; do not repeat them. Use your standard
report (Coverage, Premises, Findings with severity and CONFIRMED or PLAUSIBLE, scenario and fix, Bottom
line, Confidence)." })
3c. Act on the findings
The reviewer returns findings tagged CRITICAL, IMPORTANT or MINOR, each with a confidence. There is no verdict and no revision loop. You are the filter, holding the plan, the wave history and the wisdom file:
- CRITICAL: fix it before Phase 4, with
editat each citedfile:line, smallest correct fix, the reviewer'sFix:line as guidance. Then re-run the per-file checks and related tests on what you changed (references/verification.md), and the full suite again only when the fix touched code other modules call. - IMPORTANT: fix when the fix is small and local; otherwise record it in
report.mdand add it to the plan's## Deferred Ideas. - MINOR, or anything under confidence 50:
report.mdnotes. Do not touch the code for these. - An oracle PLAUSIBLE finding names what would confirm it: run that check before acting on it as CRITICAL or IMPORTANT, and treat an unchecked one as MINOR.
- An oracle REFUTED premise means the plan is wrong about the code, whatever the Findings say: route it through the plan-is-wrong BLOCKER below, naming the premise and the quote. An UNSUPPORTED premise goes to
report.mdwith the search the oracle named.
Expect volume: both reviewers report everything rather than pre-filter, so a long list does not mean bad code.
A finding that says the plan is wrong rather than the code is a BLOCKER even under auto mode. Name
it, then question (Edit plan to fix and re-verify / Accept as Risk and proceed / Stop).
Never silently rewrite the plan.
Append the outcome to .ac/plans/<slug>/review-log.md under ## Run <marker started_at>: first one line per
reviewer that ran, exactly Review: <ac:plan-code-review | ac:oracle> CRITICAL <n> IMPORTANT <n> MINOR <n>
counting the findings it returned, then what was fixed and what was deferred. ac plan-stats reads those lines to
judge a reviewer's effort level against what it finds.
3d. Convergence
CRITICAL findings fixed and re-verified, or none returned. Advance to 3e.
3e. QA pass
Runs when QA_ENABLED is true and NO_QA is unset. Otherwise emit one heartbeat line naming which of the two skipped
it and go straight to Phase 4. A plan step that already walked the app live does not replace the pass: its Layer C
evidence reaches the tester as Existing evidence, and the tester skips those scenarios and still runs the rest.
Emit one heartbeat line (
QA pass: running qa for <slug>) and refresh the marker'snoteso a resume knows where the run stands (Phase 3e QA in progress; load the qa skill with --plan <slug> again or go to 4a).Load the skill and run it on the request
--plan <slug>. Skills take no arguments, so the loaded body reads its flags from that request. It never asks the user anything, so no--autois passed:skill({ id: "qa" }) // then continue with the request: --plan <slug>Its tester,
ac/qa-tester, runs in the background, soqamay end a turn withQA: tester running for run <run id>; resuming on its notification. That wait is expected: the notification resumes insideqa, and the stop guard stays quiet. Do not poll, sleep or read the tester's output, and do not treat that turn end as the QA result.When the skill finishes, read
result.txt(written byqain the directory of the block'sreport:path) and append its content to.ac/plans/<slug>/review-log.mdunder## Run <marker started_at>, the header 3a opened. Withreport: nonethe printed block is the record. When the file is missing, append the printed block plusresult.txt missing, and still apply the rule below. Append itsfixed filestoMODIFIED_FILES(nothing fornone). The skill has already triaged and fixed by the 3c rules and run its one retest, so do not re-triage or re-run it here. Whenfixed filesis notnone, re-run 3a (build, full suite and lint, in the foreground) before 4a, because 4a commits with--skip-preflighton the strength of 3a having covered those edits.Continue to 4a in the turn the block prints. Under
--planthe block is a hand-back to this skill, not a turn end; ending the turn on it would meet the live marker's stop guard.
Every QA status (passed, findings, could-not-run, skipped) continues to Phase 4, and none is a BLOCKER: a
dev server that would not boot or a missing QA tool goes into the QA and Phase 4b reports. Findings the skill left
unfixed live in its report, with open lows and unfixed mediums added to the plan's ## Deferred Ideas.
The pass sits before 4a, which deletes the marker and then commits and pushes, so QA runs inside the stop guard and its fixes reach the final commit.
Phase 4: Deliver
Goal: commit, write the report, render the summary.
4a. Final commit
Before the marker goes, check wisdom.md once: every [RETRY] and [REMEDIATION] line must name Step <N> <tier>: (or Step - -: for a fix no step owns), because ac plan-stats counts an untagged one as lost data; correct it before closing.
Delete .ac/state/execute/<slug>.json first, this run's marker only, before the F7 check and any commit.
F7 skip check: run git check-ignore -q on every file in MODIFIED_FILES. If all are ignored and
git status --porcelain shows tracked changes not in MODIFIED_FILES, the parent repo has unrelated work that a
commit would snapshot as this plan's deliverable. Skip it, say so in one line, and record it in the report under
## Notes with the path and the count.
Otherwise load the commit skill and run it on the request --skip-preflight with MODIFIED_FILES as its note, so it commits this run's files and never another run's in-flight edits in the same checkout, plus --no-push when LANE_MODE is true or .ac/state/active-auto.json names this session (its harness is opencode and its session_id is this session's root_session_id; a marker without harness was written by Claude Code and is not this run's): an unattended run has nobody present to approve a push, and the commit skill's branch guard only asks on main or master. A lane checks LANE_MODE on its own because .ac/ is gitignored, so its worktree never holds active-auto.json; only the coordinator publishes.
skill({ id: "commit" }) // then continue with the request: --skip-preflight (plus --no-push under LANE_MODE or an away marker)
Without either, the final commit pushes as the commit skill does. Phase 2d and Phase 3 already covered the
verification --skip-preflight refers to. A clean tree exits silently, which is fine.
4b. Report and summary
Write the report, .ac/plans/<slug>/report.md (under LANE_MODE .ac/plans/<slug>/outcome.md, the name the Claude
Code side must use because its host refuses a subagent's report*.md), from the template at
references/report-template.md: Summary, Verification, Deferred and Notes only, because the plan checkboxes, git
and wisdom.md already hold the steps, files, commits and wisdom. Confirm
it landed with test -f ... && wc -l ...; retry the write once if it did not, and render the report inline if the
retry also fails, so the work is not lost in chat history.
Then render the closing summary inline from references/execution-summary-template.md. The
summary is chat output; report.md is the file artifact.
End the turn. Under LANE_MODE the last thing written is the status: DONE block, with outcome.md in artifacts.