pi-gods — Pantheon SDD Agent System

A pi extension implementing a fully autonomous multi-agent SDD pipeline. Thirteen Roman/Greek deities, each owning their domain. Tool boundaries enforced programmatically. Handoffs detected from the filesystem. Zero manual routing for the happy path.

The Pantheon

Thirteen Roman/Greek deities, each commanding their domain. Tool boundaries enforce separation. Handoffs happen at the filesystem — no custom machinery needed.

🔍 Read-Only

Deity	Role	Purpose
Janus	Orchestrator	God of doorways, transitions, beginnings and endings. The two-faced gate — reads project state and routes to the right specialist. Never writes code.

✏️ Read/Write

Deity	Role	Purpose
Minerva	Product Manager	Goddess of wisdom, strategic warfare, and crafts. Born fully armed from Jupiter's head — turns vague requests into crisp PRDs. Asks until every section writes itself.
Prometheus	Architect	Titan of forethought — his name means "one who thinks ahead." Shaped humanity and gave them fire. Translates PRDs into the simplest viable blueprint, naming every component and trade-off.
Morpheus	UX Designer	God of dreams, shaper of human experience. Constructs entire worlds — designs flows (trigger → steps → success → failure), not screens.
Plutus	Product Owner	God of wealth — not money, but VALUE. Blinded by Zeus to distribute riches without bias. Orders backlog by first-shippable-value. Cuts scope transparently.
Vesta	Scrum Master	Goddess of the hearth and sacred flame — the fire at the center of Rome. Keeps process integrity and team health. Flags blockers before stories reach Vulcan.
Calliope	Story Author	Muse of epic poetry, eldest of the nine — "beautiful-voiced." Writes hyper-detailed stories carrying goal, ACs, architecture excerpts, and out-of-scope guardrails.

⚡ Full Access

Deity	Role	Purpose
Vulcan	Developer	God of fire and the forge. Built his kingdom under Mount Etna and forged Jupiter's thunderbolts. Picks a story, implements end-to-end, never leaves the forge broken.
Nemesis	QA	Goddess of retribution against hubris. Punishes those who claim they are finished when they are not. Takes "done" and tries to falsify it — every defect earns a regression test.
Aquarius	Data Engineer	The water-bearer, Ganymede, cup-bearer to Olympus. Data is water — must flow, be pure, never stagnate. Owns schemas, migrations, queries, and data integrity.
Mars Ultor	Security	Mars the Avenger — the aspect that defends Rome. Produces STRIDE threat models, scans CVEs, audits secrets and auth flows. No critical or high risks ship.
Mercury	Release Engineer	Messenger of the gods, fastest of them all, winged sandals. Delivers — conventional commits, changelogs, semver tags, npm publish. One concern per commit.
Apollo	Documentation	God of knowledge, truth, and clarity. His oracle spoke in riddles, but he demands precision. Every example must run. Every API doc matches real symbols.

Autonomous Pipeline

User: "Build a todo app with auth"
  │
  ▼   ZERO manual switches below
Janus      → reads project state → writes .pantheon/handoff.json
  │          agent_end detects file → AUTO-SWITCH
Minerva    → asks at most 1 critical question (pipeline pauses)
  │          writes .pantheon/prd.md → handoff → AUTO-SWITCH
