From 912aed93a79b33bf355c737442153c265d63e390 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Thu, 23 Apr 2026 19:13:22 -0500 Subject: [PATCH] feat(pi): support pi reviewer model routing --- docs/PI-COMMON-REVIEWER.md | 23 +++++++++++++++++++ pi-package/skills/create-plan/SKILL.md | 13 +++++++++++ pi-package/skills/do-task/SKILL.md | 14 ++++++++++- .../skills/do-task/templates/task-plan.md | 2 +- pi-package/skills/implement-plan/SKILL.md | 14 ++++++++++- scripts/verify-pi-resources.sh | 9 ++++++++ scripts/verify-pi-workflows.sh | 21 +++++++++++++++++ skills/create-plan/pi/SKILL.md | 13 +++++++++++ skills/do-task/pi/SKILL.md | 14 ++++++++++- skills/do-task/pi/templates/task-plan.md | 2 +- skills/implement-plan/pi/SKILL.md | 14 ++++++++++- 11 files changed, 133 insertions(+), 6 deletions(-) diff --git a/docs/PI-COMMON-REVIEWER.md b/docs/PI-COMMON-REVIEWER.md index 13620ce..0cba0da 100644 --- a/docs/PI-COMMON-REVIEWER.md +++ b/docs/PI-COMMON-REVIEWER.md @@ -6,6 +6,29 @@ This document covers the shared reviewer-runtime helpers used by the Pi workflow It is intentionally separate from [PI-SUPERPOWERS.md](./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: + +```bash +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." +``` + +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 ` supports `provider/id`, `--print, -p` runs non-interactively, `--tools, -t ` 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/`: diff --git a/pi-package/skills/create-plan/SKILL.md b/pi-package/skills/create-plan/SKILL.md index b790982..cbbfc71 100644 --- a/pi-package/skills/create-plan/SKILL.md +++ b/pi-package/skills/create-plan/SKILL.md @@ -71,17 +71,30 @@ If any dependency is missing, stop and return: If the user already specified a reviewer CLI and model, use those values. Otherwise ask: +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + 1. Which CLI should review the plan? - `codex` - `claude` - `cursor` - `opencode` + - `pi` - `skip` 2. Which model? 3. Max review rounds? Default: `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for the review loop. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/plan-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/plan-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 4: Design - Load `brainstorming`. diff --git a/pi-package/skills/do-task/SKILL.md b/pi-package/skills/do-task/SKILL.md index 44cc4d8..70a6917 100644 --- a/pi-package/skills/do-task/SKILL.md +++ b/pi-package/skills/do-task/SKILL.md @@ -95,12 +95,24 @@ Use current-branch execution by default. Only switch to a worktree when the prom If the user already specified reviewer settings, use them. Otherwise ask: -1. Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, or `skip` +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + +1. Which CLI should review the plan and implementation? 2. Reviewer model 3. Max rounds, default `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 4: Initialize `task-plan.md` 1. Compute `ai_plan/YYYY-MM-DD-/` diff --git a/pi-package/skills/do-task/templates/task-plan.md b/pi-package/skills/do-task/templates/task-plan.md index c1fd273..4165ce1 100644 --- a/pi-package/skills/do-task/templates/task-plan.md +++ b/pi-package/skills/do-task/templates/task-plan.md @@ -9,7 +9,7 @@ | Created | YYYY-MM-DD | | Slug | YYYY-MM-DD- | | Runtime | pi | -| Reviewer CLI | codex \| claude \| cursor \| opencode | +| Reviewer CLI | codex \| claude \| cursor \| opencode \| pi | | Reviewer Model | | | MAX_ROUNDS | 10 | | Branch Strategy | current-branch \| worktree | diff --git a/pi-package/skills/implement-plan/SKILL.md b/pi-package/skills/implement-plan/SKILL.md index 2e10fd2..a669dab 100644 --- a/pi-package/skills/implement-plan/SKILL.md +++ b/pi-package/skills/implement-plan/SKILL.md @@ -78,12 +78,24 @@ If any dependency is missing, stop and return: If the user already provided reviewer settings, use them. Otherwise ask: -1. Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, or `skip` +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + +1. Which CLI should review milestone implementations? 2. Reviewer model 3. Max rounds, default `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/milestone-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/milestone-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 3: Set Up Workspace 1. Load `using-git-worktrees` diff --git a/scripts/verify-pi-resources.sh b/scripts/verify-pi-resources.sh index 804442d..a0dd42a 100755 --- a/scripts/verify-pi-resources.sh +++ b/scripts/verify-pi-resources.sh @@ -43,8 +43,17 @@ find skills/atlassian/pi/scripts -type f -print -quit | grep -q . for file in skills/create-plan/pi/SKILL.md skills/do-task/pi/SKILL.md skills/implement-plan/pi/SKILL.md; do grep -q 'docs/PI-SUPERPOWERS.md' "$file" grep -q 'docs/PI-COMMON-REVIEWER.md' "$file" + grep -q 'Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`' "$file" + grep -q 'pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files' "$file" + grep -q -- '--tools read,grep,find,ls -p' "$file" + grep -q 'pi --list-models \[search\]' "$file" done +grep -q 'reviewer model is configured independently' docs/PI-COMMON-REVIEWER.md +grep -q 'provider-qualified model IDs' docs/PI-COMMON-REVIEWER.md +grep -q 'MUST NOT include `write`, `edit`, or `bash`' docs/PI-COMMON-REVIEWER.md +grep -q 'Reviewer CLI | codex \\| claude \\| cursor \\| opencode \\| pi' skills/do-task/pi/templates/task-plan.md + grep -q 'pi-package/skills/atlassian/scripts' skills/atlassian/pi/SKILL.md grep -q 'pi-package/skills/web-automation/scripts' skills/web-automation/pi/SKILL.md grep -q 'local checkout package install keeps the runtime in `pi-package/skills//scripts`' docs/PI.md diff --git a/scripts/verify-pi-workflows.sh b/scripts/verify-pi-workflows.sh index 22d565f..5e90488 100755 --- a/scripts/verify-pi-workflows.sh +++ b/scripts/verify-pi-workflows.sh @@ -13,12 +13,33 @@ WORKFLOW_FILES=( for file in "${WORKFLOW_FILES[@]}"; do test -f "$file" grep -q 'docs/PI-SUPERPOWERS.md' "$file" + grep -q 'Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`' "$file" + grep -q 'pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files' "$file" + grep -q -- '--tools read,grep,find,ls -p' "$file" + grep -q 'pi --list-models \[search\]' "$file" done +grep -q 'reviewer model is configured independently' docs/PI-COMMON-REVIEWER.md +grep -q 'provider-qualified model IDs' docs/PI-COMMON-REVIEWER.md +grep -q 'MUST NOT include `write`, `edit`, or `bash`' docs/PI-COMMON-REVIEWER.md + +if command -v pi >/dev/null 2>&1; then + PI_HELP=$(pi --help 2>&1) + grep -q -- '--model ' <<<"$PI_HELP" + grep -q -- '--print, -p' <<<"$PI_HELP" + grep -q -- '--tools, -t ' <<<"$PI_HELP" + grep -q -- '--no-session' <<<"$PI_HELP" + grep -q -- '--no-skills' <<<"$PI_HELP" + grep -q -- '--no-prompt-templates' <<<"$PI_HELP" + grep -q -- '--no-extensions' <<<"$PI_HELP" + grep -q -- '--no-context-files' <<<"$PI_HELP" +fi + test -f skills/create-plan/pi/templates/continuation-runbook.md test -f skills/create-plan/pi/templates/milestone-plan.md test -f skills/create-plan/pi/templates/story-tracker.md test -f skills/do-task/pi/templates/task-plan.md +grep -q 'Reviewer CLI | codex \\| claude \\| cursor \\| opencode \\| pi' skills/do-task/pi/templates/task-plan.md test -x skills/reviewer-runtime/pi/run-review.sh test -x skills/reviewer-runtime/pi/notify-telegram.sh diff --git a/skills/create-plan/pi/SKILL.md b/skills/create-plan/pi/SKILL.md index b790982..cbbfc71 100644 --- a/skills/create-plan/pi/SKILL.md +++ b/skills/create-plan/pi/SKILL.md @@ -71,17 +71,30 @@ If any dependency is missing, stop and return: If the user already specified a reviewer CLI and model, use those values. Otherwise ask: +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + 1. Which CLI should review the plan? - `codex` - `claude` - `cursor` - `opencode` + - `pi` - `skip` 2. Which model? 3. Max review rounds? Default: `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS` for the review loop. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/plan-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/plan-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 4: Design - Load `brainstorming`. diff --git a/skills/do-task/pi/SKILL.md b/skills/do-task/pi/SKILL.md index 44cc4d8..70a6917 100644 --- a/skills/do-task/pi/SKILL.md +++ b/skills/do-task/pi/SKILL.md @@ -95,12 +95,24 @@ Use current-branch execution by default. Only switch to a worktree when the prom If the user already specified reviewer settings, use them. Otherwise ask: -1. Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, or `skip` +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + +1. Which CLI should review the plan and implementation? 2. Reviewer model 3. Max rounds, default `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 4: Initialize `task-plan.md` 1. Compute `ai_plan/YYYY-MM-DD-/` diff --git a/skills/do-task/pi/templates/task-plan.md b/skills/do-task/pi/templates/task-plan.md index c1fd273..4165ce1 100644 --- a/skills/do-task/pi/templates/task-plan.md +++ b/skills/do-task/pi/templates/task-plan.md @@ -9,7 +9,7 @@ | Created | YYYY-MM-DD | | Slug | YYYY-MM-DD- | | Runtime | pi | -| Reviewer CLI | codex \| claude \| cursor \| opencode | +| Reviewer CLI | codex \| claude \| cursor \| opencode \| pi | | Reviewer Model | | | MAX_ROUNDS | 10 | | Branch Strategy | current-branch \| worktree | diff --git a/skills/implement-plan/pi/SKILL.md b/skills/implement-plan/pi/SKILL.md index 2e10fd2..a669dab 100644 --- a/skills/implement-plan/pi/SKILL.md +++ b/skills/implement-plan/pi/SKILL.md @@ -78,12 +78,24 @@ If any dependency is missing, stop and return: If the user already provided reviewer settings, use them. Otherwise ask: -1. Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, or `skip` +Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip` + +1. Which CLI should review milestone implementations? 2. Reviewer model 3. Max rounds, default `10` Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`. +When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models. + +The pi reviewer command rendered into `/tmp/milestone-review-${REVIEW_ID}.sh` must be isolated and read-only: + +```bash +pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/milestone-${REVIEW_ID}.md and review." +``` + +The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools. + ### Phase 3: Set Up Workspace 1. Load `using-git-worktrees`