prompts-gpt 0.3.4 → 0.3.6

package/README.md

@@ -79,13 +79,15 @@ Bridges the Prompts-GPT cloud library with the agent instruction files each tool
 | `run` | Execute one prompt with a local agent (`-f <file>`) |
 | `run-batch` | Execute multiple prompts |
 | `sweep` | Multi-iteration execution (`-f <file> -n <count>`) |
+| `orchestrate` | Multi-provider parallel, pipeline, or eval orchestration |
 | `list` | Show prompts, sweeps, agents |
-| `status` | Show workspace readiness |
+| `status` | Show workspace readiness and active sweeps |
 | `providers` | Show detected CLIs |
 | `doctor` | Validate prerequisites |
 | `validate` | Check config for errors |
 | `models` | List known models per provider |
 | `sync-models` | Fetch latest model registry from prompts-gpt.com |
+| `diff` | Inspect worktree delta from a prior run |
 | `project` | Show the current project linked to the token |
 
 Run `prompts-gpt help <command>` for detailed options.
@@ -108,7 +110,12 @@ prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3 -n
 
 # 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
+
+# Multi-provider fan-out: run the same sweep across codex and cursor simultaneously
+prompts-gpt sweep --all-sweeps --providers codex,cursor --sweep-strategy parallel
+
+# Abort on first failure in a multi-file sweep
+prompts-gpt sweep --all-sweeps --sweep-strategy parallel --fail-fast
 
 # Preview what a sweep would do
 prompts-gpt sweep --dry-run
@@ -116,52 +123,14 @@ 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'
-[
-  {"name":"research","promptFile":".prompts-gpt/review.md","agent":"codex"},
-  {"name":"implement","promptFile":".prompts-gpt/review.md","agent":"claude"},
-  {"name":"review","promptFile":".prompts-gpt/review.md","agent":"cursor"}
-]
-EOF
-prompts-gpt orchestrate --mode pipeline --steps pipeline.json --dry-run
+prompts-gpt orchestrate --mode pipeline --steps pipeline.json
 
 # Run once and evaluate with explicit criteria
 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
-
-# Scaffold local runner config and prompt sources
-prompts-gpt doctor --fix
-
-# Inspect the worktree delta for a recent run
-prompts-gpt diff
-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
-
-# Sync model registry from cloud
-prompts-gpt sync-models
-
-# Use canonical model names only
-prompts-gpt run --agent claude --model claude-opus-4-7
-prompts-gpt run --agent cursor --model claude-4.6-opus-high
-prompts-gpt run --agent codex --model gpt-5.4-mini
+# Use canonical model names
+prompts-gpt run --agent claude --model claude-opus-4-1-20250805
 prompts-gpt run --agent codex --model gpt-5.5
 
 # Sync from cloud
@@ -174,94 +143,145 @@ 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
+---
+
+## Sweep
 
 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:
+### Sweep file frontmatter
+
+Each sweep file can declare defaults in YAML frontmatter:
+
+```yaml
+---
+iterations: 5
+timeout: 1200
+model: gpt-5.5
+agent: codex
+---
+```
+
+- `iterations` — default iteration count (overridden by `-n`)
+- `timeout` — per-iteration timeout in seconds (overridden by `--iteration-timeout`)
+- `model` — default model for this sweep
+- `agent` — default provider for this sweep
+
+### Use cases
 
 | 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.
+| Run the default sweep | `prompts-gpt sweep` |
+| Fixed iterations | `prompts-gpt sweep -f design.md -n 5` |
+| Parallel iterations | `prompts-gpt sweep -f design.md -n 6 --parallel 3` |
+| All sweeps sequentially | `prompts-gpt sweep --all-sweeps` |
+| All sweeps in parallel | `prompts-gpt sweep --all-sweeps --sweep-strategy parallel --file-concurrency 3` |
+| Multi-provider fan-out | `prompts-gpt sweep --all-sweeps --providers codex,cursor` |
+| Selected files | `prompts-gpt sweep --sweep-files design,research` |
+| Fail on first error | `prompts-gpt sweep --all-sweeps --fail-fast` |
+| Self-evaluation per iteration | `prompts-gpt sweep --eval --eval-criteria correctness,risk` |
+| Dry run | `prompts-gpt sweep --dry-run` |
+
+### Key flags
+
+- `--sweep-strategy sequential|parallel` — how to schedule multiple sweep files
+- `--file-concurrency <n>` — max concurrent sweep files in parallel strategy (default: 4)
+- `--parallel <n>` — parallel iterations within a single sweep file
+- `--providers <list>` — comma-separated providers for multi-provider fan-out (e.g. `codex,cursor,claude`)
+- `--fail-fast` — stop on first failure in multi-file sweeps
+- `-n, --iterations <count>` — override frontmatter iteration count for all files
+
+### Scheduling rules
+
+- `--sweep-strategy sequential` runs sweep files one at a time. Safest when sweeps may edit overlapping files.
+- `--sweep-strategy parallel` runs multiple sweep files concurrently. Use `--file-concurrency` to cap concurrency.
+- `--parallel <n>` controls parallel iterations *within* a single file. Separate from `--file-concurrency`.
+- `--providers` fans out each file across multiple providers. Total concurrent agents = files × providers.
+- When `-n` is omitted, each file uses its frontmatter `iterations:` value, falling back to `1`.
 
 ---
 
