{"id":51004708,"url":"https://github.com/k1lgor/pi-gods","last_synced_at":"2026-06-20T19:01:45.609Z","repository":{"id":356396957,"uuid":"1232335915","full_name":"k1lgor/pi-gods","owner":"k1lgor","description":"13 autonomous AI deities running a spec-driven development pipeline inside pi - from vague idea to shipped release.","archived":false,"fork":false,"pushed_at":"2026-05-07T22:02:55.000Z","size":2383,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T23:25:08.878Z","etag":null,"topics":["ai-pipeline","autonomous-agents","code-generation","multi-agent","pantheon","pi-extension","spec-driven-development","ssd-pipeline"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k1lgor.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T20:37:36.000Z","updated_at":"2026-05-07T22:40:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k1lgor/pi-gods","commit_stats":null,"previous_names":["k1lgor/pi-gods"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/k1lgor/pi-gods","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1lgor%2Fpi-gods","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1lgor%2Fpi-gods/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1lgor%2Fpi-gods/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1lgor%2Fpi-gods/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k1lgor","download_url":"https://codeload.github.com/k1lgor/pi-gods/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k1lgor%2Fpi-gods/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34581934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-pipeline","autonomous-agents","code-generation","multi-agent","pantheon","pi-extension","spec-driven-development","ssd-pipeline"],"created_at":"2026-06-20T19:01:44.993Z","updated_at":"2026-06-20T19:01:45.604Z","avatar_url":"https://github.com/k1lgor.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-gods — Pantheon SDD Agent System\n\n\u003cimg src=\"assets/cover.png\" alt=\"The Pantheon\" width=\"100%\" /\u003e\n\nA pi extension implementing a fully autonomous multi-agent SDD pipeline.\nThirteen Roman/Greek deities, each owning their domain. Tool boundaries\nenforced programmatically. Handoffs detected from the filesystem.\nZero manual routing for the happy path.\n\n## The Pantheon\n\nThirteen Roman/Greek deities, each commanding their domain. Tool boundaries enforce separation. Handoffs happen at the filesystem — no custom machinery needed.\n\n### 🔍 Read-Only\n\n| Deity     | Role         | Purpose                                                                                                                                               |\n| --------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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. |\n\n### ✏️ Read/Write\n\n| Deity          | Role            | Purpose                                                                                                                                                                                     |\n| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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.                      |\n| **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. |\n| **Morpheus**   | UX Designer     | God of dreams, shaper of human experience. Constructs entire worlds — designs flows (trigger → steps → success → failure), not screens.                                                     |\n| **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.                                 |\n| **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.                               |\n| **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.                         |\n\n### ⚡ Full Access\n\n| Deity          | Role             | Purpose                                                                                                                                                                           |\n| -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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.             |\n| **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. |\n| **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.                     |\n| **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.                        |\n| **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.                        |\n| **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.                          |\n\n## Autonomous Pipeline\n\n```\nUser: \"Build a todo app with auth\"\n  │\n  ▼   ZERO manual switches below\nJanus      → reads project state → writes .pantheon/handoff.json\n  │          agent_end detects file → AUTO-SWITCH\nMinerva    → asks at most 1 critical question (pipeline pauses)\n  │          writes .pantheon/prd.md → handoff → AUTO-SWITCH\nPrometheus → writes .pantheon/architecture.md → AUTO-SWITCH\nMorpheus   → writes .pantheon/ux-spec.md + DESIGN.md → AUTO-SWITCH\nPlutus     → writes .pantheon/epics.md → AUTO-SWITCH\nCalliope   → writes .pantheon/stories/*.md → AUTO-SWITCH\nVulcan     → implements, tests pass → AUTO-SWITCH\nNemesis    → adversarial QA (0 defects) → AUTO-SWITCH\nMercury    → commits, changelog, tags release → handoff to Janus\n  │\n  ▼\nDONE. Repeat for next epic.\n```\n\n**The pipeline only stops when a deity asks a clarifying question.**\nEverything else runs autonomously.\n\n## How Handoffs Work\n\nHandoffs happen automatically — no manual routing needed for the happy path.\n\n### Tool-based handoff (recommended)\n\nUse the `pantheon_handoff` tool (available to all deities):\n\n```\npantheon_handoff({\n  to: \"vulcan\",\n  reason: \"Story implemented — ready for QA\",\n  context: \"Everything the next deity needs to know...\"\n})\n```\n\nThe tool sets a handoff flag and returns `terminate: true`, ending the\ncurrent turn immediately — Janus stops without generating a response.\nThe `agent_end` hook switches to the target deity and defers the handoff\nmessage with `setTimeout(0)`. By the time it fires, the agent is fully idle\nand the next turn starts immediately — no user input needed.\n\n### File-based handoff (alternative)\n\nDeities can also create a handoff marker using the standard `write` tool:\n\n```json\n// .pantheon/handoff.json\n{\n  \"from\": \"minerva\",\n  \"to\": \"prometheus\",\n  \"reason\": \"PRD complete — ready for architecture\",\n  \"context\": \"Everything the next deity needs to know...\"\n}\n```\n\nThe `agent_end` hook detects the file, parses it, auto-switches the active\ndeity, and clears the file. No custom pi tools needed — `write` and `bash`\nare always available.\n\n**All deities can create handoff files** regardless of their tool policy.\n`.pantheon/handoff.json` is whitelisted as pipeline metadata, not a\nproject artifact.\n\n## The `.pantheon/` Directory\n\nAll pipeline artifacts live in one hidden directory — the temple where\nthe gods work:\n\n```\n.pantheon/\n├── handoff.json          # Handoff marker (created/cleaned per cycle)\n├── prd.md                # Minerva\n├── architecture.md       # Prometheus\n├── ux-spec.md            # Morpheus\n├── DESIGN.md             # Morpheus (design tokens)\n├── epics.md              # Plutus\n├── qa-report-*.md        # Nemesis\n├── threat-model.md       # Mars Ultor\n├── data-model.md         # Aquarius\n├── security/             # Mars Ultor (audit logs)\n├── spikes/               # Prometheus (tech investigations)\n└── stories/              # Calliope\n    ├── 1.1-server-auth-api.md\n    ├── 1.2-auth-middleware.md\n    └── 1.3-react-auth-ui.md\n```\n\nThe dot prefix keeps it hidden in file listings. Everything the pipeline\nproduces — specs, handoffs, QA reports, stories — lives in one place.\nUser-facing documentation (README, API docs, examples) stays at the\nproject root.\n\n## Tool Boundary Enforcement\n\nEvery deity has programmatic boundaries enforced at the `tool_call` hook:\n\n| Policy      | Allowed Tools                                          |\n| ----------- | ------------------------------------------------------ |\n| `readonly`  | `read`, (inspect only), Pantheon tools                 |\n| `readwrite` | Above + `write`, `edit`                                |\n| `full`      | All tools (destructive patterns still blocked for all) |\n\n**Universal guardrails (all deities):**\n\n- Destructive commands blocked: `rm -rf`, `git push --force`, `DROP TABLE`, fork bombs, pipe-to-bash\n- Forbidden paths per deity: e.g., Vulcan can't write to `.pantheon/architecture.md`\n- All parameterized — domain-appropriate error messages\n\n**Example:** Janus tries `bash` → blocked: _\"Janus (Orchestrator) has 'readonly' access — 'bash' requires higher privileges.\"_\n\n## Commands\n\n| Command        | Action                                               |\n| -------------- | ---------------------------------------------------- |\n| `/gods`        | List all 13 deities with active one highlighted      |\n| `/gods \u003cname\u003e` | Switch to a deity (e.g., `/gods vulcan`)             |\n| `/gods status` | Show current deity, pending handoffs, gate checklist |\n| `/gods next`   | Janus inspects project and recommends next deity     |\n\n## Tools\n\n| Tool               | Description                                                                                                                                       |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `pantheon_status`  | Display active deity, tool policy, pending handoffs, and routing info                                                                             |\n| `pantheon_handoff` | Hand off to another deity. Accepts `to`, `reason`, and `context` parameters. The handoff takes effect immediately — no waiting for the next turn. |\n\n## Extension File Structure\n\n```\npi-gods/\n├── index.ts              # Entry: hook registration + /gods command\n├── state.ts              # Session-persistent deity state (survives /reload)\n├── system-prompt.ts      # Builds per-deity system prompt with voice + gates\n├── types.ts              # Core types, tool sets, destructive patterns\n├── pantheon/\n│   ├── index.ts          # Registry barrel\n│   └── definitions.ts    # All 13 deity definitions (pure TypeScript, no YAML)\n├── guards/\n│   ├── index.ts          # Barrel\n│   └── tool-policy.ts    # Tool boundary enforcement + handoff whitelist\n└── pipeline/\n    ├── index.ts          # Barrel\n    ├── handoff.ts        # File-based handoff detection + creation\n    └── orchestrator.ts   # Janus routing + state persistence helpers\n```\n\n## Deity Definition Shape\n\nEach deity is a typed TypeScript object — no YAML parsing, no frontmatter\nextraction, no file-per-agent. A single source of truth in `pantheon/definitions.ts`:\n\n```typescript\n{\n  name: \"vulcan\",           // /gods vulcan\n  title: \"Developer\",       // Display role\n  role: \"...\",              // Full role description\n  domain: \"...\",            // Mythological justification\n  toolPolicy: \"full\",       // readonly | readwrite | full\n  blockedTools: [],         // Explicitly blocked tools\n  blockedPatterns: [],      // Regex patterns to block\n  forbiddenPaths: [],       // Paths this deity can't write to\n  handoffs: [...],          // Handoff rules (when X → route to Y)\n  handoffGate: [],          // Checklist before calling handoff\n  voice: [...],             // Voice DNA (how the deity speaks)\n  activation: \"...\",        // First-turn behavior\n  capabilities: [...],      // What the deity CAN do\n  restrictions: [...],      // What the deity MUST NOT do\n  systemPrompt: \"...\",      // Core operating principles\n}\n```\n\n## Key Design Decisions\n\n1. **File-based handoff over custom pi tools.** Custom tools depend on pi\n   registration quirks. Standard `write`/`bash` always work. The\n   `.pantheon/handoff.json` file is visible and debuggable.\n\n2. **Roman methodology over Greek.** Deities chosen for domain fit:\n   Janus (two-faced gatekeeper = router), Plutus (blind wealth god =\n   unbiased prioritizer), Mars Ultor (defensive war = security), Morpheus\n   (dream-shaper = UX). No forced mappings.\n\n3. **Typed definitions over YAML files.** No parsing, no validation\n   overhead, no file-per-agent bloat. One file, 13 definitions, full\n   TypeScript safety.\n\n4. **Single artifact directory.** `.pantheon/` holds everything the\n   pipeline creates. No scattering across `docs/`, `specs/`, `design/`.\n   The handoff marker lives alongside the artifacts it governs.\n\n5. **Gate checklists auto-generated.** Each deity's handoff gate is\n   inferred from their capabilities and handoff rules. Explicit\n   `handoffGate` arrays override the defaults when needed.\n\n## Inspiration\n\npi-gods was inspired by [ATLAS_OS](https://github.com/lucapohl-angel/ATLAS_OS)\n— an SDD CLI that uses Greek deities for its spec-driven development\npipeline. The concept of routing work through named specialists with defined\nboundaries and handoff triggers comes from ATLAS_OS's architecture.\npi-gods adapts this to pi extensions with file-based handoff, enforced tool\npolicies, and an autonomous auto-handoff engine.\n\n## Installation\n\n### Via git (recommended)\n\n```bash\npi install git:github.com/k1lgor/pi-gods\n```\n\n### Via npm\n\n```bash\npi install npm:pi-gods\n```\n\n### Local\n\n```bash\ngit clone https://github.com/k1lgor/pi-gods.git\npi install ~/path/to/pi-gods\n```\n\nNo dependencies beyond what pi provides (`@earendil-works/pi-coding-agent`,\n`typebox`, Node.js built-ins).\n\n## License\n\npi-gods is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk1lgor%2Fpi-gods","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk1lgor%2Fpi-gods","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk1lgor%2Fpi-gods/lists"}