Pantheon
> β οΈ **LEGACY VERSION** β Development on this repository has been paused. The active development continues in the [pantheon-opencode](https://github.com/ils15/pantheon-opencode) repository (OpenCode-only). This legacy version (v4.0) is preserved for reference and archival purposes.
**14 specialized AI agents** that plan, build, review, and deploy features through enforced TDD, persistent project memory, and human approval at every gate.
Stop settling for generalist single-agent coding. Pantheon's conductor-delegate architecture dispatches expert agents with isolated context windows β parallel execution, zero context bleed, and quality gates that block anything below 80% coverage.
Supports **VS Code Copilot**, **OpenCode**, **Claude Code**, **Cursor**, **Windsurf**, **Cline**, and **Continue.dev**.
---
## π v4.0 Changelog
| Sprint | Feature |
|--------|--------|
| 1 | Memory Commands (/pantheon-remember, search, consolidate, forget) |
| 2 | @pantheon/cli npm package |
| 3 | Themis 2.0 (3-layer review + IntentGate) |
| 4 | Background Agents + TODO Enforcer + Hash Edits |
| 5 | Memory Simplification (agents read-only, WAL) |
| 6 | YAGNI + Anti-overengineering (12 patterns) |
**π Themis audit: 100/100**
**ποΈ 9 commands removed:** ping, stop-continuation, subtask, manifest, forge, mirrordeps, praxis, metamorphosis, reflect
**β¨ 14 commands total** β all `/pantheon-*`
## Quick Links
| Resource | Link |
|----------|------|
| π **Agent Reference** | [agents/README.md](agents/README.md) β all 14 agents |
| π **Skills Reference** | [skills/README.md](skills/README.md) β all 40 skills |
| π **Installation Guide** | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
| π **MCP Servers** | [docs/mcp-recommendations.md](docs/mcp-recommendations.md) β recommended MCP servers for each project type |
| π **MCP Tool Registry** | [docs/mcp-tools.md](docs/mcp-tools.md) β canonical MCP tool reference |
| π **MCP User Guide** | [docs/mcp-user-guide.md](docs/mcp-user-guide.md) β adding custom MCP servers |
| β‘ **Quick Start** | [docs/QUICKSTART.md](docs/QUICKSTART.md) |
| π₯οΈ **VS Code** | [docs/platforms/vscode.md](docs/platforms/vscode.md) |
| β‘ **OpenCode** | [docs/platforms/opencode.md](docs/platforms/opencode.md) |
| π€ **Claude Code** | [docs/platforms/claude.md](docs/platforms/claude.md) |
| π§ **Cursor** | [docs/platforms/cursor.md](docs/platforms/cursor.md) |
| π **Windsurf** | [docs/platforms/windsurf.md](docs/platforms/windsurf.md) |
| π€ **Cline** | [docs/platforms/cline.md](docs/platforms/cline.md) |
| π **Continue.dev** | [docs/platforms/continue.md](docs/platforms/continue.md) |
---
## Overview
Traditional single-agent coding produces mediocre results because one agent attempts to
plan, implement, test, review, and document simultaneously. The result is context
fragmentation, skipped tests, and generic code.
**Pantheon** solves this with **specialization**: each agent is an expert at exactly
one thing and is invoked only when that expertise is needed. Agents collaborate through a
conductor-delegate architecture where Zeus (the orchestrator) dispatches work to
specialized sub-agents with isolated context windows, enforced quality gates, and human
approval at every transition.
| Metric | Single Agent | Pantheon |
|--------|-------------|----------|
| Average test coverage | 65β75% | **92%** |
| TDD enforcement | Optional | **Enforced (REDβGREENβREFACTOR)** |
| Code review cadence | End of feature | **After every phase** |
| Bugs reaching production | 3β5 per feature | **Near zero** |
| Context efficiency | 10β20% reasoning | **70β80% reasoning** |
| Parallel execution | Sequential only | **Multi-agent parallel** |
| Documentation | Manual | **Auto-committed in git** |
| Architecture pattern | Monolithic | **Specialized conductor-delegate** |
> Metrics based on internal benchmarks across 50+ feature implementations in the Pantheon
> test suite. Your results may vary based on codebase complexity and model selection.
---
## How It Works
The system operates in defined phases controlled by **you**. Agents work in parallel
within each phase, and every transition is gated by your explicit approval.
```mermaid
---
config:
look: classic
theme: dark
layout: elk
---
flowchart TD
classDef user fill:#2d5a8c,stroke:#5a8ac4,stroke-width:2px,color:#e2e8f0
classDef core fill:#1f2937,stroke:#4b5563,stroke-width:2px,color:#f3f4f6,font-weight:bold
classDef planner fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#dbeafe
classDef ai fill:#4a1a3f,stroke:#c084fc,stroke-width:2px,color:#f3e8ff
classDef executor fill:#7c2d12,stroke:#ea580c,stroke-width:2px,color:#fed7aa
classDef qa fill:#3f1a3e,stroke:#d946a6,stroke-width:2px,color:#f5d1f8
classDef infra fill:#1e3a3f,stroke:#14b8a6,stroke-width:2px,color:#ccfbf1
classDef ops fill:#1e294b,stroke:#60a5fa,stroke-width:1px,color:#bfdbfe
classDef gate fill:#1f1f1f,stroke:#fbbf24,stroke-width:2px,color:#fbbf24,stroke-dasharray: 5 5
User["You / Human"]:::user
Gate0{{"βΈοΈ Gate 0
Approve Decision"}}:::gate
Gate1{{"βΈοΈ Gate 1
Approve Plan"}}:::gate
Gate2{{"βΈοΈ Gate 2
Approve Review"}}:::gate
Gate3{{"βΈοΈ Gate 3
Commit"}}:::gate
subgraph Orchestrator["Orchestrator"]
Zeus["Zeus
Central Coordinator"]:::core
end
subgraph Plan["Planning & Discovery"]
Athena["Athena
Strategic Planner"]:::planner
Apollo["Apollo
Codebase Scout"]:::planner
Nyx["Nyx
Observability"]:::planner
end
subgraph AI["AI Infrastructure"]
Hephaestus["Hephaestus
AI Pipelines
RAG / LangChain"]:::ai
end
subgraph Impl["Implementation
Parallel Execution"]
Hermes["Hermes
Backend APIs"]:::executor
Aphrodite["Aphrodite
Frontend UI"]:::executor
Demeter["Demeter
Database"]:::executor
end
subgraph Quality["Quality & Observability"]
Themis["Themis
Security & Coverage Audit"]:::qa
Nyx["Nyx
Observability
Tracing & Cost"]:::qa
end
subgraph Deploy["Deployment & Release"]
Prometheus["Prometheus
Infrastructure
Docker / CI/CD"]:::infra
Iris["Iris
GitHub Operations
PR / Release"]:::ops
Mnemosyne["Mnemosyne
Documentation
Memory Bank"]:::ops
end
subgraph Express["Express Lane"]
Talos["Talos
Rapid Hotfixes"]:::qa
end
subgraph Domain["Domain Specialist"]
Gaia["Gaia
Remote Sensing"]:::planner
end
User -->|"/implement-feature"| Zeus
Gate0 -->|Approved| Zeus
Zeus -->|Phase 1| Athena
Athena -->|Discovers| Apollo
Apollo -->|Findings| Athena
Athena --> Gate1
Gate1 -->|Approved| Zeus
Zeus -->|"Phase 2 (AI Infrastructure)"| AI
Hephaestus --> Zeus
Zeus -->|"Phase 3 (Implementation)"| Impl
Hermes & Aphrodite & Demeter --> Quality
Impl -.->|Nested Apollo| Apollo
Nyx --> Themis
Themis --> Gate2
Gate2 -->|Approved| Zeus
Zeus -->|"Phase 4 (Deploy & Release)"| Deploy
Prometheus & Iris & Mnemosyne --> Gate3
Gate3 -->|"git commit"| User
User -.->|"/fix"| Express
User -.->|"/plan-architecture"| Domain
```
---
## Platform Support
Pantheon runs on 7 platforms. Here is how each supports the framework's key features:
| Feature | VS Code | OpenCode | Claude Code | Cursor | Windsurf | Cline | Continue.dev |
|---------|:-------:|:--------:|:-----------:|:-----:|:--------:|:-----:|:------------:|
| Custom Agents | β
| β
| β
| β
| β
| β
| β
|
| Skills System | β
| β
| β
| β
| β
| β
| β
|
| Parallel Execution | β
| β
| β οΈ | β
| β | β οΈ | β οΈ |
| Handoff UI | β
| β | β | β | β | β | β |
| MCP Servers | β
| β
| β
| β
| β | β
| β
|
| Agent Hooks | β
| β οΈ | β | β | β | β | β |
| Status | β
Active | β
Active | β
Active | β
Active | β
Active | β
Active | β
Active |
- **VS Code**: Best-in-class. Full subagent orchestration, handoff UI, lifecycle hooks.
- **OpenCode**: Near-complete. Permission blocks via `opencode.json`, tool mapping adapter.
- **Claude Code**: CLI-native. Agent handoff workflow, skills via markdown rules.
- **Cursor**: `.mdc` rules with `alwaysApply` and `globs` for Agent mode.
- **Windsurf**: Active. Markdown-based agent definitions, workflow support via `.windsurf/workflows/`.
- **Cline**: Agent-mode focused. Custom agent definitions, skills via instruction files.
- **Continue.dev**: IDE-agnostic. Rule-based agent configuration, skills via markdown.
> See [docs/platforms/](docs/platforms/) for setup guides and limitations.
---
## 5-Minute Quick Start
```bash
# 1. Clone the repo
git clone https://github.com/ils15/pantheon-legacy.git
cd pantheon
npm install
# 2. Install Pantheon (choose your mode)
npm run install:lite # agents + skills + instructions only (no MCP, no deps)
npm run install:full # everything: agents + skills + MCP servers + venv
npm run install:runtime # just MCP infrastructure (if agents already installed)
# 3. Open your editor and test
# OpenCode: @zeus in chat
# Claude Code: @zeus
# Cursor: @zeus in Agent mode
# VS Code: @zeus in Copilot Chat
# Cline: @zeus
# Windsurf: @zeus in Cascade
```
> **Lite vs Full:** `install:lite` is fast (~5s) and installs only the agent files. `install:full` also creates a Python venv and installs MCP servers (includes `pantheon-memory` for vector search and `pantheon-persistence` for KV cache). Choose lite if you just want the agents without MCP infrastructure.
---
### Approval Gates
| Gate | Phase | What happens |
|---|---|---|
| **Gate 1** | After planning | Athena presents a phased TDD plan. You review and approve (or request changes) before any code is written. |
| **Gate 2** | After implementation & review | Themis audits all changed files for OWASP compliance, coverage >80%, and quality. You validate items only you can judge. |
| **Gate 3** | After deployment prep | Agent suggests a commit message. You execute `git commit` manually and decide when to merge. |
---
## Three Core Principles
### 1. Specialization
Each agent has a focused, narrow context. Hermes knows FastAPI async patterns and nothing
about React. Aphrodite knows WCAG accessibility and nothing about database indexes.
Gaia knows remote sensing and nothing about Docker. This produces better code than a
generalist at every layer.
### 2. TDD β enforced
No phase proceeds without minimum 80% test coverage. The RED β GREEN β REFACTOR cycle is
not optional:
```python
# RED β Write a failing test first
def test_user_password_hashing():
user = User(email="test@example.com", password="secret123")
assert user.password != "secret123" # Should be hashed
assert user.verify_password("secret123") # Verify works
# Run β FAILS β (password is stored in plaintext)
# GREEN β Write the minimum implementation to make it pass
class User:
def __init__(self, email, password):
self.email = email
self.password = hash_password(password) # Minimal: just hash
def verify_password(self, plaintext):
return verify_hash(plaintext, self.password)
# Run β PASSES β
# REFACTOR β Improve without breaking the test
class User:
def __init__(self, email: str, password: str):
if not email or not password:
raise ValueError("Email and password required")
self.email = email
self.password = self._hash_password(password)
@staticmethod
def _hash_password(plaintext: str) -> str:
return bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt())
def verify_password(self, plaintext: str) -> bool:
return bcrypt.checkpw(plaintext.encode(), self.password)
# Run β STILL PASSES β
```
### 3. You stay in control
Every phase produces a structured summary or artifact before anything proceeds. You
review, approve, or request changes β then the next phase begins. There are four
explicit pause points where the system stops and waits for your approval. AI does the
work; you make every architectural and commit decision.
---
## Agent Ecosystem
Pantheon provides **14 specialized agents** organized into tiers. Each agent has a
single responsibility, a dedicated model assignment, a restricted tool set, and explicit
context boundaries.
### Tier Overview
```
Orchestrator
βββ Zeus β coordinates all agents, manages approval gates
Planning & Discovery
βββ Athena β strategic planner, TDD roadmap generation
βββ Apollo β parallel codebase & web research (read-only)
βββ Nyx β observability, tracing, monitoring
AI Infrastructure
βββ Hephaestus β AI pipelines + conversational AI: RAG, LangChain, NLU, dialogue
Implementation (Parallel Executors)
βββ Hermes β backend: FastAPI, Python, async, TDD (REDβGREENβREFACTOR), modern Python stdlib, obsolete lib detection
βββ Aphrodite β frontend: React 19, TypeScript strict, WCAG accessibility, responsive design, TDD
βββ Demeter β database: SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations
Quality & Observability
βββ Themis β code review, OWASP security audit, coverage gate
βββ Nyx β observability: OpenTelemetry, token/cost tracking
Infrastructure, Deployment & Release
βββ Prometheus β infrastructure: Docker, CI/CD, deployment
βββ Iris β GitHub: branches, PRs, releases, issues
βββ Mnemosyne β memory: project docs, ADRs, sprint close
Hotfix (Express Lane)
βββ Talos β rapid fixes: bypasses orchestration for small bugs
Domain Specialist
βββ Gaia β remote sensing: LULC analysis, scientific literature
```
> See [agents/README.md](agents/README.md) for the complete reference β each agent's
> tools, model assignment, behavioral rules, and invocation patterns.
### Architecture Diagram
```mermaid
---
config:
look: classic
theme: dark
layout: elk
---
graph TB
classDef tier0 fill:#1f2937,stroke:#4b5563,stroke-width:2px,color:#f3f4f6,font-weight:bold
classDef tier1 fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#dbeafe
classDef tier1b fill:#4a1a3f,stroke:#c084fc,stroke-width:2px,color:#f3e8ff
classDef tier2 fill:#7c2d12,stroke:#ea580c,stroke-width:2px,color:#fed7aa
classDef tier3 fill:#3f1a3e,stroke:#d946a6,stroke-width:2px,color:#f5d1f8
classDef tier4 fill:#1e3a3f,stroke:#14b8a6,stroke-width:2px,color:#ccfbf1
classDef tier5 fill:#1e294b,stroke:#60a5fa,stroke-width:1px,color:#bfdbfe
classDef tier6 fill:#3f065f,stroke:#a855f7,stroke-width:2px,color:#e9d5ff
O["Zeus
Orchestrator"]:::tier0
subgraph T1["Planning & Discovery"]
A1["Athena
Strategic Planner"]:::tier1
A2["Apollo
Codebase Scout"]:::tier1
A3["Nyx
Observability"]:::tier1
end
subgraph AI["AI Infrastructure"]
H["Hephaestus
AI Pipelines"]:::tier1b
end
subgraph T2["Implementation"]
I1["Hermes
Backend"]:::tier2
I2["Aphrodite
Frontend"]:::tier2
I3["Demeter
Database"]:::tier2
end
subgraph T3["Quality"]
T1a["Themis
Security & Review"]:::tier3
N["Nyx
Observability"]:::tier3
end
subgraph T4["Infrastructure & Release"]
R["Prometheus
Infrastructure"]:::tier4
I["Iris
GitHub Ops"]:::tier4
M["Mnemosyne
Memory"]:::tier4
end
subgraph T5["Express & Specialist"]
T["Talos
Hotfixes"]:::tier5
G["Gaia
Remote Sensing"]:::tier6
end
O --> A1 & A2 & A3 & H & I1 & I2 & I3 & T1a & N & R & I & M
O -.-> T & G
A1 --> A2
style T1 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
style AI fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
style T2 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
style T3 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
style T4 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
style T5 fill:#1a1a1a,stroke:#2d3748,stroke-width:1px
```
---
## π§ Level 3 Vector Memory (v4.0)
Pantheon v4.0.0 introduces a persistent two-tier memory system with semantic retrieval:
### Tier 1 β Auto-Indexed Memory (`/memories/repo/`)
Agent memory is automatically indexed at zero token cost. Every agent writes atomic facts on discovery:
- Tech stack, conventions, build commands
- Architectural decisions and patterns
- Cross-component relationships
### Tier 2 β Compressed Context (`.pantheon/memory-bank/`)
On-demand compression pipeline archives completed phases into structured context:
- **Priority scoring** β CRITICAL/HIGH/LOW budget allocation (deterministic, no LLM)
- **ZZ artifacts** β compressed phase context for agent-to-agent handoff
- **Cross-reference index** (`_xref/index.md`) β entity/decision lookup
### Usage
```bash
@mnemosyne Recall "" --top-k 5 # Retrieve past decisions
@mnemosyne Close sprint: "" # Archive and compress
```
### Benefits
- π« No more lost context between phases
- 𧩠Past decisions surface automatically before planning
- πΎ Zero manual memory management β agents self-index
- π Lossless recovery via git
---
## Skill Ecosystem
Pantheon bundles **40 cross-platform skills** β modular instruction sets that agents load
on demand to perform specialized tasks. Skills are organized into domains:
| Domain | Skills |
|---|---|
| **Orchestration** | agent-coordination, artifact-management, tdd-with-agents, auto-continue, session-goal, task-system, handoff, orchestration-workflow |
| **Backend | **Backend & API** | api-design-patterns, fastapi-async-patterns, database-migration, database-optimization | API** | api-design-patterns, fastapi-async-patterns, database-migration, database-optimization, rag-pipelines |
| **Frontend** | frontend-analyzer, nextjs-seo-optimization, visual-review-pipeline |
| **Infrastructure** | docker-best-practices, streaming-patterns, cache-strategy, mcp-security, mcp-server-development |
| **Quality & Security** | code-review-checklist, quality-gate, security-audit-pro |
| **Planning & Design** | plan-architecture, codemap, init-deep, interview, metis-gap-analysis |
| **Memory & Context** | memory-bank, file-prompts, context-compression |
| **Domain** | remote-sensing-analysis, internet-search |
| **Utilities** | agent-evaluation, agent-observability, wisdom-accumulation, simplify, test-architecture, token-audit |
> See [skills/README.md](skills/README.md) for the complete reference with descriptions
> and usage patterns.
---
## Model Tiers & Presets
Pantheon agents declare abstract model tiers (`fast` / `default` / `coding` / `premium`) rather than
hardcoded model names. The actual model resolved for each tier depends on your platform
subscription (OpenCode Go, Copilot Pro, Claude Pro, etc.).
| Tier | Purpose | Agents | Typical Models |
|------|---------|--------|----------------|
| `premium` | Deep reasoning, critical | Zeus, Athena, Themis | DeepSeek V4 Pro, Claude Opus, o3 |
| `default` | Balanced quality/speed | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Gaia | Kimi K2.6, Claude Sonnet, GPT-4o |
| `coding` | Heavy coding tasks | Hermes, Aphrodite, Demeter, Prometheus, Hephaestus, Talos | DeepSeek V4 Flash, Claude Sonnet |
| `fast` | Quick, cheap ops | Apollo, Iris, Mnemosyne, Talos, Nyx | DeepSeek V4 Flash, MiniMax M2.7, Gemini Flash |
### /forge β Model Presets
Pantheon ships with **`/forge`** β a model configuration command that applies named presets from
`platform/forge.json`. Each preset maps 4 tiers to concrete models across all 14 agents.
**Usage:**
```
/forge opencode-go β Apply a preset (12 available)
/forge default β Reset to account defaults (no models set)
/forge list β List all available presets
/forge status β Show current model configuration
/forge deepseek-flash β Single model for all agents
/forge --zeus anthropic/claude-opus-4-6 β Override a single agent
```
**Available presets:**
| Preset | Premium | Default | Coding | Fast | Requires |
|--------|---------|---------|--------|------|----------|
| `default` | β | β | β | β | Account defaults |
| `opencode-go` | DeepSeek V4 Pro | Kimi K2.6 | DeepSeek V4 Flash | MiniMax M2.7 | OpenCode Go |
| `deepseek-flash` | DeepSeek V4 Flash | DeepSeek V4 Flash | DeepSeek V4 Flash | DeepSeek V4 Flash | OpenCode Go |
| `kimi` | Kimi K2.6 | Kimi K2.5 | Kimi K2.6 | MiniMax M2.7 | OpenCode Go |
| `qwen` | Qwen3.6 Plus | Qwen3.5 Plus | Qwen3.6 Plus | DeepSeek V4 Flash | OpenCode Go |
| `opencode-co` | DeepSeek V4 Pro | Kimi K2.6 | Kimi K2.6 | MiniMax M2.7 | OpenCode Go |
| `claude-pro` | Claude Opus-4 π€ | Claude Sonnet-4 π€ | Claude Sonnet-4 π€ | Claude Haiku-4 π€ | Anthropic key |
| `openai` | o3 (high) | GPT-4o | GPT-4o | GPT-4o-mini | OpenAI key |
| `gemini` | Gemini 3.5 Flash | Gemini 2.5 Flash | Gemini 2.5 Flash | Gemini 3.1 Flash-Lite | Google AI key |
| `github-copilot` | Claude Opus-4 | GPT-4o | GPT-4o | GPT-4o-mini | Copilot ($10/m) |
| `byok-best` | Claude Opus-4 π€ | GPT-4o | GPT-4o | GPT-4o-mini | Anthropic + OpenAI |
| `together-moe` | DeepSeek V4 | Llama 4 Scout | Llama 4 Scout | Llama 3.2 3B | Together key |
> π€ = thinking habilitado
See `platform/forge.json` for full preset definitions and `docs/platforms/` for per-platform setup guides.
---
## Quick Start
### 1. Choose your platform
Pantheon supports 7 platforms. Pick the one that matches your editor:
- **VS Code Copilot** β native `.agent.md` files, full subagent orchestration, lifecycle hooks
- **OpenCode** β config-based agent loading, permission blocks, tool mapping adapter
- **Claude Code** β CLI-based, agent handoff workflow, skills via markdown rules
- **Cursor** β `.mdc` rules with `alwaysApply` and `globs` for Agent mode
- **Windsurf** β markdown agent definitions with workflow support (preview)
- **Cline** β custom agent definitions with skills via instruction files
- **Continue.dev** β IDE-agnostic rule-based agent configuration with markdown skills
> Follow the [Platform Setup Guides](docs/platforms/) for your chosen platform.
### 2. Set up the framework
Installation varies by platform, but generally involves:
```bash
git clone https://github.com/ils15/pantheon-legacy.git
cd pantheon
# Optional: install dependencies for sync/install tools
npm install
```
Then run the platform-specific installer from the guides above.
### 3. Run your first feature
Once agents are loaded in your editor, invoke the orchestrator:
```
@zeus: Implement JWT authentication with refresh tokens and rate limiting
```
Zeus will:
1. Ask Athena to plan the architecture (approval gate)
2. Deploy parallel AI infrastructure + implementation (Hephaestus + Hermes + Aphrodite + Demeter)
3. Have Nyx instrument + Themis review all code (approval gate)
4. Prepare deployment and commit (approval gate)
---
## Commands
Pantheon provides slash commands via OpenCode. On other platforms (Copilot, Cursor, Claude Code), use natural language with the agent name.
| Command | Agent | Description |
|---------|-------|-------------|
| `/pantheon` | zeus | Multi-perspective synthesis (Council) via inline agents |
| `/pantheon-install` | zeus | Sync + install + verify pipeline with `--tier` (none/essential/recommended/full), `--backup`, `--detect`, `--dry-run` |
| `/pantheon-update` | iris | Version bump + changelog + git tag + GitHub Release |
| `/pantheon-deepwork` | zeus | Heavy multi-phase task with persisted checkpoints |
| `/pantheon-focus` | zeus | Pin a session goal |
| `/pantheon-sketch` | athena | Turn rough idea into spec |
| `/pantheon-audit` | themis | Code review + security audit |
| `/pantheon-remember` | mnemosyne | Store a new memory entry
| `/pantheon-search` | mnemosyne | Search across all memories
| `/pantheon-consolidate` | mnemosyne | Compress old memories
| `/pantheon-forget` | mnemosyne | Delete a specific memory
| `/pantheon-optimize` | zeus | Context optimization & token audit |
| `/pantheon-status` | zeus | Show system health and agent status |
| `/cancel` | zeus | Stop auto-continuation |
> **Multi-platform note:** Commands are native to OpenCode. On VS Code Copilot, use `@agent-name` in chat. On Cursor/Claude Code, describe the task in natural language.
### TUI Sidebar Plugin (OpenCode) β Temporarily Disabled
The TUI Sidebar Plugin is currently disabled. It will be re-enabled in a future release once the TUI package compatibility is resolved. For agent discovery, use `AGENTS.md`, `agents/README.md`, or `/pantheon-status` to list all agents.
---
## Repository Structure
```
pantheon/
βββ README.md β this file
βββ AGENTS.md β full agent reference
βββ CHANGELOG.md β release history
βββ CONTRIBUTING.md β how to extend
βββ LICENSE β MIT
βββ package.json β sync & install tooling
βββ opencode.json β OpenCode platform config
βββ plugin.json β marketplace plugin manifest
β
βββ agents/ β 14 agent definitions (.agent.md)
β βββ zeus.agent.md β orchestrator
β βββ athena.agent.md β strategic planner
β βββ apollo.agent.md β codebase & web discovery
β βββ nyx.agent.md β observability
β βββ hermes.agent.md β backend APIs
β βββ aphrodite.agent.md β frontend UI
β βββ demeter.agent.md β database
β βββ themis.agent.md β quality & security review
β βββ prometheus.agent.md β infrastructure
β βββ iris.agent.md β GitHub operations
β βββ mnemosyne.agent.md β memory & documentation
β βββ talos.agent.md β hotfixes
β βββ gaia.agent.md β remote sensing
β βββ hephaestus.agent.md β AI pipelines
β βββ README.md
β
βββ skills/ β 40 cross-platform skill modules
β βββ README.md
β βββ agent-coordination/ * orchestration & coordination
β βββ artifact-management/
β βββ auto-continue/
β βββ handoff/
β βββ orchestration-workflow/
β βββ session-goal/
β βββ task-system/
β βββ tdd-with-agents/
β βββ api-design-patterns/ * backend & API
β βββ fastapi-async-patterns/
β βββ database-migration/
β βββ database-optimization/
β βββ frontend-analyzer/ * frontend
β βββ nextjs-seo-optimization/
β βββ rag-pipelines/ * AI pipelines
β βββ mcp-server-development/
β βββ docker-best-practices/ * infrastructure
β βββ streaming-patterns/
β βββ cache-strategy/
β βββ security-audit-pro/ * security & quality
β βββ code-review-checklist/
β βββ mcp-security/
β βββ quality-gate/
β βββ memory-bank/ * memory & context
β βββ codemap/
β βββ init-deep/
β βββ file-prompts/
β βββ context-compression/
β βββ plan-architecture/ * planning & design
β βββ interview/
β βββ metis-gap-analysis/
β βββ remote-sensing-analysis/ * domain
β βββ internet-search/
β βββ prompt-improver/ * utilities
β βββ agent-evaluation/
β βββ agent-observability/
β βββ simplify/
β βββ test-architecture/
β βββ token-audit/
β βββ wisdom-accumulation/
β βββ */SKILL.md
β
βββ instructions/ β 10 domain coding standards
β βββ agent-return-format.instructions.md
β βββ backend-standards.instructions.md
β βββ checkpoint-standards.instructions.md
β βββ documentation-standards.instructions.md
β βββ frontend-standards.instructions.md
β βββ memory-protocol.instructions.md
β βββ zeus-anti-stall.instructions.md
β βββ zeus-communication-rules.instructions.md
β βββ zeus-council-synthesis.instructions.md
β βββ zeus-timeout-retry.instructions.md
β
βββ prompts/ β 13 agent invocation prompts
β βββ implement-feature.prompt.md
β βββ orchestrate-with-zeus.prompt.md
β βββ debug-issue.prompt.md
β βββ plan-architecture.prompt.md
β βββ optimize-database.prompt.md
β βββ sketch.prompt.md
β βββ focus.prompt.md
β βββ subtask.prompt.md * bounded child task
β βββ quick-discovery-large-codebase.prompt.md
β βββ quick-plan-large-feature.prompt.md
β βββ semantic-summarize.md
β βββ README.md
β βββ dynamic/ * generated prompts
β
βββ platform/ β platform-specific configurations
β βββ optimize-context.sh * context optimization script
β βββ copilot/ * VS Code Copilot configs
β βββ opencode/ * OpenCode configs
β βββ claude/ * Claude Code configs & agents
β βββ cursor/ * Cursor rules
β βββ windsurf/ * Windsurf configs
β βββ continue/ * Continue.dev rules
β βββ cline/ * Cline configs
β βββ _template/ * template for new platforms
β
βββ scripts/ β tooling, automation & lifecycle hooks
β βββ install.mjs * multi-platform installer
β βββ sync-platforms.mjs * agent format sync engine
β βββ validate-sync.mjs * sync integrity check
β βββ hooks/ * agent lifecycle hooks (8 .sh scripts)
β βββ audit-imports.sh
β βββ format-multi-language.sh
β βββ log-session-start.sh
β βββ on-subagent-delegation-start.sh
β βββ on-subagent-delegation-stop.sh
β βββ run-type-check.sh
β βββ scan-secrets.sh
β βββ validate-talos-scope.sh
β
βββ commands/ # 14 interaction commands
β βββ pantheon-cancel.md
β βββ pantheon-audit.md
β βββ pantheon-deepwork.md
β βββ pantheon-focus.md
β βββ pantheon-install.md
β βββ pantheon-remember.md * store memories
β βββ pantheon-consolidate.md * compress memories
β βββ pantheon-forget.md * delete memories
β βββ pantheon-search.md * search memories
β βββ pantheon-optimize.md
β βββ pantheon-sketch.md
β βββ pantheon-status.md
β βββ pantheon-update.md
β βββ pantheon.md
β
βββ docs/
β βββ INSTALLATION.md β generic installation guide
β βββ SETUP.md β step-by-step tutorial
β βββ PLATFORMS.md β platform comparison
β βββ RELEASING.md β versioning & release process
β βββ INDEX.md β documentation index
β βββ platforms/ β platform-specific setup guides
β β βββ vscode.md
β β βββ opencode.md
β β βββ claude.md
β β βββ cursor.md
β β βββ windsurf.md
β β βββ cline.md
β β βββ continue.md
β βββ memory-bank/ β project memory (Mnemosyne domain) β needs init
β βββ 00-project.md * project overview
β βββ 01-active-context.md * current sprint focus (priority file)
β βββ 02-progress-log.md * completed milestones (append-only)
β βββ _notes/ * architectural decisions (ADRs)
β βββ _tasks/ * sprint task records
β
βββ template/ β project templates
β βββ CLAUDE.md
β βββ README.md
β
βββ logs/ β agent session audit logs
β
βββ .github/
β βββ copilot-instructions.md
β βββ workflows/ * CI/CD workflows (10 workflows)
β βββ ci.yml * main CI pipeline
β βββ conformance-matrix.yml * automated release creation
β βββ release.yml * release workflow
β βββ release-gate.yml * version sync enforcement
β βββ pr.yml * pull request checks
β βββ commit-lint.yml * conventional commit enforcement
β βββ docs.yml * documentation build
β βββ codeql.yml * security scanning
β βββ auto-release.yml * automated release auto-release.yml * automated release creation publish
β βββ sync-check.yml * platform sync integrity
β
βββ .vscode/ β VS Code workspace settings
βββ node_modules/ β npm dependencies
```
---
## How Agents Collaborate
### Standard Feature Workflow
```
User β Zeus: "Implement email verification"
1. PLAN: Zeus β Athena β Apollo β Athena β USER (approve gate 1)
2. AI INFRA: Zeus β Hephaestus (if AI components needed)
3. BUILD: Zeus β Hermes + Aphrodite + Demeter (parallel execution)
4. OBSERVE: Nyx instruments tracing, cost, and metrics
5. REVIEW: Themis audits all code β USER (approve gate 2)
6. DEPLOY: Prometheus (infra) + Iris (release) + Mnemosyne (docs)
7. COMMIT: USER (git commit gate 3)
```
### Direct Invocation
Agents can also be invoked directly for focused tasks:
```
@apollo: Find all authentication-related files and usages
@hermes: Create POST /products endpoint with cursor pagination
@aphrodite: Refactor ProductCard for WCAG AA compliance
@demeter: Analyze and fix N+1 queries on orders table
@hephaestus: Build a RAG pipeline with pgvector for product docs
@nyx: Set up OpenTelemetry tracing for the payment service
@themis: Review this PR for security vulnerabilities
@iris: Create branch feat/search and open a draft PR
@gaia: Analyze agreement metrics between MapBiomas and ESA WorldCover
```
### Hotfix Express Lane
For trivial fixes (CSS typos, simple logic bugs), bypass the full orchestration:
```
@talos: Fix the missing breakpoint class on MobileMenuButton
```
---
## Memory System
Pantheon uses a two-tier memory architecture to maintain context across sessions:
| Tier | Location | Content | Access Cost |
|---|---|---|---|
| **Tier 1 β Native** | `/memories/repo/` | Atomic facts (stack, conventions, commands) | Zero (auto-loaded) |
| **Tier 2 β Reference** | `.pantheon/memory-bank/` | Project overview, architecture, active sprint, decisions | Read cost per file |
| **Session** | `/memories/session/` | Current conversation plans, work-in-progress | One read per session |
`01-active-context.md` is the priority file. Agents read it first when starting any task.
It contains the current sprint focus, the most recent architectural decision, active
blockers, and next steps.
Architectural decisions are recorded as ADRs in `.pantheon/memory-bank/_notes/` and are
permanently committed to the repository.
---
## Documentation Maintenance
**Mnemosyne is the documentation owner.** She maintains the README, CHANGELOG, memory
bank, and ADRs. Never manually edit badge numbers or agent/skill counts β always delegate
to Mnemosyne so counts stay accurate and consistent.
### When to invoke Mnemosyne
| Trigger | Invocation |
|---|---|
| Agent added or removed | `@mnemosyne Update README agent count and tier overview` |
| Skill added or removed | `@mnemosyne Update README skills table and count` |
| Version bump | `@mnemosyne Update README version badge and CHANGELOG` |
| Sprint close | `@mnemosyne Update 01-active-context.md and append to 02-progress-log.md` |
| Architectural decision | `@mnemosyne Document decision: [topic]` |
| Task record needed | `@mnemosyne Create task record: [feature] complete` |
### What CI enforces automatically
`release-gate.yml` validates that the version number is consistent across all manifests
(`package.json`, `plugin.json`, `CHANGELOG.md`, and the README badge) on every release.
If they diverge, the release is blocked until Mnemosyne reconciles them.
### Anti-patterns
```
# Wrong β manual badge edit creates drift
Edit README.md line 11: agents-17 β agents-18
# Right β delegate to Mnemosyne
@mnemosyne Update README: added @ares agent, increment agent count to 18
```
```
# Wrong β session output as files
Create IMPLEMENTATION_SUMMARY.md with what we did
# Right β use the memory bank
@mnemosyne Append to 02-progress-log.md: [summary of what was completed]
```
---
## Extending the Framework
### Adding a new agent
1. Create `agents/.agent.md` with YAML frontmatter (tools, model, handoffs)
2. Define behavioral rules and context boundaries
3. Register with Zeus by adding it to his delegation list
4. Test with a sample task
5. Invoke `@mnemosyne Update README agent count and tier overview`
### Adding a new skill
1. Create `skills//SKILL.md` with YAML frontmatter
2. Include 2β3 sentence overview, usage conditions, step-by-step examples
3. Reference relevant agents in the skill body
4. Invoke `@mnemosyne Update README skills table and count`
### Adding a new platform
1. Create `platform//` with platform-specific configs
2. Add a setup guide to `docs/platforms/.md`
3. Extend `scripts/install.mjs` and `scripts/sync-platforms.mjs`
---
## Security & Privacy
- **All processing stays local** β no code sent to external APIs beyond your editor's AI provider
- **No code storage or tracking** β agents operate entirely within your session
- **No automatic commits** β you control every git operation
- **No model training** on your code (per your editor's terms of service)
**Themis enforces on every phase:**
- OWASP Top 10 compliance
- SQL injection, XSS, CSRF prevention
- Hardcoded secret detection
- Minimum 80% test coverage (hard block)
**Agent hooks enforce at runtime (`scripts/hooks/` + `.opencode/plugins/pantheon-hooks.ts`):**
- `scan-secrets.sh` β detects hardcoded secrets and credentials (PreToolUse)
- `validate-talos-scope.sh` β restricts Talos hotfix scope (PreToolUse)
- `on-subagent-delegation-start.sh` β tracks delegation start (PreToolUse)
- `format-multi-language.sh` β auto-formats modified files (PostToolUse)
- `log-session-start.sh` β audit trail of sessions (PostToolUse)
- `on-subagent-delegation-stop.sh` β delegation cleanup (PostToolUse)
The `.opencode/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events. OpenCode auto-discovers plugins from `.opencode/plugins/` when running from the project directory.
---
## FAQ
**How much does this cost?**
You need an existing subscription for your AI coding editor (Copilot, Claude Pro, Cursor
Pro, or OpenCode). Pantheon itself is free and open-source (MIT).
**Can I use this outside VS Code?**
Yes β 7 platforms supported (VS Code, OpenCode, Claude Code, Cursor, Windsurf, Cline, Continue.dev). See
[Platform Setup Guides](docs/platforms/).
**How are platform configs synced?**
Edit `agents/*.agent.md` (the canonical format), then run `npm run sync`.
The sync engine transforms agents into every platform's native format.
**Can I override Themis's code review?**
You can proceed past the review gate even if Themis flags issues β except test coverage.
Below 80% coverage is a hard block by design.
**How long does a typical feature take?**
Simple endpoints: 2β4 hours. Full features (backend + frontend + DB): 6β8 hours. Large
systems: 20β30 hours across multiple sprint sessions.
**What happens if my editor session is interrupted?**
Open phases pause. The memory bank captures the last committed state. Resume by reading
`01-active-context.md` at the start of the next session.
---
## Inspiration & Ecosystem
Pantheon draws from the broader multi-agent landscape while diverging in key ways:
| Framework | Pattern | Key Difference |
|---|---|---|
| **AutoGen** (Microsoft) | Event-driven conversations | Research-grade, Python SDK; Pantheon is config-only |
| **CrewAI** | Role-based crews | Visual editor, self-hosted; Pantheon lives inside your editor |
| **LangGraph** | Stateful actor graphs | Code-first graph DSL; Pantheon uses markdown + YAML config |
| **MetaGPT** | Software company roles | Simulates a company; Pantheon delegates to you at every gate |
| **OpenAI Swarm** | Lightweight handoffs | Sequential only; Pantheon supports parallel subagents |
### Key design decisions
- **Context isolation via subagents** β Apollo runs in isolated context; only findings return
- **Parallel execution** β Independent scopes execute simultaneously
- **Tool minimization** β Each agent has the smallest necessary tool surface
- **Human approval gates** β No auto-merging, no phantom commits
- **Model-role alignment** β Fast models for discovery, powerful models for reasoning
---
## References
| Resource | Purpose |
|---|---|
| [AGENTS.md](AGENTS.md) | Full agent reference β behavior, tools, constraints |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to extend the framework |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Generic installation guide |
| [docs/platforms/](docs/platforms/) | Platform-specific setup guides (7 platforms) |
| [docs/platforms/vscode.md](docs/platforms/vscode.md) | VS Code setup |
| [docs/platforms/opencode.md](docs/platforms/opencode.md) | OpenCode setup |
| [docs/platforms/claude.md](docs/platforms/claude.md) | Claude Code setup |
| [docs/platforms/cursor.md](docs/platforms/cursor.md) | Cursor setup |
| [docs/platforms/windsurf.md](docs/platforms/windsurf.md) | Windsurf setup |
| [docs/platforms/cline.md](docs/platforms/cline.md) | Cline setup |
| [docs/platforms/continue.md](docs/platforms/continue.md) | Continue.dev setup |
| [agents/README.md](agents/README.md) | Agent directory |
| [skills/README.md](skills/README.md) | Skill directory |
| [docs/platforms/](docs/platforms/) | Per-platform setup guides |
| [docs/mcp-tools.md](docs/mcp-tools.md) | Canonical MCP tool registry |
| [docs/mcp-user-guide.md](docs/mcp-user-guide.md) | Adding custom MCP servers |
| [docs/mcp-recommendations.md](docs/mcp-recommendations.md) | Recommended MCP servers per project type |
| [scripts/hooks/](scripts/hooks/) | Agent lifecycle hooks |
| [skills/agent-coordination/SKILL.md](skills/agent-coordination/SKILL.md) | When to use which agent |
| [skills/tdd-with-agents/SKILL.md](skills/tdd-with-agents/SKILL.md) | TDD standards and rules |
---
**License:** MIT
**Architecture Pattern:** Conductor-Delegate