70 lines
3.7 KiB
Markdown
70 lines
3.7 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`).
|
|
|
|
Stages that can change files (`edit` or `shell`) declare a `checks` block. These
|
|
examples leave changes uncommitted, so each says `none: <reason>`: implementers
|
|
run focused checks only and reviewers read the diff without running suites. A
|
|
landing stage would set `delivery=true` and list the project's check commands
|
|
there for the server to run. Every example passes `pipelines validate` with no
|
|
errors or warnings.
|
|
|
|
## 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.
|