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.

Quick start

Zero footprint — drop this into a workflow file (plus a PR trigger and pull-requests: write):

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

(@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), every change has gone through the gate: Artemis and Apollo on a pull request, fail-closed, no direct pushes. The history shows which is which.

88e0b01, one of those 14, is the commit that introduced a shell-injection defect in the vendored workflow — found and fixed later by this repo's own twin gate, 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.