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.