review-pantheon — Spec Driven AI Coding toolkit

• AI-assisted development produces work faster than a human can independently verify it — the bottleneck moves from writing the change to trusting the report of it.
• A pass with no fail-closed rule turns a missing or malformed verdict into a quiet green — the one failure mode worse than an honest red.

A portable review gate — a GitHub Action plus a provider-agnostic CLI — that splits "does the diff look right" from "did the PR actually do what it claims" into two independent agents (Artemis, Apollo), backed by three advisory philosopher agents for the planning stage before anything is built. Built for teams where a written spec is the contract, not a suggestion read once and forgotten: DESIGN.md in this repo is itself that contract.

Who it's for: teams or solo builders shipping AI-assisted changes fast enough that human review has become the bottleneck, who want a second opinion that can't be talked out of a red verdict by a confident-sounding PR description.

Why this instead of CodeRabbit/Copilot code review: two independent agents (Artemis, Apollo) split "does the diff look right" from "did the PR actually do what it claims," instead of one reviewer doing both jobs. DESIGN.md is a spec-as-contract — Apollo gates against what YOU wrote down, not a generic checklist. The verdict is fail-closed, not a review-quality promise. And it's bring-your-own Claude subscription (claude_code_oauth_token), not a per-seat SaaS.

Stability. Within v1, the action's input names, gate.conf keys, and CLI flags are a stable contract — renames only ride a major version bump, with a deprecation note.

Quick start

No GitHub App, no signup, no third-party access grant — this file plus your own token is the entire footprint. Three steps, no app:

1. Add the workflow file — .github/workflows/review-gate.yml:

