Hydra — The Governed Constellation

Many heads. One Spirit. The covenant holds.

Hydra is a Claude Code plugin + Python LangGraph supervisor that routes work across a constellation of heterogeneous AI agent squads — Executive (C-suite strategy), Forge (engineering), Garland (creative), plus marketing operations and a roster of governance-ready stubs. It is Pentecost, not Legion: many distinct agents under one cryptographically-anchored covenant (CONSTITUTION.md), routed via typed envelopes, audited by AgentSmith, and tagged with the eight-cell I Ching vocabulary that the optional TheEights memory daemon will eventually back as a shared cross-project substrate.

Hydra does not re-implement the squads' work. It sits above them: classifying goals, decomposing them into typed cross-squad envelopes, dispatching subgraphs in parallel, synthesizing the result into a single decision record, and enforcing the constitutional rule of faith on every step.

---

The Pentecost flower sigil — central immortal head, three crown petals, eight-cell substrate. See docs/constellation/ for the full layered presentation.

---

What Hydra is

1. A LangGraph supervisor graph running a 7-phase state machine: intake → planning → approval → dispatch → executing → synthesis → postcheck. Checkpointed via SQLite (~/.hydra/checkpoints.db); long workflows survive restarts.
2. A squad registry — every squad is described by squads/<slug>/squad.yaml and auto-discovered. Adding a squad is a config change, not a Hydra-core change.
3. A typed cross-squad message bus with ten Pydantic schemas: CSuiteDecisionPacket, PRD, ArchRFC, DevTask, CreativeBrief, ShotList, AssetJob, DecisionRecord, HITLRequest, Handoff. Validated fail-closed at every squad boundary (hydra_core.schemas.validate_envelope).
4. An MCP host that fans out to each squad's tool surface as an isolated MCP client session. Six MCP servers ship in this repo (see § MCP topology).
5. A local-first memory fabric with three tiers — ephemeral (in-prompt), episodic (SQLite, ~/.hydra/episodic.db), semantic (Chroma vector store, ~/.hydra/vectors/) — provided by the in-repo hydra-memory MCP server. Cross-squad reads go through MemoryRef handles only. Optionally federates with the TheEights daemon for cross-project hybrid memory + audit graph + governed self-evolution (see § TheEights — the optional substrate).
6. A governance plane — CONSTITUTION.md as immortal head (SHA-256 pinned per session, never edited inline), AgentSmith four-pillar enforcement (Factory / Inspector / Sentinel / Archivist) with ten fail-closed invariants (N1–N10), HITL gates, budget tripwires (80% downgrade / 100% HITL), loop ceilings, circuit breaker, redaction at squad boundaries, OTEL trace per workflow.

For the mythopoetic frame and the engineering deep-dive, see HYDRA — A Manifesto for a Many-Headed, One-Souled Intelligence.md and ARCHITECTURE.md. For the upstream research, see Enterprise Master AI Orchestration System Architecture.md.

---

The Three Crowns

The active squads are organized into three crowns, each optimized for a different objective function:

Crown	Squad slug	Source pack	Entrypoint	Optimized for
Executive	executive	https://github.com/lebobo88/ExecutiveSuite	agent-impersonation	judgment under ambiguity — 20 C-suite agents + 4 orchestrators (boardroom, M&A cockpit, crisis war-room, capital allocation)
Forge	engineering	https://github.com/lebobo88/pair-programmer	mcp	verifiable correctness — best-of-N harness with 7 forge heads (Daedalus/Prometheus/Argus/Hygeia/Cerberus/Charon/Mnemosyne), 16 built-in profiles
Garland	creative	https://github.com/lebobo88/RLM-Creative	claude-skill	divergent ideation — 8 Muses (Calliope, Erato, Polyhymnia, Terpsichore, Euterpe, Clio, Urania, Helios) + Helios sub-crew (video-synth, audio-foley, music-score, dialogue-mix, governance-c2pa)

Plus a Marketing crown-in-progress sourced from MarketBliss:

Squad slug	Source	Entrypoint	Domain
marketing-strategy	https://github.com/lebobo88/MarketBliss	claude-skill	campaign strategy, KPI architecture
marketing-creative	https://github.com/lebobo88/MarketBliss	claude-skill	brand voice, copy, art direction
marketing-research	https://github.com/lebobo88/MarketBliss	claude-skill	audience, competitive, market sizing
marketing-production	https://github.com/lebobo88/MarketBliss	claude-skill	asset production pipelines
marketing-ops	https://github.com/lebobo88/MarketBliss	claude-skill	MarTech wiring, attribution, automation