-## Configuration
+## Parallel Sweep Coordination
 
-Create `.prompts-gpt/config.json` via `prompts-gpt setup`, or manually:
+When multiple sweeps run concurrently — across files, providers, or separate terminals — the CLI provides robust coordination:
 
-```json
-{
-  "providerOrder": ["codex", "cursor", "claude", "copilot"],
-  "defaultAgent": "router",
-  "timeoutSeconds": 900,
-  "artifactsDir": ".scripts/runs"
-}
-```
+### Cross-process locking
+
+- Per-sweep-file locks (`.sweep-<slug>.lock`) prevent duplicate execution of the same sweep
+- Artifact directory rotation uses `.rotation.lock` to prevent concurrent rotation races
+- Lock files include PID, hostname, and timestamp for stale detection
+- Stale locks from dead processes are automatically detected and released
+
+### Multi-terminal awareness
+
+- `prompts-gpt status` shows all active sweeps across terminals with PID, provider, and elapsed time
+- Coordination manifests (`.sweep-active.json`) track active sweep metadata in artifact directories
+- New sweeps warn when other sweeps are already active in the same workspace
+
+### Resource management
+
+- Total concurrent agents are capped (files × providers × parallel iterations)
+- Parallel launches are staggered by 500ms to avoid provider rate limits
+- Disk space warnings scale with the number of active sweeps
+- Log reads use retry logic to handle concurrent writes from parallel processes
+
+### Signal handling
 
-All options can be overridden via environment variables. See `prompts-gpt help setup`.
+- SIGTERM/SIGINT propagate to active child agent processes via `AbortController`
+- Lock files and coordination manifests are cleaned up in `finally` blocks
+- Orphaned processes are detected via PID liveness checks
+
+### Atomic operations
+
+- Log appends use `O_APPEND` for kernel-level atomic writes
+- Worktree captures use per-iteration files to avoid cross-sweep clobbering
+- Run ID generation includes random suffixes to prevent collisions
 
 ---
 
 ## Orchestration Patterns
 
-- `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.
-- `sweep --eval --eval-criteria correctness,completeness,...`: add self-evaluation after each successful iteration.
-- `diff <run-id>`: inspect the stored worktree delta from a prior run.
-- `run --watch`: rerun automatically when the prompt file changes.
-- `doctor --fix`: scaffold `.prompts-gpt/config.json`, detect prompt sources, and add the artifacts directory to `.gitignore`.
-
-### Visibility implementation workflow
+- `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.
+- `sweep --eval` — add self-evaluation after each successful iteration.
+- `diff <run-id>` — inspect the stored worktree delta from a prior run.
+- `run --watch` — rerun automatically when the prompt file changes.
+- `doctor --fix` — scaffold config, detect prompt sources, and add artifacts to `.gitignore`.
 
-Use orchestration after a monitor or checker identifies a concrete gap:
+---
 
-1. Export the prompt, answer evidence, cited URLs, and desired fix from Prompts-GPT.com.
-2. Run `prompts-gpt orchestrate --mode parallel` when multiple agents should propose competing fixes.
-3. Run `prompts-gpt orchestrate --mode pipeline` when research, implementation, and review should stay separated.
-4. Run `prompts-gpt orchestrate --mode eval` or `prompts-gpt sweep --eval --eval-criteria correctness,risk,clarity` when output quality needs a score.
-5. Run `prompts-gpt diff <run-id>` before sharing the worktree changes.
+## Configuration
 
