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:

{
  "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" } }.