Files
pipelines/internal/author/skill/references/format.md
T
alan c9b904186a Update templates and authoring skill to the current pipeline contract
Bring the packaged starters and the pipelines skill up to the guidelines the
project now works to.

Templates:
- task and three-stage now end in a committer stage that stages the union of the
  runner's captured input.server_changed_files and the producer's declared
  changed_files, runs the repository's checks, commits locally and never pushes;
  their producers no longer commit.
- Every model/agent prompt states the line-oriented result contract (outcome on the
  first non-empty line, "# output" JSON map, other "# <heading>" sections kept
  verbatim as evidence) and an "# evidence" section for exact commands and results,
  with proportionate verification and no fabricated checks.
- Stages that can write save their reports, logs and screenshots into the runtime
  artifacts directory.
- Remove the summary starter: a tool-free single-prompt text transform with no
  repository interaction, artifact or commit is a format demonstration, not a
  reusable workflow. No starter invents a pretend approval stage; a decision point
  is a type=human stage.

Skill:
- references/format.md gains a Result format section (line form, legacy JSON
  precedence, result_parse, raw-output.md, artifacts) and a Committer stages
  section with the pre-commit checklist; the role-split and envelope notes mention
  the line form and the committer.
- orchestration.md points at the checklist and records that a genuine gate is a
  human stage; operations.md and the SKILL.md index drop the removed starter and
  name the result format and committer. No new reference, so the managed inventory
  is unchanged.

Docs/tests: examples/README, README, docs/cli, docs/first-version-testing, the CLI
help example and the smoke script track the four starters; catalog, tool-role,
server, tui and pipeline tests are updated, with a new test pinning the committer
ending and server-captured change set.

Commands run: go build ./...; go vet ./...; go test ./...; python3 -m unittest
discover -s scripts -p 'test_*.py'; python3 scripts/smoke-first-install.py. All
passed. Templates inspected through an isolated CLI server (pipelines templates;
pipelines template KEY --source). No server, service or device was restarted, and
nothing was pushed.
2026-10-17 01:09:42 +01:00

279 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
## Result format
A model or agent stage returns a line-oriented document: the first non-empty line
is the declared outcome (one of the stage's non-error `edges` keys), sections begin
with `# <heading>`, and the required `# output` section holds one JSON object — the
output map that later stages and `memory` select from. Every other heading becomes
an evidence field keyed by its normalised heading (lowercased, spaces to
underscores) and is retained verbatim, so prose, code fences, quotes and embedded
JSON need no escaping. Extra sections are best-effort and never fail the stage.
````markdown
success
# output
{"task": "x", "changed_files": ["a.go"]}
# evidence
go test ./... — PASS (observed output)
````
The legacy single JSON envelope `{ "outcome": "...", "output": {...} }` is still
accepted unchanged. The parser chooses by precedence: a response whose first
non-empty character is `{` (after an optional surrounding fence) uses the JSON path;
a `# ` heading that appears before any `{` uses the line path. A missing outcome, an
undeclared outcome, or a missing/invalid `# output` fails the stage with
`FINAL RESULT VALIDATION`; salvageable sections are retained and the parse status is
recorded under the reserved key `result_parse` (`parsed`, `partial`, `failed`). The
full raw response is saved as `raw-output.md` in the stage's artifacts directory. Use
the line form when the evidence is prose, logs or code; never fabricate a result,
never flatten the output fields alongside the outcome, and save any reports, logs or
screenshots you produce into the artifacts directory the runtime names
(`references/delivery.md`).
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 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, 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; 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
```output
The operator's decision evidence.
```
```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.
```
```memory
{"changed_files":"implementer.changed_files","server_changed_files":"input.server_changed_files"}
```
```tools
read
glob
grep
shell
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
````
State this pre-commit checklist in the prompt:
1. Stage the union of `input.server_changed_files` (the authoritative,
server-captured set) and the declared `changed_files`, restricted to paths that
still exist, keeping every exclusion. A declared list can be incomplete, and a
captured path it omitted is still this run's change (`references/control.md`).
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.
Merging is the operator's or a lane's job, not the committer's: it commits locally
and stops (`references/orchestration.md`, `references/lanes.md`). The server does
not create the commit and cannot enforce the message; a reviewer checks the rules.
Malformed final JSON has bounded recovery even with `retries=0`; it never changes
verdict/evidence. Recovery tries a deterministic local pass first (append missing
closing delimiters, drop one trailing comma, or insert the single comma/colon the
parser expected), then at most one deny-all formatter request whose deadline is
derived from the payload size and the attempt's remaining budget rather than a
fixed short constant. Every path records `repaired`, `partial` or `unrecoverable`
in `format_repairs`; a partial or unrecoverable result is never returned as
complete, and an ambiguous payload (an unescaped quote/colon inside a string
value) is never guessed at. On an explicit read-only stage a rejected malformed
result may be re-emitted up to `retries`; a stage with `edit`/`shell` or no tools
block never replays stage tools or re-emits the result, though the deterministic
pass and the fresh deny-all, tool-free formatter session still apply. 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 line-oriented result format above, or 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` (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.