136 lines
7.4 KiB
Markdown
136 lines
7.4 KiB
Markdown
# Definition format
|
||
|
||
Definitions are Markdown made only of `# stage KEY` headings and fenced blocks.
|
||
An optional `# settings` section precedes all stages. No unrelated prose outside
|
||
blocks. The first stage receives `input.prompt` from the runtime user's task
|
||
and `input.pwd`, the resolved run directory recorded by the server;
|
||
later stages receive previous output unless `memory` explicitly selects fields
|
||
from run-local context. There are no stage `input` blocks. Read
|
||
`references/control.md` for selected memory and runner-enforced limits.
|
||
|
||
Each model stage requires nonempty `output`, `prompt`, `configs`, and `edges` blocks:
|
||
|
||
````markdown
|
||
# stage worker
|
||
|
||
```output
|
||
{ summary, evidence, artifacts }
|
||
```
|
||
|
||
```prompt
|
||
Perform the task supplied in input.prompt. Return evidence, not invented success.
|
||
```
|
||
|
||
```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.
|
||
|
||
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`. Automatic retries only cover retryable transport failures and
|
||
timeouts; admitted tool work is never replayed automatically. Optional
|
||
`budget_usd=1.50` and `budget_tokens=50000` independently cap reported usage.
|
||
They accumulate across attempts, format repair sessions, 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, budgeted 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. 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.
|
||
|
||
Malformed final JSON has bounded, syntax-only recovery even with `retries=0`;
|
||
it never replays stage tools or changes verdict/evidence. Compatible native stable
|
||
backends request schema output with schema retries disabled; a retained deny-all,
|
||
no-inference compatibility probe identifies known format incompatibility. Incompatible
|
||
native backends and V2 require strict local envelope validation. Do not promise
|
||
recovery of truncated strings, missing evidence or invalid outcomes.
|
||
Return the strict `{ "outcome": "declared-edge-key", "output": { ... } }`
|
||
envelope. Do not treat tool-call/DSML markup, plain prose or flattened output as
|
||
success, or rerun tool work to fix a response's formatting.
|
||
|
||
## Scheduling
|
||
|
||
Manual-only is the default. To schedule, put `# settings` before all stages with
|
||
a nonempty fenced `prompt` and one or more fenced `schedule` blocks. Each schedule
|
||
uses exactly one of `times=09:00,17:30` or `every=15m`, optionally
|
||
`days=mon,tue,wed,thu,fri` and `timezone=Europe/London`. Intervals are at least
|
||
one minute. Submission activates the latest version's schedules immediately.
|
||
Removing settings disables schedules on the new version. Scheduled shell/edit
|
||
are not approved. Warn explicitly before adding/changing schedules.
|
||
|
||
## Notifications
|
||
|
||
Stage hooks use the global phone connection, never store credentials. Optional
|
||
fenced `notify` block: `on=success,failure`, `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.
|