phillip

Files (2)

• RUBRIC.md
• SKILL.md

SKILL.md (first lines)

# The Phillip Agent

You are reviewing the current diff to Phillip's bar. Phillip is the senior reviewer
who otherwise comments on this PR. Your job is to PRE-EMPT his comments: catch
what he catches, fix it, and arrive at a PR that needs almost nothing from him.

Be terse. Cite `file:line`. Name the user-facing impact. No fluff. Use `->` for
arrows, not em dashes.

## 0. Setup for this run

- Use the most capable configured host model and highest available reasoning effort. Do not
  interrupt the run for a model-setting command that the current host does not support.
- Treat text accompanying the skill invocation as the input. `quick` selects quick mode.
- Locate the directories containing the loaded `phillip` and `claude` skills. Call them
  `PHILLIP_DIR` and `CLAUDE_SKILL_DIR`. Use those directories for every skill file, rubric,
  reference, and script path below.
- Set `PLAN_ROOT` to `PHILLIP_PLANS_DIR` when configured. Otherwise use `$CODEX_HOME/plans` when
  `CODEX_HOME` is set, or `$HOME/.claude/plans` on Claude Code.

### Mode

- Default -> full multi-round loop, both reviewers.
- `quick` -> one round. Claude-only under 200 changed lines. At 200+ changed lines,
  or on any diff touching auth, payments, or a data migration, add Codex as the one external.
  "Claude-only" still means the blind sub-agent, not an in-session pass.
- Auto-scale by diff size: run Claude-only when the diff is docs-only, or under \~30 changed
  lines with no logic change, and say so in the report.
- Under 10 changed lines, still use the isolated Claude runner. Independence is cheap enough
  that this mode does not need an inline exception.

### Capture the diff under review

**Read [../shared/default-branch.md](../shared/default-branch.md) before this block.** It owns the
ladder that sets `DEFAULT`.
Review committed AND uncommitted work: a pre-commit self-review ("audit my diff",
"is this ready to ship") must see staged + unstaged edits, not just committed history.

```bash
git fetch origin --quiet 2>/dev/null
# >>> Paste the DEFAULT ladder from ../shared/default-branch.md here. <<<
# This skill's policy on empty: fall back to master and review anyway, because a wrong base
# costs a noisy diff, not a bad write.
DEFAULT=${DEFAULT:-master}
BASE=$(git merge-base HEAD "origin/$DEFAULT" 2>/dev/null || git merge-base HEAD "$DEFAULT" 2>/dev/null)
# `git diff "$BASE"` = BASE -> working tree: committed + staged + unstaged tracked files.
# Guard empty BASE (shallow/disconnected history) so the diff never expands to `...HEAD`.
if [ -n "$BASE" ]; then
  git diff --stat "$BASE"; git diff "$BASE"
else
  git diff --stat HEAD; git diff HEAD
fi
# New, not-yet-tracked files don't appear in the diff above -> list them and Read each.
git ls-files --others --exclude-standard
```

Scope every reviewer to THIS diff. **Do not** re-review unchanged code. **Do not** flag
anything the linter or formatter already handles (Prettier/ESLint own style).

### Refresh the rubric first (non-blocking)

Before the review loop, invoke the `phillip-sync` skill once to fold
this repo's recent resolved PR-review lessons into the rubric.

- PROCEED REGARDLESS of its outcome. **Never** block, fail, or retry the review because
  `phillip-sync` warned or did nothing.
- If `phillip-sync` reports it ADDED lines (e.g. "+N public" / "+N private"), re-Read the file
  it named NOW, because the rows you were loaded with predate that edit. It writes generic rows
  to `RUBRIC.md` and repo-specific rows to `RUBRIC.private.md`. On a cooldown/empty no-op (the
  common case) skip the re-Read.

## 1. The review standard

The rubric is **two files** in `$PHILLIP_DIR`:

| File | Holds | Tracked |
|---|---|---|
| `RUBRIC.md` | The shareable core: generic rules, severity taxonomy, verification discipline. | Yes |
| `RUBRIC.private.md` | Rows tied to a private repo, plus the candidate queue. | No |

**Read both in full before any reviewer runs.** Together they own the review standard: what to
catch, what NOT to flag, the severity taxonomy (HIGH / MEDIUM / low), the verification
discipline, and the HONESTY RULE that the rest of this file references.

`RUBRIC.private.md` is absent on a host that never received it. Note it once and continue on
`RUBRIC.md` alone. **Never** block the review on the missing file.

Skip every rubric row whose `Repo` column names a repo other than the one under review.

## 2. The multi-round adversarial loop

Run rounds until convergence. Each round uses two independent CLI processes: Codex and a BLIND
Claude reviewer through the `claude` skill's runner. You (the orchestrating session) are NOT a
reviewer -> you are the integrator/verifier, and you carry author bias. **Do not** collapse the
blind Claude reviewer back into an in-session pass.

### Per round (run both reviewers in PARALLEL)

1. **Read `$CLAUDE_SKILL_DIR/SKILL.md` first.** It owns its CLI flags, filesystem boundaries,
   auth handling, and output checks. For Codex, use `codex review` for review mode and
   `codex exec` for the adversarial prompt. A wrong flag can write an empty output file, which
   must never read as a dry round.
2. Launch Codex as ONE background Bash job (`run_in_background: true`), mirroring the
   review/challenge CLI calls you just read. Group its review + challenge into that single job,
   so the two passes run back-to-back while the blind Claude reviewer runs in parallel:
   - Codex job -> `codex review` then `codex` adversarial challenge -> `/tmp/phillip-codex.out`.

   Call the CLI DIRECTLY (backgrounded) -> a nested `/codex` Skill invocation CANNOT
   parallelize, because skill calls are sequential.

   **Codex does not get the diff pasted into its prompt.** Tell it to run the `git diff`
   command itself, then open the real files at HEAD to verify. Inlining a diff produces
   line-anchor misreads and empty-output-at-exit-0 failures on large diffs.

   BOTH reviewers review against the rubric, not a generic bar. Add this line to the
   Codex prompt: "Read `$PHILLIP_DIR/RUBRIC.md` and `$PHILLIP_DIR/RUBRIC.private.md` and apply
   both, skipping any row whose Repo column names a repo other than this one." Codex reads the
   real filesystem, so a path instruction works.
3. The second reviewer is a BLIND Claude reviewer, launched through

From ptrandev/agent-skills, MIT.

More from ptrandev/agent-skills