Files
pipelines/internal/author/skill/SKILL.md
T

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.