/vanara-orchestrate

name: vanara-orchestrate
description: Run a goal end-to-end as a gated pipeline of specialist agents — reproduce → test → patch → review → commit — where nothing advances past a gate until its exit condition holds and the required agent has signed off. Use when a task needs several agents in sequence with checkpoints, not a single one-shot answer.
type: skill
version: 1.0.1
updated: 2026-07-27

vanara-orchestrate — outcomes, not one-shots

A single agent answers a question. **Orchestration delivers an outcome**: it chains the right specialists into a pipeline with **gates** between stages, so the work only advances when the previous stage actually succeeded — and nothing risky ships without a sign-off. This is the difference between "here's a suggested fix" and "the bug is fixed, tested, reviewed, committed."

You run in the main Claude Code context, so you can invoke installed agents (via the Task tool, or the `vanara-route` skill) one after another and enforce the gates between them.

The core loop

For any goal, run **plan → act → gate → advance**, repeating until done:

1. **Plan the pipeline.** Pick the named workflow that fits the goal (see [references/workflows.md](references/workflows.md)), or compose one from installed agents. State the stages and their gates up front, in one short line each. 2. **Run one stage.** Invoke exactly one agent for the current stage and let it finish. 3. **Check the gate.** Before advancing, verify the stage's **exit condition** holds (tests green, a failing test now written, no blocking review findings, no new secrets — see [references/gates.md](references/gates.md)). If it doesn't hold, do **not** advance: loop back, fix, and re-check. A gate is a hard stop, not a suggestion. 4. **Checkpoint.** Record the stage result so the run is auditable and resumable:

   node .claude/skills/vanara-orchestrate/scripts/checkpoint.mjs "fix-defect" "review" "pass"

5. **Advance** to the next stage, or finish.

Named workflows

• **fix-defect** — reproduce → write a failing regression test → patch → review → commit.

Gate before commit: tests green **and** the reviewer returns no blocking findings.

• **ship-feature** — plan → write tests first → implement → review → commit. Gate before

implement: tests exist and fail (RED); gate before commit: GREEN + review clean.

• **harden** — audit (security) → triage → fix highest severity → re-audit → report. Gate

before "done": the re-audit shows the fixed findings gone and no new ones introduced.

Full stage/gate definitions are in [references/workflows.md](references/workflows.md).

Rules that make orchestration trustworthy

• **One agent per stage.** Don't blur stages; each has one owner and one gate.
• **Never skip a gate to save time.** A red gate means the pipeline stops and reports exactly

which condition failed and why — that failure is the useful output, not a thing to hide.

• **Escalate, don't loop forever.** If a stage can't clear its gate after a reasonable attempt,

stop and hand back to the user with the specific blocker. Cap retries (2–3), don't spin.

• **The reviewer is the last gate.** For anything that writes to the repo, the final stage is a

review, and nothing commits with blocking findings open.

• **Respect the operating protocol.** Every stage still grounds its claims and logs its changes;

orchestration adds sequencing and gates on top, it doesn't replace an agent's own discipline.

Edge cases

• **Missing agent for a stage** → use `vanara-route` to find the closest fit, or tell the user

which specialist to `npx vanara install` before the pipeline can run.

• **A gate that can't be evaluated** (no tests exist to run) → say so; treat an unverifiable

gate as *not passed*, don't wave it through.

• **Partial progress** → the checkpoint log lets you resume from the last passed stage instead

of restarting the whole pipeline.

Example

> **Goal:** "the login endpoint 500s on an empty email." > > Pipeline (`fix-defect`): `debugger` reproduces → `test-author` writes a failing test for the > empty-email case (gate: test is RED) → `debugger` patches validation (gate: that test is now > GREEN) → `code-reviewer` reviews (gate: no blocking findings) → commit. Each stage checkpointed; > if review flags a blocking issue, the pipeline loops back to the patch stage, not forward.

Worked micro-example

A real run of the fix-defect pipeline, gate by gate:

$ goal: "users report duplicate webhooks after retry"

[gate 1 REPRODUCE] debugger writes a failing test that fires the dup
                   → RED (good — the bug is now falsifiable)      PASS
[gate 2 TEST]      test-author hardens it: adds the idempotency-key
                   contract test the codebase never had            PASS
[gate 3 PATCH]     fix lands: dedupe on (source_id, delivery_id)
                   unique index + upsert                           PASS
[gate 4 REVIEW]    code-reviewer: flags the index migration as
                   non-concurrent — BLOCKS                         FAIL
[gate 4 RETRY]     migration rewritten CONCURRENTLY → re-review    PASS
[gate 5 COMMIT]    checkpoint.mjs logs all five gates; commit cites
                   the checkpoint id

The point of the transcript: gate 4 FAILING is the system working — a blocked stage stops the pipeline instead of shipping a table lock to production.