feat: support reasoning effort level ~effort=<level> on review agents

PRD.md

@@ -63,7 +63,7 @@ Aligned with [GOALS.md](./GOALS.md)'s Core Goals:
 |---|---|---|---|
 | FR-11 | The system MUST persist user-set defaults (e.g. `review-with`, `merge`, `autoUpdate`) to a per-environment config file and make them available to commands without the flag being re-specified each time. | Must | Setting `review-with` once via `/do:config` causes `/do:pr` to use it on a later run with no flag passed. |
 | FR-12 | Saved config MUST survive a filtered (single-command) uninstall — only a full uninstall or explicit reset clears it. | Must | Uninstalling just `push` leaves `.slashdo-config.json` intact. |
-| FR-13 | Config values MUST round-trip complex reviewer syntax verbatim (bracket groups, `~opt`, `~max=<n>`, `@login[bot]`). | Should | A saved `review-with` value with brackets and `~max=3` reads back identical to what was written. |
+| FR-13 | Config values MUST round-trip complex reviewer syntax verbatim (bracket groups, `~opt`, `~max=<n>`, `~effort=<level>`, `@login[bot]`). | Should | A saved `review-with` value with brackets, `~max=3`, and `~effort=max` reads back identical to what was written. |
 
 ### Self-Update
 

README.md

@@ -56,8 +56,35 @@ That's it. slashdo detects your installed AI coding environments and installs co
 
 ## Workflows
 
+> **Note on Command Syntax:** In the examples below, Claude Code syntax (`/do:<command>`) is shown. Syntax varies slightly by AI assistant:
+> - **Claude Code**: `/do:*` (e.g. `/do:plan-task`, `/do:next`, `/do:pr`)
+> - **Codex**: `$do-*` (e.g. `$do-plan-task`, `$do-next`, `$do-pr`)
+> - **Antigravity CLI (`agy`/`gemini`), OpenCode, Grok Build**: `/do-*` (e.g. `/do-plan-task`, `/do-next`, `/do-pr`)
+
 Real end-to-end examples of how the commands compose. Every flag shown here is optional — the bare command always works.
 
+### Typical Developer Loop: Plan → Implement → Custom Review PR
+
+A complete end-to-end workflow from idea to reviewed, merged PR:
+
+1. **Plan & file a decision-complete task:**
+   ```
+   /do:plan-task add a --json flag to the export command
+   ```
+   *Investigates the codebase, drafts a comprehensive issue with acceptance criteria, and files it in your tracker.*
+
+2. **Claim & implement the task in isolation:**
+   ```
+   /do:next --issues #123
+   ```
+   *Claims issue `#123`, implements the solution in an isolated git worktree, verifies tests, and opens a PR.*
+
+3. **Ship with custom multi-agent code reviews:**
+   ```
+   /do:pr --review-with=ollama[qwen2.5-coder:32b]~opt,codex[gpt-5.6-luna]~effort=max~opt --merge
+   ```
+   *Runs a local fast Ollama pass (`~opt` non-blocking) followed by a maximum-effort Codex pass (`~effort=max~opt`), automatically applying fixes and merging once CI passes.*
+
 ### Ship the work in your working tree
 
 You've been coding with your assistant and want it committed, pushed, and PR'd:
@@ -239,11 +266,13 @@ Reviewers run **in the order listed**, and whatever you list is exactly what run
 
 **Optional reviewers** (`~opt` suffix): the reviewer runs and its findings get fixed, but an *inconclusive* result (timeout / skipped / no verdict) is excluded from the merge gate, so it never blocks `--merge`. A hard error from it (broken build / failed tests) still blocks. Use it for a second-opinion reviewer that doesn't reliably return a verdict, such as a local Ollama model.
 
