# 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 `memory.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: ````markdown # stage worker ```prompt Perform the task. Write the complete output.md markdown; only `# outcome` is required. ``` ```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. Read `references/control.md` for the exact format. ## Result format Each visit gets `input.md`, `memory.md`, `output.md` and `private/` in `/stages/-/`, plus the run-level shared `public/`. The model reads input and memory and returns the complete `output.md` markdown. The only required section is the outcome heading, followed by one of the stage's declared edge words: ````markdown # 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`. 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. Bundled starters show the intended role split: a task stage may read/edit/shell and conditionally use `websearch`/`webfetch`; a planner may read plus conditional web search/fetch; a three-stage implementer has no web tools and works from the planner's research with local read/glob/grep/edit/shell; a reviewer may read plus conditional web; 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. 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. ````markdown # 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 [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: ````markdown # stage committer ```prompt Commit this run's change locally; never push. ``` ```tools read glob grep shell ``` ```edges success -> #success blocked -> #failure error -> #failure ``` ```` State this pre-commit checklist in the prompt: 1. Inspect `git status` and 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. 2. Inspect the staged diff before committing; never commit unrelated work, secrets or generated artifacts. 3. Run the repository's required checks and record the exact commands and observed results as evidence. Do not commit when a required check fails; return `blocked` with the failing output instead. 4. Create no empty commit: when nothing is staged, return `success` with a clear note. 5. Commit with a concise message naming the run's change and report the commit hash; never push, tag, rebase or amend. 6. Ensure the item's per-item documentation note (`docs/notes/.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. The bundled starters `task`, `three-stage` and `docs-fold` each repeat it in their committer prompt because a template is embedded and published on its own; keep those copies in sync with this list. 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. 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 starters are generic and manual-only. Notification attachment/report support and model availability need real runtime tests; structural validation alone cannot confirm delivery.