feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

2026-05-03 20:14:44 -05:00
parent 0443381aa0
commit be993429c1
59 changed files with 1898 additions and 385 deletions
@@ -0,0 +1,81 @@
+# 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.