Files
alan bd07abcde8 Run pipeline stages on Claude Code (harness=claude)
A model stage with harness=claude, provider=anthropic and a Claude model id
runs one claude -p process per visit with the server user's Claude sign-in.
Only the declared tools exist (--tools) and nothing else is approved
(--permission-mode dontAsk); edits are approved only below the run directory
and the stage's artifacts directory. A permissions block, run write paths,
delivery=true and reasoning_effort none/minimal are refused, not widened.

Usage comes from the CLI's final result and counts toward budgets. Failures
are fixed text; billing, quota and rate-limit refusals map to
ErrProviderQuota. The redacted stream is the session export and evidence.
provider-check --harness claude and model overrides are covered.
2026-11-11 10:30:37 +00:00

8.7 KiB
Raw Permalink Blame History

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 # 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:

# 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: <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:

  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: <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.