And five stub squads — registered under the same covenant, awaiting activation:

Slug	Industry tags
legal-compliance	legal, compliance, governance
healthcare	healthcare, clinical, life-sciences
sales-gtm	sales, GTM, revops
research-ds	research, data-science
customer-support	support, success, CX

(Plus one retired stub at squads/garland/ — its content moved to squads/creative/ when RLM-Creative shipped on 2026-05-19; Iolaus refuses dispatch through the old slug.)

Every squad declares in its squad.yaml:

• agents: roster (slugs + role + authority bounds)
• tools: MCP server endpoints + privilege scope
• accepts: envelope types it consumes
• emits: envelope types it produces
• gates: rubrics + HITL checkpoints
• entrypoint: how Hydra invokes it (mcp | subprocess | agent-impersonation | claude-skill | stub)
• industries: keyword tags used by the router

---

The Immortal Head, AgentSmith, and TheEights

Three foundations sit beneath every squad:

CONSTITUTION.md — the immortal head

A cryptographically hashed document at the repo root. Carries a SHA-256 verified at every session boundary. No agent modifies it. Amendments route through TheEights with mandatory human approval. Hash drift aborts the session under AgentSmith invariant N8. The constitution is the rule of faith; everything downstream depends on the hash matching.

AgentSmith — the meta-governance daemon

