Synced package doc
Docs/prompts-gpt Package/Execution Modes Guide

Execution Modes Guide

The prompts-gpt package offers four distinct execution modes. This guide helps you choose the right one and shows how to configure each.

Overview

┌─────────────────────────────────────────────────────────────┐
│                    Execution Modes                          │
├──────────┬──────────┬──────────────┬────────────────────────┤
│  run     │ run-batch│   sweep      │     orchestrate        │
│ (single) │ (multi)  │ (iterative)  │ (multi-agent)          │
│          │          │              │ ┌────────┬────┬──────┐ │
│          │          │              │ │parallel│pipe│ eval │ │
│          │          │              │ └────────┴────┴──────┘ │
└──────────┴──────────┴──────────────┴────────────────────────┘

1. Single Run

Execute a single prompt with one provider.

prompts-gpt run review.md --provider codex --model gpt-5.5

Characteristics:

  • One prompt, one agent, one invocation
  • No context chaining or iteration
  • Fastest execution mode

Use when:

  • You have a specific, well-defined task
  • Speed matters more than thoroughness
  • The task can be completed in one pass

2. Batch Run

Execute multiple prompts sequentially.

prompts-gpt run-batch review.md tests.md docs.md --provider codex

Characteristics:

  • Multiple prompts, one agent, sequential
  • Each prompt is independent (no shared context)
  • Results aggregated in a batch report

Use when:

  • You have multiple independent tasks
  • Building CI/CD pipelines with check lists
  • Processing a manifest of prompts

3. Sweep

Execute a single prompt multiple times with context chaining.

prompts-gpt sweep security-audit.md -n 5 --provider codex

Characteristics:

  • One prompt, one agent, N iterations
  • Each iteration receives previous summary as context
  • Optional self-evaluation after each iteration
  • Lock management prevents concurrent execution

Use when:

  • Tasks benefit from progressive refinement
  • Comprehensive audits and reviews
  • You want self-evaluation scoring

Configuration via YAML frontmatter:

---
title: Security Audit
sweep:
  defaultIterations: 5
  maxIterations: 10
  summaryLines: 40
  eval:
    criteria: [correctness, completeness]
    passThreshold: 0.8
---

4. Orchestrate: Parallel

Race the same prompt across multiple providers.

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

Characteristics:

  • One prompt, multiple agents, simultaneous
  • Compare results across providers
  • Identifies fastest/best provider

Use when:

  • Evaluating which provider works best for a task
  • Getting multiple perspectives on the same problem
  • Speed-testing providers

5. Orchestrate: Pipeline

Chain providers sequentially, passing output forward.

prompts-gpt orchestrate --mode pipeline \
  --pipeline pipeline.json

pipeline.json:

{
  "steps": [
    { "name": "research", "agent": "claude", "promptFile": "research.md" },
    { "name": "implement", "agent": "codex", "promptFile": "implement.md" },
    { "name": "review", "agent": "cursor", "promptFile": "review.md" }
  ]
}

Characteristics:

  • Multiple prompts, multiple agents, sequential
  • Output from step N feeds into step N+1
  • Different providers can excel at different stages

Use when:

  • Complex workflows with distinct stages
  • Leveraging each provider's strengths
  • Research → implement → review patterns

6. Orchestrate: Eval

Execute a prompt and automatically score the output.

prompts-gpt orchestrate --mode eval \
  --prompt review.md --provider codex \
  --criteria correctness,completeness,quality

Characteristics:

  • One prompt, one (or two) agents
  • Automatic scoring against criteria
  • Optional separate evaluator provider

Use when:

  • Measuring agent output quality
  • Comparing model performance
  • Building quality gates in CI

Execution Mode Comparison

Featurerunrun-batchsweepparallelpipelineeval
Prompts1N11N1
Providers111NN1-2
Iterations11 eachN11 each1
Context chainNoNoYesNoYesNo
Self-evalNoNoOptionalNoNoYes
Lock mgmtNoNoYesNoNoNo
ParallelismNoNoOptionalYesNoNo

Choosing the Right Mode

Start
  │
  ├─ Single task, one provider?
  │  └─ Need multiple passes? → sweep
  │     └─ No → run
  │
  ├─ Multiple independent tasks?
  │  └─ run-batch
  │
  ├─ Compare providers on same task?
  │  └─ orchestrate --mode parallel
  │
  ├─ Chain different providers?
  │  └─ orchestrate --mode pipeline
  │
  └─ Score output quality?
     └─ orchestrate --mode eval

Combining Modes

Modes can be combined in scripts or CI pipelines:

#!/bin/bash

# 1. Quick lint check (run)
prompts-gpt run lint-check.md --provider codex

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

# 3. Compare refactoring approaches (parallel)
prompts-gpt orchestrate --mode parallel \
  --prompt refactor.md --providers codex,claude

# 4. Full workflow (pipeline)
prompts-gpt orchestrate --mode pipeline --pipeline workflow.json

# 5. Quality gate (eval)
prompts-gpt orchestrate --mode eval \
  --prompt final-check.md --provider codex \
  --criteria correctness,completeness

See Also