arbeitsplan-waves
Installs an approved multi-wave design into a project as project-owned files — a pinned interpreter, the plan, a state helper, a path and runner guard, and one agent file per agent type — then launches and resumes it from the primary checkout. Use when a restructuring needs several waves of parallel, disjoint rows, each building on the merged and gated result of the last; when a hand-written multi-wave workflow should become a table; or when a stopped wave run must be resumed. The installed files run without werkstoff. Runs nothing it has not been asked to; a red gate or a pending human gate stops the run, never a retry.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- arbeitsplan-waves
- description
- Installs an approved multi-wave design into a project as project-owned files — a pinned interpreter, the plan, a state helper, a path and runner guard, and one agent file per agent type — then launches and resumes it from the primary checkout. Use when a restructuring needs several waves of parallel, disjoint rows, each building on the merged and gated result of the last; when a hand-written multi-wave workflow should become a table; or when a stopped wave run must be resumed. The installed files run without werkstoff. Runs nothing it has not been asked to; a red gate or a pending human gate stops the run, never a retry.
- argument-hint
- install <design.json> | launch <name> | resume <name> | approve <name> <gate-id>
03 SKILL.md 正文
Multi-wave runs
arbeitsplan-run runs one change: N candidates over one scope, and exactly one lands.
Some restructurings are larger than one change. They need several rows of different work
per wave, each wave built on the merged result of the one before. This skill installs that
kind of run into the project and drives it. The design comes from arbeitsplan-design, and
references/design-table-schema.md is its contract.
Each requirement below comes from a failure observed in a hand-written prototype (#106), and each is a check in code rather than a sentence here:
- the run refuses to start from a linked worktree;
- every row starts with
git merge --ff-only <wave base>, and the run halts on a wrong base; - a finished wave is skipped before any of its builders is dispatched;
- merges go into an integration branch, and the target moves only on a green gate;
- gates run twice, once in the primary checkout and once in a clean worktree, so a finding
that only the primary checkout shows is labelled
primary-only; - a swarm row's losers are discarded, never merged;
- prompts carry ids and branch names only;
- an authored step is written by a shell-less author and verified (syntax, a sample in a scratch worktree, the output schema) before anything runs it, and the guard refuses to run it once its file or its contract has changed.
Install (once per design)
-
The design must already be approved and written.
compile_spec.py --design --writeprints its sha256. Refuse a design whose hash differs from the approved one. -
Install:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/install_waves.py" \ --design analysis/arbeitsplan/<runId>/design.json [--artifact]Pass
--artifactwhen the repository is itself an installable artefact, so the generated tooling isexport-ignored.A design with authored steps gets a skeleton per step under
.claude/workflows/<name>.steps/(gitignored), in the language its runtime names, plus a<name>-authoragent. The first launch writes and verifies them; re-installing never overwrites a step that is no longer a stub.The installer resolves the one prerequisite, a Python >= 3.11 for the helper and the guard, by probing
python3,pythonandpy -3, or the command given with--python. That interpreter is written into every command. The installer refuses to overwrite any file it did not generate. -
End the turn. Launch on the next one. An agent type written to
.claude/agents/is not found in the turn that wrote it, not even 30 s later, and resolves from the next turn on (scripts/probe_runtime.py, probe P4, CLI 2.1.283, ADR 0004). The installer printsLAUNCH IN A LATER TURN, andhandoff.py planrepeats it together with a fresh session's exact start prompt, which also works. Never launch in the turn that ran the install.
Launch and resume
-
From the primary checkout. The wave base is the primary checkout's HEAD, and the merge-gate switches branches there. The interpreter's preflight halts on a linked worktree and on tracked changes; do not try to route around it.
Where a builder's worktree starts was measured by
scripts/probe_runtime.py(P5) on CLI 2.1.283 (ADR 0004). It starts from the project'sworktree.baseRef: the remote's default branch by default, the primary's HEAD when there is no remote, and the caller's HEAD with"head". Each builder then fast-forwards to the wave base. So the base must descend from the remote's default branch: push it, or setworktree.baseRefto"head"in.claude/settings.json. -
Read the state and launch:
python3 .claude/workflows/<name>_state.py showLaunch the Workflow tool with
scriptPath: .claude/workflows/<name>.jsandargs: {plan: <the parsed .claude/workflows/<name>.plan.json>, state: <that output>}. Pass both as objects; a JSON string is refused. There is no cost cap by default. Subscription limits stop the run, and relaunching with the saved state is the whole resume. -
Read the result, and act on its shape:
result what to do aborted: falsereport the final integrationShaand that the target moved; donepending_human_gate: <id>show the user what that gate approves. On their yes, run <name>_state.py approve --gate <id>, then relaunchabortReasonnames a red gatereport findingswith each one'ssource(primary-onlymeans only the primary checkout's untracked or ignored files produced it) and thekeptworktrees. Do not retry. A fix is a new row or a new designPRIMARY CHECKOUT ONLYthe launch site is wrong; relaunch from the primary checkout WRONG BASEa builder could not fast-forward to the wave base (see step 1): push the base, or set worktree.baseRefto"head", then relaunchSCRIPT CONTRACTa declared command exited unexpectedly or printed output that breaks its schema: a defect in the step, not a flake AUTHOR CONTRACTan authored step was refused by verify-stepafter its node'sretries. Report theproblemand thesteppath. Read the file; the fix is a sharperpurpose, a bettersample, or moreretriesin a new design, never a hand edit the hash would refuse anywayshowreports each authored step asmissing,stub,authored,verifiedorstale. Onlyverifiedis skipped on the next launch. To re-check a step by hand, run<name>_state.py verify-step --node <id>.Whatever the result, render where the run stands, from the state it left:
python3 .claude/workflows/<name>_state.py show > analysis/arbeitsplan/<runId>/show.json python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_design_html.py" \ --design .claude/workflows/<name>.plan.json --state analysis/arbeitsplan/<runId>/show.json \ --out analysis/arbeitsplan/<runId>/design-report.htmlRed gates, stale or missing authored steps and pending human gates are marked on the graph where they sit. Quote the printed verdict; it is computed from the state, not from the chat.
The state helper persists its state as the run goes. Every finished builder is recorded the moment it returns, and every green wave when its gate passes, so a relaunch skips both.
Rules
- Never merge by hand to "help" a stopped run. The integration branch and the kept worktrees are the evidence; the next launch or a new design moves forward.
- Never widen
offLimitsor edit the generated guard to get a row through. The guard is a hook because a permission rule did not hold inside agent worktrees. - The installed files are the project's. A new round of work is a new design and a new install, never an edit to the generated interpreter.
Output format
arbeitsplan-waves rebuild-cli — launched from /work/proj (primary checkout)
preflight head 4e1a9c0, clean, python 3.12.3
wave 1 w1-parse ✓ w1-render ✓ gate-1 green (go vet, go test: both trees) main → 7b2d110
wave 2 w2-cli ✓ gate-2 RED
test primary-only exit 1 (clean worktree: exit 0)
kept: agent/w2-cli (worktree .claude/worktrees/w2-cli)
STOPPED at gate-2: main is still 7b2d110. The failure appears only in the primary checkout —
an untracked or ignored file there. Inspect it; this run does not retry.
Resume after the fix: relaunch with `rebuild-cli_state.py show` — wave 1 will be skipped.
Resources
references/design-table-schema.md— the design, the wave rules, the rejections.references/patterns.md—gated-disjoint-waves, and why only this form of merging different work is admissible.scripts/install_waves.py,scripts/waves_state.py,scripts/waves_guard.py,workflows/waves.js— what gets installed, each with its own selftest.scripts/build_design_html.py— the plan and its state as a graph.
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.