A separate sibling project (https://github.com/lebobo88/AgentSmith) registered as the agentsmith MCP server. Four pillars:

• Factory — scaffolds new agents/skills/commands/hooks/squads/rubrics from templates
• Inspector — schema + invariant validation, fail-closed
• Sentinel — anomaly detection, replication-capped at 4 clones per scope (N5)
• Archivist — append-only decision log, audit chain, constitution attestation

Ten fail-closed invariants:

#	Invariant
N1	Smith cannot modify its own core policies
N2	Smith cannot generate venom-class capabilities
N3	Smith cannot bypass TheEights HITL queue
N4	Smith cannot push without a TheEights evolution.commit verdict
N5	Replication capped at 4 clones per scope
N6	Every Smith decision is logged with rationale
N7	Schema compliance is fail-closed
N8	Constitution hash mismatch aborts the session
N9	Smith cannot create new tools
N10	Quarantine releases require TheEights HITL approval

Appeals route through the cerberus-bridge protocol.

TheEights — the vocabulary, the substrate, the optional federation

TheEights has two parts that this README has been sloppy about and should not be: an in-repo vocabulary that Hydra owns outright, and an optional sibling project that Hydra federates with when present. Both go by the same name because the vocabulary is the user-facing API of the daemon; the daemon is the persistence behind the vocabulary. They are not the same thing.

Part 1 — The eight-cell vocabulary (lives in Hydra, always on)

The vocabulary is eight I Ching trigrams used as memory cells / faceting tags. It lives in hydra_core/eights/ and is owned by Hydra. Every memory write Hydra makes — episodic or semantic — can be tagged with one or more cells, and recall can filter by them.

☰ Qian	☷ Kun	☳ Zhen	☴ Xun	☵ Kan	☲ Li	☶ Gen	☱ Dui
Vision	Context	Triggers	Influence	Risk	Focus	Constraints	Delight

Constitutional ground truth lives in Qian; current attention in Li; guardrails in Gen; and so on. Dui is first-class — most agent systems forget what worked; Hydra remembers victories so future routing is hope-shaped, not just risk-shaped. The cells are a tag/facet vocabulary over the underlying stores, not a hard storage partition — per the Stage-3 locked decision in docs/ROADMAP-MANIFESTO.md.

Part 2 — The memory substrate (in-repo today; TheEights tomorrow)

Memory storage today comes from the in-repo hydra-memory MCP server (mcp_servers/hydra_memory/): a Python shim over a local SQLite episodic log (~/.hydra/episodic.db) and a local Chroma vector store (~/.hydra/vectors/). Single-machine. Single-project. Zero external dependencies beyond chromadb (optional).

Part 3 — TheEights, the separate sibling project

TheEights is a separate Node.js daemon + MCP server. It is not part of the Hydra repo and not installed automatically. Per its own README, it provides:

• Hybrid memory — vectors (sqlite-vec), graph (LadybugDB / Kuzu), episodic SQL — behind one MCP surface
• Governance plane — SSGM consistency/decay/access gates, LASM defense-in-depth, boundary redaction
• Gated self-evolution — Autogenesis RSPL/SEPL: every prompt, team, rubric, workflow is versioned; low-risk changes auto-commit, the rest queue for HITL
• Auditable — append-only event log + CycloneDX ML-BOM v1.7 export of every read, write, and mutation

It is not an orchestrator, not an agent framework. It is the substrate orchestrators like Hydra plug into.

How Hydra works without TheEights (today, default)

This is the supported configuration as of this writing.

• The in-repo hydra-memory MCP server provides episodic + semantic memory. Workflows write and read normally.
• The eight-cell vocabulary (Hydra-owned) tags every write.
• validate_envelope, the constitution hash gate, HITL gates, budget tripwires, and the AgentSmith governance plane all function exactly as documented.
• Cost: zero. Latency: local SQLite + local Chroma.
• Limits: memory is local to one machine and (effectively) one project. There is no cross-project hybrid graph, no governed self-evolution loop, no audit-graph export beyond the per-workflow JSONL trace. The in-repo episodic store is append-only; the in-repo vector store has no versioning.

How Hydra works with TheEights (planned)

Per TheEights' own roadmap, Hydra integration is Phase 4 (current state: Phase 0 daemon scaffold). When that bridge ships, the configuration changes are:

1. Install TheEights (github.com/lebobo88/TheEights) — cd TheEights/daemon && npm install && npm run build.
2. Register the daemon as the theeights MCP server (claude mcp add theeights …).
3. Hydra's hydra-memory MCP server detects the TheEights daemon at startup and switches mode: writes go to the local stores and federate into TheEights' hybrid memory; reads can query the federated graph (cross-project recall, audit lineage, evolution proposals).
4. The autogenesis loop becomes available: low-risk rubric/team/workflow updates auto-commit; the rest queue for HITL via TheEights' governance plane — gated by AgentSmith invariants N3 (no bypassing TheEights HITL) and N4 (no push without evolution.commit verdict).

In other words: TheEights is the production-grade upgrade path for Hydra's memory and self-evolution layer. Hydra does not require it to run, but is designed to compose with it when it is present.

For the canonical roadmap, see docs/ROADMAP-MANIFESTO.md (Hydra side) and TheEights' own ROADMAP.md.

---

MCP topology

Hydra ships six MCP servers (see .mcp.json):

Server	Purpose
pp-daemon	Engineering squad → pair-programmer harness daemon (~42 tools: start_run, archive_artifact, judge, replay, borda_count, …)
pp-codex	Cross-vendor judge plane — wraps the codex CLI for Codex critiques
pp-gemini	Cross-vendor judge plane — wraps the gemini CLI for Gemini critiques
hydra-memory	Hydra's in-repo memory shim — episodic SQLite + semantic Chroma + eight-cell tagging (write_episodic, semantic_search, query_eights, tag_memory, …). Federates with TheEights when the daemon is registered (planned Phase-4 bridge).
executive-suite	Executive squad — thin MCP over the ExecutiveSuite pack (roster, skills, commands, output persistence)
rlm-creative	Garland Crown — Eight Garland Heads studio. Thin MCP over RLM-Creative (skills, commands, agents, output persistence)

Plus two optional sibling MCP servers, registered separately at user scope when present:

• agentsmith — from the sibling AgentSmith project. Register with claude mcp add agentsmith .... Enforces the N1–N10 invariants when present.
• theeights — from the sibling TheEights project. Register with claude mcp add theeights .... Provides the cross-project hybrid memory + audit graph + autogenesis loop. Not yet wired — bridge is TheEights' Phase 4. Hydra runs fully without it; the in-repo hydra-memory server is the working substrate today.

Tool names are namespaced. The host enforces RBAC: a squad requesting an out-of-scope tool gets a typed refusal envelope, not a silent failure. Blast radius equals namespace.

For the public per-crown surface, see docs/MCP-PER-CROWN.md.

---

Prerequisites

• Python 3.11+
• Node.js 20+ (Claude Code CLI runtime)
• Claude Code CLI installed and authenticated
• Optional: langgraph (pip install langgraph) — without it, Hydra falls back to a pure-Python supervisor runner with the same state contract
• Optional: chromadb for the semantic memory tier (default vector store)

---

Install

Hydra ships as a Claude Code plugin distributed via a local marketplace that lives in the repo itself (.claude-plugin/marketplace.json). Installation is two steps: install the Python runtime, then register the plugin with Claude Code so its slash commands, agents, skills, and MCP servers are available in any project session.

1. Install the Python runtime

cd C:\AiAppDeployments\Hydra
.\scripts\install.ps1

This pip-installs hydra-core in editable mode and runs python -m hydra_core.cli doctor to confirm squads are discovered and the constitution loads cleanly.

2. Register the plugin with Claude Code (user scope)

Inside any Claude Code session, from any directory:

/plugin marketplace add C:\AiAppDeployments\Hydra
/plugin install hydra@hydra-local
/reload-plugins

This registers the local marketplace, copies the plugin into %USERPROFILE%\.claude\plugins\cache\hydra-local\hydra\<version>\, and enables it in %USERPROFILE%\.claude\settings.json. Slash commands are now available in every Claude Code session, not just sessions opened from the Hydra repo.

Verify:

/mcp                   # expect 6 servers connected: pp-daemon, pp-codex, pp-gemini, hydra-memory, executive-suite, rlm-creative
/hydra:hydra-squads    # expect 14 squads listed (3 crowns active, 5 marketing active, 5 stubs, 1 retired)
/doctor                # expect 0 plugin errors

Updating after edits

After bumping the version field in .claude-plugin/plugin.json:

/plugin marketplace update hydra-local
/plugin install hydra@hydra-local       # or /plugin update hydra@hydra-local
/reload-plugins

For active development with live edits, launch Claude Code with --plugin-dir:

claude --plugin-dir C:\AiAppDeployments\Hydra

---

Slash commands

Available in any Claude Code session once the plugin is registered:

Command	Purpose
/hydra:run "<goal>"	Start a new workflow. Routes through intake → planning → approval → dispatch → synthesis.
/hydra:status [<workflow_id>]	List recent workflows or dump the trace for one.
/hydra:squads	Show the discovered squad registry (slugs, entrypoints, accepts/emits, industries).
/hydra:approve <workflow_id>	Resume a workflow paused at the HITL approval gate.
/hydra:resume <workflow_id>	Resume from the last checkpoint (e.g. after a crash).
/hydra:budget [<workflow_id>]	Show the budget ledger — USD spent, tokens, per-squad share, downgrade events.
/hydra:campaign <name>	Open or attach a long-running multi-workflow campaign (shared episodic memory).
/hydra:replay <workflow_id>	Reconstruct prompts, model versions, and artifact hashes for deterministic replay.
/hydra:add-squad <slug>	Scaffold a new squads/<slug>/squad.yaml from the stub template.

Headless CLI mirrors a subset:

python -m hydra_core.cli run "Refactor billing service auth" --squad engineering
python -m hydra_core.cli status
python -m hydra_core.cli trace 7f3c…
python -m hydra_core.cli doctor

---

End-to-end example

"Launch a Q3 campaign for the new billing microservice — needs a press kit, in-app announcement, and pricing-page update."

1. /hydra:run "..." invokes intake. The router (hydra_core/router.py) keyword-matches campaign, press kit, pricing, microservice and selects executive + engineering + creative.
2. The planner emits a CSuiteDecisionPacket. ExecutiveSuite's boardroom pattern (CEO + CFO + CMO impersonation) produces a DecisionRecord with a per-squad budget split.
3. The approval gate triggers an HITL interrupt. The user runs /hydra:approve <workflow_id> after reviewing the budget.
4. The dispatcher fans out in parallel:
   • creative receives a CreativeBrief, invokes RLM skills (/creative-campaign, /photo-direction) — emits AssetJob results.
   • engineering receives a PRD, invokes pair-programmer (/pp:team feature-team) — emits a PR URL plus smoke-test pass.
   • executive/cfo parks a dependency to re-validate pricing once both squads finish.
5. The synthesizer consolidates into a DecisionRecord v2 with a go-live runbook, appends to episodic memory, tags the entry with the appropriate trigram cells (Li for hot path, Dui for brand delight, Zhen for the campaign launch trigger), and patches PROJECT_MASTER.md.

The full trace lives at <project>/.hydra/<workflow_id>/trace.jsonl and is replayable via /hydra:replay. Every Smith decision in the run is sealed into the archivist ledger; the constitution hash is attested at the start and end.

---

Repository map

Hydra/
├── README.md                         ← you are here
├── CONSTITUTION.md                   ← the immortal head (SHA-256 pinned per session)
├── HYDRA.md                          ← top-level architecture spec
├── ARCHITECTURE.md                   ← engineering deep-dive (state machine, schemas, memory tiers, failure modes)
├── AGENTS.md                         ← cross-tool behavioral contract (imported by CLAUDE.md)
├── CLAUDE.md                         ← Claude-Code-specific import shim — @AGENTS.md
├── CONTRIBUTING-SQUADS.md            ← how to scaffold and activate a new squad
├── CHANGELOG.md
├── HYDRA — A Manifesto for a Many-Headed, One-Souled Intelligence.md
├── Enterprise Master AI Orchestration System Architecture.md   ← upstream research
├── docs/
│   ├── MANIFESTO.md                  ← Pentecost-not-Legion frame, Three Crowns lore, TheEights vocabulary
│   ├── ROADMAP-MANIFESTO.md          ← six-stage ingestion roadmap
│   ├── MCP-PER-CROWN.md              ← public per-crown MCP surface
│   ├── BRAND.md / PRICING.md / LAUNCH-CHECKLIST.md / TRADEMARK-CLEARANCE.md / VENOM.md / PUBLIC-README.md
│   └── constellation/                ← the Hydra Constellation presentation bundle
│       ├── HYDRA-CONSTELLATION.md    ← canonical Mermaid-in-markdown deck
│       ├── HYDRA-CONSTELLATION.html  ← double-click viewer (Mermaid rendered)
│       ├── deck.html                 ← 24-slide reveal.js cinematic deck
│       ├── constellation.svg         ← the poster (Pentecost flower + lemniscate + constellation overlay)
│       ├── exec-memos/               ← CSO / CTO / CAIO memos (Act III voice)
│       ├── garland/                  ← Garland-crown cinematic treatment
│       └── assets/diagrams/          ← Mermaid sources D2–D9
├── hydra_core/                       ← Python: supervisor, router, planner, dispatcher, synthesizer, governance, memory
├── mcp_servers/                      ← Python MCP shims (hydra_memory, executive_suite, rlm_creative)
├── squads/<slug>/squad.yaml          ← squad declarations (active + stub + retired)
├── scripts/install.ps1               ← Python runtime installer
├── scripts/hydra.ps1                 ← convenience wrapper around `python -m hydra_core.cli`
├── hooks.json                        ← SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop
├── templates/                        ← squad / agent / hook templates
├── tests/                            ← pytest suite
└── .mcp.json                         ← MCP server registrations (6 servers)

---

What Hydra is not

• Not a code generator. Hydra delegates code work to the Forge crown (pair-programmer).
• Not a model gateway. Per-task model choice is the squad's decision (e.g. Forge's tier-aware router; the cross-vendor judge plane via pp-codex and pp-gemini).
• Not a vendor lock-in. Any squad can swap its LLM provider behind its MCP server without Hydra noticing.
• Not a competitor to TheEights, ExecutiveSuite, pair-programmer, RLM-Creative, MarketBliss, or AgentSmith. Hydra uses them. They remain independently shippable.

