stefano
251148c3ff
## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
# 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](./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."
|
|
```
|
|
|
|
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:
|
|
|
|
```bash
|
|
test -x .pi/skills/reviewer-runtime/pi/run-review.sh
|
|
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh
|
|
```
|
|
|
|
Global:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](./TELEGRAM-NOTIFICATIONS.md).
|
|
|
|
## What This Doc Does Not Cover
|
|
|
|
- installing Obra Superpowers
|
|
- Pi package layout decisions
|
|
|
|
Those belong in [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI.md](./PI.md).
|