name: review-pantheon
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    if: ${{ vars.REVIEW_GATE_ENABLED == 'true' && github.event.pull_request.draft == false }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: G-Schumacher44/review-pantheon@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

2. Add the token secret — mint one with claude setup-token, then add it as the CLAUDE_CODE_OAUTH_TOKEN repo Actions secret.

3. Arm it — set the REVIEW_GATE_ENABLED repo variable to true. Until then, the workflow file sits inert; adding it never silently starts gating PRs.

Full recipe with comments explaining every line: examples/review-gate.yml.

(@v1 tracks the latest release — it moves when a new one is cut (see RELEASING.md). Prefer updates on your own schedule? Pin a full commit SHA instead — that's exactly what install.sh's generated workflow does.)

Nothing else lands in your repo. The CLI installs from PyPI or Homebrew:

pipx install review-pantheon            # or: pip install review-pantheon
brew install g-schumacher44/tap/review-pantheon

Want to try it first with zero tokens spent? From any install (or a local checkout in a venv, pip install -e .):

pantheon gate --pr <number> --dry-run

runs the real thing — real diff, real prompts — right up to calling a provider, then prints exactly what it would post. pantheon is the CLI (docs/CLI.md). Prefer a vendored install, or the CLI only? Full walkthrough for every path: docs/SETUP.md.

The other half — counsel before you build

The gate above enforces after the fact. The same install (pip install review-pantheon or brew install g-schumacher44/tap/review-pantheon) also ships pantheon counsel — three advisory agents (Socrates on options and go/no-go, Diogenes on excess, Plato on coherence) run against a branch diff before it's a PR:

pantheon counsel --branch

Prints each agent's verdict to stdout and posts nothing — no PR required, no comment left anywhere. One prerequisite the Action path below doesn't have: this local CLI lane invokes the Claude Code CLI, so claude must be installed and authenticated on your machine (the same login you minted the Actions token from — that secret lives in GitHub and doesn't reach a local shell). Setup detail: docs/SETUP.md · every flag: docs/CLI.md.

Via the Action. Same three counsel agents, reachable through the same install as the gate above — no local claude CLI needed, since the Action invokes anthropics/claude-code-action the same way the gate does. Add mode: counsel to the Action step and it posts one advisory comment (never a failing check) instead of enforcing:

- uses: G-Schumacher44/review-pantheon@v1
  with:
    mode: counsel
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Whole install: examples/review-counsel.yml — workflow_dispatch (run it on a branch on demand) and/or pull_request gated on a label (e.g. design), your choice.

Trust capsule — what you're wiring in

Before you hand it a token, here's what you're wiring in:

• What it sends to the reviewer: your PR's diff (git diff <base>...<head>); plus two kinds of review input — the bundled personas and verdict decider ship inside the action itself (github.action_path), so their revision is fixed by the ref your workflow calls — @v1 in the Quick start is a moving major tag; call a release tag or full commit SHA instead to freeze them; your repo's own REVIEW_RULES.md, DESIGN.md, and any custom personas (personas_path) are optional and, when present, read base-pinned from your PR's base commit. It does not read or need your other secrets.

• What it could reach: the reviewer's Read/Grep/Glob tools are not path-scoped — they can open any file the runner process can read (SECURITY.md → Execution tiers). The list above is what a review uses; this line is the honest ceiling on what it could read.

• What it can post: exactly one PR comment — the combined verdict. No commits, no branches, no releases, no settings.

• The permissions ceiling is the permissions: block in the Quick start YAML above: contents: read and pull-requests: write, nothing more. GitHub enforces whatever the calling workflow grants, so keep that block as shown — widening it widens a compromised run's reach (SECURITY.md → Blast radius).

• The inner reviewer is SHA-pinned. Inside the action, anthropics/claude-code-action is pinned to a full commit SHA, not a floating tag (this pin covers the reviewer engine — the outer ref your workflow calls is governed by the bullet above). Verify the pin yourself before adopting — resolve the pinned version's tag to its commit and confirm it matches action.yml:

  gh api repos/anthropics/claude-code-action/commits/v1.0.195 --jq .sha
  # → d40ddef4c030e508327d6e35a9c45f3368482c50   (must equal the SHA action.yml pins)
  

Reviewing untrusted content runs read-only by default; the full model and its honest limits are in SECURITY.md.

The panel

Gate agents (Artemis, Apollo) enforce — they run on every PR and can block a merge. Counsel agents (Socrates, Diogenes, Plato) inform — a human weighs their verdict; they never gate, whatever they're pointed at (spec, design doc, proposal, code, or a diff). Via the Action, that split is mode: gate (default, Artemis + Apollo) vs. mode: counsel (Socrates + Diogenes + Plato, posts advisory, never fails a check) — see "The other half" above.

Full persona definitions, verdict vocabulary, and the gate-flow diagram: DESIGN.md.

Where to go

Also here: the binding spec (DESIGN.md), the Claude Code skills (skills/, /gate + /counsel), the release ceremony (RELEASING.md), and the full doc index (docs/README.md).

How the gate stays honest

A missing, empty, or unparseable verdict can never render green — it degrades to UNVERIFIED, mechanically, so the one failure mode worse than an honest red can't happen quietly. Cross-review by a second agent is the real backstop against a compromised agent's deceptive-but-schema-valid verdict, not a guarantee. Full model, honestly scoped: SECURITY.md and DESIGN.md's "Security posture".

Works with Conductor

aug-conductor-wrkflw pairs with this repo — it plans the work (slices, handoffs), review-pantheon verifies the delivery and pressure-tests the plan before it's built.

On generative AI use. Claude agents built this repo — a from-scratch public rebuild of a private review system the author runs, no code copied over, DESIGN.md as the binding contract, a human coordinator directing. It has gated its own PRs since branch protection landed 2026-07-31 (one disclosed pre-gate exception used the admin hatch and was re-landed through the gate after — CONTRIBUTING.md's "Ground rules" covers it). The git history shows what landed before the gate and what after; that's the point of keeping it. See DESIGN.md for the design story.

License

MIT — © 2026 Garrett Schumacher. See LICENSE.