Running the Pipeline

You don’t run the coding pipeline by hand. You brief an AI coding agent in plain language, and the agent drives it — reading the issue, recommending a review-rigor variant, and (once you approve) working through the phases, calling the outside-review tooling itself at the two human gates. Your job is the decision points: confirm the variant, approve the brief, approve the diff, merge.

For the phases, roles, and the per-variant flow diagrams, see the Coding Pipeline reference page; for when to reach for each rung, see the AI Pipeline page.

How you start it

Kick the pipeline off with a natural-language instruction. A typical opener asks the agent to scope the work and recommend a rung, but not to start:

Execute issue #3579xxx using the coding pipeline. Read the issue, tell me which review-rigor variant you recommend (base / second-opinion / panel) and why, and note that recommendation on the issue. Don’t start yet.

(The base rung has accepted synonyms — base, standard, no variant, and none all name the same rung; base is the primary label.)

The agent reads the issue and the playbook, posts its recommended variant (with reasoning) to the issue, and stops. When you’re ready:

Looks good — begin work at second-opinion.

From there the agent runs the phases and pauses for you at the two gates:

• Brief gate (after it writes the brief) — you approve the plan. On second-opinion / panel the agent has already run the outside review and folds its findings in first.
• Diff gate (after the tests go green) — you approve the diff for merge; a hard (BLOCK) finding stops it.

If the change touches a UI surface, there is also a wireframe sign-off before any code is written. The agent never self-merges — a human does the final merge.

The review-rigor dial — the agent recommends, you confirm

The rung is picked per issue. The agent proposes one and records it on the issue; you can accept or override it:

• base — thin / mechanical changes; the pipeline’s own architecture / test / UI / spec agents are the only reviewers. No API key needed. (Accepted synonyms: standard, no variant, none — the same rung. base is the primary label; none remains accepted.)
• second-opinion (also called dual review) — the default minimum for non-trivial work; the agent adds the Critic (Model 2, one independent outside model) at the brief and diff gates. Needs the Critic configured (see setup below).
• panel — high-stakes changes; the agent adds a two-model pair — the Critic (ideally a different provider) and a fresh-context Author (Model 1) — on a byte-identical prompt, then reconciles their findings.

The two models

The dial names two models as variables, so you bind them to whatever you have access to — no one is locked to a specific provider:

• Author (Model 1) — your primary/coding model; the agent you already run. It writes the code and, on panel, serves as the fresh-context same-house reviewer.
• Critic (Model 2) — the independent outside reviewer called at the gates. It’s reached through LiteLLM, so it can be any of 100+ providers — OpenAI, Anthropic, Google, Azure, Bedrock, OpenRouter, Groq, or a local runtime (Ollama, vLLM, LM Studio) — named with a LiteLLM model string (openai/o4-mini, anthropic/claude-sonnet-5, ollama/llama3, …). A raw command escape hatch covers anything else. Ideally a different provider than the Author, so panel gets genuine cross-vendor diversity.

One-time setup — setup-pipeline.sh (only for second-opinion / panel)

base needs no setup. For second-opinion / panel, bind the two models to whatever you have access to by running the setup script once, from the repo root:

.claude/scripts/setup-pipeline.sh

It walks you through three things and writes them to .env (chmod 600, git-ignored and export-ignored — never committed, never shipped):

1. Author model — the model your coding agent runs on (informational; e.g. claude-opus-4-8).
2. Critic model — a LiteLLM model string, e.g. openai/o4-mini, anthropic/claude-sonnet-5, gemini/gemini-2.5-flash, ollama/llama3, openrouter/<vendor>/<model>.
3. Credentials — the API key for that model’s provider (the script infers which key from the model prefix; local runtimes need none). It also checks for the litellm package and offers to pip install it. (Press Enter to keep a default; re-run any time to change a value.)

Use a local model as the Critic — no key, nothing leaves your machine. Either give a LiteLLM local model string (ollama/llama3, vllm/…, lm_studio/…), or use the raw command type with any CLI that reads the prompt on stdin and writes the review to stdout (e.g. ollama run llama3).

Non-interactive (CI, scripting) — pass flags instead of answering prompts:

