89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
---
|
|
name: Pipelines
|
|
description: Use existing Pipelines workflows to run, inspect, wait, recover and deliver project work. Use only when the work belongs in an existing pipeline; authoring is a separate, explicit task.
|
|
---
|
|
|
|
# Pipelines
|
|
|
|
Pipelines are reusable workflows for repositories. They are optional: direct
|
|
work, delegation and a pipeline are all valid routes. Use whichever finishes the
|
|
task with the least ceremony, and keep work small enough to verify.
|
|
|
|
## Using it
|
|
|
|
`pipelines list` shows the registered workflows; `pipelines runs` shows history.
|
|
Start a run with `pipelines run <name> "<task>"`, and inspect it with
|
|
`pipelines inspect <id>`. `pipelines wait <id>` blocks until it finishes.
|
|
|
|
A failed run keeps its worktree and commits. Read `pipelines inspect <id> --json`
|
|
before deciding: resume the failed stage (`pipelines retry <id>`), fix directly,
|
|
or continue from the preserved branch.
|
|
|
|
## Use an existing pipeline
|
|
|
|
A request to run work is not a request to author. `pipelines list` and
|
|
`pipelines search` come before `pipelines new`. Use the closest existing
|
|
workflow and put task-specific requirements in the run prompt; a pipeline prompt
|
|
is deliberately generic and does not need to match every request word for word.
|
|
|
|
Never create, edit, submit, import, or publish a pipeline or version merely to
|
|
complete a run request. Those actions require an explicit request from the user
|
|
in the current conversation. If no existing pipeline can do the work, stop and
|
|
explain the gap; ask before authoring. Do not add a task-specific pipeline as a
|
|
"safer" alternative to direct work or an existing workflow.
|
|
|
|
## Authoring
|
|
|
|
A definition is Markdown: `# stage <Name>` sections with `prompt`, `configs`,
|
|
`tools`, `edges`, and optional `limits`/`checks`. Start from
|
|
`examples/`. Use stage names that describe the work:
|
|
|
|
`Plan` · `Code` · `Review` · `UIReview` · `Land` (`Prepare` and `Survey` are
|
|
useful variants).
|
|
|
|
Keep prompts short and objective: what the stage should produce and any real
|
|
constraints. The runner enforces turns, tools and limits; prompts do not need to
|
|
repeat them. Only `# outcome` is parsed from `output.md`; everything else is
|
|
free markdown. Use `links` and `memory` only when they clarify a handoff.
|
|
|
|
`pipelines validate DRAFT` checks a draft; `pipelines submit DRAFT` publishes a
|
|
new immutable version. `pipelines help <command>` has flags.
|
|
|
|
Schedules are separate saved run configurations: pipeline/version, prompt,
|
|
workspace and other run options, plus timing. Never add `# settings` or schedule
|
|
blocks to a workflow to arrange recurring work. One generic pipeline can have
|
|
many independent topics and timers. Read `references/schedules.md` when the user
|
|
explicitly asks to manage a schedule; scheduling alone is not workflow authoring.
|
|
|
|
## Turns and artifacts
|
|
|
|
Each visit has `input.md` (the run prompt or previous body), `memory.md`
|
|
(completed turns), `output.md`, and `private/`. Every run also has one shared
|
|
`public/` directory, addressed by its absolute path; files there are visible to
|
|
later stages and are the stage's real artifacts. `input.md`, `memory.md`,
|
|
`output.md` and `session.html` are system evidence for auditing, not stage
|
|
output.
|
|
|
|
## References
|
|
|
|
Read only what the task needs:
|
|
|
|
| Need | Reference |
|
|
| --- | --- |
|
|
| Definition syntax and turn files | `references/format.md` |
|
|
| Limits, tools and permissions | `references/control.md` |
|
|
| Stages, parallel work, recovery | `references/orchestration.md` |
|
|
| CLI, storage and evidence | `references/operations.md` |
|
|
| Verification and accounting | `references/verification.md` |
|
|
| Failures | `references/debugging.md` |
|
|
| Delivery and installation | `references/delivery.md` |
|
|
| Harnesses and models | `references/harnesses.md` |
|
|
| Notifications | `references/notifications.md` |
|
|
| Independent saved run schedules | `references/schedules.md` |
|
|
| Transfer and versions | `references/transfer.md` |
|
|
| Hosting, auth and deployment | `references/access.md` |
|
|
| Queue and work items | `references/work.md`, `references/queue.md` |
|
|
|
|
Ask about real ambiguity, destructive actions or changes outside the request;
|
|
routine steps of an authorized task do not need another confirmation.
|