Files
pipelines/examples/README.md
T
alan a48e4a5b6a Replace starters with four graded examples seeded into new databases
The template catalog is now Example 1-4: one stage, two stages (handoff),
feedback loop (runner-owned limits, retries, timeout) and human decision
(type=human approve/revise/abort with notify hooks). All read-only or leave
changes uncommitted; none commits, pushes or deploys.

A brand-new database (schema created by this Open) gets the examples once at
server start, bound to the configured default model and harness. A
server_settings marker records the decision, so removed examples never come
back and existing installs are marked without any pipeline being added or
rewritten.
2026-11-03 19:35:47 +00:00

63 lines
3.3 KiB
Markdown

# Example pipelines
Four small examples, read in order. Each adds one feature to the one before. They
work with any project and use the server's default model and harness.
| Key | Pipeline | Stages | Teaches |
| --- | --- | --- | --- |
| `one-stage` | Example 1: one stage | review | A single read-only stage |
| `two-stages` | Example 2: two stages | draft → check | Handing one stage's output to the next |
| `feedback-loop` | Example 3: feedback loop | implement ⇄ review | A bounded loop (`limits`), `retries` and `timeout` |
| `human-decision` | Example 4: human decision | plan → decide → act | A `type=human` approve/revise/abort stage and `notify` hooks |
- **one-stage** reviews the files or folder named in the run prompt. Read-only.
- **two-stages** drafts a short document from local files, then a second stage
checks it against the sources and the request. Read-only.
- **feedback-loop** makes a small change, then an independent review approves it
or rejects it back to `implement` with must-fix findings. The runner, not the
model, caps the loop with `{"max_visits":3,"on":["rejected"]}`: a third
rejection fails the run. Each stage sets its own `retries` and `timeout`.
Changes stay uncommitted.
- **human-decision** plans a change read-only, then waits for a person to choose
`approve` (carry it out), `revise` (send feedback back to the planner) or
`abort`. Decide in the app, the TUI or with `pipelines decide`. Its `notify`
blocks follow the terminal-path recipe: `plan` on failure, `decide` on
`waiting`, `act` on success and failure. Notifications need the phone
connection set up. Changes stay uncommitted.
No example installs dependencies, commits, pushes or deploys. Missing input
routes to `blocked` (or `rejected`) and fails the run with an explanation. Each
stage returns Markdown; only its `# outcome` section is interpreted (see
`docs/notes/stage-turns.md`).
## On a new install
A brand-new database starts with these four as ordinary pipelines, bound to the
server's default model and harness when the server first creates it. Open, run or
edit them like any other pipeline. This happens once: the server records that it
seeded the database, so removing them does not bring them back, and upgrading an
existing install never adds or rewrites a pipeline. If no default model was set
up before that first start, the examples keep the `provider=default` /
`model=default` markers; pick a model when you run them (`--model`) or edit them.
## As templates
The same files are the server's template catalog: the web/app create flow, TUI
`:templates` and `pipelines templates`. Choosing one creates a new pipeline
through the normal create-only flow; it never replaces an existing one.
```sh
pipelines new "My loop" --template feedback-loop --no-open
pipelines drafts
pipelines submit /path/printed/by/new.md
```
`provider=default` and `model=default` in the checked-in files are neutral markers,
**not real provider/model IDs**. Web, TUI and CLI template creation, and seeding,
bind them to the configured default model and harness. For direct file
submission, replace them with real provider/model IDs yourself.
Editing these files never changes pipelines already in a database, published
versions, run history, drafts or sessions. Renderer regression fixtures live in
`internal/pipeline/testdata`, not here.