Pantheon
Read this document in Portuguese: README.pt-BR.md.
Pantheon is an open-source, deterministic agentic development framework for Claude Code and Codex. It turns software work into a file-backed lifecycle: discuss the scope, write a specification, generate a plan, audit it, sign the contract, execute tasks, verify the result, and preserve enough state to resume later without losing context.
Pantheon is intentionally lightweight. The framework is made of Markdown instructions, command files, schemas, shell scripts, PowerShell scripts, and a small Node.js metrics helper. It does not require a server, database, or package installation to run its core workflow.
What Pantheon Solves
Agentic coding sessions often fail for predictable reasons: vague scope, skipped planning, silent drift from requirements, weak verification, and lost context after long sessions. Pantheon addresses those problems by assigning each responsibility to a specialist agent role and by making every phase write its state to files.
Pantheon is useful when you want:
- Spec-first execution instead of ad hoc code generation.
- Explicit approval gates before implementation begins.
- A clean separation between planning, auditing, building, verification, and memory.
- A resumable workflow for long-running development tasks.
- Stronger safeguards around command execution and file modification.
- A repeatable process that works in both Claude Code and Codex.
Core Principles
- File-backed state: Specs, plans, contracts, audits, execution summaries, verification reports, handoffs, and progress logs are written as Markdown files.
- Strict role boundaries: Each agent has a narrow authority model. Builders build, auditors audit, sensors run checks, and orchestrators coordinate.
- No hidden approval: A plan must pass audit and contract signing before normal execution.
- Verification before completion: Work is not considered complete until configured checks have run and the verification report has been judged.
- Resumability: Hermes keeps progress and handoff files so another session can continue from the last known state.
- Self-contained core: Pantheon avoids third-party runtime dependencies for the framework itself.
Agent Roles
Pantheon models its workflow as a small council of specialist agents. Zeus is the entry point; the other agents are invoked through the lifecycle.
| Agent | Role | Main Responsibility | Writes |
|---|
| Zeus | Orchestrator | Validates preconditions, drives phase transitions, routes commands to specialist agents, and blocks process violations. | .pantheon/ state files, lifecycle outputs |
| Athena | Auditor and Judge | Audits PLAN.md before execution and judges VERIFY-REPORT.md after verification. | AUDIT.md, judgment section of VERIFY-REPORT.md |
| Themis | Scope Signer | Compares SPEC.md and PLAN.md, detects missing requirements or scope drift, and signs the contract only when coverage is exact. | CONTRACT.md |
| Hephaestus | Builder | Executes approved tasks, edits planned files, runs task checks, records results, and commits completed tasks. | Source changes, EXECUTION-SUMMARY.md, task status updates |
| Hermes | Messenger and Memory | Tracks progress, creates handoffs, compresses completed phase context, manages checkpoints, and restores session state. | PROGRESS.md, HANDOFF.md, .pantheon/memory/* |
| Apollo | Sensor | Runs configured lint, test, typecheck, build, or task verification commands and reports raw results objectively. | Sensor section of VERIFY-REPORT.md |
Zeus
Zeus owns orchestration. Every /pantheon:* command starts with Zeus validating the current workspace state and the command preconditions. Zeus does not implement code, run shell commands, approve plans, or judge test output. Its job is to keep the process deterministic and route work to the right agent.
Athena
Athena has two modes:
- Audit Mode: Before execution, Athena checks the generated plan for blockers, major risks, missing acceptance criteria, unsafe file changes, dependency issues, and other rejection conditions.
- Judge Mode: After Apollo runs sensors, Athena decides whether the phase passes verification.
Athena cannot edit code or ignore failed sensors. A blocker or major finding rejects the plan or fails verification.
Themis
Themis is the scope control layer. It maps requirements from SPEC.md to tasks in PLAN.md and rejects plans that either miss requirements or introduce unapproved work. When the plan exactly matches the specification, Themis writes a signed CONTRACT.md.
Hephaestus
