# Pipeshape

> Plans and runs a multi-agent pipeline for a development task. Use when work should fan out across agents, repeat the same step over many items, be cross-checked by independent reviewers, or pause for human sign-off between stages.

- Skill: `terrasnail/pipeshape` (Agent Skill)
- Install (CLI): `npx skillmds@latest add terrasnail/pipeshape`
- Raw SKILL.md: https://api.skillmd.com/api/skills/terrasnail/pipeshape/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: terrasnail (https://skillmd.com/u/terrasnail)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/terrasnail/pipeshape

---


# pipeshape

Pick the execution shape for the task, compose the orchestration script, run
it, and carry the result forward. Never scaffold files the task does not need.
A small task that fits in this session is finished in this session; that exit
is the most common correct outcome of step 1.

## 0. Check the environment once

Gather all of this in one pass and keep it for the rest of the session. Do not
ask the user for any of it.

- Build, test, and lint commands from `CLAUDE.md` and the project's build files.
  Read them; never guess.
- Discipline skills available to agents: look for `tdd`, `code-review`,
  `diagnosing-bugs`, and `codebase-design` under `.claude/skills/` and the
  installed plugins. Record which exist.
- Saved workflows under `.claude/workflows/` and plugin workflows in the `/`
  command list. If one already matches the task, run it instead of writing a
  new script.
- Whether the Workflow tool is available in this session. If it is not, run
  the chosen shape in this session with the Agent tool and tell the user once
  that dynamic workflows can be enabled from `/config`.
- Whether `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set to `1` in the
  environment or settings. Agent teams are an option only when it is.

## 1. Decide the shape

Match the task against this list in order and stop at the first hit. State
the chosen shape and its reason in one sentence, then proceed. Do not ask the
user to choose.

- Three or fewer steps, no parallelism, a handful of files: do the work in
  this session with no workflow and without loading the other pipeshape skills.
- The same step repeats over five or more items: workflow with `pipeline()`.
- Two to five independent viewpoints must cross-check one result: workflow
  with `parallel()` followed by a synthesis agent.
- A human must approve something before later stages may run: workflow split
  at each approval point. Follow `pipeshape-gate`.
- Peers must argue with each other and converge on a shared answer: agent
  team, only when the flag from step 0 is on. Otherwise downgrade to a
  workflow with adversarial verification.
- The user will run the same procedure again later: workflow, and offer to
  save it at the end.

## 2. Compose the script

- Load the `workflow-authoring` bundled skill before writing any script.
- Take the topology from `pipeshape-topologies` and fill in the commands and
  skill names gathered in step 0.
- Reference discipline skills by name inside agent prompts, and always attach
  the inline fallback line so the prompt works when the skill is absent:

  ```
  Follow the `tdd` skill if it is available in this environment.
  Otherwise write one failing test at an agreed seam, make it pass, and stop.
  ```

- Give every agent that produces a decision a `schema`. Comparisons on the
  result are plain JavaScript on the returned object.
- Pass task input through `args`. Put text over 2 KB in a file under
  `.pipeline/<slug>/` and pass the path.
- When the task has a gate, compose only the segment up to the first gate.
  When that segment is a single agent, skip the workflow and run it in this
  session with the Agent tool under the same schema and file contract from
  `pipeshape-gate`; a one-agent workflow buys nothing but a saved command.

## 3. Run

Call the Workflow tool with the script inline. This skill's instruction is the
opt-in for that call. Do not write the script to a file first; the runtime
persists it and returns the path.

## 4. Carry the result forward

- Summarize the returned object for the user: what was produced, what failed,
  what was dropped by a cap.
- When a gate follows, continue with the `pipeshape-gate` procedure.
- When the procedure will repeat, tell the user in one line to open
  `/workflows`, select the run, and press `s` to save it as a command.
- When a run fails or returns an empty result, switch to `pipeshape-tune`.