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.