# 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`). ````markdown # 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 `/stages/-/`, 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 `# handoff` with its outcome and `public/` 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 with `read` reads it on demand; a stage without `read` gets it inlined (up to 32 KB) on every call, so give `read` to stages that follow a large output. - `history.md`: every completed turn in full; on demand for stages with `read`, 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: ````markdown # 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 needs `pipelines provider-check`. - `harness=opencode|pi|claude`; omission means OpenCode (`references/harnesses.md`). `claude` needs `provider=anthropic` and a Claude model ID, and accepts no `permissions` block, `delivery=true` or run write paths. - `retries` 0–100, default 2 (three attempts). Retries cover transport failures and timeouts; a stage with `edit`/`shell` (or no tools block) never replays admitted work. - `timeout` per attempt, default `1h` (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 a `skipped` edge (`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: `, 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: 1. Commit only this run's changes (server list + git status). 2. Check the staged diff for unrelated work and secrets. 3. 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: `-runs/--<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.