prompts-gpt 0.3.1 → 0.3.3

package/README.md

@@ -102,12 +102,23 @@ prompts-gpt run -f .prompts-gpt/review.md --agent cursor
 prompts-gpt sweep
 prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 5
 
+# Run every sweep file sequentially or in parallel
+prompts-gpt sweep --all-sweeps --sweep-strategy sequential
+prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 -n 2
+
+# Run only selected sweep files
+prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel -n 2
+prompts-gpt sweep --sweep-files .prompts-gpt/sweeps/design.md,.prompts-gpt/sweeps/research.md --sweep-strategy sequential
+
 # Preview what a sweep would do
 prompts-gpt sweep --dry-run
 
 # Run and score multiple providers on one prompt
 prompts-gpt orchestrate --mode parallel -f .prompts-gpt/review.md --providers codex,claude,cursor --criteria correctness,completeness
 
+# Interactive orchestration mode picker
+prompts-gpt orchestrate
+
 # Chain steps with context passing
 cat > pipeline.json <<'EOF'
 [
@@ -122,6 +133,9 @@ prompts-gpt orchestrate --mode pipeline --steps pipeline.json --dry-run
 prompts-gpt orchestrate --mode eval -f .prompts-gpt/review.md --criteria correctness,risk,clarity
 prompts-gpt orchestrate --mode eval --dry-run --eval-criteria correctness,risk,clarity
 
+# Inspect available models for the resolved orchestration providers
+prompts-gpt orchestrate --mode eval --list-models
+
 # Re-run a prompt when the file changes
 prompts-gpt run -f .prompts-gpt/review.md --watch
 
@@ -135,6 +149,9 @@ prompts-gpt diff <run-id>
 # Run a sweep with reduced output
 prompts-gpt sweep --quiet
 
+# Run one sweep file with independent parallel iterations
+prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 6 --parallel 3
+
 # List available models for a provider
 prompts-gpt models --provider codex
 
@@ -157,6 +174,47 @@ prompts-gpt generate --goal "Review PRs for security issues" --sync-agents
 printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
 ```
 
+## Sweep Use Cases
+
+Sweeps live in `.prompts-gpt/sweeps/*.md`. By default, `prompts-gpt sweep` auto-selects the local sweep when there is only one, or prompts you to choose when multiple sweeps exist.
+
+Use these modes when you want explicit control over which sweep files run and how iterations are scheduled:
+
+| Use case | Command |
+|----------|---------|
+| Run the default or selected single sweep | `prompts-gpt sweep` |
+| Run one sweep file for a fixed number of iterations | `prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 5` |
+| Run one sweep file with iterations in parallel | `prompts-gpt sweep -f .prompts-gpt/sweeps/design.md -n 6 --parallel 3` |
+| Run every sweep file sequentially | `prompts-gpt sweep --all-sweeps --sweep-strategy sequential` |
+| Run every sweep file sequentially with the same iteration count per file | `prompts-gpt sweep --all-sweeps --sweep-strategy sequential -n 2` |
+| Run every sweep file in parallel | `prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3` |
+| Run every sweep file in parallel with repeated iterations per file | `prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 -n 2` |
+| Run selected sweep files sequentially by name | `prompts-gpt sweep --sweep-files design,research --sweep-strategy sequential` |
+| Run selected sweep files sequentially by path | `prompts-gpt sweep --sweep-files .prompts-gpt/sweeps/design.md,.prompts-gpt/sweeps/research.md --sweep-strategy sequential` |
+| Run selected sweep files in parallel | `prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel --file-concurrency 2` |
+| Run selected sweep files in parallel with repeated iterations per file | `prompts-gpt sweep --sweep-files design,research --sweep-strategy parallel --file-concurrency 2 -n 3` |
+| Preview the selected sweep plan without launching providers | `prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 --dry-run` |
+| Run and score each sweep iteration | `prompts-gpt sweep --all-sweeps --eval --eval-criteria correctness,risk,clarity` |
+
+Key scheduling rules:
+
+- `--sweep-strategy sequential` runs selected sweep files one after another. This is the safest default when sweeps may edit overlapping files.
+- `--sweep-strategy parallel` runs multiple sweep files at the same time. Use `--file-concurrency <n>` to cap how many files run concurrently.
+- `--parallel <n>` controls parallel iterations inside a single sweep file. It is separate from `--file-concurrency`.
+- `-n, --iterations <count>` overrides the frontmatter `iterations:` value for every selected sweep file.
+- When `-n` is omitted, each sweep file uses its own frontmatter `iterations:` value, falling back to `1`.
+- `--sweep-files` accepts comma-separated sweep names, filenames, or paths. For example, `design`, `design.md`, and `.prompts-gpt/sweeps/design.md` can all resolve the same file.
+- `--all-sweeps` cannot be combined with `--sweep-files`, and multi-file selection cannot be combined with `-f, --prompt-file`.
+- `--files-mode sequential|parallel` is accepted as an alias for `--sweep-strategy sequential|parallel`.
+
+Practical recommendations:
+
+- Use sequential all-sweeps for broad repo QA where each sweep may write code.
+- Use parallel selected sweeps for independent areas such as docs, tests, and marketing copy.
+- Use single-file `--parallel` when you want competing iterations of the same prompt, then compare outputs.
+- Use `--dry-run` before large parallel runs to verify file selection, iteration counts, and concurrency.
+- Keep `--file-concurrency` modest when sweeps call paid providers or local agents that consume heavy CPU.
+
 ---
 
 ## Configuration
@@ -178,7 +236,7 @@ All options can be overridden via environment variables. See `prompts-gpt help s
 
 ## Orchestration Patterns
 
-- `parallel`: run multiple providers against the same prompt, score outputs, and keep the strongest result with local logs and diffs.
+- `parallel`: run multiple providers against the same prompt, score outputs, and report the strongest result with local logs and diffs.
 - `pipeline`: pass context across named steps when research, implementation, and review should be separated.
 - `eval`: run one provider and force a structured quality score for the output.
 - `eval --dry-run`: if `-f` is omitted, the CLI uses the first discovered `.prompts-gpt` prompt so workspace scaffolds can verify orchestration immediately.
@@ -203,6 +261,8 @@ Dry-runs verify command wiring, prompt resolution, evaluator selection, and crit
 npx prompts-gpt orchestrate --mode eval --dry-run --eval-criteria correctness,risk,clarity
 ```
 
+Full pattern guide (parallel vs pipeline vs eval, visibility handoff, diff/watch): [docs/orchestration-patterns.md](../../docs/orchestration-patterns.md) in the main repo.
+
 ---
 
 ## SDK