17 KiB
Definition format
Definitions are Markdown made only of # stage KEY headings and fenced blocks.
Scheduling belongs to separate saved run configurations, not # settings or
schedule blocks in the definition. No unrelated prose outside blocks. The first
stage receives the run prompt in its input.md; later stages receive
the previous turn's output. Every visit also gets a short memory.md (essential
memory, inlined in the prompt) and a full history.md of completed turns. There are no stage input, output, or memory blocks: the model reads
the turn files and writes free-form markdown, and only the # outcome section is
interpreted. Read references/control.md for runner-enforced limits.
Each model stage requires nonempty prompt, configs, and edges blocks:
# stage worker
```prompt
Perform the task.
```
```configs
type=model
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```tools
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
Stage/outcome keys begin with a letter and contain letters, digits, _, or -.
Each outcome has exactly one target: another stage, #success, or #failure.
An omitted error edge defaults to failure. Execution is sequential; forks choose
one outcome, never execute parallel branches. Cycles are allowed; every stage
must be reachable from entry and have a possible path to a terminal. Use bounded
runner-owned limits for feedback loops, never revision counters in model
prompts/outputs: publishing rejects an edge to the same or an earlier stage
(definition order) unless the source stage limits that outcome or the target
stage has limits (a human stage's choices are exempt). Read
references/control.md for the exact format.
Checks
Every model stage that can modify the workspace (it declares edit or shell,
has no tools block, or sets delivery=true) must declare a checks block, so
the author decides where verification happens. Read-only stages need none.
- A
delivery=truestage lists 1–20 commands, one per line. The server runs them on the committed candidate (and again on a merged tree) before landing; a failing command blocks landing. These are the run's deterministic checks. - Every other stage writes exactly one line,
none: <reason>, naming where verification happens instead, for examplenone: focused tests only; the Land delivery gate runs the suiteornone: read-only review; shell is used only for git diff. Commands on a non-delivery stage are rejected because nothing would run them.
A check must fail when it cannot run. Validation rejects guards that pass
without running anything: || true, || :, || exit 0, || echo,
[ ! -x tool ] || ..., test ! -f ... || ..., ! command -v tool || ...,
an if ...; then ...; fi with no failing else, and set +e. Cover every
language the run can change (a Go-only check list does not verify Flutter work).
pipelines validate reports these with the remaining authoring rules
(references/practices.md).
Result format
Each visit gets input.md, memory.md, history.md, output.md and
private/ in <run>/stages/<seq>-<stage>/, plus the run-level shared
public/. What a stage receives:
memory.md(essential, hard cap 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 (latest visit; a revisit is marked) and the server-captured changed files. A stage must be able to work from this alone.input.md(on demand): the full run task and the previous turn's full output.history.md(on demand, never inlined): every completed turn in full, the formatmemory.mdhad before essential memory existed.
Stages with read are told the two on-demand paths; stages without it get
input.md inlined too (capped at 32 KB) but never history.md.
The previous stage's handoff is its # handoff section (any level, up to the
next heading of the same or higher level); without one the server uses the head
of its output, marked as such. Either is truncated to fit with a pointer to
input.md, so nothing depends on the model following the convention. The
prompt asks every stage to start its output with a short handoff: what it did,
files changed, open issues or findings. The only required section is the
outcome heading, followed by one of the stage's declared edge words:
# handoff
Fixed both review findings in cache.go; tests pass. No open issues.
# outcome
success
# Result
Free-form markdown for the next stage and the operator.
internal/turn.ParseOutput matches the heading case-insensitively at any ATX
level and ignores headings or words inside fenced code blocks. A missing,
duplicate, empty or undeclared outcome fails the stage with
FINAL RESULT VALIDATION. Every other heading is uninterpreted and preserved
verbatim in the body. There is no JSON envelope, output schema, field selection
or format-repair pass: do not ask for JSON fields or invent server sections.
Keep turn-local files in private/; put reports, logs and screenshots for later
stages in public/. Never fabricate a result.
Model configs may set harness=opencode or harness=pi; omission preserves
historical OpenCode execution. Read references/harnesses.md for setup/limits.
Use the exact provider/model IDs validated during server setup. New drafts/templates
inherit that selection; do not assume the host's login matches the container's.
Other OpenCode provider/model IDs are accepted syntactically; actual availability,
authentication and inference require pipelines provider-check on the execution
computer/container. Optional retries defaults to 2 (three total attempts),
and accepts integers 0–100; explicit 0 disables execution retries. Optional
timeout defaults to 1h per attempt and accepts positive durations such as
30m or 90s.
A stage that declares a skipped edge (for example a UI reviewer) is eligible
for the server skip fallback: when every earlier visit's file-change capture was
complete and recorded no changed files or screenshots, the server completes the
stage as skipped without a model call (reason_source: fallback). Any recorded
change or incomplete capture runs the model. Optional auto_skip=false (values
true/false, default true) always runs the model. Read
references/operations.md ("Server skip fallback") for the exact rule.
Optional reasoning_effort=high selects a model's reasoning/thinking level for
this stage. Values are default, none (alias off), minimal, low, medium,
high, xhigh, or max. Omission or default preserves the harness/model
default; never add a level automatically to existing workflows. Availability is
model-specific: OpenCode V2 selects the corresponding named model variant and
rejects unavailable variants; Pi uses its native thinking level (none becomes
off) and verifies the effective level before prompting, rejecting unsupported
or silently clamped levels. Explicit effort on OpenCode V1 is unsupported.
Do not instruct the agent to “think harder” as a substitute for this native
setting. Effort is not a token budget or a guaranteed quality improvement; keep
usage budgets/provider spending limits separate. Both text-only and tool-using
model stages honor the setting, without changing their tools or permissions.
Automatic retries cover retryable transport failures and
timeouts; an explicit read-only stage may additionally retry a post-admission
deadline or transport failure, while a stage with edit/shell (or no tools
block) never replays admitted work. Optional budget_usd=1.50 and
budget_tokens=50000 independently cap reported usage.
They accumulate across attempts and repeated visits
to this stage in the same run. Omit either budget to leave that resource unlimited.
Both budgets must be positive; tokens include input, output, reasoning and cache
reads/writes. Accounting failures stop budget-limited stages. In-flight requests
may exceed limits before usage is reported; these are not provider-side hard caps.
In current source, all OpenCode V2 text-only calls use tracked prompting with
all tools denied, rather than the usage-less /generate path. Completed
token-budgeted responses reporting zero tokens fail closed. This is an execution
implementation detail, not a new Markdown field: never add backend/format/API
settings to definitions. Read references/verification.md for the dated live
accounting result and its provider/deployment limitations when relevant.
The run has no additional wall-clock deadline; step/visit caps and cancellation
still apply. A native ntfy stage accepts timeout but never automatically retries
delivery and has no model budget.
Explicit empty tools denies all; allowed tools are read, glob,
grep, webfetch, websearch, edit, shell, one per line. No wildcards,
delegation, or browser tools. Tools are per-stage and automatically enabled by
starting a run. edit supports any file type and creating files/directories in the
run directory; no file list is required. shell supports commands appropriate to
the repository's language and tooling, not a language-specific allowlist. A missing
tools block uses local read/glob/grep/edit/shell tools; prefer explicit stage roles.
Planning stages must not label a task blocked simply because they defer edits to
an implementer stage. The intended role split: an implementer may
read/glob/grep/edit/shell; a planner reads, plus conditional web search/fetch only
when external knowledge is needed; a reviewer reads and may run read-only checks
with shell but never edits; a source-only review stage has no edit/shell; a
research stage uses web search/fetch; a committer has read/glob/grep and shell but
no edit. The bundled examples (one-stage, two-stages, feedback-loop,
human-decision) follow it without web tools. Never force web access for
trivial, fully understood local edits, and return blocked only when required
reliable evidence cannot be obtained rather than whenever one search tool fails.
Keep examples and prompts language-neutral unless the task itself asks for a
specific language.
Optional permissions is a JSON object with edit (run-directory-relative
patterns) and shell (exact commands) arrays. It narrows declared tools and any
run-level file scope; it never enables a missing tool. Empty arrays deny actions.
Nulls, duplicate/unknown keys, traversal and shell wildcards/chaining/redirects or
expansion are rejected. If edits are restricted and shell is enabled, provide an
explicit shell list too. Example: {"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}.
Use this block for intentional file/command restrictions; prose is not a runtime
permission policy. Keep ordinary workflows language-neutral and unrestricted
within their run directory unless the user asks for a narrower scope.
Human (decision) stages
A type=human stage pauses its run until a person chooses one of its outgoing
options. It has no model, agent, tools or configs: it needs a nonempty prompt
block (the operator instructions) and at least one non-error edges outcome.
Its outcomes are exactly its non-error edges, so a draft can express choices such
as deploy, revise or abort; the mandatory error edge is a failure route,
not a choice. It validates, renders, exports and imports like every other type.
# stage gate
```prompt
Review the screenshots and artifacts above, then choose where the run goes.
```
```edges
deploy -> publish
revise -> worker
abort -> #failure
error -> #failure
```
When a run reaches a human stage its step becomes waiting, the run reports it is
waiting on a person, and nothing later runs. Decide from the TUI (open the run,
press c, pick an option, optionally type feedback, Enter) or the CLI:
pipelines decide <run-id> [stage] --option KEY [--feedback TEXT]. The decision
and feedback are recorded as the step's evidence (the feedback stays in the step
output, never an error diagnostic) and the run resumes along that
edge. The wait is persisted, so it survives a server restart. An unknown option is
refused with the valid list; a decision to a stage that is not waiting is refused;
a repeated decision for an already-decided visit does not double-apply. Cancel and
retry keep working while waiting and after a decision, and a human stage is never
killed by a stage timeout or max_visits (the shared run budget still applies).
Committer stages
A workflow that changes the repository ends in a committer: a normal model stage
whose prompt commits the run's change locally and never pushes, tags, deploys or
rewrites history. It is not a native type. Declare shell (and read/glob/grep
when it inspects content) and no edit, so a failed check is reported rather than
patched, and select the runner's captured change set alongside the producer's
declared list:
# stage committer
```prompt
Commit this run's change locally; never push.
```
```tools
read
glob
grep
shell
```
```checks
none: commits locally; the manager lands and runs the suite
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
A landing committer instead sets delivery=true in configs and lists the
repository's required check commands in checks; the server runs them, so its
prompt does not run the suite again.
State this pre-commit checklist in the prompt:
- Inspect
git statusand the full diff. Stage this run's change, including inherited work, restricted to paths that still exist, and keep every exclusion. Do not rely on a model-declared file list. - Inspect the staged diff before committing; never commit unrelated work, secrets or generated artifacts.
- Without a delivery gate, run the repository's required checks once (summary
output) and record the exact commands and observed results as evidence. Do not
commit when a required check fails; return
blockedwith the failing output instead. Withdelivery=truethe server runs thechecksblock; skip this step. - Create no empty commit: when nothing is staged, return
successwith a clear note. - Commit with a concise message naming the run's change and report the commit hash; never push, tag, rebase or amend.
- Ensure the item's per-item documentation note (
docs/notes/<slug>.md, written when the change makes a shared document stale) is staged with the change. Never edit a shared document (a README or topic doc, or a packaged skill reference) here: a single documentation writer folds notes later (references/orchestration.md). An item that staled no shared document has no note and needs no step 6.
This list is the canonical checklist. Repeat it in each committer prompt, because a definition is published on its own; keep those copies in sync with this list. The bundled examples leave changes uncommitted and have no committer.
The committer prepares the complete clean candidate and resolves integration conflicts.
When delivery=true, the server executes the declared checks and lands after the
stage returns success; do not run the post-landing ancestry check beforehand.
If canonical main moved meanwhile, the server merges it into the item (a normal
merge commit), re-runs the checks on the merged tree and lands that; a conflicting
catch-up is aborted with the workspace unchanged and the conflicting files named.
Without a delivery gate, the original workflow or manager completes the merge
and verifies ancestry. No separate merger pipeline is required (references/queue.md).
A stage returns the markdown above, never the retired
{ "outcome": ..., "output": ... } envelope. Do not treat tool-call/DSML markup,
plain prose, or a missing outcome as success, and never rerun tool work merely to
fix a response's formatting.
Scheduling
Publishing a workflow does not schedule it. Create a separate saved schedule
with an explicit pipeline/version and complete run information (prompt, server
workspace, model overrides, notifications, output format and write restrictions
when used). Multiple saved schedules can reuse one workflow with different
research items or timers; updates and deletion do not rewrite the definition.
Use exactly one timing rule: times (24-hour clock values) or every (a duration
of at least one minute), with optional weekdays and timezone.
New definitions with embedded schedules are rejected. Historical immutable
versions remain readable; their latest legacy slots migrate into separate saved
schedules without changing source/history or replaying old occurrences. Never
reintroduce legacy scheduling blocks or make a new workflow just to set another
topic/timer. Warn explicitly before enabling unattended runs. See
references/schedules.md for the API and retry/concurrency guards.
Notifications
Stage hooks use the global phone connection, never store credentials. Optional
fenced notify block: on=success,failure (add waiting to fire when a human
stage parks the run), artifacts=markdown.
Read this skill's references/notifications.md for the minimal terminal-path
recipe and optional native publisher format. Prefer hooks for ordinary success/error
alerts; a request to notify is not a request for a new delivery stage. Do not scan
the user's repository for Pipelines docs. Bundled examples are generic and manual-only.
Notification attachment/report support and model availability need real runtime
tests; structural validation alone cannot confirm delivery.