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), 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). 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.

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.