@codions/portta 0.0.0-develop.147.sha-1859ad1

package/dist/assets/skills/portta-workflows/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: taskflow-workflows
+description: Author and run custom multi-agent workflows with Taskflow — JavaScript files that orchestrate Codex, Claude Code, OpenCode, and Pi agents deterministically via agent()/parallel()/pipeline()/phase(). Use when a task should be decomposed across agents, independently verified, resumed durably, or managed as a reusable project workflow.
+metadata:
+  type: reference
+---
+
+# Taskflow workflows
+
+Create custom workflows in `<project>/.portta/workflows/`. `portta flow workflows list` shows the project catalog; `portta flow run workflow <workflow-id>` starts a durable Taskflow Run that can be observed in the dashboard and resumed with `portta flow runs resume <run-id>`. Each `agent()` call spawns a real **Codex**, **Claude Code**, **OpenCode**, or **Pi** agent — you pick the provider per call.
+
+A workflow structures work across many agents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps). The file is where you encode that structure: what fans out, what verifies, what synthesizes.
+
+When you write one, the right move is often **hybrid**: scout first (list the files, find the channels, scope the diff) to discover the work-list, then write a workflow to pipeline over it. You don't need to know the shape before the *task* — only before the *orchestration step*.
+
+Common single-phase workflows you can chain across runs:
+- **Understand** — parallel readers over relevant subsystems → structured map
+- **Design** — judge panel of N independent approaches → scored synthesis
+- **Review** — dimensions → find → adversarially verify (example below)
+- **Research** — multi-modal sweep → deep-read → synthesize
+- **Migrate** — discover sites → transform each (workspace isolation) → verify
+
+For larger work, run several in sequence — read each result before deciding the next phase. You stay in the loop; each workflow is one well-scoped fan-out.
+
+Every script must begin with `export const meta = {...}`:
+```js
+export const meta = {
+  name: 'find-flaky-tests',
+  description: 'Find flaky tests and propose fixes',   // one-line summary
+  phases: [                                            // one entry per phase() call
+    { title: 'Scan', detail: 'grep test logs for retries' },
+    { title: 'Fix', detail: 'one agent per flaky test' },
+  ],
+}
+// script body starts here — use agent()/parallel()/pipeline()/phase()/log()
+phase('Scan')
+const flaky = await agent('grep CI logs for retry markers', { schema: FLAKY_SCHEMA })
+// ...
+```
+
+The `meta` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: `name`, `description`. Optional fields: `phases`, `defaultProvider` with `defaultModel`, `defaultSandbox`, `whenToUse`, and `workspace`. Use the SAME phase titles in `meta.phases` as in `phase()` calls — titles are matched exactly; a `phase()` call with no matching meta entry just gets its own progress group.
+
+Script body hooks:
+- agent(prompt: string, opts?: {provider?: 'codex' | 'claude-code' | 'opencode' | 'pi', model?: string, effort?: string, schema?: object, label?: string, phase?: string, sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access', approval?: 'never' | 'on-request', cwd?: string, instructions?: string, maxTurns?: number, worktree?: boolean | string, key?: string}): Promise<any> — spawn an agent. Without schema, returns its final text as a string. With schema (a JSON Schema), the agent is forced to return JSON matching it and `agent()` returns the validated object — no parsing needed. Returns null if the user skips the agent mid-run (filter with `.filter(Boolean)`). `opts.provider` / `opts.model`: **default to omitting both** — the agent inherits the provider and model the workflow is being run with, which is almost always correct. Only set them when the user explicitly asks for a specific provider/model, or you're highly confident a particular step needs a different one — and then set them **together**: provider and model are both-or-neither. `opts.label` overrides the display label. `opts.phase` assigns one call to a named phase without changing the ambient phase. `opts.sandbox` defaults to `read-only`; use `workspace-write` only when the agent must write. `opts.worktree` requests an isolated child workspace: in a durable Taskflow Run this is a Taskflow-managed fork lease; in a standalone workflow run it is an engine-managed git worktree. Use it only when parallel agents mutate files and would otherwise conflict. `opts.key` is a stable resume pin that survives prompt-wording/reordering edits.
+- pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives `(prevResult, originalItem, index)` — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to `null` and skips its remaining stages.
+- parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to `null` in the result array — the call itself never rejects, so `.filter(Boolean)` before using the results. Use ONLY when you genuinely need all results together.
+- log(message: string): void — emit a progress message to the user (shown as a narrator line above the progress tree)
+- phase(title: string): void — start a new phase; subsequent `agent()` calls are grouped under this title in the progress display
+- args: any — the workflow input. Durable Taskflow Runs receive it from `--input` / `--input-json`; standalone runs receive it from `--args` / `--args-file`. Use this to parameterize a workflow — e.g. pass a research question, target path, or config object.
+- budget: {total: number|null, spent(): number, remaining(): number} — the run's output-token target, set with `--budget N` for standalone runs. `budget.total` is null if no target was set. `budget.spent()` returns output tokens spent this run. `budget.remaining()` returns `max(0, total - spent())`, or `Infinity` if no target. The target is a HARD ceiling, not advisory: once `spent()` reaches `total`, further `agent()` calls throw. Use for dynamic loops: `while (budget.total && budget.remaining() > 50_000) { ... }`, or static scaling: `const FLEET = budget.total ? Math.floor(budget.total / 100_000) : 5`.
+- now(): number / random(): number — journal-seeded deterministic time/RNG. Use these instead of `Date.now()`/`Math.random()` (which throw — see below).
+
+Agents are told their final text IS the return value (not a human-facing message), so they return raw data. For structured output, use the schema option — validation happens at the worker layer and the agent retries once on a mismatch.
+
+## Providers
+
+Every `agent()` runs under a provider/model. **By default, do NOT set `provider` or `model` per agent** — each agent inherits the provider/model the workflow is being run with, which is almost always what you want. Most workflows (including the canonical example and the patterns above) omit them entirely. Pin them only when the user explicitly asks for a specific provider/model, or you're confident a particular step needs a different one.
+
+**Provider and model are both-or-neither** — at every site (per-call opts, `meta.defaultProvider`/`defaultModel`, standalone `--provider`/`--model`): set both, or omit both to inherit the run defaults. A lone `provider:` (or lone `model:`) is rejected before the agent spawns. This exists because a lone provider override could inherit a model belonging to a *different* provider. When you pin a provider, name the model explicitly. `portta flow workflows doctor` shows which providers are installed/authenticated.
+
+The four providers:
+- **codex** (OpenAI) — the default. `opts.effort` tunes reasoning depth: `"none" | "minimal" | "low" | "medium" | "high" | "xhigh"`. Requires the `codex` CLI authenticated (ChatGPT login); its built-in tools come from that auth, and it ignores `OPENAI_API_KEY`. Native structured output uses a free-form working turn followed by a schema-constrained extraction turn.
+- **claude-code** (Anthropic) — via the Claude Agent SDK; requires the `claude` CLI / SDK available. `opts.effort` accepts `"low" | "medium" | "high" | "xhigh" | "max"` (`max` is Opus-tier; the model silently downgrades unsupported levels). Structured output is delivered on the final result only (intermediate messages stay free-form).
+- **opencode** (OpenCode CLI ≥ 1.16.2) — spawn-per-call subprocess backend. `model` is an open `provider/model` string routed by OpenCode, required whenever `provider: "opencode"` is set. **Requires `sandbox: "danger-full-access"`** — OpenCode has no enforceable confinement, so the default `read-only` sandbox is rejected. `effort` maps directly to OpenCode's provider-specific `--variant` flag. `maxTurns` is rejected. Structured output uses a silent extraction turn that reuses the working session.
+- **pi** (`@earendil-works/pi-coding-agent` ≥ 0.79.1) — spawn-per-call subprocess backend. `model` is an open Pi model reference. **Requires `sandbox: "danger-full-access"`** — Pi's tool allowlists are not OS confinement, so `read-only`/`workspace-write` are rejected. `effort` maps onto Pi's full thinking range (`none`→off … `max`→xhigh); `maxTurns` is rejected. Structured output uses a silent tool-less extraction turn.
+
+(`opts.effort` is a single union — `"none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"` — and each worker maps to its nearest supported level: `minimal`→`low` on Claude, `max`→`xhigh` on Codex/Pi. OpenCode passes the value through as `--variant`.)
+
+Codex and Claude Code honor every `sandbox` mode (read-only by default); **OpenCode and Pi are full-access-only** — every call on them needs an explicit `sandbox: "danger-full-access"` (per call or via the standalone `--sandbox`), a deliberate fail-closed choice because neither CLI can honestly enforce confinement. All providers honor `cwd`; `worktree` isolates parallel file edits regardless of provider. Outdated OpenCode/Pi binaries are refused at runtime (`provider_outdated`); `portta flow workflows doctor` flags them up front.
+
+The default case — omit provider, so fan-out and synthesis run on the workflow's selected provider:
+```js
+const findings = await parallel(AREAS.map(area => () =>
+  agent(`Inspect ${area} and list concrete issues.`, { schema: FINDINGS_SCHEMA })))
+const report = await agent(`Synthesize into a prioritized report:\n${JSON.stringify(findings.filter(Boolean), null, 2)}`)
+return report
+```
+Pin a provider only when you mean to — e.g. a deliberate cross-provider verify pass when the user has asked for that diversity:
+```js
+const verified = await pipeline(
+  suspects,
+  s => agent(`Is this a real bug? ${s.desc}`, { schema: VERDICT }),
+  (v, s) => agent(`Try to REFUTE that ${s.desc} is a bug; default to refuted if unsure.`,
+    { provider: "claude-code", model: "<claude-model>", schema: VERDICT }).then(r => ({ ...s, real: v.real && !r.refuted })))
+```
+
+Scripts are plain JavaScript, NOT TypeScript — type annotations (`: string[]`), interfaces, and generics fail to parse. The script body runs in an async context — use await directly. Standard JS built-ins (JSON, Math, Array, etc.) are available — EXCEPT `Date.now()`/`Math.random()`/argless `new Date()`, which throw (they would break resume) and are rejected by a submit-time lint; use the injected `now()`/`random()` instead, or pass timestamps in via `args`. No filesystem, network, or relative import/require in the workflow body (the agents do the I/O).
+
+DEFAULT TO `pipeline()`. Only reach for a barrier (`parallel()` between stages) when you genuinely need ALL prior-stage results together.
+
+A barrier is correct ONLY when stage N needs cross-item context from all of stage N-1:
+- Dedup/merge across the full result set before expensive downstream work
+- Early-exit if the total count is zero ("0 bugs found → skip verification entirely")
+- Stage N's prompt references "the other findings" for comparison
+
+A barrier is NOT justified by:
+- "I need to flatten/map/filter first" — do it inside a pipeline stage: `pipeline(items, stageA, r => transform([r]).flat(), stageB)`
+- "The stages are conceptually separate" — that's what `pipeline()` models. Separate stages ≠ synchronized stages.
+- "It's cleaner code" — barrier latency is real. If 5 finders run and the slowest takes 3× the fastest, a barrier wastes 2/3 of the fast finders' idle time.
+
+Smell test: if you wrote
+```js
+const a = await parallel(...)
+const b = transform(a)        // flatten, map, filter — no cross-item dependency
+const c = await parallel(b.map(...))
+```
+that middle transform doesn't need the barrier. Rewrite as a pipeline with the transform inside a stage. When in doubt: pipeline.
+
+Concurrent `agent()` calls are capped at 100 per standalone workflow by default (override with `--concurrency N`) — excess calls queue and run as slots free up. You can pass more items than the cap to `parallel()`/`pipeline()` and they all complete; only up to the cap run at any moment. Total agent count across a workflow's lifetime is capped at 1000. A single `parallel()`/`pipeline()` call accepts at most 4096 items; passing more is an explicit error, not a silent truncation.
+
+The canonical multi-stage pattern — pipeline by default, each dimension verifies as soon as its review completes:
+```js
+export const meta = {
+  name: 'review-changes',
+  description: 'Review changed files across dimensions, verify each finding',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+const DIMENSIONS = [{ key: 'bugs', prompt: '...' }, { key: 'perf', prompt: '...' }]
+const results = await pipeline(
+  DIMENSIONS,
+  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS_SCHEMA }),
+  review => parallel(review.findings.map(f => () =>
+    agent(`Adversarially verify: ${f.title}`, { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT_SCHEMA })
+      .then(v => ({ ...f, verdict: v }))
+  ))
+)
+const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
+return { confirmed }
+// Dimension 'bugs' findings verify while dimension 'perf' is still reviewing. No wasted wall-clock.
+```
+
+When a barrier IS correct — dedup across all findings before expensive verification:
+```js
+const all = await parallel(DIMENSIONS.map(d => () => agent(d.prompt, { schema: FINDINGS_SCHEMA })))
+const deduped = dedupeByFileAndLine(all.filter(Boolean).flatMap(r => r.findings))
+const verified = await parallel(deduped.map(f => () => agent(verifyPrompt(f), { schema: VERDICT_SCHEMA })))
+```
+
+Loop-until-count pattern — accumulate to a target:
+```js
+const bugs = []
+while (bugs.length < 10) {
+  const result = await agent("Find bugs in this codebase.", { schema: BUGS_SCHEMA })
+  bugs.push(...result.bugs)
+  log(`${bugs.length}/10 found`)
+}
+```
+
+Loop-until-budget pattern — scale depth to `--budget`. Guard on `budget.total`: with no target set, `remaining()` is Infinity and the loop would run straight to the 1000-agent cap.
+```js
+const bugs = []
+while (budget.total && budget.remaining() > 50_000) {
+  const result = await agent("Find bugs in this codebase.", { schema: BUGS_SCHEMA })
+  bugs.push(...result.bugs)
+  log(`${bugs.length} found, ${Math.round(budget.remaining() / 1000)}k remaining`)
+}
+```
+
+Composing patterns — exhaustive review (find → dedup vs seen → diverse-lens panel → loop-until-dry):
+```js
+const seen = new Set(), confirmed = []
+let dry = 0
+while (dry < 2) {
+  const found = (await parallel(FINDERS.map(f => () =>
+    agent(f.prompt, { phase: 'Find', schema: BUGS })))).filter(Boolean).flatMap(r => r.bugs)
+  const fresh = found.filter(b => !seen.has(key(b)))
+  if (!fresh.length) { dry++; continue }
+  dry = 0; fresh.forEach(b => seen.add(key(b)))
+  const judged = await parallel(fresh.map(b => () =>
+    parallel(['correctness', 'security', 'repro'].map(lens => () =>
+      agent(`Judge "${b.desc}" via the ${lens} lens — real?`, { phase: 'Verify', schema: VERDICT })))
+      .then(vs => ({ b, real: vs.filter(Boolean).filter(v => v.real).length >= 2 }))))
+  confirmed.push(...judged.filter(v => v.real).map(v => v.b))
+}
+return confirmed
+// dedup vs `seen`, NOT `confirmed` — else judge-rejected findings reappear every round and it never converges.
+```
+
+Quality patterns — common shapes; pick by task and compose freely:
+- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE. Kill if ≥majority refute. Prevents plausible-but-wrong findings from surviving.
+  ```js
+  const votes = await parallel(Array.from({ length: 3 }, () => () =>
+    agent(`Try to refute: ${claim}. Default to refuted=true if uncertain.`, { schema: VERDICT })))
+  const survives = votes.filter(Boolean).filter(v => !v.refuted).length >= 2
+  ```
+- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, perf, does-it-reproduce) instead of N identical refuters — diversity catches failure modes redundancy can't.
+- Judge panel: generate N independent attempts from different angles (e.g. MVP-first, risk-first, user-first), score with parallel judges, synthesize from the winner while grafting the best ideas from runners-up. Beats one-attempt-iterated when the solution space is wide.
+- Loop-until-dry: for unknown-size discovery (bugs, issues, edge cases), keep spawning finders until K consecutive rounds return nothing new. Simple counters (`while count < N`) miss the tail.
+- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time). Each is blind to what the others surface; useful when one search angle won't find everything.
+- Completeness critic: a final agent that asks "what's missing — modality not run, claim unverified, source unread?" What it finds becomes the next round of work.
+- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), `log()` what was dropped — silent truncation reads as "covered everything" when it didn't.
+
+Scale to what the user asked for. "find any bugs" → a few finders, single-vote verify. "thoroughly audit this" or "be comprehensive" → larger finder pool, 3–5 vote adversarial pass, synthesis stage. When unsure, lean toward thoroughness for research/review/audit requests and toward brevity for quick checks.
+
+These patterns aren't exhaustive — compose novel harnesses when the task calls for it (tournament brackets, self-repair loops, staged escalation, whatever fits).
+
+Use a workflow for multi-step orchestration where control flow should be deterministic (loops, conditionals, fan-out) rather than model-driven.
+
+## Workspaces
+
+`meta.workspace` declares the Run-level workspace policy:
+```js
+workspace: {
+  default: 'isolated_worktree',
+  allowed: ['isolated_worktree', 'new_branch', 'current_branch'],
+  mutatesRepository: true,
+  reason: 'Review agents may prepare fixes',
+}
+```
+
+Taskflow owns the lifecycle of Run workspaces. Select one at launch with `--workspace worktree|branch|current`; do not create or remove those worktrees manually. Use `agent(..., { worktree: true })` only for child agents that need isolated parallel writes. Taskflow grants each such execution a fork lease and releases the lease after the agent finishes, preserving changed branches for inspection.
+
+## Resume
+
+Every durable Taskflow Run has a run ID. `portta flow runs resume <run-id>` resumes an interrupted Run from its frozen workflow snapshot and original input. Completed agent calls replay from the durable journal while incomplete or failed calls run again. Stable `opts.key` values keep independently meaningful calls associated with their cached results across safe edits and reorderings.
+
+For a standalone workflow run, re-run the same file with `portta flow workflows run <file> --resume <run-id>` — the longest unchanged prefix of agent calls returns cached results instantly; the first edited/new call and everything after it runs live. Same file + same args gives a full cache hit. `Date.now()`/`Math.random()`/`new Date()` are unavailable in scripts because they would break this — use `now()`/`random()`, or pass timestamps via `args`.
+
+## CLI commands
+
+Durable Taskflow Runs:
+```
+portta flow workflows list
+portta flow run workflow <workflow-id> [--input <text> | --input-json <json>]
+                                           [--profile <name>]
+                                           [--workspace worktree|branch|current]
+                                           [--branch <name>] [--base <branch>]
+portta flow runs list
+portta flow runs show <run-id>
+portta flow runs cancel <run-id>
+portta flow runs resume <run-id>
+portta flow runs transcript <execution-id>
+```
+
+Authoring and standalone validation/execution:
+```
+portta flow workflows run <file.workflow.js | name> [--args '<json>' | --args-file <f>]
+                                       [--provider codex|claude-code|opencode|pi --model m] [--effort e]
+                                       [--sandbox read-only|workspace-write|danger-full-access] [--cwd dir]
+                                       [--concurrency N] [--budget N] [--resume <runId>] [--fake] [--json] [--open]
+portta flow workflows save <file.workflow.js> [--project] [--force]
+portta flow workflows validate <file.workflow.js | name>
+portta flow workflows doctor
+portta flow workflows guide
+portta flow workflows install-skill [--claude] [--agents|--codex]
+```
+
+Use `portta flow workflows validate <file>` before adding or changing a catalog workflow. `--fake` runs with a fake worker for a fast smoke test; `--json` prints `{runId, status, url, result, error}`. A standalone `run` auto-starts its live viewer and prints the URL; `--open` also opens it in a browser.
+
+## Saved / named workflows
+
+Workflow IDs come from **`meta.name`**, not the filename. The durable Taskflow catalog resolves across three tiers, highest precedence first: **project** (`<project>/.portta/workflows/`), **global** (`~/.portta/state/host/workflows/`), and package **built-ins**. Place new workflows in Taskflow directories.
+
+Six built-ins ship with Taskflow. Two are ports of Claude Code's bundled workflows:
+- **`deep-research`** — scope → 5 parallel web searches → fetch/dedup top sources → 3-vote adversarial verification per claim → cited report.
+- **`code-review`** — one finder per review angle, an independent verifier per finding, a gap-sweep at high levels, ranked report.
+
+The other four are multi-provider workflows — designs where two models' decorrelated errors are the point:
+- **`multi-provider-review`** — Codex and Claude independently review the same target, then a synthesis agent merges consensus, unique catches, and disagreements.
+- **`bake-off`** — both providers implement the same task in isolated workspaces, blind judges score the diffs, and a tie-break settles splits.
+- **`provider-debate`** — one provider proposes, the other attacks, N rounds of rebuttal, then a judge rules.
+- **`second-opinion`** — both providers answer cheaply; disagreement triggers deeper passes and adjudication.
+
+## Running a workflow for a user (from an agent)
+
+When you (an agent such as Claude Code or Codex) create or run a workflow on a user's behalf:
+
+- Put reusable project workflows in `.portta/workflows/`, validate them, and confirm they appear in `portta flow workflows list` before starting a durable Run.
+- Prefer `portta flow run workflow <workflow-id>` for work the user should observe, cancel, inspect, or resume in Taskflow. Return the Run ID immediately and tell the user it is visible in the Taskflow dashboard; then inspect the final Run/result when it completes.
+- Use `portta flow workflows run <file> --fake --no-serve` for a cheap authoring smoke test. Use a real standalone run only when the user explicitly wants the standalone viewer or CLI-only execution.
+- For a real standalone run, background it in Claude Code or block on it in Codex unless the user specifies otherwise. Surface the printed viewer URL immediately so the user can watch live progress, then report the result when the workflow completes.
+
+## Installation
+
+Install this repository's skill with:
+```
+npx skills add <owner/repo> --skill taskflow-workflows
+```
+
+The Skills CLI can install it for Claude Code, Codex, OpenCode, Pi, and other supported agents. `portta flow workflows install-skill` remains available as a compatibility installer for Claude Code and the generic/Codex skill directory.

