Orchestration Patterns

Advanced multi-agent orchestration patterns for complex workflows.

Pattern 1: Research → Implement → Review

Use pipeline orchestration to leverage each provider's strengths:

{
  "mode": "pipeline",
  "steps": [
    {
      "name": "research",
      "agent": "claude",
      "promptFile": "research.md",
      "model": "claude-sonnet-4-20250514"
    },
    {
      "name": "implement",
      "agent": "codex",
      "promptFile": "implement.md",
      "model": "gpt-5.5"
    },
    {
      "name": "review",
      "agent": "cursor",
      "promptFile": "review.md"
    }
  ]
}

Why it works: Claude excels at analysis and reasoning, Codex at code generation, and Cursor at IDE-integrated review.

Pattern 2: Provider Race

Compare providers on the same task to find the best fit:

prompts-gpt orchestrate --mode parallel \
  --prompt complex-refactor.md \
  --providers codex,claude,cursor

When to use: Evaluating which provider handles a specific task type best. Check artifacts to compare output quality, speed, and token usage.

Pattern 3: Quality Gate Pipeline

Pipeline with eval scoring at the end:

# Step 1: Implement
prompts-gpt run implement.md --provider codex

# Step 2: Evaluate
prompts-gpt orchestrate --mode eval \
  --prompt eval-implementation.md \
  --provider claude \
  --criteria correctness,completeness,test-coverage

Pattern 4: Sweep + Cross-Provider Verification

Deep audit followed by independent verification:

# Step 1: Deep sweep with Codex
prompts-gpt sweep security-audit.md -n 5 --provider codex

# Step 2: Verify findings with Claude
prompts-gpt run verify-findings.md --provider claude

Pattern 5: Iterative Refinement with Eval Gating

Sweep with self-evaluation that stops when quality threshold is met:

---
title: Code Quality Improvement
sweep:
  defaultIterations: 10
  eval:
    criteria: [correctness, code-quality, test-coverage]
    passThreshold: 0.9
---

The sweep continues until:

All iterations complete, OR
Eval score exceeds 0.9 (early termination)

Pattern 6: Multi-Stage Security Audit

# Stage 1: Quick scan (run)
prompts-gpt run quick-security-scan.md --provider codex

# Stage 2: Deep audit (sweep)
prompts-gpt sweep full-security-audit.md -n 5 --provider codex

# Stage 3: Cross-provider verification (parallel)
prompts-gpt orchestrate --mode parallel \
  --prompt verify-security.md \
  --providers codex,claude

# Stage 4: Final assessment (eval)
prompts-gpt orchestrate --mode eval \
  --prompt final-assessment.md \
  --provider claude \
  --criteria correctness,completeness,thoroughness

Pattern 7: CI Pipeline Integration

# .github/workflows/ai-review.yml
jobs:
  quick-check:
    runs-on: ubuntu-latest
    steps:
      - run: prompts-gpt run lint-check.md --provider codex --json

  deep-review:
    needs: quick-check
    runs-on: ubuntu-latest
    steps:
      - run: prompts-gpt sweep security-audit.md -n 3 --provider codex --json

  quality-gate:
    needs: deep-review
    runs-on: ubuntu-latest
    steps:
      - run: |
          prompts-gpt orchestrate --mode eval \
            --prompt quality-check.md --provider claude \
            --criteria correctness,completeness --json

Pattern 8: Programmatic Custom Orchestration

Build custom workflows using the SDK:

import { runPrompt, sweepPrompt, orchestrateEval } from "prompts-gpt";

async function customWorkflow() {
  // 1. Quick lint
  const lint = await runPrompt({
    promptFile: "lint.md",
    provider: "codex",
  });

  if (!lint.ok) {
    console.error("Lint failed, aborting");
    return;
  }

  // 2. Deep security sweep
  const sweep = await sweepPrompt({
    promptFile: "security.md",
    iterations: 5,
    provider: "codex",
    eval: { criteria: ["correctness"], passThreshold: 0.8 },
  });

  // 3. Quality gate
  const eval = await orchestrateEval({
    promptFile: "final-check.md",
    provider: "claude",
    criteria: [
      { name: "correctness", weight: 0.4 },
      { name: "completeness", weight: 0.3 },
      { name: "security", weight: 0.3 },
    ],
  });

  console.log(`Final score: ${eval.overallScore}`);
  return eval.overallScore >= 0.8;
}