-**Per-reviewer iteration caps** (`~max=<n>` suffix): caps how many **review → fix → re-review cycles** that one reviewer runs. It is the per-entry form of `--review-iterations`, and unlike that flag it reaches every reviewer type — including `codex`/`agy`/`claude`/`grok` and `ollama`, whose caps are otherwise fixed at 3 — so a single run can budget each reviewer differently: `--review-with claude~max=2,ollama~max=1,codex~max=3`. `<n>` is a non-negative integer; `0` means "loop until clean", bounded by a 10-iteration safety guardrail. A reviewer that stops because it spent a cap *you* set reports `capped`, which counts as clean for the merge gate — as opposed to `guardrail`, which is what a *built-in* cap reports when it cuts off a reviewer that was still finding real problems, and which blocks the merge.
+**Per-reviewer iteration caps** (`~max=<n>` suffix): caps how many **review → fix → re-review cycles** that one reviewer runs. It is the per-entry form of `--review-iterations`, and unlike that flag it reaches every reviewer type — including `codex`/`agy`/`claude`/`grok` and `ollama`, whose caps are otherwise fixed at 3 — so a single run can budget each reviewer separately: `--review-with claude~max=2,ollama~max=1,codex~max=3`. `<n>` is a non-negative integer; `0` means "loop until clean", bounded by a 10-iteration safety guardrail. A reviewer that stops because it spent a cap *you* set reports `capped`, which counts as clean for the merge gate — as opposed to `guardrail`, which is what a *built-in* cap reports when it cuts off a reviewer that was still finding real problems, and which blocks the merge.
+
+**Per-reviewer reasoning effort** (`~effort=<level>` suffix): specifies the reasoning effort level (`low`, `medium`, `high`, `xhigh`, `max`) for that reviewer: `--review-with codex[gpt-5.6-luna]~effort=max~opt`, `--review-with claude~effort=high~max=2`.
 
 `~max` applies in `series` mode (the default). In `--review-mode parallel` each reviewer runs a single review-only pass and the orchestrator applies the union once, so there are no per-reviewer cycles to cap — `~max` is ignored there with a warning.
 
-Both suffixes chain in either order and are shell-safe: `ollama[qwen2.5-coder:32b]~opt~max=1`. Neither affects reviewer identity, so `ollama~max=2` and `ollama` still dedupe to one pass. Both also ride through `/do:config` saved defaults.
+All three suffixes chain in any order and are shell-safe: `codex[gpt-5.6-luna]~effort=max~opt~max=1`. None affects reviewer identity, so `ollama~effort=high` and `ollama` still dedupe to one pass. All ride through `/do:config` saved defaults.
 
 ### Loop flags
 
