session-orchestrator 5.12.0 → 5.13.0

package/README.md

@@ -1,186 +1,185 @@
-# Session Orchestrator
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-5.12.0-blue.svg)](CHANGELOG.md)
-[![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
-[![Release](https://img.shields.io/github/v/release/Kanevry/session-orchestrator)](https://github.com/Kanevry/session-orchestrator/releases/latest)
-
-**Give your agents a working rhythm.**
-
-Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. On their own, coding agents drift from the plan, overwrite each other's files and call work done before it is checked; Session Orchestrator closes those gaps.
-
-You type three commands:
-
-- **`/session`** reads your repository, your open issues and the last session, proposes what to work on, and waits for your correction.
-- **`/go`** runs the agreed work in waves of parallel agents. After each implementation wave your tests and typecheck run, and failures become fix tasks for the next wave. The full test, typecheck and lint gate runs before `/close` commits.
-- **`/close`** checks every planned item against what actually happened, commits, and files the rest as issues for next time.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="site/brand/a3-terminalmodule/mark-on-dark.svg">
+  <img src="site/brand/a3-terminalmodule/mark-on-light.svg" alt="Session Orchestrator logo: a person at a workbench with three terminal modules" width="64" align="left" hspace="12">
+</picture>
 
-Session Orchestrator is a free, MIT-licensed workflow plugin for **Claude Code, Codex CLI, Cursor IDE, or [Pi](docs/pi-setup.md)**. It runs on your machine and writes plain text into your repository. No account, no server, nothing to sign up for.
+# Session Orchestrator
 
-[![Session Orchestrator: Plan, Go, Close, with an illustration of an agent workshop under human direction](site/og.png)](https://session-orchestrator.com)
+**Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session.**
 
-```mermaid
-flowchart LR
-    S["/session"] --> G["/go"]
-    G --> Q{"quality gate"}
-    Q -- "fails" --> G
-    Q -- "passes" --> C["/close"]
-```
+A free, MIT-licensed workflow plugin for Claude Code, Codex CLI, Cursor IDE and Pi. It runs on your machine and writes plain text into your repository. No account, no server.
 
-Longer explanation, with examples and screenshots: **[session-orchestrator.com](https://session-orchestrator.com)** ([auf Deutsch](https://session-orchestrator.com/de)).
+**[Install](#install)** · **[Website](https://session-orchestrator.com)** ([Deutsch](https://session-orchestrator.com/de)) · **[User guide](docs/USER-GUIDE.md)** · **[Add-on for parallel sessions](#add-on-lead-session-orchestrator)** · [Changelog](CHANGELOG.md)
 
-[User guide](docs/USER-GUIDE.md) · [Install & upgrade](docs/install.md) · [Changelog](CHANGELOG.md)
+[![Tests](https://github.com/Kanevry/session-orchestrator/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/Kanevry/session-orchestrator/actions/workflows/test.yml)
+[![Version](https://img.shields.io/badge/version-5.13.0-blue.svg)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Website](https://img.shields.io/badge/website-session--orchestrator.com-blue)](https://session-orchestrator.com)
 
-## Install
+<br clear="left">
 
-You need **Node.js 24 or later**, a git repository, and one of the four agents below. Full requirements, upgrade path and uninstall: [docs/install.md](docs/install.md).
+<img src="site/img/agent-production-1536.webp" width="720" alt="Illustration: a person in an elevated control room directs small agents at separate workstations below, with a conveyor carrying finished parts to inspection and handover">
 
-In Claude Code, two lines:
+*Plan, Go, Close: one person directs, the agents work at separate stations. AI-generated illustration, not a product screenshot.*
 
-```text
-/plugin marketplace add Kanevry/session-orchestrator
-/plugin install session-orchestrator@kanevry
-```
+## Why
 
-Optional, Claude Code only: `/plugin install so-hud@kanevry` adds a status line for the running session ([mods/so-hud](mods/so-hud/README.md)).
+On their own, coding agents drift from the plan, overwrite each other's files and call work done before it is checked.
 
-| Platform | Install |
+| Without it | With it |
 |---|---|
-| **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry`, then [check its Node dependencies once](docs/install.md#claude-code-check-the-node-dependencies) (current Claude Code installs them for you). |
-| **Codex CLI** | `git clone` the repo, `npm install`, then `node scripts/codex-install.mjs` ([guide](docs/codex-setup.md)). |
-| **Cursor IDE** | `git clone` the repo, `npm install`, then `node scripts/cursor-install.mjs /path/to/your/project` ([guide](docs/cursor-setup.md)). |
-| **Pi** | `pi install npm:session-orchestrator` ([guide](docs/pi-setup.md)). |
+| You paste your working rules into every session | `/session` reads git, issues and the last session first |
+| Two agents edit the same file | Each agent gets a declared file list; overlaps are rejected |
+| "Done" before the tests ran | Tests and typecheck run after each implementation wave |
+| A crash loses the plan | `STATE.md` records each wave; the next `/session` offers to resume |
 
-After a clone-based install (Codex CLI, Cursor IDE, or contributing), run `npx husky` once: `.npmrc` sets `ignore-scripts=true` (SEC-020), which skips the `prepare` script that would otherwise activate the git hooks.
+It is built for one person running a coding agent on a git repository, possibly in several sessions at once. It runs on top of your agent and does not replace it.
 
-## Quick Start
-
-**1. Run `/bootstrap` once in your project.** It creates the minimum structure, writes `.orchestrator/bootstrap.lock` and adds a Session Config. `/session` refuses to start until the lock exists. For the shortest path, `/bootstrap --fast --no-interview` skips the tier question and the personal-preferences interview; run that interview later with `/bootstrap --owner-reset`.
+## How it works
 
-**2. Check the Session Config** that `/bootstrap` wrote into your project's instruction file — `CLAUDE.md` on Claude Code and Cursor, `AGENTS.md` on Codex CLI and Pi ([which file each platform reads](skills/_shared/instruction-file-resolution.md)). Add it by hand only if the block is missing. These seven fields are enough:
+You type three commands:
 
-```yaml
-## Session Config
+- **`/session`** reads your repository, your open issues and the last session, proposes what to work on, and waits for your correction. Nothing changes in your code until you agree.
+- **`/go`** runs the agreed work in waves of parallel agents, each with its own list of files. After each implementation wave your tests and typecheck run, and failures become fix tasks for the next wave.
+- **`/close`** runs the full test, typecheck and lint gate, checks every planned item against what happened, commits, and files the rest as GitLab or GitHub issues for next time.
 
-test-command: npm test
-typecheck-command: npm run typecheck
-lint-command: npm run lint
-agents-per-wave: 6
-waves: 5
-persistence: true
-enforcement: warn
+```mermaid
+flowchart LR
+    B["/bootstrap<br/>once per repo"] --> S["/session<br/>reads repo, proposes scope"]
+    S --> A{"you agree?"}
+    A -- no --> S
+    A -- yes --> W1["wave 1"] --> Q1["tests + typecheck"] --> W2["wave 2 ..."]
+    W2 --> F["full gate<br/>test, typecheck, lint"]
+    F --> C["/close<br/>verify, commit, file the rest as issues"]
+    C -.->|"next session resumes from STATE.md"| S
 ```
 
-The first three are the commands the quality gate runs: tests and typecheck after each implementation wave, all three after the Quality wave and before `/close` commits — use whatever your project actually uses. Everything else is opt-in: [full template](docs/session-config-template.md) · [every key, its type and default](docs/session-config-reference.md).
+The session type sets the number of waves: housekeeping 1, feature 3, deep 5, the ultradeep profile 7.
+
+<details>
+<summary>What it writes into your repository</summary>
 
-**3. Run the loop.**
+All of it plain text, all of it local:
 
 ```text
-/session feature    # read the repo, propose scope, wait for your correction
-/go                 # execute in waves, check between each
-/close              # verify, commit, file the rest as issues
+.orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
+.orchestrator/current-session.json  # which session owns this working copy right now
+.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
+.orchestrator/host.json             # host-local identity for peer-session detection
+.orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
+.orchestrator/steering/             # stable product/tech/structure context injected each session
+.claude/STATE.md                    # wave progress and deviations (harness-specific directory)
 ```
 
-On Codex the same three are `$session-orchestrator:session feature`, `$session-orchestrator:go`, `$session-orchestrator:close` ([Codex usage](docs/codex-setup.md#usage)). `/plan` and `/evolve` extend the loop; you can start with just these three.
+</details>
 
-In headless Claude Code (`claude -p`), `/session` and `/plan` are reserved terminal-only built-in names and the bare form is refused; use `/session-orchestrator:session` and `/session-orchestrator:plan` there. Every other command keeps its bare form.
+## Install
 
-## What you get
+You need Node.js 24 or later, a git repository and one of Claude Code, Codex CLI, Cursor IDE or Pi. In Claude Code:
 
-Each item: what it does for you, then how it works.
+```text
+/plugin marketplace add Kanevry/session-orchestrator
+/plugin install session-orchestrator@kanevry
+```
 
-| You get | How |
+| Platform | Install |
 |---|---|
-| **Know what to work on.** Every session starts from the real state of your project, not from a prompt you rewrite. | `/session` reads git, open issues, recent commits and the last session record, recommends one scope and waits for your correction. `/plan`, `/brainstorm` and `/grill` help while an idea is still vague. |
-| **Errors stop at the next check.** A broken test is found right after the work that caused it, not after more work is built on top. | `/go` checks each wave with your tests and typecheck and turns failures into fix tasks; lint and the full suite run before the commit. `/close` checks every planned item against what happened. `/debug` looks for the root cause before a fix. |
-| **Agents keep to their files.** Parallel agents do not overwrite each other, and destructive commands do not slip through. | Each agent gets a declared list of files it may change; overlapping lists are rejected before dispatch. A guard blocks 12 destructive command patterns (hard reset, `rm -rf`, force-push, `DROP TABLE`, …) and warns on 4. Hooks on Claude Code, bridges on Cursor and Pi, instructions only on Codex. |
-| **Pick up where you stopped.** A crash or a second session in the same folder does not cost you the work. | `STATE.md` (a progress file in your repo) records each finished wave, and the next `/session` offers to resume. A session lock with a heartbeat keeps two sessions apart in one checkout. `/close` files what is left as GitLab or GitHub issues. |
-| **It improves with your sessions.** Patterns from your own work become rules, once you approve them. | Every session appends a record. `/evolve` proposes learnings with a confidence score, `/reconcile` drafts rules from them; you approve or delete each one. Optional mirror into a Markdown notes vault. |
-| **Audit, test and review on demand.** Find problems you did not ask about, and show the app works. | A discovery scan at `/close` turns confirmed findings into issues. `/test` drives web and macOS flows end to end, `/ux-grill` audits a running web app, `/test-audit` removes tests that catch nothing. `/repo-audit` and `/harness-audit` score a repository against a checklist, and `/persona-panel` has several reviewer personas read the same output in parallel. |
-| **Longer runs, more repositories.** | `/autopilot` chains sessions and stops on any of 10 kill-switches. `/dispatcher` recommends the next free repository and claims it once you confirm, and `/portfolio` summarises issues, MRs and CI across the repositories registered in your notes vault. |
+| **Claude Code** | The two commands above. Current Claude Code installs the Node dependencies with the plugin; on older versions [check them once](docs/install.md#claude-code-check-the-node-dependencies). |
+| **Codex CLI** | `git clone` this repository, `npm install`, then `node scripts/codex-install.mjs` ([guide](docs/codex-setup.md)). |
+| **Cursor IDE** | `git clone` this repository, `npm install`, then `node scripts/cursor-install.mjs /path/to/your/project` ([guide](docs/cursor-setup.md)). |
+| **Pi** | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`, then `pi install npm:session-orchestrator` ([guide](docs/pi-setup.md)). |
 
-## How it works
+Optional extras, upgrade and uninstall: [docs/install.md](docs/install.md). On Claude Code, `/plugin install so-hud@kanevry` adds a status line and gates that refuse secret-printing commands and ask before pushes to `main`, merges, releases, publishes and deploys ([so-hud](mods/so-hud/README.md)).
 
-When you type `/session feature`:
+## First session
 
-1. **It reads the project.** Git state, open issues, recent commits, documentation, host resources and the records of previous sessions become a Session Overview with one recommendation.
-2. **You correct the scope.** Nothing is implemented until you agree to the plan.
-3. **The work is split into waves.** The session type decides how many: housekeeping 1, feature 3, deep 5, the ultradeep profile 7. Each wave gets a purpose, a list of file paths it may write to, and a result that can be checked.
-4. **`/go` runs it.** Agents whose file scopes do not overlap run at the same time on Claude Code and Codex; Cursor and Pi run them one after another. After each implementation wave your tests and typecheck run, and failures become fix tasks for the next wave. The full test, typecheck and lint gate runs after the Quality wave.
-5. **`/close` checks and records.** It compares the plan against what happened, runs the full quality gate, commits file by file, and opens issues for whatever was not finished.
+1. **Run `/bootstrap --fast --no-interview` once in your project.** It writes `.orchestrator/bootstrap.lock` and a Session Config into your instruction file (`CLAUDE.md` on Claude Code and Cursor, `AGENTS.md` on Codex CLI and Pi).
+2. **Set the three gate commands** in that Session Config to what your project actually uses:
 
-**What it writes into your repository**, and nothing else — all of it plain text, all of it local:
+   ```yaml
+   test-command: npm test
+   typecheck-command: npm run typecheck
+   lint-command: npm run lint
+   ```
 
-```text
-.orchestrator/bootstrap.lock        # written by /bootstrap, the gate for every later run
-.orchestrator/current-session.json  # which session owns this working copy right now
-.orchestrator/session.lock          # heartbeat lock; stops two sessions colliding in one checkout
-.orchestrator/host.json             # host-local identity for peer-session detection
-.orchestrator/metrics/*.jsonl       # append-only session, learning, event and subagent records
-.orchestrator/steering/             # stable product/tech/structure context injected each session
-.claude/STATE.md                    # wave progress and deviations (harness-specific directory)
-```
+   Every other key is optional: [template](docs/session-config-template.md) · [reference](docs/session-config-reference.md).
+3. **Run `/session feature`** and describe the task. The agent reads the repository and presents a scope. Correct it, then run **`/go`** and, when the work is done, **`/close`**.
 
-The plugin is **51 skills, 30 slash commands, 14 typed subagents and 29 hook files across 10 event types**. A slash command is a skill whose frontmatter says `user-invocable: true` (28 of them) or one of the two remaining `commands/*.md` files (`/session`, `/templates-ack`) — one definition per name, so nothing is listed twice in the `/` picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
+On Codex the commands are `$session-orchestrator:bootstrap`, `$session-orchestrator:session feature`, `$session-orchestrator:go` and `$session-orchestrator:close` ([Codex usage](docs/codex-setup.md#usage)). In headless Claude Code (`claude -p`), use `/session-orchestrator:session` and `/session-orchestrator:plan`; the bare names are reserved there.
 
-## Why it is built this way
+## What you get
 
-- **The wave order is deliberate.** Discovery runs first so every implementer starts from the same picture of the code. Impl-Core runs before Impl-Polish so the structure exists before anything integrates against it. The Quality wave simplifies generated code *before* tests are written — write the tests first and they assert whatever the model produced, so changing it later means rewriting the tests too.
-- **Checks run after each implementation wave, not only at the end.** A mistake caught after wave 2 costs one wave. The same mistake found at `/close` has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.
-- **A crash does not lose the session.** `STATE.md` records which wave finished and what deviated from the plan. The next `/session` offers to continue from the last completed wave.
-- **Two sessions in one working copy is treated as a real risk.** Two people, or two of your own sessions, in the same checkout share one git index, one filesystem and one `STATE.md`, and neither can see the other's uncommitted work. A heartbeat session lock, per-agent file-scope manifests, and the PSA rules in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that case.
-- **Guards run where the harness supports them, and the table below says where it does not.** A destructive-command policy — 12 rules block, 4 warn — and file-scope enforcement run as real hooks on Claude Code, as bridges on Cursor and Pi, and as instructions only on Codex. Details: [`docs/components.md`](docs/components.md#other-surfaces).
-- **What it learns is opt-in and readable.** Every session appends a record. After 5 or more sessions, `/evolve analyze` proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.
-- **GitLab and GitHub, both fully.** It detects which one your remote points at and drives issues and merge/pull requests for either.
+- **Know what to work on.** `/session` starts from git, open issues, recent commits and the last session record, and recommends one scope. `/plan`, `/brainstorm` and `/grill` help while an idea is still vague.
+- **Errors stop at the next check.** Each wave is checked with your tests and typecheck; lint and the full suite run before the commit. `/debug` looks for the root cause before a fix.
+- **Agents keep to their files.** Overlapping file lists are rejected before dispatch. A guard blocks 12 destructive command patterns (hard reset, `rm -rf`, force-push, `DROP TABLE`, …) and warns on 4.
+- **Pick up where you stopped.** A crash or a second session in the same folder does not cost you the work: `STATE.md` and a heartbeat lock keep the thread.
+- **It learns from your sessions, with your approval.** `/evolve` proposes learnings with a confidence score and `/reconcile` drafts rules from them; you approve or delete each one.
+- **Audit and test on demand.** `/test` drives web and macOS flows end to end, `/ux-grill` audits a running web app, `/repo-audit` and `/harness-audit` score a repository, `/test-audit` removes tests that catch nothing.
+- **Longer runs.** `/autopilot` chains sessions and stops on any of 10 kill-switches; `/dispatcher` and `/portfolio` work across repositories.
 
-How this compares to other orchestrators, with measured results kept separate from unmeasured claims: [`docs/components.md` § Comparisons](docs/components.md#comparisons).
+Every skill, command, agent and hook: [docs/components.md](docs/components.md).
 
 ## Platform support
 
-| Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
+| | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 30 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
-| Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
-| Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
-| Scope enforcement | Active PreToolUse hook; blocking in `strict`, reporting in `warn` | Instructions only; no compatible `apply_patch` handler | `preToolUse` + `beforeShellExecution` bridge; scope blocking requires `strict`; `afterFileEdit` is post-hoc | `tool_call` bridge; scope blocking requires `strict` |
-| Destructive-command guard | Active PreToolUse hook applies policy severity | Instructions only; no handler wired | `beforeShellExecution` bridge for supported commands | `tool_call` bridge for supported commands |
-| AskUserQuestion | Native tool | Numbered-list fallback | Numbered-list fallback | Numbered-list fallback |
+| Commands | Native slash commands | Skills (`$session-orchestrator:<name>`) | Native slash commands | Prompt templates |
+| Parallel agents | Yes | Yes | One after another | One after another |
+| Destructive-command guard | Hook | Hook | Bridge for supported commands | Bridge for supported commands |
+| File-scope guard | Hook (blocks in `strict`) | Instructions only | Bridge (blocks in `strict`) | Bridge (blocks in `strict`) |
 | Quality gates | Full | Full | Full | Full |
 
-All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads ([why](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected)). Cursor and Pi have known event-coverage limits — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
+All four share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex edits files through `apply_patch`, which the scope guard does not read ([why](docs/codex-setup.md#which-pretooluse-guards-run-on-codex--the-reason-corrected)). Event-coverage limits: [Cursor](docs/cursor-setup.md), [Pi](docs/pi-setup.md).
 
-## Recent highlights (v5.12.0)
+## Add-on: lead-session-orchestrator
 
-Highlights of the v5.12.0 line:
+Running three or four sessions side by side? Then a job shows up that no single session can do: deciding which one goes next, and answering the questions they all ask you at the same time. That is what [lead-session-orchestrator](https://www.npmjs.com/package/lead-session-orchestrator) is for. One lead session sits above your sessions, prepares the decisions and puts them into one queue for you.
 
-- **A status line inside Claude Code.** The new `so-hud` mod shows the session state and a warning band when something needs attention, and how many peer sessions are running; install it with `/plugin install so-hud@kanevry` (#1508).
-- **Mode recommendations reach the next session.** The STATE.md idle reset at session start is code now and keeps the previous session's recommendation for the mode selector (#1560).
-- **A first `/session` asks before it starts.** Without any session history of its own, a bare `/session` asks for the task and the mode instead of starting `deep` (#1561).
-- **Solo use stays quiet.** Without fleet integration there is no fleet line and no check-in file, and a repo that is not set up yet is pointed to `/bootstrap` first (#1559).
-- **Vault files are no longer left behind unnoticed.** `/close` names untracked vault files modified since the session started, and new learning-note slugs keep umlauts (#1563, #1548).
-- **One repo, one identity.** A repo reached through a symlink counts as the same repo for peer discovery and the live-status board (#1557).
+```mermaid
+flowchart LR
+    Y(["you"]) -- "answer one queue" --> L["lead session<br/>lead-session-orchestrator"]
+    L -- "constraints" --> A["session A<br/>session-orchestrator"]
+    L -- "constraints" --> B["session B<br/>session-orchestrator"]
+    A -- "check-in" --> L
+    B -- "check-in" --> L
+```
 
-Full changes and upgrade notes: [CHANGELOG.md](CHANGELOG.md).
+The split: session-orchestrator makes one session good (plan, waves, gates, handover), lead-session-orchestrator keeps several of them in line. What you get on top:
 
-## Documentation
+- **One inbox instead of a row of terminals.** Open questions from every session land in one queue; in Claude Code the Inbox mod shows it in a side pane.
+- **Written rules for what needs no asking.** A signed authority file per repository lists what is free, what needs your yes and what never happens. Anything not on the list asks you.
+- **Checks before a run and before a merge.** Busy repository, low disk or memory, a pipeline that is not green on this exact commit: the lead refuses. It also refuses when it cannot measure.
+- **A trail you can check.** Decisions and merges go into an append-only, hash-chained log.
+
+```sh
+npm i -g lead-session-orchestrator
+navigator --help
+```
+
+Each works on its own. Together they talk only through files, and a session never waits for the lead. Worth knowing before you try it: version 0.x, GitLab only for now, tested on macOS. Setup and the Inbox mod: [npm page](https://www.npmjs.com/package/lead-session-orchestrator) · [session-orchestrator.com/lead](https://session-orchestrator.com/lead).
 
-- [User guide](docs/USER-GUIDE.md) — config reference, a walkthrough of one session, troubleshooting, FAQ
-- [Install, upgrade, uninstall](docs/install.md) — requirements, per-harness setup, migration paths
-- [Components & reference](docs/components.md) — every skill, command, agent and hook; the guards; comparisons
-- [Telemetry](docs/telemetry.md) — what stays on your machine, what the optional anonymous telemetry would send, and every switch that turns it off
-- [Contributing](https://github.com/Kanevry/session-orchestrator/blob/main/CONTRIBUTING.md) · [Plugin architecture](docs/plugin-architecture-v3.md) · [docs/ router](docs/README.md)
+## Recent highlights (v5.13.0)
 
-## Running many sessions at once
+Highlights of the v5.13.0 line:
 
-session-orchestrator makes one session reliable. When several sessions run in parallel across repositories, a lead session can coordinate them: who runs next, what each may do, one queue for your decisions, one stop for everything. That is the sibling project [lead-session-orchestrator](https://session-orchestrator.com/lead) ([GitHub](https://github.com/Kanevry/lead-session-orchestrator), npm `lead-session-orchestrator`). Each works alone; together they use the shared fleet contract in `skills/_shared/fleet-protocol.md`.
+- **so-hud guards the session.** The optional mod refuses commands that would print a secret and asks before pushes to `main`, merges, releases, publishes and deploys.
+- **Every agent names its model and effort.** No agent inherits the session model any more. On Codex the agents use `gpt-6.1-sol`; change the `model` line in `.codex-plugin/agents/*.toml` if you have no access to it.
+- **Pre-push on a merge-request branch** runs a local partial gate when no remote host is free; main and tags keep the full gate.
+- **Learnings from a second host** go to a separate inbox file, so two machines no longer rewrite the same `learnings.jsonl`.
+
+Everything else: [CHANGELOG.md](CHANGELOG.md).
+
+## Documentation
 
-## Scope and support
+- [User guide](docs/USER-GUIDE.md): a walkthrough of one session, config, troubleshooting, FAQ
+- [Install, upgrade, uninstall](docs/install.md) · [Components and design choices](docs/components.md) · [Telemetry](docs/telemetry.md) (off unless you turn it on)
+- [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [All docs](docs/README.md)
 
-Provided **as-is**: a community project, best-effort maintenance, no SLA. Questions and ideas go to [Discussions](https://github.com/Kanevry/session-orchestrator/discussions), bugs to [Issues](https://github.com/Kanevry/session-orchestrator/issues).
+## Support
 
-It is **not** an official product of any agent vendor — independent and community-maintained, not affiliated with, endorsed by or sponsored by Anthropic, OpenAI, Cursor or any agent it integrates with, and distributed through the Claude Code plugin marketplace without being an Anthropic product. It does **not replace** your agent; it runs on top of one, and you still need it installed. It is built for **one operator**: the parallel-session machinery protects your own concurrent sessions, not a shared team workspace.
+Provided as-is: a community project with best-effort maintenance and no SLA. Questions, ideas and bugs go to [Issues](https://github.com/Kanevry/session-orchestrator/issues). Independent, and not affiliated with or endorsed by Anthropic, OpenAI or Cursor.
 
-The reasoning behind the method is taught at [agenticbuilders.at](https://agenticbuilders.at). The plugin is free and MIT; the courses go deeper and are not required to use it.
+The method behind it is taught at [agenticbuilders.at](https://agenticbuilders.at); the plugin is free and does not need the courses.
 
 ## License
 

package/agents/analyst.md

@@ -1,7 +1,8 @@
 ---
 name: analyst
-description: 'Use this agent for read-only PRD-quality review. Checks acceptance-criteria specificity, scope drift detection, and completeness of /plan output. <example>Context: /plan feature produced a PRD. user: "Review the PRD before /go." assistant: "I''ll dispatch analyst to check acceptance-criteria specificity and scope drift before wave execution." <commentary>Analyst catches vague acceptance criteria before they cause carryover at session end.</commentary></example>'
-model: inherit
+description: 'Use this agent for read-only PRD-quality review. Checks acceptance-criteria specificity, scope drift detection, and completeness of /plan output.'
+model: sonnet
+effort: medium
 color: yellow
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only
@@ -97,3 +98,7 @@ Verdict variants (concrete examples per scenario):
 - Vague verbs / minor specificity gaps → `{"verdict": "PROCEED_WITH_FOLLOWUPS", "scope_drift_count": 0, "finding_counts": {"high": 0, "med": 4, "low": 2}}`
 - Scope-drift detected or vague critical AC → `{"verdict": "FIX_REQUIRED", "scope_drift_count": 2, "finding_counts": {"high": 2, "med": 3, "low": 1}}`
 - PRD/criteria unreviewable → `{"verdict": "BLOCKED", "blockers": ["PRD path missing"]}`
+
+## Examples
+
+<example>Context: /plan feature produced a PRD. user: "Review the PRD before /go." assistant: "I'll dispatch analyst to check acceptance-criteria specificity and scope drift before wave execution." <commentary>Analyst catches vague acceptance criteria before they cause carryover at session end.</commentary></example>

package/agents/architect-reviewer.md

@@ -1,7 +1,8 @@
 ---
 name: architect-reviewer
-description: 'Use this agent for read-only architectural audits between waves. Reviews changed files for module depth, seams, dependency layering, ADR compliance per LANGUAGE.md vocabulary. <example>Context: After Impl-Core wave shipped 8 files. user: "Audit the W2 architecture before proceeding." assistant: "I''ll dispatch architect-reviewer to check module depth, seams, and adapter quality before W3." <commentary>Architect-reviewer catches design smells (shallow modules, speculative seams) earlier than Quality-Lite, which only catches lint/typecheck.</commentary></example>'
-model: inherit
+description: 'Use this agent for read-only architectural audits between waves. Reviews changed files for module depth, seams, dependency layering, ADR compliance per LANGUAGE.md vocabulary.'
+model: opus
+effort: medium
 color: blue
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only
@@ -91,3 +92,7 @@ Verdict variants (concrete examples per scenario):
 - Advisory findings only, no blockers → `{"verdict": "PROCEED_WITH_FOLLOWUPS", "finding_counts": {"high": 0, "med": 3, "low": 5}}`
 - ADR violation or HIGH-severity coupling/seam issue → `{"verdict": "FIX_REQUIRED", "finding_counts": {"high": 2, "med": 4, "low": 3}}`
 - Review could not complete (missing files, malformed inputs) → `{"verdict": "BLOCKED", "blockers": ["missing target file"]}`
+
+## Examples
+
+<example>Context: After Impl-Core wave shipped 8 files. user: "Audit the W2 architecture before proceeding." assistant: "I'll dispatch architect-reviewer to check module depth, seams, and adapter quality before W3." <commentary>Architect-reviewer catches design smells (shallow modules, speculative seams) earlier than Quality-Lite, which only catches lint/typecheck.</commentary></example>

package/agents/code-implementer.md

@@ -1,7 +1,8 @@
 ---
 name: code-implementer
 description: 'Use this agent for feature implementation, API development, refactoring, and general code changes. Handles backend logic, API routes, service layers, and cross-cutting concerns.'
-model: inherit
+model: opus
+effort: medium
 color: green
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
@@ -27,7 +28,7 @@ You are a focused implementation agent. You write production code, refactor exis
 5. **Run a fast feedback loop**: After substantive edits, run the project's typecheck (`tsgo --noEmit`, `tsc --noEmit`, or the configured command) to catch type errors early. Do not run the full test suite as a routine loop — that is the Quality wave's responsibility. You MAY still run the typecheck/lint command or targeted tests to gather evidence for a `Status: done` claim (Verification gate below) — the bar is on the *routine full-suite run*, not on verifying your own scope.
 6. **Self-review the diff — then hand it over anyway**: Before reporting completion, walk the diff and verify each change serves the task; delete dead branches, debug logging, and TODO stubs. Self-review is a precondition of handoff, never a substitute for review, and a green quality gate is not review either (`.claude/rules/receiving-review.md` § RCR-009). Never mark your own diff reviewed, however small it is.
 7. **Report**: Output a structured summary (see Output Format).
-- **Bite-sized plan**: If a bite-sized executable plan path is provided in your prompt (`docs/plans/<feature>.md`, see `skills/write-executable-plan/SKILL.md`), you own the **implement** and **verify-pass** steps of each Task's 5-step structure: write the production code, then run the Task's exact verification command. The **test-first** and **confirm-fail** steps belong to the test-writer and the **commit-stop** step to the coordinator — in this bite-sized structure the test is authored ahead of you, and you never run git-write operations (see Rules below), so do not attempt those three steps yourself. (Outside a bite-sized plan, a need-gated regression test for a bug you fix IS yours — see Rules.)
+- **Bite-sized plan**: If a bite-sized executable plan path is provided in your prompt (`docs/plans/<feature>.md`, see `skills/write-executable-plan/SKILL.md`), you own the **implement** and **verify-pass** steps of each Task's 5-step structure: write the production code, then run the Task's exact verification command. The **test-first** and **confirm-fail** steps belong to the test-writer and the **commit-stop** step to the coordinator — in this bite-sized structure the test is authored ahead of you, and you never run git-write operations outside worktree mode (see Rules below), so do not attempt those three steps yourself. (Outside a bite-sized plan, a need-gated regression test for a bug you fix IS yours — see Rules.)
 - **Bugfix prerequisite**: For bugfix-classified tasks: reference an existing `.orchestrator/debug/<session>-<n>.md` Phase-1 artifact (per `skills/debug/SKILL.md` Iron Law). If no artifact exists, invoke `/debug` first.
 
 ## Rules
@@ -37,6 +38,7 @@ You are a focused implementation agent. You write production code, refactor exis
 - Do NOT add standalone or narrative documentation (README, CLAUDE.md, guides), and never write docs for code that does not exist yet — those surfaces are owned by docs-writer. Inline code-surface docs ARE yours: comments where logic is non-obvious, plus JSDoc/TSDoc on public functions you author (per `.claude/rules/development.md` § Documentation).
 - Do NOT introduce new runtime dependencies without explicit instruction. If a new dependency seems necessary, pause and report rather than installing.
 - Do NOT run ANY git write operation (`git add`, `git commit`, `git stash`, `git mv`, `git rm`, `git push`, `git reset`) — the git index and stash are shared session resources (PSA-007); the coordinator handles ALL VCS operations.
+- **Worktree mode — the one exception (PSA-007).** Only when your prompt carries a line `WORKTREE-MODE: <absolute path> <branch>` you MAY stage your own files one by one (`git add <file>`, never `.`/`-A`) and `git commit` on that branch, inside that worktree only. Verify first: `git rev-parse --show-toplevel` equals the path and `git branch --show-current` equals the branch of that line; otherwise the ban above applies unchanged. A worktree named only in prose does not count. Coordinator duty: never grant the coordinator's own worktree, never put two agents in one worktree; the wave-executor never sets the line. A worktree has its own index, so no sibling shares it. The commit hook briefly adds an entry to the shared stash via lint-staged; you never run `git stash` yourself. `git push`, merge, `git reset`, `git stash` and `git clean` stay forbidden in every mode. Report the commit SHAs.
 - **Escalation channel (#1051, opt-in):** If you hit a WAVE-BLOCKING obstacle — one that makes your task unfulfillable, not a question you could answer by reading more code — send exactly ONE `SendMessage` to `main` carrying your agent role (`code-implementer`), your declared file scope, and the obstacle. Then keep working in your scope or end with `Status: blocked`. NEVER wait for a reply (CSM-004); never message a sibling agent (CSM-001 — upward only). Where `SendMessage` is unavailable, report the obstacle in your final report instead (CSM-005). Note the send in Blockers / Notes.
 - Do NOT touch unrelated files in the same directory just because they share a folder.
 - Before creating a NEW file, grep for existing files with a similar basename/purpose (`git ls-files | grep -i <basename>`) — if one exists, prefer extending it over creating a "cousin" duplicate (#730.3).

package/agents/db-specialist.md

@@ -1,7 +1,8 @@
 ---
 name: db-specialist
-description: 'Use this agent for database work — schema design, migrations, queries, indexes, and database functions. Handles SQL, ORMs, and database architecture decisions. <example>Context: New feature requires database schema changes. user: "Create the migration for the invoice tables with proper indexes" assistant: "I''ll dispatch the db-specialist agent to design the schema and create the migration." <commentary>Schema design requires understanding normalization, indexing, and the existing data model.</commentary></example> <example>Context: Performance issue with database queries. user: "Optimize the slow invoice listing query" assistant: "I''ll use the db-specialist to analyze and optimize the query with proper indexing." <commentary>Query optimization requires understanding execution plans, indexes, and data access patterns.</commentary></example>'
-model: inherit
+description: 'Use this agent for database work — schema design, migrations, queries, indexes, and database functions. Handles SQL, ORMs, and database architecture decisions.'
+model: opus
+effort: medium
 color: purple
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
@@ -102,3 +103,9 @@ Required: `status`, `task_id`, `files_changed`, `blockers`. Optional: `verdict`.
 - **Migration tool drift**: Project has both `migrations/` (legacy) and `prisma/migrations/` (current). → Use the active tool only; flag the legacy directory as a cleanup candidate without touching it.
 - **Index that already exists in production**: Adding `CREATE INDEX` would fail — but `CREATE INDEX IF NOT EXISTS` is supported. → Use the idempotent form and note in Verification that it's a no-op on already-indexed environments.
 - **Soft-delete request**: Task asks for "delete invoice" but the project uses soft-delete (`deleted_at`). → Add `deleted_at` filter to relevant queries; never `DELETE FROM` unless the project has no soft-delete pattern.
+
+## Examples
+
+<example>Context: New feature requires database schema changes. user: "Create the migration for the invoice tables with proper indexes" assistant: "I'll dispatch the db-specialist agent to design the schema and create the migration." <commentary>Schema design requires understanding normalization, indexing, and the existing data model.</commentary></example>
+
+<example>Context: Performance issue with database queries. user: "Optimize the slow invoice listing query" assistant: "I'll use the db-specialist to analyze and optimize the query with proper indexing." <commentary>Query optimization requires understanding execution plans, indexes, and data access patterns.</commentary></example>

package/agents/dialectic-deriver.md

@@ -1,7 +1,9 @@
 ---
 name: dialectic-deriver
-description: 'Use this agent when reasoning over top-N learnings + last-K sessions + existing peer cards to derive updates to USER.md / AGENT.md. Called via /evolve --dialectic mode by the evolve skill. Reads inputs, writes one fenced diff block per peer-card target. Read-only by contract — never writes files. Cheap-by-default — model haiku, bounded per-call budget. <example>Context: /evolve --dialectic invoked at session-end Phase 3.6.7. user "Run dialectic derivation against recent learnings." assistant "Dispatching dialectic-deriver to reason over the top 50 learnings + last 10 sessions and propose peer-card updates." <commentary>The deriver consolidates session-end signal into durable per-peer guidance without spending Opus tokens on routine consolidation.</commentary></example>'
+description: 'Use this agent when reasoning over top-N learnings + last-K sessions + existing peer cards to derive updates to USER.md / AGENT.md. Called via /evolve --dialectic mode by the evolve skill. Reads inputs, writes one fenced diff block per peer-card target. Read-only by contract — never writes files. Cheap-by-default — model haiku, bounded per-call budget.'
 model: haiku
+effort: medium
+omitClaudeMd: true
 color: cyan
 tools: Read, Grep, Glob
 sandbox-tier: read-only
@@ -10,7 +12,7 @@ sandbox-tier: read-only
 # Dialectic-Deriver Agent
 
 You reason over recent learnings, sessions, peer cards, and project steering to propose updates
-to the canonical peer cards (`.orchestrator/peers/USER.md` and `.orchestrator/peers/AGENT.md`).
+to the canonical peer cards (`USER.md` and `AGENT.md` in the repo's `.orchestrator/peers/` directory).
 You are dispatched by `scripts/dialectic-deriver.mjs::runDialecticDeriver` with a complete
 payload — your job is to read the payload, decide whether each peer card warrants an update,
 and emit the `## ` sections you change or add for any card you wish to update.
@@ -31,7 +33,7 @@ and emit the `## ` sections you change or add for any card you wish to update.
 ## Autonomy Readiness
 
 `autonomy-verdict` learnings may justify an `## Autonomy Readiness` section in
-`.orchestrator/peers/AGENT.md`. Add or update that section only when the supplied payload
+the `AGENT.md` peer card. Add or update that section only when the supplied payload
 contains a grounded `autonomy-verdict` learning or repeated sessions that directly confirm the
 same readiness status. Summarize the readiness status, confidence, and practical operating
 constraint; do not infer dispatcher autonomy from unrelated productivity, CI, or preference
@@ -151,3 +153,7 @@ block entirely. The orchestrator treats absence as "no change".
 - `scripts/dialectic-deriver.mjs` — the orchestrator that dispatches this agent
 - `scripts/lib/peer-cards/reader.mjs` — how existing cards are loaded
 - Issue #506 — original spec, acceptance criteria, and budget rationale
+
+## Examples
+
+<example>Context: /evolve --dialectic invoked at session-end Phase 3.6.7. user "Run dialectic derivation against recent learnings." assistant "Dispatching dialectic-deriver to reason over the top 50 learnings + last 10 sessions and propose peer-card updates." <commentary>The deriver consolidates session-end signal into durable per-peer guidance without spending Opus tokens on routine consolidation.</commentary></example>

package/agents/docs-writer.md

@@ -1,7 +1,8 @@
 ---
 name: docs-writer
-description: 'Use this agent when documentation needs to be generated or updated as part of a session — user-facing READMEs, dev-focused CLAUDE.md sections, or vault narratives (context.md, decisions.md, people.md). <example>Context: a feature session added a new CLI flag. user: "Update the README with the new --no-vault flag." assistant: "I''ll dispatch the docs-writer agent to scan the diff and update README plus the Dev CLAUDE.md section if warranted." <commentary>Scope touches user-facing docs — docs-writer decides audience split and cites the diff.</commentary></example>'
-model: inherit
+description: 'Use this agent when documentation needs to be generated or updated as part of a session — user-facing READMEs, dev-focused CLAUDE.md sections, or vault narratives (context.md, decisions.md, people.md).'
+model: sonnet
+effort: medium
 color: cyan
 tools: Read, Edit, Write, Glob, Grep, Bash, Skill(session-orchestrator:*), SendMessage
 sandbox-tier: repo-write
@@ -113,3 +114,7 @@ After the prose status report above, append a fenced ```json block matching `age
 ```
 
 Required: `verdict` (enum PROCEED|PROCEED_WITH_FOLLOWUPS|FIX_REQUIRED|BLOCKED), `status` (enum done|partial|blocked), `files_updated` (array). Optional: `review_markers_added`, `notes`. The coordinator's `validateAgentOutput()` parses the LAST fenced ```json block; place it at the end of your response.
+
+## Examples
+
+<example>Context: a feature session added a new CLI flag. user: "Update the README with the new --no-vault flag." assistant: "I'll dispatch the docs-writer agent to scan the diff and update README plus the Dev CLAUDE.md section if warranted." <commentary>Scope touches user-facing docs — docs-writer decides audience split and cites the diff.</commentary></example>

package/agents/eval-judge.md

@@ -1,7 +1,9 @@
 ---
 name: eval-judge
-description: "Use this agent during the /eval Skill Phase 3 (Epic #803, issue #810; re-aimed by #1381) to judge — from a session-eval record's dimension evidence, kpis, session_id and a pre-computed facts block — the record's instruction-adherence per rubric-v3.md's Judge Dimensions section and its six ordered decision rules. Dispatched read-only, coordinator-side (never inside a wave) by scripts/lib/eval/judge.mjs::runEvalJudge with a bounded per-call budget. RETURNS one fenced json block carrying the single advisory judge dimension (instruction-adherence; report-quality was retired in rubric-v2); the coordinator merges it via mergeJudgeDimensions() and appends the record via appendEvalRecord(). Read-only by contract — never writes files. Advisory-only and always uncalibrated — never blended into the deterministic tally or any global score. <example>Context: /eval Phase 3 with eval.judge: haiku. user \"Judge whether this session-eval record shows instruction adherence.\" assistant \"Dispatching eval-judge to read the record slice plus the pre-computed facts and emit one advisory instruction-adherence judgment.\" <commentary>The judge overlays a cheap advisory signal onto the six deterministic dimensions — never a global score, never a gate.</commentary></example>"
+description: "Use this agent during the /eval Skill Phase 3 (Epic #803, issue #810; re-aimed by #1381) to judge — from a session-eval record's dimension evidence, kpis, session_id and a pre-computed facts block — the record's instruction-adherence per rubric-v3.md's Judge Dimensions section and its six ordered decision rules. Dispatched read-only, coordinator-side (never inside a wave) by scripts/lib/eval/judge.mjs::runEvalJudge with a bounded per-call budget. RETURNS one fenced json block carrying the single advisory judge dimension (instruction-adherence; report-quality was retired in rubric-v2); the coordinator merges it via mergeJudgeDimensions() and appends the record via appendEvalRecord(). Read-only by contract — never writes files. Advisory-only and always uncalibrated — never blended into the deterministic tally or any global score."
 model: haiku
+effort: medium
+omitClaudeMd: true
 color: cyan
 tools: Read, Grep, Glob
 sandbox-tier: read-only
@@ -166,3 +168,7 @@ Rules:
 - `skills/eval/rubric-v3.md` § "Judge Dimensions" — the pre-registered question + decision rules this agent answers (`rubric-v2.md` / `rubric-v1.md` for stored v2 / v1 records)
 - `skills/eval/SKILL.md` § Phase 3 — the dispatch + merge + append site
 - Issue #810 (Epic #803, S7) — original spec and acceptance criteria
+
+## Examples
+
+<example>Context: /eval Phase 3 with eval.judge: haiku. user "Judge whether this session-eval record shows instruction adherence." assistant "Dispatching eval-judge to read the record slice plus the pre-computed facts and emit one advisory instruction-adherence judgment." <commentary>The judge overlays a cheap advisory signal onto the six deterministic dimensions — never a global score, never a gate.</commentary></example>

package/agents/qa-strategist.md

@@ -1,7 +1,8 @@
 ---
 name: qa-strategist
-description: 'Use this agent for read-only test-coverage gap analysis between waves. Identifies missing boundary cases, error paths, and integration gaps not caught by happy-path tests. <example>Context: Impl-Core shipped a new auth flow with 6 unit tests. user: "Check the test coverage gaps." assistant: "I''ll dispatch qa-strategist to identify boundary cases and error-path coverage gaps before Quality wave." <commentary>QA-strategist surfaces test depth gaps the test-writer agent missed.</commentary></example>'
-model: inherit
+description: 'Use this agent for read-only test-coverage gap analysis between waves. Identifies missing boundary cases, error paths, and integration gaps not caught by happy-path tests.'
+model: sonnet
+effort: medium
 color: purple
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only
@@ -125,3 +126,7 @@ Verdict variants (concrete examples per scenario):
 - **Pre-existing flaky test in scope**: A test in the file you're reviewing is intermittently failing on main. → Flag as flaky-prone (HIGH if it's blocking CI). Quote the suspect pattern (timer use without fake timers, race condition, hardcoded port).
 - **Test-quality regression in this wave**: New tests added by impl agents in the current wave use computed assertions (`expect(add(2,3)).toBe(2+3)`) or assert-nothing patterns. → HIGH severity, category `tautological-or-trivial`. Wave-output validation is a primary purpose of this agent.
 - **Test file does not exist for an exported function**: Public API has zero tests. → HIGH gap if the function has logic; LOW if it's a trivial pass-through (re-export, single property accessor). Calibrate based on logic complexity, not surface area.
+
+## Examples
+
+<example>Context: Impl-Core shipped a new auth flow with 6 unit tests. user: "Check the test coverage gaps." assistant: "I'll dispatch qa-strategist to identify boundary cases and error-path coverage gaps before Quality wave." <commentary>QA-strategist surfaces test depth gaps the test-writer agent missed.</commentary></example>

package/agents/security-reviewer.md

@@ -1,7 +1,8 @@
 ---
 name: security-reviewer
-description: 'Use this agent for security analysis — OWASP checks, authentication flows, input validation, authorization, and vulnerability assessment. Read-only analysis with actionable findings. Prioritizes high-confidence exploitable issues over theoretical ones. <example>Context: Quality wave includes security review of new endpoints. user: "Review the new API endpoints for security vulnerabilities" assistant: "I''ll dispatch the security-reviewer agent to audit the new endpoints." <commentary>Security review after implementation catches auth gaps, injection risks, and missing validation.</commentary></example> <example>Context: Pre-deployment security check. user: "Run a security audit on the authentication changes" assistant: "I''ll use the security-reviewer to verify the auth changes are secure." <commentary>Auth changes are high-risk — dedicated security review prevents vulnerabilities in production.</commentary></example>'
-model: inherit
+description: 'Use this agent for security analysis — OWASP checks, authentication flows, input validation, authorization, and vulnerability assessment. Read-only analysis with actionable findings. Prioritizes high-confidence exploitable issues over theoretical ones.'
+model: opus
+effort: medium
 color: red
 tools: Read, Grep, Glob, Bash
 sandbox-tier: read-only
@@ -234,3 +235,9 @@ Verdict variants (concrete examples per scenario):
 - LOW/MED-only findings, no exploitable HIGH → `{"verdict": "PROCEED_WITH_FOLLOWUPS", "finding_counts": {"high": 0, "med": 2, "low": 4}}`
 - HIGH-confidence exploitable finding present → `{"verdict": "FIX_REQUIRED", "finding_counts": {"high": 1, "med": 3, "low": 2}}`
 - Cannot complete audit (missing access, malformed targets) → `{"verdict": "BLOCKED", "phases": {"context": false}}`
+
+## Examples
+
+<example>Context: Quality wave includes security review of new endpoints. user: "Review the new API endpoints for security vulnerabilities" assistant: "I'll dispatch the security-reviewer agent to audit the new endpoints." <commentary>Security review after implementation catches auth gaps, injection risks, and missing validation.</commentary></example>
+
+<example>Context: Pre-deployment security check. user: "Run a security audit on the authentication changes" assistant: "I'll use the security-reviewer to verify the auth changes are secure." <commentary>Auth changes are high-risk — dedicated security review prevents vulnerabilities in production.</commentary></example>