# Pipeshape Gate

> Splits a pipeline at human sign-off points. Use when a workflow needs approval between stages, since the runtime cannot pause for user input mid-run.

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

---


# pipeshape-gate

Turn every approval point into a workflow boundary. N gates produce N+1
workflow segments, and the session carries approved state across them.

## Segment contract

- End every segment with one agent that returns a `schema` object holding
  what the user must decide on. Include a `summary` string and a `questions`
  array; each question carries `options` and a `recommended` value.
- Have that same agent write the full artifact to
  `.pipeline/<slug>/<stage>.md`. The script cannot write files; the agent
  does.
- Keep `.pipeline/` readable by people. Do not put machine logs there. Add
  `.pipeline/` to `.gitignore` when it is missing.

## Single-agent first segment

When the segment before a gate is one agent (an analysis or a spec draft), run
it in the session with the Agent tool instead of a workflow. Keep the same
contract: the agent writes `.pipeline/<slug>/<stage>.md` and returns the
`summary` and `questions` object. Use a workflow for that segment only when
the user wants it saved as a `/<name>` command.

## Between segments

1. Present the returned `summary` and `questions` to the user with
   `AskUserQuestion`. Offer approve, revise, and stop on every gate. Forward
   the agent's options and recommendation as they are.
2. On approve, record the decisions in `.pipeline/<slug>/decisions.md` and
   launch the next segment.
3. On revise, rerun the current segment with the user's changes appended to
   its `args`.
4. On stop, report what `.pipeline/<slug>/` holds and end.

## Passing state forward

- Put decisions and short results directly in `args`.
- When the payload exceeds 2 KB, pass the `.pipeline/<slug>/` path instead
  and have the first agent of the next segment read it.
- Always pass `slug` so every segment writes to the same directory.

## Example

Segment 1 returns:

```json
{
  "summary": "Expiry policy touches CouponService and the batch job.",
  "questions": [
    { "id": "scope", "text": "Include already-issued coupons?",
      "options": ["yes", "no"], "recommended": "no" }
  ]
}
```

The session asks the user, records `scope=no`, then launches segment 2 with
`args: { slug, decisions: { scope: "no" } }`.