b01cfd8eb3
Add validated per-stage MCP allowlists while keeping builtin tools separate. Enable matching Claude Code permission rules only for Claude stages, reject unsupported harnesses, and document the unattended-stage safety model.
91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
---
|
|
name: Pipelines
|
|
description: Use existing Pipelines workflows to run, inspect, wait, recover and deliver work, and author definitions when the user explicitly asks.
|
|
---
|
|
|
|
# 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>`.
|
|
|
|
After starting a run, always follow it with `pipelines wait <id>` until it
|
|
finishes; never start a run and move on without waiting. Run the wait as a
|
|
background command (one per run, or one loop over several ids) so the session is
|
|
notified the moment the run ends, then read its result with
|
|
`pipelines inspect <id> --json` and act on it: land, retry, or fix and report.
|
|
Do not poll with repeated `pipelines runs` calls, and do not tell the user a run
|
|
is done, or will be reported, without a wait covering it.
|
|
|
|
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
|
|
|
|
Start from `pipelines templates` and `pipelines new NAME --template KEY`
|
|
(`research`, `task`); these fill in
|
|
the server's provider/model. Read `references/format.md` and
|
|
`references/practices.md` before writing prompts. Stage names: `plan` ·
|
|
`implement` · `review` · `ui-review` · `decide` (human) · `land`.
|
|
|
|
Keep prompts short and objective: what the stage should produce and any real
|
|
constraints. The runner enforces turns, tools and limits and explains the output
|
|
format; prompts do not repeat them. Only `# outcome` is parsed from `output.md`;
|
|
everything else is free markdown. There are no memory, links, input or output
|
|
blocks; stages communicate through `output.md` (`# handoff`) and `public/`.
|
|
|
|
`pipelines validate DRAFT` checks a draft, including the authoring rules
|
|
(errors block submit; `warning:` lines do not but should be fixed);
|
|
`pipelines submit DRAFT` publishes a new immutable version.
|
|
`pipelines help <command>` has flags.
|
|
|
|
Stage `tools` blocks may use `mcp:<server>` or `mcp:<server>/<tool>` for
|
|
Claude-only, allowlisted MCP access. Prefer read-only tools; unattended stages
|
|
deny every MCP tool not listed. The name is the Claude Code display name
|
|
(mapped internally to `mcp__<server>__<tool>`).
|
|
|
|
## References
|
|
|
|
Read only what the task needs. Rows marked operator only are for setting up or
|
|
debugging the server; skip them when authoring.
|
|
|
|
| Need | Reference |
|
|
| --- | --- |
|
|
| Definition syntax, turn files, output.md, checks, landing | `references/format.md` |
|
|
| Good practices (tokens, checks, prompts, loops) | `references/practices.md` |
|
|
| Loop limits | `references/control.md` |
|
|
| Stages, parallel work, recovery | `references/orchestration.md` |
|
|
| Verification and evidence | `references/verification.md` |
|
|
| Failures | `references/debugging.md` |
|
|
| Delivery and installation | `references/delivery.md` |
|
|
| Notifications | `references/notifications.md` |
|
|
| Saved run schedules (never in a definition) | `references/schedules.md` |
|
|
| Transfer and versions | `references/transfer.md` |
|
|
| Queue and work items | `references/work.md`, `references/queue.md` |
|
|
| CLI, storage and run evidence (operator only; not needed for authoring) | `references/operations.md` |
|
|
| Harnesses and models (operator only) | `references/harnesses.md` |
|
|
| Hosting, auth and deployment (operator only) | `references/access.md` |
|
|
|
|
Ask about real ambiguity, destructive actions or changes outside the request;
|
|
routine steps of an authorized task do not need another confirmation.
|