Files
pipelines/examples/README.md
T

3.7 KiB

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.

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.