A fresh run started from a repository's main checkout gets its own worktree and branch next to the repository, so runs never share a tree or see the operator's uncommitted work, and several can run at once. Retries and runs started in a linked worktree keep their directory. A clean, landed run tree is removed after success; anything else is kept. The delivery gate commits what the land stage left uncommitted in a run worktree, and no longer requires the operator's main checkout to be clean: Git's fast-forward refuses safely when a local change conflicts.
8.5 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; omission means OpenCode (references/harnesses.md).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,
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"]}.
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; see the
human-decision template). 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.