pi-prompt-template-model 0.6.8 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.7.1] - 2026-04-03
+
+### Changed
+- Bumped `@mariozechner/pi-agent-core`, `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, and `@mariozechner/pi-tui` to `^0.65.0` and updated the extension for the pi `0.65.0` session/runtime breaking changes (`session_start` migration and `getApiKeyAndHeaders()` auth lookup).
+
+### Fixed
+- Added regression coverage for the shipped `best-of-n` example and re-verified the installed prompt still matches the shipped example used for manual installs.
+
+## [0.7.0] - 2026-04-01
+
+### Added
+- Added a first-class `bestOfN:` prompt-template authoring surface for compare workflows, with configurable `workers`, `reviewers`, optional `finalApplier`, and nested `bestOfN.worktree` support.
+- Added configurable compare runtime overrides via `--workers`, `--reviewers`, `--workers-append`, `--reviewers-append`, and `--final-applier`.
+- Added `count: N` compare-slot shorthand so one worker or reviewer slot can fan out into repeated identical runs without manual duplication.
+- Added a shipped `/best-of-n` example prompt that demonstrates mixed worker counts, mixed reviewer counts, thinking-level model suffixes, `taskSuffix`, and final real-branch application.
+
+### Changed
+- Compare prompts now run as worker fan-out, reviewer fan-in, then an optional final apply step that edits the real branch instead of stopping at recommendation prose.
+- Reviewer defaults now stay findings-only, while `finalApplier` handles winner-picking or synthesis plus best-effort verification on the current branch.
+- Legacy top-level compare frontmatter in templates (`workers`, `reviewers`, `finalApplier`, top-level compare `worktree`) is now rejected in favor of `bestOfN:`.
+- Delegated parallel live rendering now shows richer per-task output, including task index, model, recent tools, and bounded rolling output lines.
+- README and bundled examples were refreshed to match the shipped compare/runtime surface, including `bestOfN`, compare-wide vs slot-level `cwd`, and chain `parallel(...)` `cwd` rules under `worktree: true`.
+
+### Fixed
+- Compare execution now allows partial success by phase: worker and reviewer phases continue as long as at least one slot succeeds, and `finalApplier` can still fall back to worker-only evidence when every reviewer fails.
+- Preserved successful worker `=== Worktree Changes ===` summaries when building reviewer and final-apply inputs, so downstream compare stages do not lose worktree evidence.
+- Invalid `bestOfN` blocks and legacy compare templates no longer degrade into ordinary runnable prompts after diagnostics; they are skipped entirely.
+- `finalApplier` validation now correctly rejects unsupported `cwd` and `count` fields in both frontmatter and runtime overrides.
+- Corrected remaining docs/tooling drift, including the `run-prompt` unlimited-loop cap text and compare/chain `cwd` wording.
+
+## [0.6.10] - 2026-03-30
+
+### Added
+- Added lineup-based compare frontmatter for prompt templates: `workers` and `reviewers` slot lists (`agent` or `subagent`, optional `model`, optional `task`, optional `taskSuffix`, optional `cwd`, optional `count`), plus optional `finalApplier` for one final apply step.
+- Added a two-phase compare execution flow for lineup templates: parallel worker phase first, then reviewer phase fed by aggregated worker output.
+- Added runtime lineup override flags for compare templates: `--workers`, `--reviewers`, `--workers-append`, `--reviewers-append`, and `--final-applier`.
+- Added compare lineup `count: N` shorthand so one worker or reviewer slot can expand into repeated identical runs without manually duplicating entries.
+- Added an example compare prompt template under `examples/`: `best-of-n`, intended for manual installation into `~/.pi/agent/prompts/`.
+- Added compare-lineup `subagent` shorthand so prompt authors can use `subagent: true` for default worker/reviewer slots instead of spelling the internal `delegate` / `reviewer` agent names directly.
+
+### Changed
+- Prompt-template compare authoring now uses nested `bestOfN:` frontmatter; the loader lowers `bestOfN.workers`, `bestOfN.reviewers`, `bestOfN.finalApplier`, and `bestOfN.worktree` into the existing runtime compare fields and rejects legacy top-level compare fields in templates.
+- Removed fixed three-worker compare assumptions from docs and prompt guidance; compare lineups are now caller-defined and duplicate slots are preserved.
+- The shipped `best-of-n` example now shows mixed workers, mixed reviewers, and an optional final apply phase, while the runtime fallback still stays at one worker when `workers` is omitted.
+- Reviewers now default to findings-only output, and the optional final phase now applies the real-branch patch instead of ending at recommendation prose.
+- Parallel delegated task contract now supports per-task `cwd` passthrough end-to-end across the prompt-template bridge.
+- README now explains same-model vs multi-model best-of-N configuration explicitly.
+
+### Fixed
+- Compare execution now uses partial-success-by-phase behavior: worker and reviewer phases continue as long as at least one slot succeeds, and `finalApplier` can fall back to worker-only synthesis if reviewer slots all fail.
+- Compare lineup slots now support `taskSuffix` so shared worker/reviewer instructions can stay in the prompt body while slots add small per-model suffixes such as output-file paths.
+- Documented the current compare worktree constraint explicitly: when `worktree: true` is enabled, all worker slots must resolve to the same `cwd`.
+
+## [0.6.9] - 2026-03-28
+
+### Added
+- Added `worktree: true` frontmatter and `--worktree` runtime flag for chain templates with parallel steps. When enabled, each parallel subagent runs in its own git worktree to avoid file conflicts during concurrent execution. Requires a chain with at least one `parallel()` step.
+- Added `parallel: N` frontmatter for delegated prompts. This expands one delegated prompt into `N` parallel `pi-subagents` tasks targeting the same agent, with automatic slot headers like `[Parallel subagent 2/3]` prepended to each task.
+
+### Changed
+- Bumped `@mariozechner/pi-agent-core`, `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, and `@mariozechner/pi-tui` to `^0.64.0`.
+- Delegated prompt execution now forwards `ctx.signal` into subagent runs so turn cancellation can stop in-flight delegated work for both single delegated prompts and delegated parallel chain steps.
+- `worktree: true` now also works on delegated prompts that use `parallel: N`, not just chain templates with `parallel()` steps.
+
 ## [0.6.8] - 2026-03-28
 
 ### Added

