Files
pipelines/internal/author/skill/references/format.md
T

93 lines
4.3 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 exactly the previous executed stage's output map. There are
no stage `input` blocks. Preserve needed context explicitly in `output` handoffs.
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=0
```
```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
revision counters in prompts/outputs for feedback loops (runtime also has limits).
Only provider `opencode-go` / model `deepseek-v4.1-flash` are accepted. Retries are
integers 0–100. 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. The native stable API
requests schema output; V2 still requires local envelope validation. Do not
promise recovery of truncated strings, missing evidence or invalid outcomes.
## 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`.
The legacy destination field does not select a per-stage phone. For a native
publisher, inspect the `anime-today` template's ntfy stage: `type=ntfy`,
`destination=system`; its type-specific blocks differ from model stages.
Notification attachment/report support and model availability need real runtime
tests; structural validation alone cannot confirm delivery.