Files
pipelines/internal/author/skill/references/format.md
T
alan b01cfd8eb3 Allow named MCP servers in Claude stages
Add validated per-stage MCP allowlists while keeping builtin tools separate. Enable matching Claude Code permission rules only for Claude stages, reject unsupported harnesses, and document the unattended-stage safety model.
2026-11-13 16:06:48 +00:00

9.4 KiB
Raw 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, or (Claude stages only) mcp:<server> / mcp:<server>/<tool>, 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"]}.

Named MCP entries are an explicit allowlist for unattended Claude stages: mcp:ai-memory allows that server's tools, while mcp:linear/list_issues allows one tool. Names are the server/tool names Claude Code displays (mapped internally to mcp__<server>__<tool>; claude.ai connectors may look like claude_ai_Linear). Other harnesses reject these entries. Prefer read-only MCP tools; server configuration is not inspected during validation, so an unknown name may fail at runtime.

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

The notify block accepts on, optional legacy destination, optional artifacts=markdown|files, and optional open=<relative-glob>. open selects an artifact in the run's shared public/; without it, one and only one regular file there is selected automatically.