Files
pipelines/internal/author/skill/references/format.md
T
alan 05ae530442 Make Pipelines Docker-only with OpenCode and Pi
Install current verified harness releases inside Docker, preserve persistent accounts and settings, and provide separate interactive and pipeline model defaults with terminal onboarding and fuzzy pickers.

Add Docker-aware authoring transport, Pi stage execution, bounded workflow controls, reliable final-result readback and usage settlement, and finite short-lived CLI pipe draining. Keep dated installation evidence and packaged authoring guidance consistent.

Verified with a real Docker installation, both harness stages and interactive authors, the built-in plan/implement/review starter, independent host race/vet checks, installer tests, and packaged skill tests. Generated release receipts stay ignored in clean checkouts.
2026-10-11 23:00:25 +01:00

6.8 KiB
Raw Blame History

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:

# 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. 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.