@@ -385,13 +414,15 @@ Defaults are stored per host CLI (the one you run `/do:config` in) under a `defa
 
 ## Supported Environments
 
-```
-  Claude Code      ~/.claude/commands/do/             YAML frontmatter + subdirectories
-  OpenCode         ~/.config/opencode/commands/       YAML frontmatter + flat naming
-  Antigravity CLI  ~/.gemini/antigravity-cli/skills/  Agent Skills (SKILL.md) — aliases: gemini, agy
-  Codex            ~/.codex/skills/                   SKILL.md per-command directories
-  Grok Build       ~/.grok/skills/                    SKILL.md per-command directories
-```
+Each environment formats commands appropriately for its host assistant:
+
+| Assistant / Environment | Invocation Syntax | Installed Path | Format |
+|:---|:---|:---|:---|
+| **Claude Code** | `/do:<command>` (e.g. `/do:plan-task`, `/do:pr`) | `~/.claude/commands/do/` | YAML frontmatter + subdirectories |
+| **Codex** | `$do-<command>` (e.g. `$do-plan-task`, `$do-pr`) | `~/.codex/skills/` | SKILL.md per-command directories |
+| **Antigravity CLI** (`agy`/`gemini`) | `/do-<command>` (e.g. `/do-plan-task`, `/do-pr`) | `~/.gemini/antigravity-cli/skills/` | Agent Skills (SKILL.md) |
+| **OpenCode** | `/do-<command>` (e.g. `/do-plan-task`, `/do-pr`) | `~/.config/opencode/commands/` | YAML frontmatter + flat naming |
+| **Grok Build** | `/do-<command>` (e.g. `/do-plan-task`, `/do-pr`) | `~/.grok/skills/` | SKILL.md per-command directories |
 
 slashdo auto-detects which environments you have installed. Or specify manually:
 

commands/do/better-swift.md

@@ -15,7 +15,7 @@ Parse `$ARGUMENTS` for:
 - **`--interactive`**: pause at each decision point for user approval
 - **`--scan-only`**: run Phase 0 + 1 + 2 only (audit and plan), skip remediation — no worktree, no code changes, no PRs. **When `ISSUE_MODE` is also true, this is the "audit and file the work, don't touch my code" combination**: every surviving finding is filed as a labelled tracker issue before the run exits, not just the deferred subset (see the Phase 2 gate). `--scan-only` is the flag that stops the pipeline; `--issues` only chooses where findings are recorded
 - **`--no-merge`**: run through PR creation (Phase 5), skip the review loop and merge
-- **`--review-with <agent[,agent,...]>`**: which reviewer(s) run the Phase 6 review loop on each PR. Accepted slugs: `codex`, `agy` (aliases `gemini` / `antigravity` — all run the Antigravity CLI's `agy` binary), `claude`, `grok`, `ollama` (bare `ollama` auto-selects the most capable installed coding model; `ollama[<model>]` pins a specific installed model, e.g. `ollama[qwen2.5-coder:32b]` — strip the bracket into a per-entry `OLLAMA_MODEL`; `codex`/`claude`/`agy`/`grok` likewise accept a `<agent>[<model>]` bracket — e.g. `codex[o3]`, `claude[claude-opus-4-8]`, `grok[grok-code-fast-1]` — stripped into a per-entry `REVIEW_MODEL`, empty → the reviewer's built-in default; `copilot` and `@<login>` take no model bracket), `copilot` (**legacy** — GitHub's cloud Copilot review; still supported when you name it, never selected implicitly), or an arbitrary GitHub login `@<login>` — any GitHub user or App/bot (e.g. `@octocat`, `@org-review-bot`, `@some-app[bot]`); slashdo requests its review on the PR and waits for it (GitHub only, never posts an approval itself) (comma-separated, ordered list; split on `,`, trim whitespace, normalize `gemini`/`antigravity` → `agy`, dedupe preserving first-occurrence order, with each model-taking agent's (`codex`/`claude`/`agy`/`grok`/`ollama`) `[<model>]` bracket suffix part of the dedup identity). Record as `REVIEW_AGENTS`. **There is no built-in default** — if omitted, leave `REVIEW_AGENTS` **unset for now**; the saved-defaults step below fills it from `/do:config` if a default exists, and **only if it is still unset after that** is `REVIEW_AGENTS=[]` (Phase 6 skipped, PRs left open without merging — see Phase 6). `copilot` is never added implicitly. Any slot may end in `~opt` (e.g. `ollama~opt`, `ollama[qwen2.5-coder:32b]~opt`) to mark that reviewer **optional/non-blocking** — still requested and its findings still fixed, but an inconclusive result from it (timeout/skipped/incomplete/no-verdict) never blocks the PR merge (a hard-error from it still does); strip `~opt` into a per-entry `{OPTIONAL}` flag before slug parsing, and it is **not** part of the dedup identity (`ollama~opt` == `ollama`, optional-wins on collapse). A slot may also end in `~max=<n>` (e.g. `claude~max=2`, `ollama~max=1`) to cap how many review → fix → re-review cycles **that one reviewer** runs — the per-entry form of `--review-iterations`, and the only way to move the local-agent / `ollama` caps (otherwise fixed at 3), so one run can budget each reviewer separately (`claude~max=2,ollama~max=1,codex~max=3`). `<n>` is a non-negative integer (`0` = loop until clean, bounded by each loop's 10-iteration guardrail); strip it into a per-entry `{ENTRY_MAX}` alongside `~opt` — both suffixes come off the right of the token in either order before slug parsing, and neither is part of the dedup identity (the cap comes from the first occurrence that carried a `~max`, so a bare earlier occurrence does not erase a later cap). A reviewer that stops because it reached a `~max` you set returns `capped`, which is clean-equivalent for the merge gate. See `lib/multi-reviewer-loop.md`. Abort on an unknown slug with `Unknown --review-with value: {value}. Use one of: codex, agy, claude, grok, ollama, copilot, @<login> (each optionally suffixed ~opt and/or ~max=<n>).` The reserved token `none` (case-insensitive) is **not** validated as a slug — `--review-with none` means no reviewer (set `REVIEW_AGENTS=[]`) and overrides any saved `review-with` default.
+- **`--review-with <agent[,agent,...]>`**: which reviewer(s) run the Phase 6 review loop on each PR. Accepted slugs: `codex`, `agy` (aliases `gemini` / `antigravity` — all run the Antigravity CLI's `agy` binary), `claude`, `grok`, `ollama` (bare `ollama` auto-selects the most capable installed coding model; `ollama[<model>]` pins a specific installed model, e.g. `ollama[qwen2.5-coder:32b]` — strip the bracket into a per-entry `OLLAMA_MODEL`; `codex`/`claude`/`agy`/`grok` likewise accept a `<agent>[<model>]` bracket — e.g. `codex[o3]`, `claude[claude-opus-4-8]`, `grok[grok-code-fast-1]` — stripped into a per-entry `REVIEW_MODEL`, empty → the reviewer's built-in default; `copilot` and `@<login>` take no model bracket), `copilot` (**legacy** — GitHub's cloud Copilot review; still supported when you name it, never selected implicitly), or an arbitrary GitHub login `@<login>` — any GitHub user or App/bot (e.g. `@octocat`, `@org-review-bot`, `@some-app[bot]`); slashdo requests its review on the PR and waits for it (GitHub only, never posts an approval itself) (comma-separated, ordered list; split on `,`, trim whitespace, normalize `gemini`/`antigravity` → `agy`, dedupe preserving first-occurrence order, with each model-taking agent's (`codex`/`claude`/`agy`/`grok`/`ollama`) `[<model>]` bracket suffix part of the dedup identity). Record as `REVIEW_AGENTS`. **There is no built-in default** — if omitted, leave `REVIEW_AGENTS` **unset for now**; the saved-defaults step below fills it from `/do:config` if a default exists, and **only if it is still unset after that** is `REVIEW_AGENTS=[]` (Phase 6 skipped, PRs left open without merging — see Phase 6). `copilot` is never added implicitly. Any slot may end in `~opt` (e.g. `ollama~opt`, `ollama[qwen2.5-coder:32b]~opt`) to mark that reviewer **optional/non-blocking** — still requested and its findings still fixed, but an inconclusive result from it (timeout/skipped/incomplete/no-verdict) never blocks the PR merge (a hard-error from it still does); strip `~opt` into a per-entry `{OPTIONAL}` flag before slug parsing, and it is **not** part of the dedup identity (`ollama~opt` == `ollama`, optional-wins on collapse). A slot may also end in `~max=<n>` (e.g. `claude~max=2`, `ollama~max=1`) to cap how many review → fix → re-review cycles **that one reviewer** runs, or `~effort=<level>` (e.g. `codex[gpt-5.6-luna]~effort=max~opt`, `claude~effort=high~max=2`) to specify its reasoning effort level (`low`, `medium`, `high`, `xhigh`, `max`). Strip suffixes off the right of each token in any order before slug parsing. Deduplication preserves first-occurrence order and excludes `~` suffixes (survivor takes `~opt` if any had it, and cap/effort level from the first that carried them). Reject a malformed suffix with `Invalid --review-with suffix on {entry}: ~max must be a non-negative integer and ~effort must be one of low, medium, high, xhigh, max, each appearing at most once; the only suffixes are ~opt, ~max=<n>, and ~effort=<level>.` Abort on an unknown slug with `Unknown --review-with value: {value}. Use one of: codex, agy, claude, grok, ollama, copilot, @<login> (each optionally suffixed ~opt, ~max=<n>, and/or ~effort=<level>).` The reserved token `none` (case-insensitive) is **not** validated as a slug — `--review-with none` means no reviewer (set `REVIEW_AGENTS=[]`) and overrides any saved `review-with` default.
 - **`--review-stop-on-findings`** / **`--review-stop-on-clean`** (mutually exclusive): forwarded to the multi-reviewer loop for each PR; control when a per-PR reviewer list stops early. Set `REVIEW_STOP_MODE` (`all` default, `on-findings`, or `on-clean`). If both are present, abort with `--review-stop-on-findings and --review-stop-on-clean cannot be combined`.
 - **`--review-mode <series|parallel>`**: forwarded to each PR's multi-reviewer loop. `series` (default) runs the reviewers one-at-a-time so each sees the prior's committed fixes; `parallel` runs their reviews concurrently against one baseline and applies the deduped union once (`--reviewer-applies` and the stop-modes are ignored in parallel). Set `REVIEW_MODE`; if omitted, leave it **unset for now** (saved-defaults fills it from `review-mode`; built-in default `series`). Abort with `--review-mode must be one of series, parallel (got: {value}).` on any other value.
 - **`--reviewer-applies`**: forwarded to each PR's review loop — the reviewing CLI applies fixes directly instead of the orchestrator (no effect on copilot or `@<login>` passes, which are read-only cloud-side reviews). Record `REVIEWER_APPLIES=true`/`false`.