Vanara Orchestrate

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.

1. Run one stage. Invoke exactly one agent for the current stage and let it finish.
2. 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.

1. Checkpoint. Record the stage result so the run is auditable and resumable:

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

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vanara-agents
• Source: vanara-agents/skills
• License: Apache-2.0
• Homepage: https://vanaraagents.com

Install and usage instructions live in the source repository linked above.