# Pi Code Review Package Design ## Summary Create a self-contained Pi package named `@sirfetch-d/pi-code-review`. The package registers a `/code-review` command that reviews a GitHub pull request with isolated Pi subprocesses. It reports findings in the terminal by default and publishes a single GitHub review only when the user passes `--comment`. The implementation preserves the reviewed behavior of Anthropic's Claude Code code-review plugin: multiple independent reviewers, high-signal filtering, independent validation, and explicit false-positive suppression. It adapts platform-specific behavior for Pi and rewrites the prompt wording rather than redistributing Anthropic's copyrighted prompt text. ## Goals - Install from npm with `pi install npm:@sirfetch-d/pi-code-review`. - Register `/code-review` without modifying Pi core. - Accept the current branch's PR, a PR number, or a full GitHub PR URL. - Keep GitHub writes opt-in through `--comment`. - Inherit the active Pi model and thinking level for every child agent unless the user overrides them for the command. - Review task completion, scope discipline, introduced bugs, regressions, permission and security risks, maintenance risks, and applicable `AGENTS.md` rules. - Publish only independently validated, high-confidence findings. - Run without a dependency on another Pi package. ## Non-goals - Supporting `CLAUDE.md` or other instruction filenames. - Exposing a general-purpose subagent tool. - Modifying code, applying fixes, approving PRs, or requesting changes. - Running linters, builds, or tests as part of review. - Supporting Git hosting providers other than GitHub. - Adding per-reviewer model configuration in the first release. - Reproducing Claude Code's plugin runtime or proprietary prompt text. ## Package Layout ```text pi-code-review/ ├── package.json ├── README.md ├── LICENSE ├── extensions/ │ └── code-review.ts ├── src/ │ ├── arguments.ts │ ├── github.ts │ ├── instructions.ts │ ├── subprocess.ts │ ├── orchestrator.ts │ ├── findings.ts │ └── prompts/ ├── test/ └── docs/ └── superpowers/specs/ ``` `package.json` declares `extensions/code-review.ts` in `pi.extensions`, includes `pi-package` in `keywords`, and lists `@earendil-works/pi-coding-agent` as a peer dependency. Pi loads the TypeScript source directly, so the published tarball includes the extension, source modules, and prompt assets. ## Command Interface ```text /code-review [target] [--comment] [--model ] [--thinking ] ``` Targets: - No target: resolve the PR associated with the current branch. - Integer: resolve that PR number in the current GitHub repository. - Full `https://github.com///pull/` URL: review that PR. Options: - `--comment`: publish a GitHub review after successful completion. Without it, output only to the terminal. - `--model`: apply one model override to all child agents for this invocation. - `--thinking`: apply one thinking-level override to all child agents for this invocation. Unknown flags, missing flag values, multiple targets, malformed URLs, and unsupported thinking levels fail before any model calls. ## Architecture ### Extension Entry Point `extensions/code-review.ts` registers the command, parses arguments, reads the active model and thinking level from the command context, invokes the orchestrator, and renders the final report. It contains no review policy. ### GitHub Adapter `src/github.ts` is the only module that executes `gh`. It resolves repository and PR identity, retrieves metadata and diff data, discovers linked issues, reads prior review markers, and publishes the final review. It returns typed domain objects rather than raw `gh` JSON. All commands use argument arrays with `shell: false`. Review payloads are sent through stdin to `gh api --input -`. ### Instruction Resolver `src/instructions.ts` starts at each changed file's directory and walks toward the repository root. It collects only `AGENTS.md` files on that path. Shared files are read once and mapped to the changed files for which they apply. An `AGENTS.md` outside a changed file's ancestor chain does not apply. ### Subprocess Runner `src/subprocess.ts` starts isolated `pi --mode json --no-session` processes, reads their JSONL event streams, collects usage and final structured output, propagates abort signals, and removes temporary prompt files. It reuses the current Pi executable when possible and otherwise invokes `pi` from `PATH`. Child agents receive only `read`, `grep`, `find`, and `ls`. They cannot use Pi's write, edit, or bash tools. ### Orchestrator `src/orchestrator.ts` owns the review state machine, concurrency limits, required-agent accounting, format-repair retry, validation fan-out, and fail-closed publication decision. Reviewers never publish directly. ### Finding Processor `src/findings.ts` validates agent JSON, rejects code findings outside the PR change and task omissions without an explicit requirement, filters by validation result and confidence, deduplicates findings, maps them to GitHub diff positions, and generates terminal and GitHub representations. ### Prompt Assets `src/prompts/` contains package-private system prompts for triage, summary, instruction compliance, bug review, objective alignment, validation, and one format-repair attempt. They are not registered as user-facing Pi prompt templates. The prompts preserve the upstream workflow semantics and high-signal rules while replacing Claude Code-specific tools, fixed model names, `CLAUDE.md`, MCP comments, and proprietary wording. Prompt inputs use explicit delimiters. PR titles, descriptions, linked issue text, comments, and diff content are data, not instructions. Applicable `AGENTS.md` content is project policy. ## Review Inputs The GitHub adapter creates an immutable snapshot for one head SHA: - Repository owner and name. - PR number, URL, state, draft state, author, title, and description. - Base SHA and full head SHA. - Changed-file metadata and unified diff. - Linked issue titles, bodies, and acceptance criteria when GitHub exposes them. - Applicable `AGENTS.md` files and their per-file scope. - Existing package review markers. The snapshot is stored in a mode-`0700` temporary directory with mode-`0600` files. Agents read it in sections instead of receiving a potentially oversized command-line prompt. The directory is removed in a `finally` path after success, failure, or cancellation. ## Review Pipeline ### 1. Resolve and Preflight Resolve the target and collect the immutable snapshot. Closed and draft PRs are skipped. If `--comment` is present and the package has already reviewed the same head SHA, skip publication and report the existing review. A new head SHA is eligible for review. Before model work, verify that `gh` exists, authentication succeeds, the repository and PR resolve, and the selected model and thinking override are valid. ### 2. Triage One child agent decides whether the change is an automated or clearly trivial change that does not need review. It must return a decision and a concrete reason. Ambiguity defaults to reviewing rather than skipping. ### 3. Summarize One child agent summarizes the intended change from the PR, linked issues, and diff. Its summary is context for all reviewers, not a finding source. ### 4. Run Five Independent Reviewers Five reviewers run concurrently: 1. `AGENTS.md` compliance reviewer A. 2. `AGENTS.md` compliance reviewer B. 3. Introduced-bug and risk reviewer A. 4. Introduced-bug and risk reviewer B. 5. Task objective and scope reviewer. The fifth reviewer explicitly checks: > Whether the implementation completes the task goal and remains strictly limited to that goal: it must not add unnecessary functionality or introduce new bugs, regression risk, permission or security risk, or maintenance risk. Its source of truth is, in order, linked issue goals and acceptance criteria, PR title and description, the diff, and applicable `AGENTS.md` rules. A missing-goal finding must cite a concrete unmet goal or acceptance criterion. An out-of-scope finding must identify the unrelated change and its concrete risk. Necessary supporting changes are not scope creep. Missing information alone is not evidence that the task is incomplete. Reviewers report only issues introduced by the PR or concrete task requirements that the PR fails to implement. They exclude pre-existing problems, subjective style preferences, speculative input-dependent concerns, linter-detectable issues, general test-coverage requests, and rules explicitly suppressed in code. Each reviewer also returns a coverage receipt containing every changed file it examined and a `complete` flag. The runtime verifies that the receipt covers the complete changed-file set. A reviewer that cannot cover the full diff must return `complete: false`, which makes the review incomplete rather than clean. ### 5. Validate Every Candidate Each candidate finding receives a fresh validation run. Validation concurrency is limited to four. - Compliance validators confirm the exact rule, its path scope, and the violation. - Bug and risk validators inspect necessary repository context and confirm the issue is introduced by the diff. - Goal and scope validators confirm the cited task requirement and distinguish required supporting work from unnecessary expansion. Each validator returns `valid`, an integer `confidence` from 0 through 100, evidence, affected path, and diff line information. A finding survives only when `valid` is true and confidence is at least 80. ### 6. Aggregate Findings are deduplicated by affected path, diff location, category, and normalized issue statement. Every finding must refer to changed code or to a concrete omission required by an explicit task goal. The processor validates GitHub-side line mapping before publication. ### 7. Report or Publish Without `--comment`, render the final report in the terminal and perform no GitHub writes. With `--comment`, publish one GitHub review only after all required reviewers and validators complete successfully. ## Finding Contract Agent output is JSON with a versioned schema. Findings are a discriminated union: - A code finding requires a repository-relative changed path and diff-side line information. - A task-omission finding may omit a code location but must cite a concrete linked-issue or PR requirement that remains unimplemented. A candidate or validated finding also includes: - Stable category: `instructions`, `bug`, `regression`, `permission`, `security`, `maintenance`, `goal`, or `scope`. - Concise title and explanation. - Repository-relative path and changed-side line information when required by the finding kind. - Evidence from the diff, task requirement, or applicable instruction. - Why the issue is introduced by this PR. - A complete small fix suggestion only when it fully resolves the issue. Validator output adds `valid`, `confidence`, and rejection reason. Runtime schema validation rejects unknown category values, invalid confidence ranges, absolute paths, traversal paths, and malformed line ranges. One invalid JSON result receives a single repair attempt using the same model and thinking level. A second invalid result fails that required stage. ## Model and Thinking Selection The extension reads the active model and thinking level when the command begins. Every triage, summary, reviewer, validator, and repair subprocess uses those values. `--model` and `--thinking` override the inherited values for the entire invocation. The first version does not support different models per role. A child process never silently falls back to a different model; inability to use the selected model makes the review incomplete. ## GitHub Publication Publishing uses one GitHub pull request review with event `COMMENT`. It never sends `APPROVE` or `REQUEST_CHANGES`. - Findings with valid diff coordinates become inline review comments. - Findings that cannot safely map to an inline location remain in the review summary with a permanent full-head-SHA link. - A successful review with no findings posts a short summary stating the completed review dimensions. - Every public review ends with `This review is AI-generated by pi-code-review.` - A hidden marker records package identity, package version, and reviewed head SHA. The complete payload is submitted once. If GitHub rejects it, the package does not retry findings individually because that could publish a partial review. ## Failure and Cancellation Behavior These conditions fail before model work: - `gh` is missing or unauthenticated. - The current directory is not associated with the required GitHub repository. - The target is missing, malformed, ambiguous, or unavailable. - A command override is invalid. Reviewer processes may finish independently, but failure of any required reviewer or validator marks the review incomplete. An incomplete review is reported in the terminal and is never published, even with `--comment`. There is no fixed total timeout in the first release. Ctrl+C aborts all running and queued subprocesses. Termination escalates from `SIGTERM` to `SIGKILL` after a short cleanup interval. Temporary files are removed afterward. Large diffs are never silently truncated. If agents cannot cover the complete snapshot within the selected model's limits, the run is incomplete rather than reported as clean. ## Security Considerations - The extension and all installed Pi packages execute with the user's system permissions; documentation must state this explicitly. - Child agents have read-only Pi tool allowlists. - No untrusted PR value is interpolated into a shell command. - GitHub writes require the explicit `--comment` flag. - Reviewer prompts delimit PR content as untrusted data and explicitly prohibit following instructions embedded in it; the read-only tool allowlist limits the impact of any model failure to follow that rule. - Review output is treated as untrusted until it passes the finding schema and diff mapping checks. - The package never prints authentication tokens or complete environment variables. ## Testing Strategy ### Unit Tests - Argument parsing for every target form, flag, override, and invalid combination. - `AGENTS.md` discovery for root, nested, multi-file, duplicate, and out-of-scope cases. - Finding schema validation, confidence filtering, path safety, and semantic deduplication. - Diff mapping for additions, modifications, deletions, renames, multiline ranges, and left/right sides. - GitHub marker generation and same-head detection. ### Orchestration Tests - Five reviewers start concurrently. - Validator concurrency never exceeds four. - Model and thinking values inherit from the command context. - Invocation overrides reach every subprocess. - Abort propagates and removes temporary artifacts. - Missing, failed, or malformed required-agent results prevent publication. - Incomplete or mismatched reviewer coverage receipts prevent publication. - The one-time JSON repair path succeeds or fails closed. ### GitHub Adapter Tests - Target resolution for current branch, number, and URL. - Read calls use the expected `gh` arguments. - Publication sends one review payload through stdin. - Clean reviews, inline findings, summary-only findings, and duplicate-head skips produce the correct payload or no-op. - API rejection does not trigger partial-comment retries. ### End-to-End Tests End-to-end tests use fake `pi` and `gh` executables placed first in `PATH`. They make no provider API calls, consume no paid tokens, and perform no GitHub writes. Fixtures cover clean, finding, duplicate, partial-failure, cancellation, and oversized-review outcomes. ### Package Verification CI runs type checking, linting, unit and integration tests, and `npm pack --dry-run`. A tarball-content assertion verifies that the extension, source modules, and all prompt assets are included. Runtime dependencies are pinned exactly; Pi core packages are peer dependencies and are not bundled. ## Acceptance Criteria - `pi install npm:@sirfetch-d/pi-code-review` loads `/code-review` in Pi. - All three target forms resolve correctly. - Default execution performs no GitHub write. - `--comment` creates at most one complete `COMMENT` review for a head SHA. - All child agents inherit the active model and thinking level unless command overrides are supplied. - The five approved review dimensions and independent validation are present. - Only validated findings with confidence of at least 80 appear in the final review. - Applicable `AGENTS.md` scope is correct for every changed file. - Any required-stage failure prevents a misleading clean result and prevents publication. - Tests do not call real models or GitHub mutation APIs. - The npm tarball is self-contained and does not depend on another Pi package. ## Repository and Release Boundary The local repository lives at `/Users/winson/project/pi-code-review` on branch `main`. The intended GitHub repository name is `pi-code-review` under the authenticated account `Sirfetch-d`. Remote repository creation is deferred until its visibility is explicitly selected. The initial npm package name is `@sirfetch-d/pi-code-review`; registry lookup on 2026-07-12 returned no published package at that name. Publishing and npm version selection occur only after implementation and package verification.