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: a missing or malformed verdict can never render green — the fail-closed rule below is mechanical, not a review-quality promise. 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. 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

Zero footprint — drop this into .github/workflows/review-gate.yml (this is the whole install; gated on a repo variable so adding the file never silently starts gating PRs):

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 }}

Set the REVIEW_GATE_ENABLED repo variable to true once the token secret is in place. 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 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).

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

Where to go

How the gate stays honest

• Reviewing untrusted PR content runs read-only by default (execution=readonly).
• That tool-scoping covers both surfaces — the CLI and the published action — which invoke Claude; non-Claude provider lanes aren't covered.
• Nothing here eliminates a fully-compromised agent handing back a deceptive-but-schema-valid verdict — cross-review by a second agent is the real backstop, not a guarantee.

Full technical detail, 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. review-pantheon is a public rebuild of a private review system the author already runs — ported and re-implemented from scratch for open distribution (no code copied over), with DESIGN.md as the rebuild's binding contract. Claude-based agents did the rebuild work, with the author directing as coordinator — where a commit message says "the coordinator", that's the human in the loop. The gate could not review this repo until it existed: of the first 44 commits, 23 went straight to dev with no pull request, and 14 of those touch code — including the original CLI, the Action, the installer, and bootstrap.sh. Since branch protection landed (2026-07-31), almost every change has gone through the gate: Artemis and Apollo on a pull request, fail-closed. One admin-bypass direct push has landed since (1148e19, a .gitignore hardening commit — its content was re-landed through the gate in #63/#64) — CONTRIBUTING.md's "Ground rules" section discloses the emergency-hatch bypass this used. The history shows which is which.

The vulnerable ${{ }}-interpolation pattern that let PR content reach a shell string directly has been present since action/review.yml was first added (a94821c), carried forward through 88e0b01's restructure — found and fixed by this repo's own twin gate in 4b35500, once there was a gate to find it. Human-directed, spec-driven, self-gated, and late to gate itself.

License

MIT — © 2026 Garrett Schumacher. See LICENSE.