# Reviewer CLI Support Matrix

This document is the **single canonical source** for the reviewer CLI support
matrix used by `create-plan`, `implement-plan`, and `do-task`. All workflow
docs and `SKILL.md` variants must refer here and stay in sync.

## Canonical Reviewer CLIs

| CLI | Install | Verify | Read-Only Mode | Session Resume |
|-----|---------|--------|----------------|----------------|
| `codex` | `npm install -g @openai/codex` | `codex --version` | `-s read-only` | Yes (`codex exec resume <id>`) |
| `claude` | `npm install -g @anthropic-ai/claude-code` | `claude --version` | `--strict-mcp-config --setting-sources user` | No (fresh call each round) |
| `cursor` | `curl https://cursor.com/install -fsS \| bash` | `cursor-agent --version` | `--mode=ask` | Yes (`--resume <id>`) |
| `opencode` | `brew install opencode` or your package manager | `opencode --version` | `--agent plan` | Opt-in (`-s <id>`; fresh call is the default) |
| `pi` | Install Pi coding agent | `pi --version`; list models with `pi --list-models [search]` | `--tools read,grep,find,ls` | No (fresh call each round) |

**`skip`** is always a valid value; it bypasses the reviewer loop and requires
explicit user approval instead.

## Notes

- The reviewer CLI is independent of which agent is running the skill. For
  example, Claude Code can send plans to Codex for review and vice versa.
- **`cursor` reviewer prerequisite:** `jq` is required to parse Cursor's JSON
  output. Install via `brew install jq` (macOS) or your package manager.
  Verify: `jq --version`. The Cursor variant of `do-task` makes `jq` a hard
  prerequisite regardless of which reviewer CLI is selected.
- **`opencode` reviewer:** Uses `--agent plan` (built-in read-oriented agent)
  for review posture. Session resume is opt-in via `-s <id>`; fresh call is the
  recommended default for non-interactive headless runs.
- **`pi` reviewer:** Use `pi/<pi-model-name>` shorthand, for example
  `pi/claude-opus-4-7`; this means `REVIEWER_CLI=pi` and
  `REVIEWER_MODEL=claude-opus-4-7`. Provider-qualified or multi-slash Pi model
  IDs are preserved after the first `pi/` prefix, for example
  `pi/anthropic/claude-opus-4-7`. The canonical isolated read-only Pi reviewer
  flag contract lives in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md).

## Reviewer Output Contract

All reviewer CLIs must return the following structure:

```markdown
## Summary
...

## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...

## Verdict
VERDICT: APPROVED
```

Severity levels:

| Level | Meaning |
|-------|---------|
| `P0` | Total blocker |
| `P1` | Major risk |
| `P2` | Must-fix before approval |
| `P3` | Cosmetic / nice to have (non-blocking) |

Rules:

- `VERDICT: APPROVED` is valid only when no `P0`, `P1`, or `P2` findings remain.
- `P3` findings are non-blocking, but the caller should still try to fix them
  when cheap and safe.
- Each severity section uses `- None.` when empty.

## References

- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — Canonical Pi reviewer
  flag contract and read-only command template.
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Telegram
  notification setup used by reviewer-driven workflows.