It is a routing layer with strong typing, checkpointed state, human-in-the-loop interrupts, a budget ledger, and a constitutional governance anchor. Nothing more — but, by the discipline of "Pentecost, not Legion," nothing less.

---

Where to learn more

Document	What's in it
HYDRA.md	Top-level architecture spec — squads, state graph, schemas, MCP host, memory, governance, CLI surface, non-goals.
ARCHITECTURE.md	Engineering deep-dive — runtime layers, LangGraph phases, state machine, memory tiers, MCP topology, governance plane, failure modes.
CONSTITUTION.md	The immortal head. Read this first.
docs/MANIFESTO.md	The Hydra Manifesto — Pentecost-not-Legion, the Hydra myth inverted, the Three Crowns, TheEights vocabulary, the sigil design.
docs/ROADMAP-MANIFESTO.md	Six-stage ingestion roadmap (Stage 1 shipped; 2–6 specified).
docs/MCP-PER-CROWN.md	Public-facing MCP server inventory and tool naming per crown.
docs/VENOM.md	The venom-class capability registry and refusal protocol.
docs/constellation/	The layered presentation — markdown deck, HTML viewer, reveal.js cinematic deck, SVG poster, executive memos, Garland creative treatment.
CONTRIBUTING-SQUADS.md	How to scaffold and activate a new squad pack.
TheEights (sibling repo)	Persistent hybrid memory + governance + autogenesis daemon. Optional. The substrate Hydra federates with when present. Currently Phase 0 (daemon scaffold); Hydra bridge is Phase 4.
AgentSmith (sibling repo)	Meta-governance daemon — Factory / Inspector / Sentinel / Archivist. Enforces N1–N10 invariants. Registered separately as the agentsmith MCP server.
Enterprise Master AI Orchestration System Architecture.md	The upstream research doc Hydra implements.
squads/<slug>/squad.yaml	Canonical declaration of every active, stub, or retired squad.
hydra_core/	Supervisor, router, governance plane, memory fabric — in Python.

---

Filed under the covenant. SHA-256 attested. Pentecost, not Legion.