Files
pipelines/examples/README.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

70 lines
4.1 KiB
Markdown

# Simple workflow templates
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, 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 → 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
APIs, current security/compatibility guidance, or unfamiliar techniques, and they
state why when no research is needed. Trivial, fully understood local edits do not
force web access, and conditional research fails closed only when the required
reliable evidence cannot be obtained, not merely because one search failed. The
`three-stage` implementer has no web tools and works from the planner's research
with local read/edit/shell. The `three-stage` reviewer is an independent quality
gate: it receives the original task and the planner's plan/design/reuse
targets/acceptance checks, inspects the actual changed files and runs its own
checks, returns success only when the applicable acceptance checks were
independently observed passing and no unresolved substantive issue remains, and
otherwise rejects with concrete findings even when a stage reported success.
In the TUI, use `:templates`, choose a starter, and press **s** or Enter on
**Submit template**. Type a name, press Enter to save a retained draft, then
confirm publication. **e Customize** opens the editor picker instead. Canceling
the name prompt creates nothing; canceling publication keeps the saved draft.
CLI equivalent:
```sh
pipelines new "My workflow" --template task --no-open
pipelines drafts
pipelines submit /path/printed/by/new.md
```
New drafts inherit the server's configured default model. The checked-in files
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 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.