prompts-gpt 0.3.2 → 0.3.3

package/README.md

@@ -102,6 +102,14 @@ 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
 
@@ -141,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
 
@@ -163,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