package/dist/assets/workflows/bake-off.workflow.js

@@ -0,0 +1,171 @@
+// Taskflow bake-off: both providers implement the same task in isolated fork leases, then
+// blind judges from both providers score the two diffs (neutral A/B labels, shuffled per run, so
+// neither judge knows whose work is whose), a tie-break settles splits, and the closing report
+// says what to graft from the loser. Both worktree branches are preserved for the user.
+// Run with: portta flow workflows run bake-off --args '"<task>"'   (or --args '{"task": "..."}')
+
+export const meta = {
+  name: "bake-off",
+  description:
+    "Implementation bake-off — Codex and Claude each build the same task in isolated worktrees, blind cross-provider judges score the diffs, tie-break on splits, report with graft suggestions.",
+  defaultSandbox: "read-only",
+  workspace: {
+    default: "current_branch",
+    allowed: ["isolated_worktree", "new_branch", "current_branch"],
+    mutatesRepository: true,
+    reason: "The checkout is only the stable base; Taskflow creates one isolated child worktree for each contender.",
+  },
+  phases: [
+    { title: "Implement", detail: "each provider builds the task in its own git worktree" },
+    { title: "Judge", detail: "blind A/B scoring by one judge per provider; tie-break on splits" },
+    { title: "Report", detail: "verdict, preserved branches, what to graft from the loser" },
+  ],
+}
+
+const CONTENDERS = [
+  { provider: "codex", model: "gpt-5.5", name: "Codex" },
+  { provider: "claude-code", model: "claude-fable-5", name: "Claude" },
+]
+
+const task =
+  typeof args === "string" && args.trim()
+    ? args.trim()
+    : args && typeof args === "object" && typeof args.task === "string" && args.task.trim()
+      ? args.task.trim()
+      : null
+if (!task) throw new Error(`bake-off needs a task — pass --args '"<task>"' or --args '{"task": "..."}'`)
+
+// Neutral, unique-per-run branch names (now() is resume-stable) with a shuffled provider→slot
+// mapping, so the judges' A/B labels carry no provider hint. Best-effort blinding: the diff
+// itself can still hint at a model's style, so judges are told to score only the code.
+const stamp = now().toString(36)
+const shuffled = random() < 0.5 ? [CONTENDERS[1], CONTENDERS[0]] : [...CONTENDERS]
+const slots = shuffled.map((c, i) => ({
+  ...c,
+  slot: i === 0 ? "A" : "B",
+  branch: `bake-off/${stamp}-${i === 0 ? "a" : "b"}`,
+}))
+
+const IMPL_SCHEMA = {
+  type: "object",
+  required: ["approach", "tested"],
+  properties: { approach: { type: "string" }, tested: { type: "string" } },
+}
+
+const JUDGE_SCHEMA = {
+  type: "object",
+  required: ["winner", "scoreA", "scoreB", "reasoning"],
+  properties: {
+    winner: { type: "string", enum: ["A", "B", "tie"] },
+    scoreA: { type: "number" },
+    scoreB: { type: "number" },
+    reasoning: { type: "string" },
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Implement — same prompt, separate worktrees. Committing is mandatory: the
+// judges read each entry as `git diff HEAD...<branch>`, so uncommitted work
+// is invisible to them (and an untouched worktree is auto-removed).
+// ---------------------------------------------------------------------------
+phase("Implement")
+log(`bake-off: ${task}`)
+
+const built = (
+  await parallel(
+    slots.map((s) => () =>
+      agent(
+        `Implement the following task in this repository, completely:\n\n${task}\n\n` +
+          `Match the existing code style and conventions. Run the project's relevant tests or build ` +
+          `if available and make them pass. COMMIT all of your work to the current branch with clear ` +
+          `messages — uncommitted changes will not be judged. Do not push.\n\n` +
+          `When done, summarize your approach and exactly what you verified (tests run, manual checks).`,
+        { provider: s.provider, model: s.model, label: `implement: ${s.name}`, phase: "Implement", worktree: s.branch, schema: IMPL_SCHEMA },
+      ).then((r) => ({ ...s, approach: r.approach, tested: r.tested })),
+    ),
+  )
+).filter(Boolean)
+
+if (built.length === 0) throw new Error("both implementations failed — nothing to judge")
+
+// ---------------------------------------------------------------------------
+// Judge — one judge per provider scores both diffs blind. Agreement on a
+// non-tie winner decides it; a split or all-tie goes to a tie-break judge
+// who also sees the first judges' reasoning.
+// ---------------------------------------------------------------------------
+let verdicts = []
+let winnerSlot = null
+
+if (built.length === 1) {
+  winnerSlot = built[0].slot
+  log(`only ${built[0].name} finished — wins by default`)
+} else {
+  phase("Judge")
+  const [a, b] = built[0].slot === "A" ? built : [built[1], built[0]]
+  const judgePrompt =
+    `Two competing implementations of the same task exist as branches in this repository.\n\n` +
+    `Task:\n${task}\n\n` +
+    `Implementation A: branch ${a.branch}\nImplementation B: branch ${b.branch}\n\n` +
+    `Review each with \`git diff HEAD...<branch>\` and read enough surrounding code to judge it in ` +
+    `context. Judge ONLY the code — ignore commit authorship, message style, and anything else ` +
+    `that hints at who wrote it. Score each implementation 0-10 weighing correctness, ` +
+    `completeness against the task, code quality, and test coverage, then pick a winner — "tie" ` +
+    `only when they are genuinely inseparable. Be specific about what decided it.`
+
+  verdicts = (
+    await parallel(
+      CONTENDERS.map((j) => () =>
+        agent(judgePrompt, { provider: j.provider, model: j.model, label: `judge: ${j.name}`, phase: "Judge", schema: JUDGE_SCHEMA }).then(
+          (v) => ({ judge: j.name, ...v }),
+        ),
+      ),
+    )
+  ).filter(Boolean)
+
+  const calls = verdicts.map((v) => v.winner).filter((w) => w !== "tie")
+  if (verdicts.length > 0 && calls.length > 0 && new Set(calls).size === 1) {
+    winnerSlot = calls[0]
+  } else if (verdicts.length === 0) {
+    log("both judges failed — reporting without a verdict")
+  } else {
+    log(`judges split (${verdicts.map((v) => `${v.judge}: ${v.winner}`).join(", ")}) — tie-break`)
+    const tiebreak = await agent(
+      `${judgePrompt}\n\nTwo judges already scored these and could not agree:\n` +
+        `${JSON.stringify(verdicts.map((v) => ({ winner: v.winner, scoreA: v.scoreA, scoreB: v.scoreB, reasoning: v.reasoning })), null, 2)}\n\n` +
+        `You are the tie-break. Weigh their reasoning against the actual diffs and make the final ` +
+        `call — "tie" only as a last resort.`,
+      { label: "tie-break", phase: "Judge", effort: "xhigh", schema: JUDGE_SCHEMA },
+    )
+    verdicts.push({ judge: "tie-break", ...tiebreak })
+    winnerSlot = tiebreak.winner === "tie" ? null : tiebreak.winner
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Report — the A/B mapping is revealed only here, after all judging is done.
+// ---------------------------------------------------------------------------
+phase("Report")
+
+const winner = winnerSlot ? built.find((c) => c.slot === winnerSlot) : null
+log(winner ? `winner: ${winner.name} (${winner.branch})` : "verdict: tie")
+
+const report = await agent(
+  `Write the closing report for an implementation bake-off.\n\n` +
+    `Task:\n${task}\n\n` +
+    `Contenders (the judges saw only the A/B labels):\n` +
+    `${JSON.stringify(built.map((c) => ({ slot: c.slot, provider: c.name, branch: c.branch, approach: c.approach, tested: c.tested })), null, 2)}\n\n` +
+    `Judge verdicts:\n${JSON.stringify(verdicts, null, 2)}\n\n` +
+    `Verdict: ${winner ? `${winner.name} (slot ${winner.slot}) won` : "tie / no verdict"}.\n\n` +
+    `Cover: the verdict and the decisive reasons; concrete strengths of the winner; anything in the ` +
+    `other implementation worth grafting — read its diff (git diff HEAD...<branch>) and name ` +
+    `specific files or ideas; and exact next steps (git commands to inspect each branch, merge the ` +
+    `winner, cherry-pick grafts). Both worktree branches are preserved.`,
+  { label: "report", phase: "Report" },
+)
+
+return {
+  winner: winner ? winner.name : "tie",
+  branches: Object.fromEntries(built.map((c) => [c.name, c.branch])),
+  judges: verdicts,
+  report,
+}

package/dist/assets/workflows/code-review.workflow.js

@@ -0,0 +1,179 @@
+// Port of Claude Code's built-in `code-review` workflow: one finder agent per review angle, an
+// independent verifier per candidate finding (CONFIRMED / PLAUSIBLE / REFUTED), a gap-sweep at
+// the higher levels, then a ranked, capped report.
+// Run with: portta flow workflows run code-review [--args '{"target": "<ref|path|diff>", "level": "high|xhigh|max"}']
+
+export const meta = {
+  name: "code-review",
+  description:
+    "Multi-agent code review — one finder per angle, independent verification of every finding, gap-sweep at higher levels, ranked report.",
+  defaultSandbox: "read-only",
+  workspace: {
+    default: "current_branch",
+    allowed: ["isolated_worktree", "new_branch", "current_branch"],
+    mutatesRepository: false,
+    reason: "Review should inspect the active branch and its uncommitted changes without modifying them.",
+  },
+  phases: [
+    { title: "Review", detail: "one finder agent per review angle" },
+    { title: "Verify", detail: "independent verifier per candidate finding" },
+    { title: "Sweep", detail: "hunt for what the angle reviewers missed (xhigh/max)" },
+    { title: "Report", detail: "rank, cap, and write up the confirmed findings" },
+  ],
+}
+
+// Review angles in priority order; each level takes a prefix and scales the caps.
+const ANGLES = [
+  "correctness — logic errors, wrong conditions, off-by-ones, broken control flow",
+  "security — injection, traversal, unsafe deserialization, secrets, authz gaps",
+  "error-handling — swallowed errors, missing edge/null cases, bad failure modes",
+  "resource-handling — leaks, missing cleanup, unbounded growth, races on shutdown",
+  "concurrency — data races, missing awaits, ordering assumptions, deadlocks",
+  "api-contracts — breaking changes, type mismatches, violated invariants between modules",
+  "performance — accidental O(n²), needless I/O in loops, oversized payloads",
+  "test-gaps — changed behavior with no covering test, tests asserting the wrong thing",
+]
+
+const LEVEL_PARAMS = {
+  high: { angles: 4, maxPerAngle: 8, maxReport: 10, gapSweep: false },
+  xhigh: { angles: 6, maxPerAngle: 10, maxReport: 20, gapSweep: true },
+  max: { angles: 8, maxPerAngle: 12, maxReport: 30, gapSweep: true },
+}
+
+const level = args && typeof args === "object" && typeof args.level === "string" ? args.level : "high"
+const params = LEVEL_PARAMS[level]
+if (!params) throw new Error(`unknown level "${level}" — expected one of: ${Object.keys(LEVEL_PARAMS).join(", ")}`)
+
+const target =
+  args && typeof args === "object" && typeof args.target === "string" && args.target.trim()
+    ? args.target.trim()
+    : "the uncommitted changes in this repository (git diff HEAD; if empty, review the most recent commit)"
+
+const angles = ANGLES.slice(0, params.angles)
+
+const FINDING_SCHEMA = {
+  type: "object",
+  required: ["findings"],
+  properties: {
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["file", "title", "why", "severity"],
+        properties: {
+          file: { type: "string" },
+          line: { type: "number" },
+          title: { type: "string" },
+          why: { type: "string" },
+          severity: { type: "string", enum: ["critical", "high", "medium", "low"] },
+        },
+      },
+    },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: "object",
+  required: ["verdict", "reason"],
+  properties: {
+    verdict: { type: "string", enum: ["CONFIRMED", "PLAUSIBLE", "REFUTED"] },
+    reason: { type: "string" },
+  },
+}
+
+// Each candidate gets an independent verifier; CONFIRMED/PLAUSIBLE survive, REFUTED dies.
+const verify = (finding) =>
+  agent(
+    `You are a skeptical senior reviewer double-checking one flagged issue in ${target}. ` +
+      `Read the actual code before judging. Verdicts:\n` +
+      `- CONFIRMED: you reproduced the reasoning against the real code and the issue is real.\n` +
+      `- PLAUSIBLE: you could not refute it, but could not fully confirm it from the code either.\n` +
+      `- REFUTED: false positive — mis-read code, already handled, intended behavior, or not present.\n` +
+      `Default toward REFUTED when the finding is vague or you cannot locate the code it describes.\n\n` +
+      `Finding (JSON):\n${JSON.stringify(finding, null, 2)}`,
+    { label: `verify: ${finding.title.slice(0, 40)}`, phase: "Verify", schema: VERDICT_SCHEMA },
+  ).then((v) => (v.verdict === "REFUTED" ? null : { ...finding, verdict: v.verdict, verdictReason: v.reason }))
+
+// ---------------------------------------------------------------------------
+// Review + Verify — pipeline: each angle's findings go to verification as soon
+// as that finder returns, while slower finders are still reading.
+// ---------------------------------------------------------------------------
+phase("Review")
+log(`reviewing ${target} at level ${level}: ${angles.length} angles`)
+
+const verifiedByAngle = await pipeline(
+  angles,
+  (angle) =>
+    agent(
+      `Review ${target} strictly through this lens:\n${angle}\n\n` +
+        `Read the relevant code (and surrounding context) rather than judging from the diff text ` +
+        `alone. Report up to ${params.maxPerAngle} concrete findings: file, line when you can ` +
+        `pinpoint it, a short title, why it is a real problem through this lens, and a severity ` +
+        `(critical|high|medium|low). Only report issues you can point to in the code — no ` +
+        `speculation, no style nits.`,
+      { label: `find: ${angle.split(" — ")[0]}`, phase: "Review", schema: FINDING_SCHEMA },
+    ),
+  (review, angle) =>
+    parallel(
+      (review.findings || [])
+        .slice(0, params.maxPerAngle)
+        .map((f) => () => verify({ ...f, angle: angle.split(" — ")[0] })),
+    ),
+)
+
+let confirmed = verifiedByAngle.filter(Boolean).flat().filter(Boolean)
+log(`${confirmed.length} findings survived verification`)
+
+// ---------------------------------------------------------------------------
+// Sweep (xhigh/max) — one agent hunts for what the per-angle reviewers missed;
+// its candidates go through the same verifier.
+// ---------------------------------------------------------------------------
+if (params.gapSweep) {
+  phase("Sweep")
+  const sweep = await agent(
+    `You are the final gap-sweep on a multi-agent review of ${target}. The angles already ` +
+      `covered: ${angles.map((a) => a.split(" — ")[0]).join(", ")}. Findings already confirmed ` +
+      `(do NOT re-report these):\n${JSON.stringify(confirmed.map((f) => ({ file: f.file, title: f.title })), null, 2)}\n\n` +
+      `Look for what they missed: cross-cutting issues, interactions between changes, anything in ` +
+      `the changed code that no single angle would catch. Up to ${params.maxPerAngle} findings, ` +
+      `same bar: concrete, code-anchored, no nits.`,
+    { label: "gap-sweep", phase: "Sweep", schema: FINDING_SCHEMA },
+  )
+  const sweepVerified = await parallel(
+    (sweep.findings || []).slice(0, params.maxPerAngle).map((f) => () => verify({ ...f, angle: "gap-sweep" })),
+  )
+  confirmed = confirmed.concat(sweepVerified.filter(Boolean))
+  log(`${confirmed.length} findings after gap-sweep`)
+}
+
+// ---------------------------------------------------------------------------
+// Report — rank (CONFIRMED before PLAUSIBLE, then severity), cap, write up.
+// ---------------------------------------------------------------------------
+phase("Report")
+
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 }
+const ranked = confirmed
+  .slice()
+  .sort(
+    (a, b) =>
+      (a.verdict === b.verdict ? 0 : a.verdict === "CONFIRMED" ? -1 : 1) ||
+      SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+      a.file.localeCompare(b.file),
+  )
+const findings = ranked.slice(0, params.maxReport)
+if (ranked.length > findings.length) log(`reporting top ${params.maxReport} of ${ranked.length} findings (cap)`)
+
+if (findings.length === 0) {
+  return { findings: [], report: `Reviewed ${target} across ${angles.length} angles at level ${level}: no findings survived independent verification.` }
+}
+
+const report = await agent(
+  `Write a concise code-review report for ${target}. The findings below are already independently ` +
+    `verified and ranked — keep that order. For each: severity, verdict (CONFIRMED/PLAUSIBLE), ` +
+    `file:line, what is wrong, and a suggested fix direction in a sentence. Open with a 2-3 ` +
+    `sentence summary of the overall state of the change.\n\n` +
+    `Findings (JSON):\n${JSON.stringify(findings, null, 2)}`,
+  { label: "write report", phase: "Report" },
+)
+
+return { findings, report }