bd07abcde8
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.
189 lines
8.7 KiB
Markdown
189 lines
8.7 KiB
Markdown
# 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.
|
||
|