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

189 lines
8.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 `<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:
````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: <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.