package/README.md

@@ -73,6 +73,7 @@ All fields are optional. Templates that don't use any extension features (no `mo
 | `rotate` | `false` | When `true` and looping, cycle through models in the `model` list instead of using fallback semantics. Thinking levels can also be comma-separated to pair with each model. |
 | `fresh` | `false` | When looping, collapse the conversation between iterations to a brief summary instead of carrying the full context forward. Saves tokens on long loops. |
 | `converge` | `true` | When looping, stop early if an iteration makes no file changes. Set `false` to always run every iteration. |
+| `worktree` | `false` | When `true`, parallel delegated work runs in separate git worktrees. Valid on chain templates with `parallel()` steps, on delegated prompts with `parallel: N`, and on compare templates via `bestOfN.worktree`. |
 
 ### Delegation
 
@@ -80,7 +81,12 @@ All fields are optional. Templates that don't use any extension features (no `mo
 |-------|---------|--------------|
 | `subagent` | — | Delegate execution to a subagent instead of running in the current session. `true` uses the default `delegate` agent; a string value like `reviewer` targets that specific agent. Requires [pi-subagents](https://github.com/nicobailon/pi-subagents/). |
 | `inheritContext` | `false` | Only meaningful with `subagent`. When `true`, the subagent receives a fork of the current conversation context instead of starting fresh. |
-| `cwd` | — | Working directory for delegated subagent subprocesses. Must be an absolute path (`~/...` is expanded). Valid with `subagent`, and also on chain templates as the default cwd for delegated steps. |
+| `parallel` | — | Delegated prompts only. Repeats the same subagent in parallel `N` times. Each copy gets a slot header like `[Parallel subagent 2/3]` prepended to the task. Must be an integer greater than or equal to 2. |
+| `bestOfN` | — | Compare templates only. Nested compare authoring block with `workers`, `reviewers`, optional `finalApplier`, and optional `worktree`. Top-level compare fields are not supported in templates. |
+| `bestOfN.workers` | — | Ordered worker lineup used for the worker phase. Each slot object supports optional `agent`/`subagent`, optional `model`, optional `task`, optional `taskSuffix`, optional `cwd`, and optional `count`. If both `agent` and `subagent` are omitted, the default agent is `delegate`. |
+| `bestOfN.reviewers` | — | Ordered reviewer lineup used after worker aggregation. Slot shape matches workers. If both `agent` and `subagent` are omitted, the default agent is `reviewer`. |
+| `bestOfN.finalApplier` | — | Optional single-slot final apply phase that edits the real branch after reviewers. Supports optional `agent`/`subagent`, optional `model`, optional `task`, and optional `taskSuffix`. If both `agent` and `subagent` are omitted, the default agent is `delegate`. `count` and `cwd` are not supported. Requires `bestOfN.worktree: true` at runtime. |
+| `cwd` | — | Working directory for delegated subagent subprocesses. Must be an absolute path (`~/...` is expanded). Valid with `subagent`, on chain templates as the default cwd for delegated steps, and on compare prompts as the default repo cwd. Worker/reviewer slots can also set their own `cwd` inside `bestOfN.workers` / `bestOfN.reviewers`. |
 
 ## Model Format
 
@@ -238,6 +244,21 @@ Use url in the prompt to take screenshot: $@
 
 The subagent process runs with `/tmp/screenshots` as its working directory. Paths must be absolute (`~/...` is expanded). The directory is validated at execution time.
 
+To fan the same delegated prompt out to multiple copies in parallel, add `parallel: N`:
+
+```markdown
+---
+model: anthropic/claude-sonnet-4-20250514
+subagent: simplifier
+inheritContext: true
+parallel: 3
+worktree: true
+---
+Review changed code and fix any issues found.
+```
+
+This expands to three parallel `pi-subagents` tasks targeting the same agent. Each one receives the same rendered prompt plus an automatic slot header like `[Parallel subagent 1/3]`, `[Parallel subagent 2/3]`, and `[Parallel subagent 3/3]` so the body can assign different roles to each copy. `worktree: true` is optional here and gives each parallel run its own git worktree.
+
 During execution, a live progress widget appears above the editor showing elapsed time, tool count, token usage, and the current tool. When the run finishes, it's replaced by a completion card with the task preview, tool call history, output, and usage stats.
 
 You can override delegation at runtime per invocation with `--subagent`, `--subagent=<name>`, `--subagent:<name>`, or `--cwd=<path>`. `--cwd=<path>` must be absolute after optional `~/...` expansion. Runtime flags take precedence for that invocation only.
@@ -253,6 +274,85 @@ Two additional runtime flags work for any prompt (not just delegated ones):
 /deslop --model=openai/gpt-5.4 --loop 3
 ```
 
+Compare templates also accept runtime lineup overrides:
+
+Prompt-template frontmatter authoring uses `bestOfN:`. Runtime overrides stay on the low-level flags below.
+
+- `--workers=<json-array>` / `--reviewers=<json-array>` replace the corresponding frontmatter lineup.
+- `--workers-append=<json-array>` / `--reviewers-append=<json-array>` append to the corresponding lineup.
+- `--final-applier=<json-object-or-one-element-array>` replaces the optional final apply slot.
+
+Each worker/reviewer JSON array entry must be an object with either `subagent` or `agent`, plus optional `model`, `task`, `taskSuffix`, `cwd`, and `count`. In worker slots, `"subagent": true` maps to `delegate`. In reviewer slots, `"subagent": true` maps to `reviewer`. `--final-applier=` accepts one slot object (or a one-element array) with `subagent`/`agent`, optional `model`, optional `task`, and optional `taskSuffix`; for this final slot, `"subagent": true` maps to `delegate`, and both `count` and `cwd` are not supported.
+
+## Best-of-N Compare Prompt
+
+This repo ships one example compare prompt under `examples/`:
+
+- `examples/best-of-n.md` installs as `/best-of-n`, runs in the current repo, and shows mixed workers, mixed reviewers, and an optional final apply phase.
+- Smoke test: `/best-of-n smoke test`.
+
+Install them manually from this repo checkout (or from the installed package directory):
+
+```bash
+PTM_DIR=/path/to/pi-prompt-template-model
+mkdir -p ~/.pi/agent/prompts
+cp "$PTM_DIR/examples/best-of-n.md" ~/.pi/agent/prompts/best-of-n.md
+```
+
+After copying the file, restart `pi` if it is already running. The prompt then runs an explicit compare flow:
+
+Compare prompt templates are authored under `bestOfN:`. Top-level `workers`, `reviewers`, and `finalApplier` frontmatter fields are rejected with migration diagnostics.
+
+1. Worker phase: run the worker lineup in parallel (`context: fork`) so workers generate candidate implementations in temporary worktrees.
+2. Continue as long as at least one worker succeeds. Reviewer slots receive successful worker outputs plus worker/worktree summaries and produce findings only.
+3. Optional final apply phase: if `finalApplier` is configured, run one delegated apply step on the real compare repo (`compareCwd`) to pick a winner or synthesize/cherry-pick and apply the final patch.
+4. If all reviewers fail but `finalApplier` exists, the final apply step still runs with fallback context from workers plus reviewer failure summaries.
+
+Worker/reviewer lineups are fully configurable from `bestOfN` frontmatter or runtime overrides, so there is no fixed three-model worker assumption. If a compare prompt omits `bestOfN.workers`, it falls back to one `delegate` worker using the current/main model. If it omits `bestOfN.reviewers`, it falls back to one `reviewer` slot. `bestOfN.finalApplier` is optional, and compare runs reject an effective final applier unless `bestOfN.worktree: true` is set.
+
+For same-model best-of-N, use `count: N` on one worker slot:
+
+```yaml
+bestOfN:
+  workers:
+    - model: openai-codex/gpt-5.4:low
+      count: 4
+```
+
+You can also mix models and give each slot its own count:
+
+```yaml
+bestOfN:
+  workers:
+    - model: openai-codex/gpt-5.4:low
+      count: 3
+    - model: google/gemini-2.5-pro:medium
+      count: 2
+    - model: anthropic/claude-sonnet-4-20250514:high
+```
+
+Reviewer slots support the same lineup shape, and `bestOfN.finalApplier` is one optional single-slot final apply step:
+
+```yaml
+bestOfN:
+  reviewers:
+    - model: openai-codex/gpt-5.4:low
+      count: 2
+    - model: google/gemini-2.5-pro:medium
+      taskSuffix: Focus on regression risk.
+  finalApplier:
+    model: anthropic/claude-sonnet-4-20250514:high
+    taskSuffix: Apply the final patch on the current branch and report verification.
+```
+
+Within compare lineups, omitting both `agent` and `subagent` uses phase defaults: `delegate` in workers, `reviewer` in reviewers, and `delegate` in finalApplier. You can still set explicit `agent` or `subagent` when needed.
+
+Explicitly repeating the same slot still works, but `count: N` is the cleaner shorthand when the slot is identical.
+
+Within a compare lineup, use `task` for a full per-slot override and `taskSuffix` for a small per-slot append. `taskSuffix` is added after the shared worker task (or after the slot's `task` if you set one), which makes it the better fit for things like per-model output file names.
+
+When a compare prompt uses `bestOfN.worktree: true`, all worker slots must resolve to the same `cwd`. Mixed worker `cwd` values are only allowed when worktree isolation is off. Worktree isolation is for the worker phase only; `bestOfN.finalApplier` always applies on the real branch (`compareCwd`).
+
 ## Loop Execution
 
 Run a template multiple times with `--loop`:
@@ -387,11 +487,22 @@ chain: parallel(scan-frontend, scan-backend) -> consolidate
 ---
 ```
 
-Each entry inside `parallel(...)` runs as a delegated subagent task concurrently. Parallel entries can include per-step args (for example `parallel(scan-frontend, scan-backend "auth")`), but per-step `--loop` is not supported inside parallel groups. Nested `parallel(...)` is rejected. Parallel entries must be delegated templates (`subagent: ...` or runtime `--subagent` override), and all entries in the same parallel group must resolve to the same `inheritContext` mode and `cwd`.
+Each entry inside `parallel(...)` runs as a delegated subagent task concurrently. Parallel entries can include per-step args (for example `parallel(scan-frontend, scan-backend "auth")`), but per-step `--loop` is not supported inside parallel groups. Nested `parallel(...)` is rejected. Parallel entries must be delegated templates (`subagent: ...` or runtime `--subagent` override). All entries in the same parallel group must resolve to the same `inheritContext` mode. Mixed `cwd` values are allowed normally, but when `worktree: true` is enabled they must all resolve to the same `cwd`.
+
+Add `worktree: true` (or `--worktree` at runtime) so each parallel subagent runs in its own git worktree, avoiding file conflicts when agents edit concurrently:
+
+```markdown
+---
+chain: parallel(scan-frontend, scan-backend) -> consolidate
+worktree: true
+---
+```
+
+`worktree` requires a chain with at least one `parallel()` step. The flag is passed to pi-subagents, which handles worktree creation and cleanup.
 
 Steps with a `model` field use their own model. Steps without one inherit a snapshot of whatever model was active when the chain started — not the previous step's model. This keeps behavior deterministic regardless of what earlier steps do.
 
-Chain templates support `loop`, `fresh`, `converge`, `restore`, and `cwd` in their frontmatter for controlling the overall execution:
+Chain templates support `loop`, `fresh`, `converge`, `restore`, `worktree`, and `cwd` in their frontmatter for controlling the overall execution:
 
 ```markdown
 ---
@@ -439,6 +550,7 @@ Parallel groups work in `/chain-prompts` too:
 
 ```
 /chain-prompts parallel(scan-fe, scan-be) -> review
+/chain-prompts parallel(scan-fe, scan-be) -> review --worktree
 ```
 
 Looping applies to the entire chain:

package/args.ts

@@ -24,6 +24,27 @@ export interface SubagentOverrideExtraction {
 	fork?: boolean;
 }
 
+export interface LineupOverrideSlot {
+	agent: string;
+	model?: string;
+	task?: string;
+	taskSuffix?: string;
+	cwd?: string;
+	count?: number;
+}
+
+export interface LineupOverrideAction {
+	target: "workers" | "reviewers" | "finalApplier";
+	mode: "replace" | "append";
+	slots: LineupOverrideSlot[];
+}
+
+export interface LineupOverrideExtraction {
+	args: string;
+	actions: LineupOverrideAction[];
+	errors: string[];
+}
+
 export function extractLoopCount(argsString: string): LoopExtraction | null {
 	let loopCount: number | null = null;
 	let loopFound = false;
@@ -165,8 +186,8 @@ export function extractLoopFlags(argsString: string): LoopFlags {
 	return { args: cleaned.trim(), fresh, converge: !noConverge };
 }
 
-export function extractChainContextFlag(argsString: string): { args: string; chainContext: boolean } {
-	let chainContext = false;
+function extractBooleanFlag(argsString: string, flag: string): { args: string; found: boolean } {
+	let found = false;
 	const tokensToRemove: Array<{ start: number; end: number }> = [];
 
 	let i = 0;
@@ -190,14 +211,14 @@ export function extractChainContextFlag(argsString: string): { args: string; cha
 		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
 		const token = argsString.slice(tokenStart, i);
 
-		if (token === "--chain-context") {
-			chainContext = true;
+		if (token === flag) {
+			found = true;
 			tokensToRemove.push({ start: tokenStart, end: i });
 		}
 	}
 
 	if (tokensToRemove.length === 0) {
-		return { args: argsString.trim(), chainContext: false };
+		return { args: argsString.trim(), found: false };
 	}
 
 	tokensToRemove.sort((a, b) => b.start - a.start);
@@ -206,7 +227,17 @@ export function extractChainContextFlag(argsString: string): { args: string; cha
 		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
 	}
 
-	return { args: cleaned.trim(), chainContext };
+	return { args: cleaned.trim(), found };
+}
+
+export function extractChainContextFlag(argsString: string): { args: string; chainContext: boolean } {
+	const { args, found } = extractBooleanFlag(argsString, "--chain-context");
+	return { args, chainContext: found };
+}
+
+export function extractWorktreeFlag(argsString: string): { args: string; worktree: boolean } {
+	const { args, found } = extractBooleanFlag(argsString, "--worktree");
+	return { args, worktree: found };
 }
 
 export function extractSubagentOverride(argsString: string): SubagentOverrideExtraction {
@@ -290,6 +321,275 @@ export function extractSubagentOverride(argsString: string): SubagentOverrideExt
 	};
 }
 
+function parseLineupOverrideSlots(
+	raw: string,
+	target: "workers" | "reviewers" | "finalApplier",
+	mode: "replace" | "append",
+	errors: string[],
+): LineupOverrideAction | undefined {
+	const label = `--${target === "finalApplier" ? "final-applier" : `${target}${mode === "append" ? "-append" : ""}`}`;
+	if (!raw) {
+		errors.push(`Invalid ${label}: expected ${target === "finalApplier" ? "a slot object or a one-element JSON array" : "a JSON array of slot objects"}.`);
+		return undefined;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		errors.push(`Invalid ${label}: expected valid JSON (${message}).`);
+		return undefined;
+	}
+	const entries = target === "finalApplier"
+		? (Array.isArray(parsed)
+			? parsed.length === 1
+				? parsed
+				: null
+			: [parsed])
+		: (Array.isArray(parsed) && parsed.length > 0 ? parsed : null);
+	if (!entries) {
+		errors.push(
+			target === "finalApplier"
+				? `Invalid ${label}: expected a slot object or a one-element JSON array.`
+				: `Invalid ${label}: expected a non-empty JSON array.`,
+		);
+		return undefined;
+	}
+
+	const slots: LineupOverrideSlot[] = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+			errors.push(`Invalid ${label}: slot ${i + 1} must be an object.`);
+			return undefined;
+		}
+		const slot = entry as Record<string, unknown>;
+		if (slot.agent !== undefined && slot.subagent !== undefined) {
+			errors.push(`Invalid ${label}: slot ${i + 1} cannot combine "agent" and "subagent".`);
+			return undefined;
+		}
+
+		let agent: string | undefined;
+		if (typeof slot.agent === "string" && slot.agent.trim()) {
+			agent = slot.agent.trim();
+		} else if (slot.agent !== undefined) {
+			errors.push(`Invalid ${label}: slot ${i + 1} requires a non-empty string "agent".`);
+			return undefined;
+		}
+
+		if (!agent && slot.subagent !== undefined) {
+			if (slot.subagent === true) {
+				agent = target === "reviewers" ? "reviewer" : "delegate";
+			} else if (typeof slot.subagent === "string" && slot.subagent.trim()) {
+				agent = slot.subagent.trim();
+			} else {
+				errors.push(`Invalid ${label}: slot ${i + 1} requires "subagent" to be true or a non-empty string.`);
+				return undefined;
+			}
+		}
+
+		if (!agent) {
+			errors.push(`Invalid ${label}: slot ${i + 1} requires "agent" or "subagent".`);
+			return undefined;
+		}
+		const model = typeof slot.model === "string" && slot.model.trim() ? slot.model.trim() : undefined;
+		const task = typeof slot.task === "string" && slot.task.trim() ? slot.task.trim() : undefined;
+		const taskSuffix = typeof slot.taskSuffix === "string" && slot.taskSuffix.trim() ? slot.taskSuffix.trim() : undefined;
+		if (target === "finalApplier" && slot.cwd !== undefined) {
+			errors.push(`Invalid ${label}: slot ${i + 1} "cwd" is not supported.`);
+			return undefined;
+		}
+		const cwd = typeof slot.cwd === "string" && slot.cwd.trim() ? slot.cwd.trim() : undefined;
+		let count: number | undefined;
+		if (slot.count !== undefined) {
+			if (target === "finalApplier") {
+				errors.push(`Invalid ${label}: slot ${i + 1} "count" is not supported.`);
+				return undefined;
+			}
+			const rawCount = slot.count;
+			if (typeof rawCount !== "number" || !Number.isInteger(rawCount) || rawCount < 1) {
+				errors.push(`Invalid ${label}: slot ${i + 1} "count" must be an integer greater than or equal to 1.`);
+				return undefined;
+			}
+			count = rawCount;
+		}
+		slots.push({
+			agent,
+			...(model ? { model } : {}),
+			...(task ? { task } : {}),
+			...(taskSuffix ? { taskSuffix } : {}),
+			...(cwd ? { cwd } : {}),
+			...(count !== undefined ? { count } : {}),
+		});
+	}
+
+	return { target, mode, slots };
+}
+
+interface LineupOverrideFlagSpec {
+	flag: string;
+	target: "workers" | "reviewers" | "finalApplier";
+	mode: "replace" | "append";
+}
+
+const LINEUP_OVERRIDE_FLAGS: LineupOverrideFlagSpec[] = [
+	{ flag: "--workers-append=", target: "workers", mode: "append" },
+	{ flag: "--reviewers-append=", target: "reviewers", mode: "append" },
+	{ flag: "--workers=", target: "workers", mode: "replace" },
+	{ flag: "--reviewers=", target: "reviewers", mode: "replace" },
+	{ flag: "--final-applier=", target: "finalApplier", mode: "replace" },
+];
+
+function readQuotedValue(input: string, start: number): { value: string; end: number } | undefined {
+	const quote = input[start];
+	if (quote !== `"` && quote !== `'`) return undefined;
+
+	let i = start + 1;
+	while (i < input.length) {
+		const char = input[i];
+		if (char === "\\") {
+			i += 2;
+			continue;
+		}
+		if (char === quote) {
+			return {
+				value: input.slice(start + 1, i),
+				end: i + 1,
+			};
+		}
+		i++;
+	}
+
+	return undefined;
+}
+
+function readBalancedValue(
+	input: string,
+	start: number,
+	open: string,
+	close: string,
+): { value: string; end: number } | undefined {
+	if (input[start] !== open) return undefined;
+
+	let depth = 0;
+	let inQuote: string | null = null;
+
+	for (let i = start; i < input.length; i++) {
+		const char = input[i];
+		if (inQuote) {
+			if (char === "\\") {
+				i++;
+				continue;
+			}
+			if (char === inQuote) inQuote = null;
+			continue;
+		}
+
+		if (char === `"` || char === `'`) {
+			inQuote = char;
+			continue;
+		}
+		if (char === open) {
+			depth++;
+			continue;
+		}
+		if (char !== close) continue;
+
+		depth--;
+		if (depth === 0) {
+			return {
+				value: input.slice(start, i + 1),
+				end: i + 1,
+			};
+		}
+	}
+
+	return undefined;
+}
+
+function readLineupOverrideValue(input: string, start: number): { value: string; end: number } {
+	if (start >= input.length) return { value: "", end: start };
+
+	const bracketed = readBalancedValue(input, start, "[", "]");
+	if (bracketed) return bracketed;
+
+	const braced = readBalancedValue(input, start, "{", "}");
+	if (braced) return braced;
+
+	const quoted = readQuotedValue(input, start);
+	if (quoted) return quoted;
+
+	let end = start;
+	while (end < input.length && !/\s/.test(input[end])) end++;
+	return {
+		value: input.slice(start, end),
+		end,
+	};
+}
+
+function parseLineupOverrideToken(
+	input: string,
+	start: number,
+): { target: "workers" | "reviewers" | "finalApplier"; mode: "replace" | "append"; raw: string; end: number } | undefined {
+	for (const spec of LINEUP_OVERRIDE_FLAGS) {
+		if (!input.startsWith(spec.flag, start)) continue;
+		const valueStart = start + spec.flag.length;
+		const parsedValue = readLineupOverrideValue(input, valueStart);
+		return {
+			target: spec.target,
+			mode: spec.mode,
+			raw: parsedValue.value,
+			end: parsedValue.end,
+		};
+	}
+
+	return undefined;
+}
+
+export function extractLineupOverrides(argsString: string): LineupOverrideExtraction {
+	const actions: LineupOverrideAction[] = [];
+	const errors: string[] = [];
+	const tokensToRemove: Array<{ start: number; end: number }> = [];
+
+	let i = 0;
+	while (i < argsString.length) {
+		const char = argsString[i];
+
+		if (char === '"' || char === "'") {
+			const quote = char;
+			i++;
+			while (i < argsString.length && argsString[i] !== quote) i++;
+			if (i < argsString.length) i++;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			i++;
+			continue;
+		}
+
+		const token = parseLineupOverrideToken(argsString, i);
+		if (token) {
+			tokensToRemove.push({ start: i, end: token.end });
+			const action = parseLineupOverrideSlots(token.raw, token.target, token.mode, errors);
+			if (action) actions.push(action);
+			i = token.end;
+			continue;
+		}
+
+		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
+	}
+
+	tokensToRemove.sort((a, b) => b.start - a.start);
+	let cleaned = argsString;
+	for (const { start, end } of tokensToRemove) {
+		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
+	}
+
+	return { args: cleaned.trim(), actions, errors };
+}
+
 export function splitByUnquotedSeparator(input: string, separator: string): string[] {
 	const parts: string[] = [];
 	let start = 0;

package/examples/best-of-n.md

@@ -0,0 +1,30 @@
+---
+description: Best-of-N code task with parallel workers using different models in separate worktrees, parallel reviewers, and a final apply step that picks or synthesizes the final patch.
+# Usage: /best-of-n fix the flaky auth test
+# Usage: /best-of-n implement the plan: /path/to/plan.md
+bestOfN:
+  # Workers run in temporary worktrees; the final apply step edits the current branch.
+  worktree: true
+  workers:
+    # count means "run this exact slot N times in parallel".
+    # So this example below runs 3 spark workers and 2 gpt-5.4-mini workers in parallel.
+    - model: openai-codex/gpt-5.3-codex-spark:low
+      count: 3
+    - model: openai-codex/gpt-5.4-mini:high
+      count: 2
+  reviewers:
+    # Reviewers use the base `reviewer` agent from `~/.pi/agent/extensions/subagent/agents/reviewer.md`.
+    # These slots can override its default model, and they get a generated compare task built from
+    # the original request, successful worker outputs/worktree summaries, and these slot instructions.
+    # count works the same way here: it runs the same reviewer slot multiple times in parallel.
+    # taskSuffix appends extra instructions to just that slot without replacing the shared prompt body.
+    - model: openai-codex/gpt-5.3-codex-spark:medium
+      count: 2
+    - model: openai-codex/gpt-5.4-mini:high
+      taskSuffix: Focus extra attention on regression risk and missing edge cases.
+  finalApplier:
+    # The final apply step picks or synthesizes from worker/reviewer findings and applies on the current branch.
+    model: openai-codex/gpt-5.4-mini:xhigh
+    taskSuffix: Apply the final patch directly on the current branch, run best-effort relevant verification, and report changed files plus verification run.
+---
+$@