arbeitsplan-run
Executes a compiled workflow as a redundant swarm — N candidates over the same scope in their own git worktrees, judged blind, exactly one landed. Use after arbeitsplan-compile, or when the user asks to run the workflow, start the swarm, or build several versions and pick one. Halts and surfaces rather than retrying when candidates fail; convergence comes from widening, never from repeating. Writes only inside candidate worktrees until the landing step.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- arbeitsplan-run
- description
- Executes a compiled workflow as a redundant swarm — N candidates over the same scope in their own git worktrees, judged blind, exactly one landed. Use after arbeitsplan-compile, or when the user asks to run the workflow, start the swarm, or build several versions and pick one. Halts and surfaces rather than retrying when candidates fail; convergence comes from widening, never from repeating. Writes only inside candidate worktrees until the landing step.
- argument-hint
- [runId]
03 SKILL.md 正文
Run the swarm
N candidates build the same scope in isolation. Exactly one lands. The rest are deleted.
That is what makes a merge conflict impossible here: this is the same worktree isolation
superpowers uses, inverted. There, N worktrees do different work and must all be
reconciled — which is why subagent-driven-development forbids parallel implementers inside
one worktree "(conflicts)" and pushes the parallelism up to where the conflicts reappear.
Here, N worktrees do the same work and N−1 are discarded. Nothing is ever merged.
Steps
-
Read
workflow.json. Read the file; do not work from a summary of it. Refuse aschemaVersionother than"2"rather than guessing at it. Then branch onbackend.kind— it is a decision the spec already made, never yours to re-make:workflow→ follow The workflow backend below;matrix→arbeitsplan-matrix;in-session→ the steps here.A phase with
mode: "plan"never runs under the lock:worktree_pool.py openrefuses it, because plan mode plus an open lock leaves no legal write. Close, run that phase in plan mode, then open the next one. -
Open the run scope lock before any dispatch:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" open --spec analysis/arbeitsplan/<runId>/workflow.json --phase buildThis writes
analysis/arbeitsplan/run_scope.json, which arms the guard. It is a per-dispatch lock, not repo-level state — that distinction is why this guard does not sweep up every other plugin's edits the way one in this repository once did. -
Create one worktree per candidate, one angle each, from
workflow.json'sangles. -
Dispatch the batch in ONE message. Multiple dispatch calls in one response run in parallel; one per response is sequential. Each
arbeitsplan:candidate-buildergets its angle, its worktree, the scope, and the acceptance list — and never another candidate's angle or output.These are in-session dispatches, so the guard sees each one. The workflow backend is a different run, compiled for it — never switch to it mid-run.
Record each builder's result as it returns — the JSON it printed, saved to a file — with its own worktree:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/record_event.py" candidate --run <runId> --phase build --result c2.json --tree .arbeitsplan/<runId>/c2This writes
candidates/c2.json, the filereconcile.py(step 8) andland_candidate.py(step 9) read; nothing else writes it on this backend.--treereplaces the builder's self-reporteddiffandfilesTouchedwith what its worktree actually holds, and notes whether they differed — builders paraphrase long diffs, and a paraphrased diff does not apply. It refuses a phase that was never opened, a result missing any field ofcandidate-builder's output shape, and a candidate already recorded, writing nothing. -
Apply the breaker, per batch, never cumulatively.
- Exclude every
measured: falsecandidate from the denominator. It is not a rejection; it is a candidate that was never fairly tried. measured == 0→ acquisition problem. The environment failed, not the contract. Fix the environment and re-run. Do not re-dispatch into a broken environment.accepted * 3 < measured * 2→ contract problem. Halt and say so: the correct response is a better contract, not more agents.
- Exclude every
-
Referee blind. One
arbeitsplan:candidate-refereeper surviving candidate, each given the criteria and that candidate's diff only — never the builder's rationale, never another candidate. Landing is an allowlist: onlyaccepted.Record the batch — every verdict the referees returned, as one JSON list — under the referee phase you opened:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/record_event.py" referee --run <runId> --phase <refereePhase> --verdict verdicts.jsonThis writes
referee/<id>.json(whatland_candidate.pyreads) and thereferee/<phase>/<id>.jsontwin thatrounds.pyrebuilds rounds from. Without it an in-session run has no rounds, and step 7'srounds.py decidecan never route a shared hole or stop a moving residual. It refuses a phase that was never opened, a malformed verdict, and a (phase, candidate) already recorded — and writes nothing when it refuses. -
Select by rule, not by preference: most criteria met, then fewest files touched, then candidate id. If no candidate is
accepted, halt and surface. All N failing the same way is a statement about the contract — do not just widen and re-dispatch. Runscripts/rounds.py record --run <runId>(from the root holdinganalysis/arbeitsplan/) to rebuild this run's rounds, thenscripts/rounds.py decide --rounds <file> --spec workflow.json(see Rounds: a shared hole or a moving residual below) to learn which of three things this halt is:ROUTE CONTINUE(nothing to say yet),ROUTE SYNTHESIZE criterion=<id>(a sharedHole: relaunch at the single-writer phase withcarry.sharedHoleset, rather than building N more candidates against the same hole), orROUTE HALT moving-residual(stop outright: the last several rounds each "advanced" on a different blocker, which is not convergence). -
Measure the winner against its own tree, before landing (#76). A builder's self-reported exit codes are never trusted on their own:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/reconcile.py" --run <runId> --run-checks --candidate c2 --tree .arbeitsplan/<runId>/c2This RUNS every checked acceptance criterion now, with
cwdset toc2's OWN worktree, and records each as anexecute_toolevent inrun.jsonl, carryingdetail.candidate == c2. Any disagreement with whatc2itself reported — in either direction — printsCONTRADICTIONand exits 1.land_candidate.py --apply(next step) refuses a candidate lacking this measurement for any checked criterion, or whose latest measurement contradicts its report; another candidate's measurement never unlocks it. An honestly-reported failure a referee already accepted is not blocked here — the gate is "unmeasured or contradicted", nothing more. -
Land exactly one diff.
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" open --spec ... --phase land python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/land_candidate.py" --run <runId> --candidate c2 --applyOptional gated synthesis, only if the spec opted in: one further writer, given the winner plus explicitly named elements to borrow. It must beat the plain winner on at least one declared criterion, or the plain winner lands unchanged.
-
Delete the losers — worktrees and branches — then record the phase as closed and close the lock:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/record_event.py" phase --run <runId> --phase land --status closed python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" closecloserefuses a phase that recorded no terminal event. On a halt, close with--halt "<the specific reason>": a halt is an event inrun.jsonl, never an absence. -
End the run in the record -- landed or halted, always last:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/record_event.py" finish --run <runId>A landed run gets
complete.json(refused while any phase is still open); a halted one getsFAILED-<stamp>.jsoncarrying the halt's reason; anything else is refused, because stopping is not an ending. This marker is whatsweep_artifacts.pywaits for -- a run without it is kept forever, whatever state its worktrees are in.Deletion itself goes through
worktree_pool.py destroy(orsweep_artifacts.pyfor a whole finished run), which never just discards a loser's uncommitted state (#80): a DIRTY worktree is committed and preserved onkept/<runId>-<cid>before its worktree and throwawayarbeitsplan/<runId>/<cid>branch are removed; a clean worktree gets nokept/branch.
Referee-owned artifacts (#77)
If workflow.json declares refereeOwned, its referee-fixture phase runs first, exactly
like any other phase (open the lock, dispatch its agentType, record the output, close). Once
it has written those paths, baseline them once:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/referee_owned.py" record --run <runId>
A second record for the same run is refused: the baseline is taken at creation, never
re-taken to accommodate a later change. worktree_pool.py open already narrows a fan-out
phase's lock to exclude every refereeOwned path, so the guard denies a candidate's Edit/Write
before it lands — but that covers only the tool calls the guard's matcher sees. Re-verify
before landing (step 9), as the belt to that guard's suspenders:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/referee_owned.py" verify --run <runId>
land_candidate.py independently refuses (citing refereeOwned by name) any candidate diff
that touches one of these paths, so the same rule is checked three ways: at the lock, at
landing, and by content.
Rounds: a shared hole or a moving residual (#78, #93)
A no-accept halt is arithmetic (accepted * den < measured * num) and never looks at WHY.
scripts/rounds.py is the one place that does, and both rules below read the SAME derived
rounds — one round per referee phase, rebuilt from referee/<phase>/<id>.json and the
adjudicator's recorded round: {outcome, blocking} — so a fix to one is a fix to both. Those
files come from record_event.py workflow (the workflow backend) or record_event.py referee
(in-session, step 6); a batch recorded any other way is invisible here:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/rounds.py" record --run <runId> > /tmp/rounds.json
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/rounds.py" decide --rounds /tmp/rounds.json --spec analysis/arbeitsplan/<runId>/workflow.json
ROUTE SYNTHESIZE criterion=<id>— asharedHole(#78). The LATEST round accepted no one and >= 2 rejected candidates share one unmet criterion — a structural hole every candidate hit, not noise. Relaunchworkflows/run.jswithstartAtat the single-writer phase andcarry.sharedHole = {criterion, candidates: [{candidateId, diff}]}(the run.js halt's ownrejectionsByCriterion, paired with each candidate's diff, builds this). The synthesizer then works from every rejected diff toward that one criterion, instead of N fresh candidates re-discovering the same hole from scratch.ROUTE HALT moving-residual(#93). A per-batch breaker and asharedHoleboth look at ONE round; a run that "advances, not closes" every round, each time naming a different blocking condition, passes both forever. This fires when the last N judged rounds (judge.outcome != "none"; an unjudged round neither breaks nor counts) are all"advanced"with non-null, pairwise-distinctjudge.blockingids — N genuinely different obstacles in a row, not real convergence. Stop outright: do not re-compile and do not widen again.Nis--max-advancing-rounds, else the spec'sroundBreaker.maxAdvancingRounds, else 3. When both rules would fire on the same rounds, themoving-residualHALT wins.ROUTE CONTINUE— neither condition holds; proceed as normal.
Stacked fan-outs across waves (#79)
A later wave's builders should sometimes start from an earlier wave's refereed winner,
not from HEAD — that is what a fanout-redundant phase's base: "<phaseId>" declares. Once a
phase's candidate is selected (step 7 above) and would normally just land (step 9), promote it
instead if a later phase names it as base:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" promote --run <runId> --phase build-w1 --candidate c2
This commits everything sitting in that candidate's worktree — untracked files included — and
points arbeitsplan/<runId>/base/build-w1 at the new commit. The next wave's create then
reads it automatically:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" create --spec analysis/arbeitsplan/<runId>/workflow.json --phase build-w2 --count 2
If build-w2 declares base: "build-w1", every worktree this creates starts from the promoted
branch instead of HEAD; if build-w1 was never promoted, create refuses, naming the
missing branch, and creates nothing. A --phase whose phase carries no base (or create with
no --phase at all) behaves exactly as before: from HEAD.
Base branches deliberately survive an ordinary worktree_pool.py destroy --run <runId> — a
still-pending later wave may need to stack on one. Only pass --bases once the whole run is
actually done with them:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/worktree_pool.py" destroy --run <runId> --bases
compile_spec.py --strict is the check that a stacked run actually declared every base it
needed: a fanout-redundant phase whose transitive requires reach another fanout-redundant
phase with no base chain reaching it back prints WARNING ... [AP-SIBLING-INVISIBLE] ...
naming both phases. A plain compile still writes past a warning (exit 0); --strict treats one
as a rejection (exit 1) — run compilation with --strict before dispatching a stacked run.
The workflow backend
When backend.kind is "workflow", the whole phase graph runs inside workflows/run.js,
and this session does only the things the Workflow tool cannot: read files, run plan-mode
phases, measure the accepted candidate with reconcile.py --run-checks (#76), and land.
-
Launch it with the spec as data. The Workflow tool has no filesystem, so pass the parsed
workflow.jsonverbatim:args: {spec}(plusstartAtandcarryon a resume). No run-scope lock is open while it runs — nothing inside writes the shared tree. 1b. Arm the script allowlist when the spec has ascriptphase (#107).compile_spec.py --writealready wroteanalysis/arbeitsplan/<runId>/scripts.jsonfrom the spec; point the guard at it before launching:printf '{"runId": "%s"}\n' <runId> > analysis/arbeitsplan/scripts_armed.jsonThe guard judges every Bash call
arbeitsplan:script-runnermakes — lock or no lock — and allows exactly one declared command per dispatch. Without an armed allowlist the runner is denied everything, which is the safe direction. For{placeholder}slots, pass their values ascarry.scriptArgs.<phaseId>; a value outside[A-Za-z0-9._/,=:@+-]halts the phase before dispatch. -
Persist what it returns, before reading it. Every return carries
events:python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/record_event.py" workflow --run <runId> --result result.jsonA halt is an event. Record it even — especially — when the run aborted.
-
On
pending_plan_node, run that phase here, in plan mode, by dispatching itsagentTypewith the carried data. Record its output, add it tocarryunder the phase id (carry.contract.acceptancereplaces the compiled acceptance for later phases), and relaunch withstartAt: <resumeWith>. Loop state lives here, never in the script. That same command writescandidates/<id>.jsonandreferee/<id>.jsonfor every candidate the return carries, once each, never overwriting. 3b. Record a plan-mode phase's output the same way:record_event.py phase-output --run <runId> --phase <id> --output <file>. An adjudicator'sverdict: "land"is what gives a borrowed synthesis its referee record; without it,land_candidate.pyrefuses the synthesis like any unjudged candidate. 3c. On a NO CANDIDATE ACCEPTED halt,rounds.pydecides the next move, not this session. The halt'srejectionsByCriterionis already grouped by criterion; runscripts/rounds.py record --run <runId>thenscripts/rounds.py decide --rounds <file> --spec workflow.json(see Rounds: a shared hole or a moving residual above — same rules, samesharedHoleandmoving-residualoutcomes, whichever backend ran the halted batch). ASYNTHESIZEroute relaunchesrun.jswithstartAtat the single-writer phase andcarry.sharedHoleset, from the same halt'srejectionsByCriterionandcandidates; amoving-residualHALT stops the run outright. -
On completion, measure then land in-session.
worktree_pool.py open --phase <last>, thenpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/reconcile.py" --run <runId> --run-checks --candidate <id> --tree .arbeitsplan/<runId>/<id>to measure every checked criterion against the accepted candidate's own tree (#76), then
land_candidate.py, where the hook, thewriteScopecheck, and this measurement gate all run. The workflow never lands.land_candidate.pywriteslanded.json, withdivergedFromif what landed differs from the recorded candidate. Then end the run withrecord_event.py finish --run <runId>-- after a halt too -- exactly as step 11 above.
Rules
- Never re-dispatch an identical prompt. The hook denies it, and the denial is correct: past the cap those rounds do not converge, they only cost. Widen instead — a new angle nobody tried — or stop.
- Never let a builder write to the shared tree. Only the landing step touches it.
- Never treat an unmeasured candidate as a failure. It has no rate, only missing data.
- Never raise the budget mid-run. That is a decision to re-compile.
- Delegation nests at most 3 deep, and never in a cycle — both enforced by the hook, see
references/delegation.md. A dispatch to arbeitsplan's own agents is fan-out and is not counted; a dispatch to another plugin is. - A denial from another plugin's guard is that plugin doing its job. Report it; never reach for its escape hatch.
Output format
arbeitsplan run — ap-2026-09-12-a3f1, phase build
c1 middleware-layer measured checks 3/3 diff 2 files
c2 decorator-per-route measured checks 3/3 diff 2 files
c3 reverse-proxy-config UNMEASURED no nginx toolchain in the worktree
breaker accepted 2 / measured 2 (c3 excluded from the denominator) — pass
phase referee (blind)
c1 rejected a3 not met: requirements.txt gains 'slowapi'
c2 accepted 3/3, evidence at src/api/search.py:41
phase land
winner c2 (3 criteria met, 2 files touched)
applied src/api/search.py, tests/test_ratelimit.py
deleted c1, c3 worktrees and branches — nothing merged
marker .takt/ap-2026-09-12-a3f1/landed
dispatches 7/9 budget.
A halt is an output, not a crash:
arbeitsplan run — ap-2026-09-12-a3f1 HALTED at phase referee
accepted 0 / measured 3 — every candidate failed criterion a1 the same way.
All three read the limit from a per-process dict, so a1 ("429 across workers")
cannot be met inside the declared writeScope at all.
This is a statement about the contract, not about the candidates.
The correct response is a better contract, not more agents: re-compile with a
scope that admits shared state, or drop a1.
Nothing was landed. Worktrees kept at .arbeitsplan/ap-2026-09-12-a3f1/ for reading.
Resources
references/candidate-contract.md— what builders and referees exchange, and why the referee is starved.references/delegation.md— read before dispatching another plugin: the registry every plugin declares, the append-only ledger, and the depth cap plus cycle detection that bound how far a delegation may nest.references/patterns.md— the breaker's thresholds and the reason they are per-batch.workflows/run.js— the workflow backend: executesspec.phases, halts before each plan-mode phase, counts the dispatch budget in code, and returns span-shapedevents.references/backend-selection.md— why a run was compiled for the backend it names.
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.