277 lines
14 KiB
Markdown
277 lines
14 KiB
Markdown
# 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
|
||
`<run>/stages/<seq>-<stage>/`, 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 <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:
|
||
|
||
````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/<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. 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.
|