Add validated per-stage MCP allowlists while keeping builtin tools separate. Enable matching Claude Code permission rules only for Claude stages, reject unsupported harnesses, and document the unattended-stage safety model.
9.4 KiB
Definition format
A definition is Markdown made only of # stage KEY headings and fenced blocks;
no prose outside blocks. Blocks: prompt, configs, tools, edges, checks,
limits (references/control.md), permissions and notify
(references/notifications.md). There are no memory, links, input or output
blocks; stages communicate through output.md (# handoff) and public/.
Schedules are saved run configurations, never definition blocks
(references/schedules.md).
# stage implement
```prompt
Make the change requested in the run task. Run focused checks for the touched
code only. Return blocked if the request cannot be met.
```
```configs
provider=default
model=default
```
```tools
read
glob
grep
edit
shell
```
```checks
none: focused tests only; the land delivery gate runs the suite
```
```edges
success -> review
blocked -> #failure
error -> #failure
```
Stage and outcome keys begin with a letter and contain letters, digits, _ or
-. Name roles plan, implement, review, ui-review, decide (human) and
land; other jobs take a plain verb (draft, check, act). Each outcome has exactly one target: another
stage, #success or #failure. An omitted error edge defaults to #failure
for every stage type, human included. Execution is sequential; an outcome picks
one edge, never parallel branches. Every stage must be reachable from the entry
and have a path to a terminal; loops need runner-owned limits.
Turn files
Each visit gets input.md, memory.md, history.md, output.md and private/
in <run>/stages/<seq>-<stage>/, plus the run-level shared public/ addressed by
its absolute path.
memory.md(capped at 4 KB, always inlined in the prompt): the run task, the previous stage's# handoffwith its outcome andpublic/additions, a one-line-per-stage outcome ledger and the server-captured changed files.input.md: the run task, plus on later turns the previous turn's full output (internal/turn/render.go). A stage withreadreads it on demand; a stage withoutreadgets it inlined (up to 32 KB) on every call, so givereadto stages that follow a large output.history.md: every completed turn in full; on demand for stages withread, never inlined.
Keep turn-local files in private/; put reports, logs and screenshots for later
stages in public/. input.md, memory.md, history.md, output.md and
session.html are server-written evidence, not stage output.
output.md
The stage returns the complete output.md in this order: # outcome, the edge
word alone on the next non-blank line, then # handoff (a few lines: what it did,
files changed, open findings), then any detail:
# outcome
success
# handoff
Fixed both review findings in cache.go; focused tests pass. No open issues.
Free-form detail for the operator and later stages.
The outcome heading matches case-insensitively at any ATX level, outside fenced
code. Never add a second heading named Outcome. If the outcome is missing, the
runner sends one repair follow-up asking only for it; a still-missing, duplicate,
empty or undeclared outcome fails with FINAL RESULT VALIDATION. Every other
heading is free-form and preserved. The handoff is the # handoff section (or,
without one, the head of the output, marked as such), truncated to fit memory.
The { "outcome": ..., "output": ... } JSON envelope and its format-repair ladder
are retired: never ask for JSON fields or invent server sections. Missing tools or
evidence route to blocked when declared, else error; never fabricate a result.
Configs
provider/model: exact IDs validated during server setup. Templates (pipelines new NAME --template KEY) fill them in; copy those IDs into a hand-written draft. Availability needspipelines provider-check.harness=opencode|pi|claude; omission means OpenCode (references/harnesses.md).claudeneedsprovider=anthropicand a Claude model ID, and accepts nopermissionsblock,delivery=trueor run write paths.retries0–100, default 2 (three attempts). Retries cover transport failures and timeouts; a stage withedit/shell(or no tools block) never replays admitted work.timeoutper attempt, default1h(e.g.30m,90s).reasoning_effort:default,none(off),minimal,low,medium,high,xhigh,max. Omit unless asked; unsupported levels are rejected. Do not prompt "think harder" instead.budget_usd,budget_tokens: positive caps on reported usage, shared across attempts and visits of this stage; totals include cache reads and writes. Set only when the user asks or a measured visit exists (references/practices.md).delivery=true: the landing stage's gate (below). OpenCode harness only.auto_skip=false: disable the server skip fallback for a stage that declares askippededge (references/operations.md, Server skip fallback).
Tools and permissions
tools lists read, glob, grep, webfetch, websearch, edit, shell,
or (Claude stages only) mcp:<server> / mcp:<server>/<tool>, one per line;
an empty block denies all and a missing block grants local
read/glob/grep/edit/shell (prefer explicit). Roles: plan reads (web only when
external knowledge is needed); implement reads, edits and runs shell; review
reads and may use shell for git diff, never edits; land has read/glob/grep and
shell, no edit. Planning stages do not return blocked merely because edits come
later. Keep prompts language-neutral unless the task names a language.
Optional permissions is a JSON object with edit (run-directory-relative
patterns) and shell (exact commands) arrays. It narrows declared tools; it never
enables a missing one. Empty arrays deny; wildcards, chaining, redirects and
traversal are rejected. With restricted edits and shell enabled, list shell too:
{"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}.
Named MCP entries are an explicit allowlist for unattended Claude stages:
mcp:ai-memory allows that server's tools, while mcp:linear/list_issues
allows one tool. Names are the server/tool names Claude Code displays (mapped
internally to mcp__<server>__<tool>; claude.ai connectors may look like
claude_ai_Linear). Other harnesses reject these entries. Prefer read-only
MCP tools; server configuration is not inspected during validation, so an
unknown name may fail at runtime.
Checks
Every model stage that can modify the workspace (edit or shell, no tools
block, or delivery=true) declares checks. A delivery=true stage lists 1–20
commands, one per line. Every other stage writes exactly one line,
none: <reason>, e.g. none: read-only review; shell is used only for git diff.
A check must fail when it cannot run: validation rejects || true, || :,
|| exit 0, || echo, negated file tests, ! command -v tool ||, an if with no
failing else, and set +e. Cover every language the run can change.
Human stages
type=human pauses the run until a person picks one of its non-error edges
(e.g. approve -> act, revise -> plan, abort -> #failure). It needs only
prompt (operator instructions),
configs with type=human and edges; no model or tools. Decide with
pipelines decide RUN_ID [STAGE] --option KEY [--feedback TEXT] or the apps. The
wait survives restarts and is never killed by a stage timeout or max_visits.
Land stage and delivery gate
A workflow that commits its change ends in land: a model stage with
read/glob/grep/shell, no edit, that commits locally. Its prompt states:
- Commit only this run's changes (server list + git status).
- Check the staged diff for unrelated work and secrets.
- No empty commit, push, amend or rebase. Report the hash.
With delivery=true and checks commands, after land succeeds the server:
commits whatever the run left uncommitted when the item is the run's own
worktree (see "Run worktrees" below); requires the item checkout to be clean,
untracked files included (the main checkout need not be: the final
fast-forward is Git's merge --ff-only, which refuses without touching
anything when a local change would be overwritten); merges
a moved main into the item (a conflict aborts with the workspace unchanged);
runs each check with sh -c from the root of a fresh detached worktree of the
commit, so include dependency bootstrap (npm ci && npm test); caps each check's
output at 64 KB; and fast-forwards main. A failing check blocks landing. Do not
check ancestry before the gate runs. Without a gate, the manager merges and
verifies ancestry; no separate merger pipeline is needed (references/queue.md).
Run worktrees
A run started from a repository's main checkout runs in its own worktree:
<repo>-runs/<date>-<title>-<hex> next to the repository, on branch
pipelines/run-<same>, from the checkout's current HEAD. Runs never share a
tree, never see the operator's uncommitted work, and any number can run at
once. A run started inside a linked worktree (an item's tree) and every retry
use their directory as is. After a successful run whose tree is clean and
whose branch is on main, the server removes the tree and branch; anything
else (a failed run, unlanded commits, stray files) is kept for recovery.
The notify block accepts on, optional legacy destination, optional
artifacts=markdown|files, and optional open=<relative-glob>. open selects
an artifact in the run's shared public/; without it, one and only one regular
file there is selected automatically.