# an Anthropic Critic (installs litellm if missing)
.claude/scripts/setup-pipeline.sh --author claude-opus-4-8 \
  --critic-provider litellm --critic-model anthropic/claude-sonnet-5 --key sk-ant-... --install-deps

# a local Critic via Ollama (through LiteLLM — no key)
.claude/scripts/setup-pipeline.sh --author claude-opus-4-8 \
  --critic-provider litellm --critic-model ollama/llama3

# a local Critic via the raw command hook
.claude/scripts/setup-pipeline.sh --author claude-opus-4-8 \
  --critic-provider command --critic-model llama3 --critic-command 'ollama run llama3'

Run .claude/scripts/setup-pipeline.sh --help for the full flag list. Prefer to do it entirely by hand? cp .env.example .env and edit — it documents every variable. With DUAL_REVIEW=0 (or no Critic configured) the dial simply degrades to the base rung (base / none), which needs no setup at all.

Check it works

Point the Critic at a throwaway brief to confirm the wiring end to end before you rely on it at a gate:

printf '# Brief\n## Goal\ntest\n' > /tmp/brief.md
.claude/scripts/dual-review.sh --mode brief --brief /tmp/brief.md --out /tmp/review.md
# → prints "critic: <model> via <provider>" and writes the review to /tmp/review.md

If it errors, the message tells you what to fix: an auth error means the provider’s key isn’t set (or is misnamed) in .env; a not_found model means your account/key doesn’t offer that exact model string — check the provider’s own model list and use one it has (model aliases like …-latest and dated snapshots vary by account).

Reasoning models (o-series, DeepSeek-Reasoner, Claude extended thinking)

A review gate wants a thinking Critic, so critic.py asks for high reasoning effort by default (PIPELINE_CRITIC_REASONING_EFFORT=high). Reasoning models have sharp edges worth knowing — they are the usual source of “it worked with model X but not model Y”:

• Models that can’t reason reject the effort param. A non-thinking model — notably many local Ollama models — errors at runtime with something like “does not support thinking”. critic.py catches this and retries once without the reasoning param, so the review still goes through. To skip that wasted first call, set PIPELINE_CRITIC_REASONING_EFFORT=none for such a Critic.
• Reasoning eats the output budget. Reasoning tokens count against the response. If you set PIPELINE_CRITIC_MAX_TOKENS too low, the model spends it thinking and returns an empty or truncated review. Leave it unset (use the provider’s default) for reasoning models, or set it generously.
• Unsupported knobs are dropped, not fatal. Reasoning models often reject temperature, system messages, etc.; LiteLLM’s drop_params silently drops them.
• Slower and pricier. High effort trades latency and cost for depth — right for the gate, but expect these calls to take longer.

Tune per Critic in .env: PIPELINE_CRITIC_REASONING_EFFORT (high | medium | low | none) and PIPELINE_CRITIC_MAX_TOKENS.

What the agent uses under the hood

You don’t invoke any of this directly — it’s what the agent drives on your behalf:

• .claude/agents/ — the role subagents (orchestrator, designer, architecture-reviewer, tester, feature-implementor, playwright-ui-walkthrough, spec-auditor). The agent loads whichever role it is playing.

• .claude/scripts/setup-pipeline.sh — the one-time setup you run yourself; binds the Author and Critic variables to your models and writes .env.

• .claude/scripts/dual-review.sh — the Critic engine it runs at the gates on the second-opinion / panel rungs. It calls the Critic through .claude/scripts/critic.py (LiteLLM — any provider incl. local), or a raw command. For reference or debugging, the calls look like:

  # brief gate
  .claude/scripts/dual-review.sh --mode brief --brief <brief> --out <review>
  # diff gate (auto-detects the diff against origin/main, then main)
  .claude/scripts/dual-review.sh --mode diff  --brief <brief> --out <review>
  # panel: dump the identical prompt so the fresh-context Author arm reviews the same bytes
  .claude/scripts/dual-review.sh --mode diff  --brief <brief> --out <review> --dump-only

Outside reviews advise only — they never edit or commit. The Orchestrator owns disposition, and a hard finding at the diff gate blocks the merge until it’s resolved or you overrule it.

Related pages

• AI Pipeline — the conceptual pipeline and when to reach for each rung.
• Pipeline Verification — a worked proof that the gates catch real, planted defects.