prompts-gpt orchestrate

Run multi-agent orchestration across providers with four modes: auto planning, parallel racing, pipeline chaining, and eval scoring.

Usage

prompts-gpt orchestrate --mode <auto|parallel|pipeline|eval> [-f <path>] [options]

Modes

Auto Mode

Describe a goal in plain English — the system plans the pipeline, generates prompts, executes end-to-end, and evaluates the result.

prompts-gpt orchestrate --mode auto --goal "Add user authentication with JWT, write tests, and update docs"

Use cases:

• Quick end-to-end task execution from a single sentence
• Prototyping workflows before building explicit pipelines
• Hands-free execution for well-scoped goals

Key flags:

• --goal <text> — Plain English description of what to accomplish
• --max-steps <n> — Maximum pipeline steps to generate (default: 5, max: 10)
• --quality-gate <n> — Minimum score (1-100) to consider the run successful (default: 70)

Parallel Mode

Race the same prompt across multiple providers simultaneously and compare results.

prompts-gpt orchestrate --mode parallel -f prompt.md --providers codex,claude,cursor

Use cases:

• Compare how different providers solve the same problem
• Pick the best result from multiple agents
• Benchmark provider quality and speed

Key flags:

• --providers <list> — Comma-separated providers to race
• If omitted, auto-selects the top 2 available providers

Pipeline Mode

Chain multiple providers sequentially — output from step 1 feeds into step 2.

prompts-gpt orchestrate --mode pipeline -f prompt.md --steps pipeline.json

Use cases:

• Research → Implement → Review workflows
• Architecture → Code → Test pipelines
• Multi-stage transformations

Steps file format (pipeline.json):

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

Eval Mode

Execute a prompt and automatically evaluate/score the output using configurable criteria.

prompts-gpt orchestrate --mode eval -f prompt.md --criteria correctness,completeness,quality

Use cases:

• Automated quality assessment
• Scoring agent outputs against rubrics
• Benchmark and compare model performance

Key flags:

• --criteria <list> — Comma-separated scoring dimensions
• --evaluator <provider> — Provider for evaluation (can differ from executor)

Options

Common Options

Auto-Specific

Parallel-Specific

Pipeline-Specific

Eval-Specific

Examples

Auto: End-to-end from a goal

# Let the system plan and execute everything
prompts-gpt orchestrate --mode auto \
  --goal "Review the codebase for security issues, fix critical ones, and add tests"

# With quality gate and step limit
prompts-gpt orchestrate --mode auto \
  --goal "Refactor the auth module to use JWT" \
  --max-steps 4 \
  --quality-gate 80

# Interactive auto mode — confirm the plan before executing
prompts-gpt orchestrate --mode auto \
  --goal "Migrate from REST to GraphQL" \
  --interactive

# Dry run to preview the generated plan
prompts-gpt orchestrate --mode auto \
  --goal "Add dark mode support" \
  --dry-run

Parallel: Compare Codex vs Claude

prompts-gpt orchestrate --mode parallel \
  -f .prompts-gpt/refactor.md \
  --providers codex,claude

Pipeline: Research → Implement → Test

# First, scaffold the pipeline
prompts-gpt generate-orchestration --title "Feature Pipeline" --mode pipeline

# Then run it
prompts-gpt orchestrate --mode pipeline \
  --steps .prompts-gpt/orchestrations/feature-pipeline.json

Eval: Score quality

prompts-gpt orchestrate --mode eval \
  -f .prompts-gpt/code-review.md \
  --criteria correctness,completeness,security \
  --agent codex

Results

Auto Result

{
  mode: "auto";
  goal: string;
  generatedSteps: Array<{ name: string; prompt: string; provider: string; model: string }>;
  pipelineResult: PipelineResult | null;
  evaluation: EvalScore | null;
  totalDurationMs: number;
}

Parallel Result

{
  mode: "parallel";
  results: Record<string, RunPromptResult>;
  winner?: string;
  runnerUp?: string;
  totalDurationMs: number;
}

Pipeline Result

{
  mode: "pipeline";
  steps: Array<{
    name: string;
    result: RunPromptResult;
  }>;
  totalDurationMs: number;
}

Eval Result

{
  mode: "eval";
  runResult: RunPromptResult;
  scores: EvalScore[];
  overallScore: number;
  totalDurationMs: number;
}

Generate Orchestration Files

Use generate-orchestration to scaffold files:

# Interactive wizard
prompts-gpt generate-orchestration

# Non-interactive
prompts-gpt generate-orchestration \
  --title "Auth Feature" \
  --goal "Add user authentication" \
  --mode pipeline

See Also

• run — Single prompt execution
• sweep — Multi-iteration sweeps
• Execution Modes Guide