Files
pipelines/internal/author/skill/SKILL.md
T
alan b01cfd8eb3 Allow named MCP servers in Claude stages
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.
2026-11-13 16:06:48 +00:00

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.