arbeitsplan-design
Designs a workflow node by node before anything runs — for each step, what it does, where it runs (primary checkout, agent worktree, scratch directory), when (dependencies, human gates between runs) and how (kind, model, write scope, output schema, and for script nodes the exact command and its toolchain, in any language). Use when the user wants to plan a workflow step by step, a restructuring spans several waves, a deterministic step (a gate, a conformance runner, a state helper) would otherwise be disguised as an agent, or a hand-written workflow keeps making where/when/how decisions in prose. Read-only; produces a validated design.json and a handoff, never runs it.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- arbeitsplan-design
- description
- Designs a workflow node by node before anything runs — for each step, what it does, where it runs (primary checkout, agent worktree, scratch directory), when (dependencies, human gates between runs) and how (kind, model, write scope, output schema, and for script nodes the exact command and its toolchain, in any language). Use when the user wants to plan a workflow step by step, a restructuring spans several waves, a deterministic step (a gate, a conformance runner, a state helper) would otherwise be disguised as an agent, or a hand-written workflow keeps making where/when/how decisions in prose. Read-only; produces a validated design.json and a handoff, never runs it.
- argument-hint
- <the approved problem statement, or its path>
03 SKILL.md 正文
Design a workflow, node by node
arbeitsplan-compile picks a pattern per phase. This skill answers the questions compile
leaves in prose, before anything runs. For every node it asks:
- what the node does;
- where it runs;
- when it runs;
- how it runs.
A hand-written multi-wave prototype answered them ad hoc. Three of its bugs came from that: a wrong worktree base, state passed as a JSON string, and a gate run where untracked files live.
Run this skill in plan mode. It writes nothing but the design under analysis/arbeitsplan/,
and only after the user approves.
Steps
-
Read the contract first.
references/design-table-schema.mddefines every key and every rejection.references/patterns.mdhasscript-stepandgated-disjoint-waves, and explains why a merge of unproven partitions is still rejected. -
Take an approved problem statement, not a vague one. If it is not scoped, stop and scope it (
zirkel:zirkel-clarify-scopewhen zirkel is installed; ask directly when it is not, and say so). Record its path asproblemRef. -
Snapshot the agent types that exist now, before designing anything:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/handoff.py" snapshot --root . \ --out analysis/arbeitsplan/<runId>/agents-before.jsonThe handoff compares against this snapshot. An agent type added in the middle of a session does not resolve in
agent(). -
Find the repository's own toolchain before writing a single command. Read its build files:
Makefile,go.mod,Cargo.toml,*.csproj,package.json,*.cabal,pyproject.toml,Project.toml,build.gradle,CMakeLists.txt, or whatever is there. Write the gates, acceptance and smoke steps in that toolchain. Never writepytestinto a project that does not use it. If a runtime is not among the built-ins, declare it undertoolchains. -
Walk the nodes one at a time. For each, settle with the user:
question the node's keys what goal,output_schema(strict, no JSON-in-a-string)where where:primary,worktreeorscratchwhen depends_on; ahuman-gateonly between runshow kind,model(recommended per node; omit it to inherit the session's),agentType,writeScope,inputs(ids and paths only),scriptor stepsA deterministic step — a gate, a conformance runner, a state helper — is a
scriptnode. It is not an agent told to run a command. When the repository has no such command yet, the node authors it:script.author = {model, purpose, sample}in a wave design, in bash, pwsh, ruby, node or python, following the repository's own language where it can (see the schema's "Authored steps"). The plan writes the script and verifies it before anything runs it. -
Prove the write scopes. Dispatch
arbeitsplan:scope-proverfor the rows that run concurrently. Where two rows need one shared file (a module manifest, a lockfile), give it to one owner: an integrator row that depends on both, or a scaffold row in an earlier wave. -
Validate, without writing:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/compile_spec.py" --design \ --spec analysis/arbeitsplan/<runId>/design.draft.jsonEvery
REJECTEDline names its key. Fix the design, never the validator. -
Preflight the toolchains. The compile prints one
TOOLCHAIN <name> <probe>line per runtime the design names. Invokearbeitsplan-preflight, which runs each probe; exit 0 means installed. A missing toolchain makes the design not ready, however clean it compiled. -
Render the design as a graph for the user to approve from. Record the probes' results as
{toolchain: true|false}inanalysis/arbeitsplan/<runId>/preflight.json, then:python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_design_html.py" \ --design analysis/arbeitsplan/<runId>/design.draft.json \ --preflight analysis/arbeitsplan/<runId>/preflight.json \ --out analysis/arbeitsplan/<runId>/design-report.htmlIt prints the page's verdict. The page shows which rows run side by side, any two that may write the same file, and where a human gate ends a run. Every rejection on it comes from the same validator as step 7.
-
Present the design table and the preflight results, in the output format below, and ask for approval. Approval binds to the printed sha256. When an ExitPlanMode hook is available, it can check that hash, but that binding is unprobed, so say so rather than claim it.
-
On approval, write the design:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/compile_spec.py" --design --write \ --spec analysis/arbeitsplan/<runId>/design.draft.jsonThen hand off:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/handoff.py" plan \ --design analysis/arbeitsplan/<runId>/design.json \ --snapshot analysis/arbeitsplan/<runId>/agents-before.json
Execute, then hand off
-
Execute in auto mode, from the primary checkout:
- a design with waves goes to
arbeitsplan-waves; - a single change goes to
arbeitsplan-compileand thenarbeitsplan-run, with each script node becoming ascriptphase.
The run stops at the first checkpoint or red gate and leaves a state file to resume from.
- a design with waves goes to
-
Same session:
EnterWorktreeinto the branch the run produced. The cwd, settings and CLAUDE.md move with it; agents and hooks are read from the main checkout. -
A later turn: when the design created agent types,
handoff.pysaysLAUNCH IN A LATER TURN. A type written mid-session is not found in the turn that wrote it, and resolves from the next turn on. A fresh session with the exact start prompthandoff.py planprints also works.
What scripts/probe_runtime.py measured on CLI 2.1.283 (ADR 0004), beyond the docs:
- Plan mode holds inside a worktree the same way it holds in the primary checkout. Asked to write a file in plan mode, the model declined in both, 3 of 3 each. That is the model honouring the mode; a headless run never reached the harness's own refusal, so do not treat a worktree as a way around plan mode, nor as a second lock.
- Resume returns to the worktree. A session that ran
EnterWorktree, resumed from the primary checkout, starts in that worktree and remembers the conversation, 3 of 3. - Agent types: a later turn, not a new session (above), 3 of 3 for both the Agent tool and
a Workflow
agent().
Rules
- Never infer a gating value. A wave design without
integration.targetis refused. A model is not a gating value: tiering is a recommendation, so a node that omitsmodelinherits the session's by design (#118) and is dispatched without amodelkey. The skill proposes a tier (opus for builders and referees, sonnet for merger, smoke, reviewer and fixer, haiku for script runners) and the design states it; a stated model that is not an alias or aclaude-...id is refused (AP-NODE-BAD-MODEL), andinheritis not one -- omit the key instead. - Commands come from the repository, not from habit. Every example here is one language among many. Match the project.
- A human gate is between runs. A Workflow run cannot pause for input, and the validator refuses a gate that does not cut the graph in two.
- Writes nothing before approval, and never runs the design.
Output format
design rebuild-cli (run ap-2026-09-27-wv01) sha256 3f9c1e… — compiles clean
problem: analysis/arbeitsplan/ap-2026-09-27-wv01/problem.md
node kind where when (after) model writes command / check
preflight script primary — haiku — python3 …_state.py preflight
w1-parse agent worktree preflight opus internal/parse/** go test ./internal/parse/...
w1-render agent worktree preflight opus internal/render/** go test ./internal/render/...
gate-1 merge-gate primary w1-parse, w1-render haiku — gates: go vet, go test
w2-cli agent worktree gate-1 opus cmd/tool/** go test ./cmd/tool/...
gate-2 merge-gate primary w2-cli haiku — gates: go vet, go test
smoke agent scratch gate-2 sonnet — go build …; go run … --help
review agent primary smoke sonnet — —
fix agent worktree review (if blocking) sonnet internal/**, cmd/** —
toolchains: go (go version) — installed · python (python3 --version) — installed, helper >= 3.11
integration: waves merge into integration/rebuild-cli; main moves only on a green gate
new agent types: rebuild-cli-builder, -smoke, -reviewer, -fixer, -runner → LAUNCH IN A LATER TURN than the install
Approve this design (sha256 3f9c1e…)? Next: arbeitsplan-waves install, then launch on the next turn.
Resources
references/design-table-schema.md— every key, every rejection, and the two worked fixtures (Go, and Rust with an integrator row).references/patterns.md—script-step,gated-disjoint-waves, and the rejectedpartition-then-merge-worktreesthis narrows.scripts/handoff.py— the snapshot, and the new-session prompt when one is required.scripts/build_design_html.py— the design (and later its run) as a graph with a verdict;assets/design-viewer.htmlis its template.
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.