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

Feature	run	run-batch	sweep	parallel	pipeline	eval
Prompts	1	N	1	1	N	1
Providers	1	1	1	N	N	1-2
Iterations	1	1 each	N	1	1 each	1
Context chain	No	No	Yes	No	Yes	No
Self-eval	No	No	Optional	No	No	Yes
Lock mgmt	No	No	Yes	No	No	No
Parallelism	No	No	Optional	Yes	No	No

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

Execution Modes Guide

Overview

1. Single Run

2. Batch Run

3. Sweep

4. Orchestrate: Parallel

5. Orchestrate: Pipeline

6. Orchestrate: Eval

Execution Mode Comparison

Choosing the Right Mode

Combining Modes

See Also