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.
This commit is contained in:
2026-10-17 01:09:42 +01:00
parent ce767c344a
commit c9b904186a
21 changed files with 370 additions and 123 deletions
+15 -14
View File
@@ -188,7 +188,7 @@ pipelines
is required on your client computer. Describe the stages, their inputs/outputs,
and the tools they need. Templates (**b** on Home) are optional; a fresh
installation has no published pipelines.
To skip authoring, use **:templates**, choose one of the five generic starters,
To skip authoring, use **:templates**, choose one of the four generic starters,
and press **s** or Enter on **Create pipeline**. Review the prefilled name
(edit it if needed), then press Enter to create—no separate naming or editor
step. **e Customize** edits it first. Templates include a smaller graph preview;
@@ -241,9 +241,9 @@ See [Tailscale troubleshooting](docs/ntfy.md#tailscale-address-times-out-while-l
pipelines uninstall # remove Go binaries; keep history, drafts, and ntfy data
```
## A three-stage pipeline
## A four-stage pipeline
**Plan → Implement → Review**. The first stage receives your task prompt.
**Plan → Implement → Review → Commit**. The first stage receives your task prompt.
Later stages receive the previous output or fields selected by an explicit
`memory` block. One outcome selects the next stage—no
parallel branches. Definitions use Markdown `output`, `prompt`, `tools`,
@@ -284,15 +284,16 @@ error -> #failure
```
````
The [complete three-stage example](examples/three-stage.md) adds the implementer
and reviewer: the planner may search/fetch official sources, the implementer has no
web tools and edits and runs checks from the planner's research, and the reviewer
independently inspects the real changes with its own shell access, receiving the
original task and the planner-owned acceptance checks rather than the
implementer's summary. The reviewer approves only when the applicable acceptance
checks were independently observed passing and no unresolved substantive issue
remains, and otherwise rejects with concrete findings. Review and explicitly
submit it:
The [complete three-stage example](examples/three-stage.md) adds the implementer,
reviewer and committer: the planner may search/fetch official sources, the
implementer has no web tools and edits and runs checks from the planner's research,
the reviewer independently inspects the real changes with its own shell access,
receiving the original task and the planner-owned acceptance checks rather than the
implementer's summary, and the committer stages the runner's captured changed paths
and commits locally without ever pushing. The reviewer approves only when the
applicable acceptance checks were independently observed passing and no unresolved
substantive issue remains, and otherwise rejects with concrete findings. Review and
explicitly submit it:
```sh
pipelines validate examples/three-stage.md
@@ -301,8 +302,8 @@ pipelines run "three stage"
```
Every submission is validated and creates an immutable version. Examples are
optional; nothing is imported automatically. The three stages give a visible
plan → implement → review path using your own accounts and repository; no
optional; nothing is imported automatically. The four stages give a visible
plan → implement → review → commit path using your own accounts and repository; no
maintainer accounts or published definitions are assumed. Run from your
repository directory; stage tools are enabled automatically. Edits support any
language/file type and new files. No file list or typed RUN confirmation is
+9 -6
View File
@@ -126,7 +126,7 @@ pipelines edit # fuzzy pipeline selection
pipelines edit "bug fix" # ask the harness what to change
pipelines edit "bug fix" "Add a review step"
pipelines new "release notes" "Summarize changes and notify my phone"
pipelines new "Text summary" --template summary
pipelines new "Add a feature" --template task
```
`new` opens the configured harness (Pi or OpenCode; host by default, or
@@ -165,14 +165,14 @@ conflicting run and advising you to wait or use a different workspace (for
example another checkout of the repository). Reusing the original request key
reattaches idempotently.
Use `:templates` for five simple, manual-only starters: task, summary, review,
research, and plan/implement/review. **Submit template** (`s` or Enter) asks for a
Use `:templates` for four simple, manual-only starters: task, review, research,
and plan/implement/review. **Submit template** (`s` or Enter) asks for a
name without opening an editor. Enter saves a retained draft, then a separate
confirmation publishes it as a new pipeline. Esc before naming creates nothing;
Esc at publication keeps the draft. **Customize** (`e`) opens the editor picker
instead. Both paths inherit the configured default model and preserve existing
pipelines/history. The research starter requires configured web search support.
Starter stages use goal-appropriate tools: the task stage and the three-stage
Starter stages use goal-appropriate tools: the task worker and the three-stage
implementer edit and run checks, the task, planner and review stages may
search/fetch official sources only when external knowledge is genuinely needed,
the three-stage implementer has no web tools and follows the planner's research,
@@ -180,8 +180,11 @@ the standalone review stage never edits or runs commands and says so explicitly,
and the three-stage reviewer independently inspects the real changes and receives
the planner-owned acceptance checks rather than the implementer's summary,
approving only when the applicable acceptance checks were independently observed
passing and no unresolved substantive issue remains. Editing a bundled template
source changes no installed or published definition; a starter becomes an
passing and no unresolved substantive issue remains. The task and three-stage
templates end in a committer stage that stages the runner's captured changed paths
and commits locally without ever pushing; a genuine operator gate is a `type=human`
decision stage, never a model stage pretending to approve. Editing a bundled
template source changes no installed or published definition; a starter becomes an
immutable version only after explicit authoring and publication.
Home's `n` / `:new` and **Customize** (`e`) on a template first ask how to author the new
+10 -9
View File
@@ -76,10 +76,11 @@ override the saved endpoint; check that you are connected to the intended server
1. Create a disposable repository, then launch `pipelines` **from that directory**.
Docker must see the same absolute path; repositories on another computer are
not uploaded automatically.
2. Use `:templates` and create the **summary** starter. Review its name and publish
explicitly. A fresh database is empty; templates are never auto-published.
3. Open the pipeline and use `:run` with a small task, such as summarizing a short
passage included in the task itself. Review the execution confirmation.
2. Use `:templates` and create the **review** starter (read-only, no repository
change). Review its name and publish explicitly. A fresh database is empty;
templates are never auto-published.
3. Open the pipeline and use `:run` with a small task, such as reviewing one short
file in the disposable repository. Review the execution confirmation.
4. Read the retained report and recorded visits. For an editing workflow, inspect
File changes as well as actual file contents and any verification commands.
Model-written claims alone are not verification.
@@ -91,13 +92,13 @@ override the saved endpoint; check that you are connected to the intended server
Phone reception is a separate manual check. Install/subscribe in the ntfy app and
confirm receipt before depending on it. The installer confirms publishing, not
delivery to your phone. A summary starter does not send alerts automatically.
delivery to your phone. A review starter does not send alerts automatically.
## Known boundaries
- Sequential stages within a run; no parallel branches or built-in
human-approval stages. Independent runs in different workspaces do execute
concurrently.
- Sequential stages within a run; no parallel branches. `type=human` decision
stages pause a run for an operator's choice. Independent runs in different
workspaces do execute concurrently.
- Cancellation/retry is **not rollback**. Retry starts from the entry stage with
fresh sessions and the pinned definition; earlier side effects can repeat.
- Diffs are bounded stage-start/stage-end observations, not full backups or proof
@@ -144,7 +145,7 @@ python3 scripts/smoke-first-install.py
The developer-only smoke check builds source binaries and installs the skill into a disposable directory,
starts an isolated loopback server/database, checks build identity, empty initial
state, five starters, draft/validate/publish, identical ZIP import and restart
state, four starters, draft/validate/publish, identical ZIP import and restart
persistence, then shuts it down and removes only its temporary directory. It does
not call models, send alerts, update your installed clients or deploy Docker services.
It does not replace real-provider, terminal interaction or fresh Docker-install tests.
+23 -7
View File
@@ -1,15 +1,27 @@
# Simple workflow templates
Five optional, technology-neutral starters. Nothing is installed as a published
pipeline automatically; all templates are manual-only and have at most three stages.
Four optional, technology-neutral starters. Nothing is installed as a published
pipeline automatically; all templates are manual-only and have at most four stages.
| Template key | Workflow | Tools |
| --- | --- | --- |
| `task` | Complete a task and report actual results | Repository read/edit and shell, plus conditional web search/fetch |
| `summary` | Summarize supplied text | None |
| `task` | Complete a task, then commit it locally | Work: read/edit/shell and conditional web search/fetch; committer: read/shell |
| `review` | Read repository content and report findings | Read/glob/grep and conditional web search/fetch; no edit/shell |
| `research` | Research a topic, then write a sourced report | Web search/fetch, then none |
| `three-stage` | Plan → implement → review and verify | Planner read/glob/grep + conditional web; implementer read/glob/grep/edit/shell with no web (follows the planner's research); reviewer independent shell + conditional web |
| `three-stage` | Plan → implement → review → commit | Planner read/glob/grep + conditional web; implementer read/glob/grep/edit/shell with no web (follows the planner's research); reviewer independent shell + conditional web; committer read/shell |
Every workflow that changes the repository ends in a **committer** stage that
commits locally and never pushes. The committer stages the union of the runner's
server-captured changed paths (`input.server_changed_files`) and the producer's
declared `changed_files` — a declared list can be incomplete — then runs the
repository's required checks before committing. `task` and `three-stage` follow this;
`review` and `research` change nothing and so do not commit.
Model and agent stages return the line-oriented result: the first non-empty line is
the declared outcome, a `# output` section holds the JSON output map for the next
stage, and any further `# <heading>` section is retained verbatim as evidence. The
legacy `{ "outcome": ..., "output": {...} }` envelope is still accepted. See
`docs/model-results.md`.
Web search/fetch is conditional: stages use it only when a task genuinely needs
external knowledge such as accepted industry approaches, framework or library
@@ -43,11 +55,15 @@ contain a fallback model; direct file submission uses those configs as written.
Provider inference and search availability must be verified on your execution
server. Parsing a definition does not prove its model/tools can run.
Templates do not impose a language, framework, schedule, notification setup,
commit, push, or deployment. Add those only when required by your own workflow.
Templates do not impose a language, framework, schedule, notification setup or
deployment, and they never push to a remote. Work-producing templates commit
locally through their committer stage; add a schedule, notifications or a
deployment step only when your own workflow requires it.
Editing these source files does not change any installed or published definition;
each starter becomes an immutable version only after explicit authoring and
publication.
Removing a template from this catalog does not delete published versions,
run history, retained drafts, or OpenCode sessions. Nested routing examples used
for renderer regression tests live in `internal/pipeline/testdata`, not this catalog.
+2 -3
View File
@@ -12,9 +12,8 @@ import (
var sources embed.FS
var starters = []protocol.Template{
{Key: "task", Name: "Complete a task", Description: "One stage to complete a task in your repository and report actual results."},
{Key: "summary", Name: "Summarize text", Description: "One tool-free stage to summarize supplied text without inventing facts."},
{Key: "three-stage", Name: "Plan, implement, review", Description: "Plan a change, implement it, then review and verify it. Any language or file type."},
{Key: "task", Name: "Complete a task", Description: "Complete a task in your repository, then commit the change locally."},
{Key: "three-stage", Name: "Plan, implement, review", Description: "Plan a change, implement it, review and verify it, then commit it locally. Any language or file type."},
{Key: "review", Name: "Review a repository", Description: "One read-only stage to review repository content and report findings."},
{Key: "research", Name: "Research a topic", Description: "Research a topic on the web, then write a sourced report. Requires web search support."},
}
+45 -9
View File
@@ -20,18 +20,18 @@ func TestReadmeThreeStageExampleIsValid(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if len(graph.Stages) != 3 || graph.Settings != nil {
t.Fatal("example must be manual-only and three stages")
if len(graph.Stages) != 4 || graph.Settings != nil {
t.Fatal("example must be manual-only and four stages")
}
}
func TestCatalogContainsValidUnpublishedTemplates(t *testing.T) {
items := examples.Catalog()
if len(items) != 5 {
if len(items) != 4 {
t.Fatal("unexpected catalog size", len(items))
}
seen := map[string]bool{}
wantStages := map[string]int{"task": 1, "summary": 1, "review": 1, "research": 2, "three-stage": 3}
wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4}
for _, item := range items {
if seen[item.Key] || item.Description == "" || item.Name == "" {
t.Fatal("invalid template metadata", item.Key)
@@ -44,8 +44,8 @@ func TestCatalogContainsValidUnpublishedTemplates(t *testing.T) {
if (graph.Settings != nil) != item.Scheduled {
t.Fatal("missing schedule warning", item.Key)
}
if graph.Settings != nil || len(graph.Stages) > 3 {
t.Fatal("starters must be simple and manual-only", item.Key)
if graph.Settings != nil || len(graph.Stages) > 4 {
t.Fatal("starters must be small and manual-only", item.Key)
}
if len(graph.Stages) != wantStages[item.Key] {
t.Fatal("unexpected/non-generic catalog entry", item.Key)
@@ -89,9 +89,11 @@ func stageTools(t *testing.T, graph pipeline.Graph, key string) ([]string, bool)
// Every bundled starter declares a tools block; an empty list is the intentional
// deny-all tool-free role.
var starterTools = map[string]map[string][]string{
"task": {"worker": {"read", "glob", "grep", "edit", "shell", "websearch", "webfetch"}},
"summary": {"summarize": {}},
"review": {"review": {"read", "glob", "grep", "websearch", "webfetch"}},
"task": {
"worker": {"read", "glob", "grep", "edit", "shell", "websearch", "webfetch"},
"committer": {"read", "glob", "grep", "shell"},
},
"review": {"review": {"read", "glob", "grep", "websearch", "webfetch"}},
"research": {
"research": {"websearch", "webfetch"},
"report": {},
@@ -100,6 +102,7 @@ var starterTools = map[string]map[string][]string{
"planner": {"read", "glob", "grep", "websearch", "webfetch"},
"implementer": {"read", "glob", "grep", "edit", "shell"},
"reviewer": {"read", "glob", "grep", "shell", "websearch", "webfetch"},
"committer": {"read", "glob", "grep", "shell"},
},
}
@@ -171,3 +174,36 @@ func TestThreeStageReviewerMemoryKeepsPlannerAcceptance(t *testing.T) {
}
}
}
// TestWorkProducingStartersEndInACommitter pins the guideline that a workflow
// which changes the repository commits locally through its final committer stage,
// staging the server-captured change set rather than only a model's declaration.
func TestWorkProducingStartersEndInACommitter(t *testing.T) {
for _, tc := range []struct{ key, producer string }{
{"task", "worker"},
{"three-stage", "implementer"},
} {
graph := parsedCatalog(t)[tc.key]
last := graph.Stages[len(graph.Stages)-1]
if last.Key != "committer" {
t.Fatalf("%s must end in a committer stage, got %q", tc.key, last.Key)
}
if got := last.Edges["success"]; got != protocol.SuccessEnd {
t.Fatalf("%s committer success route = %q, want %q", tc.key, got, protocol.SuccessEnd)
}
if got := last.Memory["server_changed_files"]; got != "input.server_changed_files" {
t.Fatalf("%s committer must select input.server_changed_files, got %q", tc.key, got)
}
if got := last.Memory["changed_files"]; got != tc.producer+".changed_files" {
t.Fatalf("%s committer changed_files = %q, want %q", tc.key, got, tc.producer+".changed_files")
}
// The producer hands its work on rather than ending the run itself.
for _, s := range graph.Stages {
if s.Key == tc.producer {
if protocol.IsTerminal(s.Edges["success"]) {
t.Fatalf("%s/%s must hand success to a later stage, not %q", tc.key, tc.producer, s.Edges["success"])
}
}
}
}
}
+8 -1
View File
@@ -17,7 +17,11 @@ gaps and source/version applicability, and do not invent citations. Return block
when required reliable evidence cannot be obtained, including empty or unreliable
results. A single failed, blocked or anti-bot search may be replaced
by a successful official-source webfetch that fully supplies the required
evidence. Return success only with reliable evidence.
evidence. Return success only with reliable evidence. Return the line-oriented
result: the first non-empty line is the declared outcome, a `# output` section
holds one JSON object with the output fields named above, and any further
`# <heading>` section is retained verbatim as evidence (for example the queries
run and source excerpts).
```
```tools
@@ -49,6 +53,9 @@ Answer input.question using only the collected evidence and sources. Write a
concise report with citations and clearly marked uncertainties. Respect the
original constraints. Do not turn missing evidence into a confident answer.
Return success for a supported report or blocked when the evidence is insufficient.
Return the line-oriented result: the first non-empty line is the declared outcome,
a `# output` section holds one JSON object with the output fields named above, and
any further `# <heading>` section is retained verbatim as evidence.
```
```tools
+5 -1
View File
@@ -21,7 +21,11 @@ hypotheses. State explicitly that no commands were run and that runtime behavior
and checks are not tested; source inspection is not proof of execution. Return
success when the review is complete, even if it finds issues; return blocked if
the requested content or required official evidence cannot be obtained rather than
fabricating it. Do not claim issues have been fixed.
fabricating it. Do not claim issues have been fixed. Return the line-oriented
result: the first non-empty line is the declared outcome, a `# output` section
holds one JSON object with the output fields named above, and any further
`# <heading>` section is retained verbatim as evidence (for example the files read
and the sources checked, with their dates/versions).
```
```tools
-28
View File
@@ -1,28 +0,0 @@
# stage summarize
```output
{ summary, key_points, open_questions }
```
```prompt
Summarize the text supplied in input.prompt. Preserve its meaning, important
facts, decisions, and unresolved questions. Follow any requested length or
format. Use only the supplied information; do not invent sources or facts.
Return blocked if no text to summarize was supplied. Otherwise return success.
```
```tools
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
+65 -12
View File
@@ -1,7 +1,7 @@
# stage worker
```output
{ task, summary, changed_files, evidence, remaining_questions }
{ task, summary, changed_files, remaining_questions }
```
```prompt
@@ -16,20 +16,25 @@ existing dependencies/APIs/helpers over bespoke or copy-pasted code, and avoid
unnecessary new dependencies rather than treating useful supported standard
libraries as off-limits; justify any genuinely needed custom implementation,
compatibility exception or dependency choice with its tradeoffs and do not force
coincidental
lookalikes into a shared abstraction. Research official primary sources with
websearch/webfetch only when the task genuinely needs external knowledge,
recording source URLs and applicability/version evidence or stating why none was
needed; keep queries free of private code and secrets. Return blocked only when
required reliable evidence cannot be obtained; a single failed, blocked or
coincidental lookalikes into a shared abstraction. Research official primary
sources with websearch/webfetch only when the task genuinely needs external
knowledge, recording source URLs and applicability/version evidence or stating why
none was needed; keep queries free of private code and secrets. Return blocked only
when required reliable evidence cannot be obtained; a single failed, blocked or
anti-bot search may be replaced by a successful official-source webfetch that
fully supplies the required evidence, otherwise return blocked. Fix causes rather
than suppressing errors or weakening checks, and avoid speculative abstractions.
Preserve unrelated work. Do not commit, push, deploy, or perform destructive
actions. Verify changes with relevant checks and report actual commands, observed
results and untested limits in evidence. Never claim an unexecuted check passed.
Return blocked if the task or required tools are unavailable; otherwise return
success with actual results.
Preserve unrelated work and leave the commit to the committer stage: do not commit,
push, deploy, or perform destructive actions. Save any artifacts you produce
(reports, logs, screenshots) into the artifacts directory named in the runtime
context; they are attached to this stage. Verify the change with the repository's
relevant checks and report the exact commands and observed results in an
`# evidence` section; never claim an unexecuted check passed. Return the
line-oriented result: the first non-empty line is the declared outcome, a
`# output` section holds one JSON object with the output fields named above, and
any further `# <heading>` section is retained verbatim as evidence. Return blocked
if the task or required tools are unavailable; otherwise return success with
actual results.
```
```tools
@@ -49,6 +54,54 @@ retries=2
timeout=1h
```
```edges
success -> committer
blocked -> #failure
error -> #failure
```
# stage committer
```output
{ committed, commit, changed_files, pre_commit_checks }
```
```prompt
Commit this run's change locally. Never push, tag, deploy or rewrite history.
Select the run's changed paths from input.server_changed_files (the runner's
captured evidence) and the worker's declared changed_files, and stage their union
of paths that still exist, keeping any exclusions. Inspect the staged diff before
committing; never commit unrelated work, secrets or generated artifacts. Pre-commit
checklist: confirm the staged paths are this run's change; run the repository's
required checks and record the exact commands and observed results in an
`# evidence` section; do not commit if a required check fails, return blocked
with the failing output instead. If nothing is staged, do not create an empty
commit; return success with a clear note. Otherwise commit with a concise message
naming this run's change and report the commit hash. Return the line-oriented
result: the first non-empty line is the declared outcome, a `# output` section
holds one JSON object with the output fields named above, and any further
`# <heading>` section is retained verbatim as evidence. Never claim an unexecuted
check passed or fabricate a commit.
```
```memory
{"task":"input.prompt","changed_files":"worker.changed_files","server_changed_files":"input.server_changed_files"}
```
```tools
read
glob
grep
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> #success
blocked -> #failure
+78 -16
View File
@@ -23,7 +23,10 @@ fully supplies the required evidence, otherwise return blocked. Limit repository
inspection to relevant repository paths; never scan filesystem or mount roots,
and use commands supported by the actual execution environment rather than
guessed platform flags (a working instruction, not an OS sandbox). Preserve the
user's task and constraints; do not invent evidence.
user's task and constraints; do not invent evidence. Return the line-oriented
result: the first non-empty line is the declared outcome, a `# output` section
holds one JSON object with the output fields named above, and any further
`# <heading>` section is retained verbatim as evidence.
```
```tools
@@ -50,7 +53,7 @@ error -> #failure
# stage implementer
```output
{ task, plan, acceptance_checks, changed_files, implementation_summary, evidence }
{ task, plan, acceptance_checks, changed_files, implementation_summary }
```
```prompt
@@ -68,11 +71,17 @@ cancellation, error handling and bounded performance where applicable. Limit
repository inspection and verification to relevant repository paths; never scan
filesystem or mount roots, and use commands supported by the actual execution
environment rather than guessed platform flags (a working instruction, not an OS
sandbox). Run the relevant checks with the stage tools and record the exact
commands, observed results and any untested limits in evidence. Preserve the
task, plan and acceptance checks and record actual changes in changed_files; do
not commit, push, deploy or destroy unrelated work. Return blocked when the
required edit scope or tools are unavailable.
sandbox). Save any artifacts you produce (reports, logs, screenshots) into the
artifacts directory named in the runtime context; they are attached to this stage.
Run the relevant checks with the stage tools and record the exact commands,
observed results and any untested limits in an `# evidence` section; never
claim an unexecuted check passed. Preserve the task, plan and acceptance checks and
record actual changes in changed_files. Do not commit, push, deploy or destroy
unrelated work; the committer stage commits this run's change. Return the
line-oriented result: the first non-empty line is the declared outcome, a
`# output` section holds one JSON object with the output fields named above, and
any further `# <heading>` section is retained verbatim as evidence. Return blocked
when the required edit scope or tools are unavailable.
```
```tools
@@ -113,18 +122,23 @@ unnecessary bespoke solutions, not only overall architecture. Support each findi
with a concrete location, evidence, severity and remedy; distinguish blocking
evidence gaps from nonblocking personal-style nits and explain legitimate
deviations. Run relevant checks with the stage tools yourself and report what was
not tested; do not accept a prior stage's summary as proof. Limit inspection and
not tested in an `# evidence` section; do not accept a prior stage's summary as
proof and never claim an unexecuted check passed. Limit inspection and
verification to relevant repository paths; never scan filesystem or mount roots,
and run commands supported by the actual execution environment rather than
guessed platform flags (working instructions, not an OS sandbox guarantee).
Return success only when the applicable acceptance checks were independently
observed passing and no unresolved substantive design, reuse, duplication,
workaround or correctness issue remains; return rejected with concrete findings
for failing checks, missing REQUIRED verification, or substantive code-quality
issues. Optional or
guessed platform flags (working instructions, not an OS sandbox guarantee). Save
any artifacts you produce (reports, logs, screenshots) into the artifacts
directory named in the runtime context; they are attached to this stage. Return
the line-oriented result: the first non-empty line is the declared outcome, a
`# output` section holds one JSON object with the output fields named above, and
any further `# <heading>` section is retained verbatim as evidence. Return success
only when the applicable acceptance checks were independently observed passing and
no unresolved substantive design, reuse, duplication, workaround or correctness
issue remains; return rejected with concrete findings for failing checks, missing
REQUIRED verification, or substantive code-quality issues. Optional or
out-of-scope checks may be recorded untested without forcing endless work. Use
websearch/webfetch only when an official standard or documentation check is
needed. Do not edit files, claim unexecuted checks, commit, push or deploy.
needed. Do not edit files, commit, push or deploy.
```
```memory
@@ -148,7 +162,55 @@ timeout=1h
```
```edges
success -> #success
success -> committer
rejected -> #failure
error -> #failure
```
# stage committer
```output
{ committed, commit, changed_files, pre_commit_checks }
```
```prompt
Commit this run's change locally. Never push, tag, deploy or rewrite history.
Select the run's changed paths from input.server_changed_files (the runner's
captured evidence) and the implementer's declared changed_files, and stage their
union of paths that still exist, keeping any exclusions. Inspect the staged diff
before committing; never commit unrelated work, secrets or generated artifacts.
Pre-commit checklist: confirm the staged paths are this run's change; run the
repository's required checks and record the exact commands and observed results in
a `# evidence` section; do not commit if a required check fails, return
blocked with the failing output instead. If nothing is staged, do not create an
empty commit; return success with a clear note. Otherwise commit with a concise
message naming this run's change and report the commit hash. Return the
line-oriented result: the first non-empty line is the declared outcome, a
`# output` section holds one JSON object with the output fields named above, and
any further `# <heading>` section is retained verbatim as evidence. Never claim an
unexecuted check passed or fabricate a commit.
```
```memory
{"task":"input.prompt","changed_files":"implementer.changed_files","server_changed_files":"input.server_changed_files"}
```
```tools
read
glob
grep
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
+1 -1
View File
@@ -63,7 +63,7 @@ and `references/format.md` (in parallel when possible); for notifications also r
| Parallel lanes, worktrees, sync/merge, restart replay | `references/lanes.md` |
| Diagnose a wedged, blocked or failed run | `references/debugging.md` |
| Publish artefacts, LAN URLs, install boundaries | `references/delivery.md` |
| Definition format, tools, permissions, routing, schedules, budgets | `references/format.md` |
| Result format, tools, permissions, committer, routing, schedules, budgets | `references/format.md` |
| Bounded loops, independent review, selected shared context | `references/control.md` |
| OpenCode/Pi configuration, model defaults, harness limits | `references/harnesses.md` |
| Phone alerts and report/file attachments | `references/notifications.md` |
+93 -4
View File
@@ -47,6 +47,39 @@ 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
@@ -89,7 +122,8 @@ 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
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
@@ -145,6 +179,60 @@ a repeated decision for an already-decided visit does not double-apply. Cancel a
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
@@ -162,9 +250,10 @@ 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.
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
@@ -10,7 +10,7 @@ parallel/distributed task engine or a guarantee that model reports are correct.
- Drafts are editable Markdown plus JSON metadata. Publishing validates and creates
immutable versions; drafts remain retained. Keep context create-only/base-version
guards. Five optional generic starters are task, summary, review, research and
guards. Four optional generic starters are task, review, research and
three-stage; a fresh database starts empty. Templates can be created directly with
an editable prefilled name or customized first. Editing a bundled repository
template changes no installed or published definition; only explicit authoring
@@ -119,7 +119,11 @@ Adapt the scope and publishing lines per item; keep the rest.
files. It must select `input.server_changed_files` (the runner's captured evidence,
`references/control.md`) alongside the implementer's declared `changed_files` and
stage their union: an implementer's declared list can be incomplete, and a captured
path it omitted is still this run's change.
path it omitted is still this run's change. Its prompt carries the pre-commit
checklist in `references/format.md`; it commits locally and stops, never pushing.
- A run cannot approve its own work. When an item genuinely needs an operator gate
before it continues or commits, insert a `type=human` decision stage
(`references/format.md`); never invent a model stage that pretends to approve.
- Choose per item: a logic, server or format change usually wants the planner
(a plan/implement/review pipeline); a small, fully understood tweak may use the
leaner implementer-first variant. Both keep all review stages.
+1 -1
View File
@@ -58,7 +58,7 @@ Use pipelines help <command> for its flags. Names with spaces must be quoted.
Examples:
pipelines edit "bug fix" "Add a review step"
pipelines new "release notes" "Summarize changes and notify my phone"
pipelines new "Text summary" --template summary --no-open --json --yes
pipelines new "Add a feature" --template task --no-open --json --yes
pipelines validate /path/to/draft.md --json
pipelines submit /path/to/draft.md
pipelines run "bug fix" "Fix the layout" --json
+1 -1
View File
@@ -10,7 +10,7 @@ import (
)
func TestShowcaseDefinitions(t *testing.T) {
for _, name := range []string{"task", "summary", "review", "research", "three-stage"} {
for _, name := range []string{"task", "review", "research", "three-stage"} {
t.Run(name, func(t *testing.T) {
source, err := os.ReadFile(filepath.Join("..", "..", "examples", name+".md"))
if err != nil {
+1 -1
View File
@@ -44,7 +44,7 @@ func TestTemplatesDoNotSeedDatabaseAndCreateOnlyPreservesExisting(t *testing.T)
if err := wsjson.Read(ctx, conn, &response); err != nil {
t.Fatal(err)
}
if response.Type != protocol.Templates || len(response.Templates) != 5 {
if response.Type != protocol.Templates || len(response.Templates) != 4 {
t.Fatal("missing catalog", response.Type, len(response.Templates))
}
items, err := store.List(ctx)
+1 -1
View File
@@ -11,7 +11,7 @@ import (
)
func TestShowcaseGraphsRender(t *testing.T) {
for _, name := range []string{"task", "summary", "review", "research", "three-stage"} {
for _, name := range []string{"task", "review", "research", "three-stage"} {
t.Run(name, func(t *testing.T) {
source, err := os.ReadFile(filepath.Join("..", "..", "examples", name+".md"))
if err != nil {
+3 -3
View File
@@ -38,7 +38,7 @@ func TestTemplateSubmitNamesRetainsAndExplicitlyPublishesSelectedTemplate(t *tes
m.templateOpen, m.keys.templates = true, true
m.defaultModel = "fixture/model"
for i, item := range m.templates {
if item.Key == "summary" {
if item.Key == "review" {
m.templateIndex = i
}
}
@@ -72,7 +72,7 @@ func TestTemplateSubmitNamesRetainsAndExplicitlyPublishesSelectedTemplate(t *tes
m = updated.(Model)
updated, _ = m.Update(tea.KeyMsg{Type: tea.KeyCtrlK})
m = updated.(Model)
updated, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("Simple summary")})
updated, _ = m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("Simple review")})
m = updated.(Model)
updated, cmd = m.Update(tea.KeyMsg{Type: tea.KeyEnter})
m = updated.(Model)
@@ -81,7 +81,7 @@ func TestTemplateSubmitNamesRetainsAndExplicitlyPublishesSelectedTemplate(t *tes
t.Fatal("single create confirmation did not send or failed to retain draft")
}
retained, err := draft.Load(m.pendingDraft.path)
if err != nil || retained.Name != "Simple summary" || retained.Server != url || !retained.CreateOnly || retained.BaseVersion != 0 {
if err != nil || retained.Name != "Simple review" || retained.Server != url || !retained.CreateOnly || retained.BaseVersion != 0 {
t.Fatal("template draft metadata lost", retained, err)
}
text, err := draft.Read(retained.Path)
+3 -3
View File
@@ -78,8 +78,8 @@ def main():
assert pong["build"] == version, "Client/server build mismatch"
assert not rpc("list").get("pipelines"), "Fresh database must be empty"
assert not rpc("runs").get("runs"), "Fresh database must have no runs"
assert len(rpc("templates")["templates"]) == 5
draft = rpc("new", "First test", "Summarize input", "--template", "summary", "--no-open", "--yes")
assert len(rpc("templates")["templates"]) == 4
draft = rpc("new", "First test", "Review the repository", "--template", "review", "--no-open", "--yes")
assert not rpc("list").get("pipelines"), "Draft creation must not publish"
rpc("validate", draft["path"])
rpc("submit", draft["path"], "--yes")
@@ -100,7 +100,7 @@ def main():
assert not rpc("runs").get("runs"), "Smoke check must not execute a workflow"
finally:
stop(process)
print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, five templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.")
print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, four templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.")
if __name__ == "__main__":