-Dry-runs verify command wiring, prompt resolution, evaluator selection, and criteria parsing without launching a provider:
+Create `.prompts-gpt/config.json` via `prompts-gpt setup`, or manually:
 
-```bash
-npx prompts-gpt orchestrate --mode eval --dry-run --eval-criteria correctness,risk,clarity
+```json
+{
+  "providerOrder": ["codex", "cursor", "claude", "copilot"],
+  "defaultAgent": "router",
+  "timeoutSeconds": 900,
+  "retryCount": 0,
+  "artifactsDir": ".scripts/runs",
+  "modelOverrides": {
+    "codex": "gpt-5.5",
+    "claude": "claude-opus-4-1-20250805"
+  },
+  "safety": {
+    "disallowDestructiveGit": true
+  }
+}
 ```
 
-Full pattern guide (parallel vs pipeline vs eval, visibility handoff, diff/watch): [docs/orchestration-patterns.md](../../docs/orchestration-patterns.md) in the main repo.
+All options can be overridden via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `PROMPTS_GPT_RUN_PROVIDER_ORDER` | Comma-separated provider order |
+| `PROMPTS_GPT_RUN_AGENT` | Default agent/provider |
+| `PROMPTS_GPT_RUN_TIMEOUT_SECONDS` | Default iteration timeout |
+| `PROMPTS_GPT_RUN_RETRY_COUNT` | Max retries per iteration |
+| `PROMPTS_GPT_RUN_ARTIFACTS_DIR` | Artifacts output directory |
+| `PROMPTS_GPT_RUN_DISALLOW_DESTRUCTIVE_GIT` | Block destructive git ops |
 
 ---
 
@@ -281,10 +301,61 @@ await syncPrompts(prompts, { agent: "all" });
 
 // Fetch available models per provider
 const models = await client.fetchModels();
-// Filter by provider
 const codexModels = await client.fetchModels({ provider: "codex" });
 ```
 
+### Programmatic sweep
+
+```typescript
+import { sweepPrompt, detectProviders, loadRunConfig } from "prompts-gpt";
+
+const config = await loadRunConfig(process.cwd());
+const providers = await detectProviders(process.cwd());
+
+const result = await sweepPrompt({
+  cwd: process.cwd(),
+  promptFile: ".prompts-gpt/sweeps/design.md",
+  agent: "codex",
+  iterations: 3,
+  onProgress: (event) => {
+    if (event.type === "iteration_end") {
+      console.log(`Iteration ${event.iteration}: ${event.status}`);
+    }
+  },
+});
+
+console.log(`Completed: ${result.succeeded}/${result.total}`);
+```
+
+### Programmatic orchestration
+
+```typescript
+import { orchestrateParallel, orchestratePipeline, orchestrateEval } from "prompts-gpt";
+
+// Run multiple providers in parallel
+const parallel = await orchestrateParallel({
+  cwd: process.cwd(),
+  promptFile: ".prompts-gpt/review.md",
+  providers: ["codex", "claude", "cursor"],
+});
+
+// Chain steps sequentially
+const pipeline = await orchestratePipeline({
+  cwd: process.cwd(),
+  steps: [
+    { name: "research", promptFile: ".prompts-gpt/research.md", agent: "codex" },
+    { name: "implement", promptFile: ".prompts-gpt/implement.md", agent: "claude" },
+  ],
+});
+
+// Run with self-evaluation
+const evalResult = await orchestrateEval({
+  cwd: process.cwd(),
+  promptFile: ".prompts-gpt/review.md",
+  criteria: ["correctness", "completeness", "risk"],
+});
+```
+
 ---
 
 ## Data Privacy
@@ -310,8 +381,16 @@ const codexModels = await client.fetchModels({ provider: "codex" });
 - HTTPS enforced for non-localhost
 - Path traversal blocked for all file writes
 - Secret patterns (`pgpt_`, `sk-`, `ghp_`) are redacted from API-bound input, command previews, and error output
-- SIGINT/SIGTERM cleanup releases locks
+- SIGINT/SIGTERM cleanup releases locks and kills child processes
 - Run artifact directories are intended to stay local and may contain sensitive prompt, output, and diff data
+- Per-sweep-file locks prevent concurrent modification of shared resources
+- Coordination manifests provide cross-process visibility
+
+---
+
+## Full Documentation
+
+See the [full package documentation](https://prompts-gpt.com/docs/prompts-gpt-package) for detailed guides on every command, sweep frontmatter options, parallel coordination, SDK types, and orchestration patterns.
 
 ---