# Pipeshape Tune

> Improves and changes an installed pipeline harness. Diagnoses a failed workflow run, applies improvements after a run, changes stages, gates, criteria, or agents in a saved workflow, and migrates a v1 pipeline.yml.

- Skill: `terrasnail/pipeshape-tune` (Agent Skill)
- Install (CLI): `npx skillmds@latest add terrasnail/pipeshape-tune`
- Raw SKILL.md: https://api.skillmd.com/api/skills/terrasnail/pipeshape-tune/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-tune

---


# pipeshape-tune

Pick the branch the request names. When a failed run is in the session,
start with **Diagnose**. Every branch that edits a script ends with
**Apply and verify**.

## Diagnose a run

1. Locate the run's transcript directory from the Workflow tool result and
   read `journal.jsonl` there. It holds each agent's actual return value; a
   cached result may be empty.
2. Open `/workflows`, select the failed agent, and read its prompt, tool
   calls, and result.
3. Name the cause as exactly one of these and say which evidence decided it:
   - prompt defect, when the agent did the wrong task or returned prose where
     a schema was required
   - schema contradiction, when the run failed before the agent started
   - permission denial, when a tool call was blocked
   - cap reached, when `parallel()` or `pipeline()` rejected the item list or
     the 1,000-agent limit ended the run
   - upstream null, when a stage received `null` from a stopped or errored
     agent
4. Fix the cause in the script, then relaunch with `resumeFromRunId` so
   unchanged agents return their cached results.

## Improve after a run

Use when a run finished but the user wants better results next time.

1. Read the returned object: `status`, `verdicts`, `rounds`, dropped counts.
2. Classify what went wrong, one label per observation:
   - the same acceptance item failed every round: verdict criteria too vague,
     or the rework prompt lacks the failing evidence
   - reviewers disagreed with QA: add a lens or narrow one
   - a finding was refuted that the user considers real: refuter prompt too
     eager; raise the vote threshold or add a reproduce step
   - the run was escalated at `maxRounds`: raise the ceiling or move the gate
     earlier
   - the user rejected the spec at the gate: analysis prompt is missing a
     question axis
3. Propose at most three changes, each pointing at the exact prompt or option
   to edit, and apply the ones the user picks.

## Change the harness

Map the request to the edit, then apply it.

- Add a stage: one more `agent()` call with a `label` and a `phase` option;
  add its `phase()` title to `meta.phases`; give it a `schema` when a later
  stage branches on it.
- Remove a stage: delete the call and every reference to its result; remove
  its title from `meta.phases`.
- Add or move a gate: split the script at that point per `pipeshape-gate`;
  the segment before it ends with a `schema` summary and a file under
  `.pipeline/<slug>/`.
- Change pass or fail criteria: edit the verdict prompt text and the
  `severity` enum or the check on `findings`.
- Parallelize two stages: wrap them in `parallel()` and move any shared
  interface into the upstream prompt.
- Change model or role: set `model` or `agentType` on that `agent()` call.
- Change commands: edit the `<!-- pipeshape start -->` block in `CLAUDE.md`,
  not the script.
- Add a review lens: append to the `lenses` default or pass it in `args`.
- Two agents overwrite each other's files (implement and test in the same
  `parallel()`): add `isolation: 'worktree'` to both `agent()` calls. It costs
  setup time and disk per agent, so add it only after a collision, not by
  default.

## Migrate a v1 pipeline

1. Read `.claude/skills/<name>/pipeline.yml`, its `prompts/*.md`, and the
   agents it names under `.claude/agents/`.
2. Map each construct with `pipeshape-topologies`:
   - a listed node becomes one `agent()` call; its prompt file becomes the
     prompt string with `{{vars.*}}` replaced by `args.*`
   - `parallel: [...]` becomes `parallel()`
   - `if: FAILED, goto, max, exhausted` becomes the producer and reviewer loop
   - `branch:` becomes expert routing
   - `type: command` becomes an agent instructed to run the command and
     return the exit code in a schema
   - `gate: true` splits the script into segments per `pipeshape-gate`
   - `context:` disappears; pass the referenced result into the prompt string
   - `GRAPH_STATUS` and `GRAPH_OUTPUT` become a `schema` on the agent
3. Fold the agent definition's role text into the prompt string, or keep the
   agent and pass its name as `agentType`.
4. Write `.claude/workflows/<name>.js` and show the user the shape as a short
   phase list.
5. Propose deleting `.claude/skills/<name>/` and the old `CLAUDE.md` marker
   block. Do not delete them yourself.

## Apply and verify

1. Load the `workflow-authoring` bundled skill before editing any script.
2. Keep `export const meta` as the first statement and a pure literal. Keep
   every `phase()` title listed in `meta.phases`.
3. Run `node --check` on the file. When `node` is absent, skip this step;
   `/reload-skills` reports syntax errors instead.
4. Append one line to `.claude/workflows/CHANGELOG.md`: date, request, files
   changed. Create the file when missing.
5. When a write under `.claude/` is denied (headless `-p` runs deny it), write
   the files to a scratch directory instead and print the exact `cp` command
   that moves them into `.claude/workflows/`. Do not silently drop them.
6. Tell the user to run `/reload-skills`, then `/<name>` again.