ai-coding-skills/docs/PI-COMMON-REVIEWER.md

PI COMMON REVIEWER

Purpose

This document covers the shared reviewer-runtime helpers used by the Pi workflow skills.

It is intentionally separate from PI-SUPERPOWERS.md. Superpowers are skill dependencies; reviewer-runtime is helper-script setup.

Pi As A Reviewer CLI

Pi workflow skills may use pi itself as the reviewer CLI, even when the main workflow is already running in pi. In that case, the reviewer model is configured independently from the running agent model. This lets the operator run a workflow with one model while asking another pi-configured model, including provider-qualified model IDs, to review the plan or implementation.

The canonical isolated, read-only reviewer command is:

pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the review payload and return the requested verdict."

Workflow docs should link to this section instead of restating the full flag contract. Each workflow substitutes its own payload path and verdict prompt:

• create-plan: /tmp/plan-${REVIEW_ID}.md
• implement-plan: /tmp/milestone-${REVIEW_ID}.md
• do-task: /tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md

User-facing shorthand pi/<pi-model-name> means REVIEWER_CLI=pi and REVIEWER_MODEL=<pi-model-name>. Split only on the first slash when the prefix before that slash is exactly pi; keep the remainder verbatim. Examples:

• pi/claude-opus-4-7 -> claude-opus-4-7
• pi/anthropic/claude-opus-4-7 -> anthropic/claude-opus-4-7
• pi/openrouter/anthropic/claude-opus-4-7 -> openrouter/anthropic/claude-opus-4-7

Pi reviewer calls must stay isolated from the main workflow:

• Use --no-session so the reviewer does not continue or persist the workflow session.
• Use --no-skills --no-prompt-templates --no-extensions --no-context-files so the reviewer does not load workflow skills, project context files, or package extensions that could re-enter create-plan, implement-plan, or do-task.
• Use exactly --tools read,grep,find,ls for review. The pi reviewer command MUST NOT include write, edit, or bash; the reviewer reads payloads and diffs but never modifies files or runs commands.

If the reviewer subprocess exits non-zero because the provider, credentials, or model ID are unavailable, surface the captured stderr/status from run-review.sh, then ask the user for a configured reviewer model. Use pi --list-models [search] to inspect available configured models when needed.

Official references:

• https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent documents pi providers, model selection, skills, extensions, and print mode.
• Local pi --help for pi 0.70.0 confirms --model <pattern> supports provider/id, --print, -p runs non-interactively, --tools, -t <tools> allowlists tools, and the read-only example is pi --tools read,grep,find,ls -p "Review the code in src/".

Required Files

The workflow-heavy Pi skills expect these helper files from skills/reviewer-runtime/pi/:

• run-review.sh
• notify-telegram.sh

Supported install locations:

1. .pi/skills/reviewer-runtime/pi/
2. ~/.pi/agent/skills/reviewer-runtime/pi/

Verify An Existing Install

Project-local:

test -x .pi/skills/reviewer-runtime/pi/run-review.sh
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh

Global:

test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh

Install The Common Reviewer Helpers

Global install:

mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh

Project-local install:

mkdir -p .pi/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
chmod +x .pi/skills/reviewer-runtime/pi/*.sh

Telegram

If you want the workflow skills to send completion messages, configure:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_CHAT_ID

The Pi helper uses the same notification behavior documented in TELEGRAM-NOTIFICATIONS.md.

What This Doc Does Not Cover

• installing Obra Superpowers
• Pi package layout decisions

Those belong in PI-SUPERPOWERS.md and PI.md.