--- 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 ""`, and inspect it with `pipelines inspect `. `pipelines wait ` blocks until it finishes. A failed run keeps its worktree and commits. Read `pipelines inspect --json` before deciding: resume the failed stage (`pipelines retry `), 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 ` 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 ` 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.