Prometheus → writes .pantheon/architecture.md → AUTO-SWITCH
Morpheus   → writes .pantheon/ux-spec.md + DESIGN.md → AUTO-SWITCH
Plutus     → writes .pantheon/epics.md → AUTO-SWITCH
Calliope   → writes .pantheon/stories/*.md → AUTO-SWITCH
Vulcan     → implements, tests pass → AUTO-SWITCH
Nemesis    → adversarial QA (0 defects) → AUTO-SWITCH
Mercury    → commits, changelog, tags release → handoff to Janus
  │
  ▼
DONE. Repeat for next epic.

The pipeline only stops when a deity asks a clarifying question. Everything else runs autonomously.

How Handoffs Work

Handoffs happen automatically — no manual routing needed for the happy path.

Tool-based handoff (recommended)

Use the pantheon_handoff tool (available to all deities):

pantheon_handoff({
  to: "vulcan",
  reason: "Story implemented — ready for QA",
  context: "Everything the next deity needs to know..."
})

The tool sets a handoff flag and returns terminate: true, ending the current turn immediately — Janus stops without generating a response. The agent_end hook switches to the target deity and defers the handoff message with setTimeout(0). By the time it fires, the agent is fully idle and the next turn starts immediately — no user input needed.

File-based handoff (alternative)

Deities can also create a handoff marker using the standard write tool:

// .pantheon/handoff.json
{
  "from": "minerva",
  "to": "prometheus",
  "reason": "PRD complete — ready for architecture",
  "context": "Everything the next deity needs to know..."
}

The agent_end hook detects the file, parses it, auto-switches the active deity, and clears the file. No custom pi tools needed — write and bash are always available.

All deities can create handoff files regardless of their tool policy. .pantheon/handoff.json is whitelisted as pipeline metadata, not a project artifact.

The .pantheon/ Directory

All pipeline artifacts live in one hidden directory — the temple where the gods work:

.pantheon/
├── handoff.json          # Handoff marker (created/cleaned per cycle)
├── prd.md                # Minerva
├── architecture.md       # Prometheus
├── ux-spec.md            # Morpheus
├── DESIGN.md             # Morpheus (design tokens)
├── epics.md              # Plutus
├── qa-report-*.md        # Nemesis
├── threat-model.md       # Mars Ultor
├── data-model.md         # Aquarius
├── security/             # Mars Ultor (audit logs)
├── spikes/               # Prometheus (tech investigations)
└── stories/              # Calliope
    ├── 1.1-server-auth-api.md
    ├── 1.2-auth-middleware.md
    └── 1.3-react-auth-ui.md

The dot prefix keeps it hidden in file listings. Everything the pipeline produces — specs, handoffs, QA reports, stories — lives in one place. User-facing documentation (README, API docs, examples) stays at the project root.

Tool Boundary Enforcement

Every deity has programmatic boundaries enforced at the tool_call hook:

Policy	Allowed Tools
readonly	read, (inspect only), Pantheon tools
readwrite	Above + write, edit
full	All tools (destructive patterns still blocked for all)

Universal guardrails (all deities):

• Destructive commands blocked: rm -rf, git push --force, DROP TABLE, fork bombs, pipe-to-bash
• Forbidden paths per deity: e.g., Vulcan can't write to .pantheon/architecture.md
• All parameterized — domain-appropriate error messages

Example: Janus tries bash → blocked: "Janus (Orchestrator) has 'readonly' access — 'bash' requires higher privileges."

Commands

Command	Action
/gods	List all 13 deities with active one highlighted
/gods <name>	Switch to a deity (e.g., /gods vulcan)
/gods status	Show current deity, pending handoffs, gate checklist
/gods next	Janus inspects project and recommends next deity

Tools

Tool	Description
pantheon_status	Display active deity, tool policy, pending handoffs, and routing info
pantheon_handoff	Hand off to another deity. Accepts to, reason, and context parameters. The handoff takes effect immediately — no waiting for the next turn.

Extension File Structure

pi-gods/
├── index.ts              # Entry: hook registration + /gods command
├── state.ts              # Session-persistent deity state (survives /reload)
├── system-prompt.ts      # Builds per-deity system prompt with voice + gates
├── types.ts              # Core types, tool sets, destructive patterns
├── pantheon/
│   ├── index.ts          # Registry barrel
│   └── definitions.ts    # All 13 deity definitions (pure TypeScript, no YAML)
├── guards/
│   ├── index.ts          # Barrel
│   └── tool-policy.ts    # Tool boundary enforcement + handoff whitelist
└── pipeline/
    ├── index.ts          # Barrel
    ├── handoff.ts        # File-based handoff detection + creation
    └── orchestrator.ts   # Janus routing + state persistence helpers

Deity Definition Shape

Each deity is a typed TypeScript object — no YAML parsing, no frontmatter extraction, no file-per-agent. A single source of truth in pantheon/definitions.ts:

{
  name: "vulcan",           // /gods vulcan
  title: "Developer",       // Display role
  role: "...",              // Full role description
  domain: "...",            // Mythological justification
  toolPolicy: "full",       // readonly | readwrite | full
  blockedTools: [],         // Explicitly blocked tools
  blockedPatterns: [],      // Regex patterns to block
  forbiddenPaths: [],       // Paths this deity can't write to
  handoffs: [...],          // Handoff rules (when X → route to Y)
  handoffGate: [],          // Checklist before calling handoff
  voice: [...],             // Voice DNA (how the deity speaks)
  activation: "...",        // First-turn behavior
  capabilities: [...],      // What the deity CAN do
  restrictions: [...],      // What the deity MUST NOT do
  systemPrompt: "...",      // Core operating principles
}

Key Design Decisions

1. File-based handoff over custom pi tools. Custom tools depend on pi registration quirks. Standard write/bash always work. The .pantheon/handoff.json file is visible and debuggable.

2. Roman methodology over Greek. Deities chosen for domain fit: Janus (two-faced gatekeeper = router), Plutus (blind wealth god = unbiased prioritizer), Mars Ultor (defensive war = security), Morpheus (dream-shaper = UX). No forced mappings.

3. Typed definitions over YAML files. No parsing, no validation overhead, no file-per-agent bloat. One file, 13 definitions, full TypeScript safety.

4. Single artifact directory. .pantheon/ holds everything the pipeline creates. No scattering across docs/, specs/, design/. The handoff marker lives alongside the artifacts it governs.

5. Gate checklists auto-generated. Each deity's handoff gate is inferred from their capabilities and handoff rules. Explicit handoffGate arrays override the defaults when needed.

Inspiration

pi-gods was inspired by ATLAS_OS — an SDD CLI that uses Greek deities for its spec-driven development pipeline. The concept of routing work through named specialists with defined boundaries and handoff triggers comes from ATLAS_OS's architecture. pi-gods adapts this to pi extensions with file-based handoff, enforced tool policies, and an autonomous auto-handoff engine.

Installation

Via git (recommended)

pi install git:github.com/k1lgor/pi-gods

Via npm

pi install npm:pi-gods

Local

git clone https://github.com/k1lgor/pi-gods.git
pi install ~/path/to/pi-gods

No dependencies beyond what pi provides (@earendil-works/pi-coding-agent, typebox, Node.js built-ins).

License

pi-gods is licensed under the MIT License. See the LICENSE file for details.