Imported from lebobo88/Hydra (AGENTS.md). Install upstream with npx skills add lebobo88/Hydra. Copyright stays with the author.

AGENTS.md — Hydra Cross-Tool Behavioral Contract

This file is the single source of truth for any AI agent (Claude Code, Codex, Gemini, Copilot, etc.) working inside the Hydra repo. Tool-specific shims (CLAUDE.md, etc.) import from this file.

What Hydra Is

A central LangGraph supervisor + Claude Code plugin that routes work across heterogeneous AI agent squads (executive, engineering, garland, plus stubs). Hydra does NOT do the squads' work; it routes, governs, and synthesizes.

See HYDRA.md for the master spec and ARCHITECTURE.md for the layered design.

Squads

14 squads: 11 active, 3 stubs (healthcare, sales-gtm, research-ds). The five marketing-* packs are filesystem symlinks into the MarketBliss checkout. rlm-gaming is the Arcade Crown — RLM-Gaming's 20-agent game-development studio squad (claude-skill entrypoint). legal-compliance is the Curia — Senate's Law-of-Citations council (9 jurists: Papinian, Gaius, Ulpian, Angerona, Minerva, Scaevola, Cicero, Cato, Tribonian, + consilium Paulus/Modestinus/Janus); it deliberates by majority with Papinian's tiebreak and halts at the Tribune's Veto. customer-support is the Xenia Hearth — an active consumer squad (not a stub) for ticket triage, recommendation, and approval-gated execution, with server-side WS-AUTH capability enforcement on send_response / execute_approved.

Hard Rules

1. Never edit CONSTITUTION.md. It is the immortal head — the cryptographically hashed rule of faith. The user authors it; agents read it; the SHA-256 must be stable across a session. Proposed edits surface as HITL with reason=constitution_breach. See hydra_core/immortal_head.py.
2. Never bypass HITL. A paused workflow resumes only via /hydra:approve or /hydra:resume.
3. Never cross a squad boundary with a raw blob. Use MemoryRef handles.
4. Never modify the squad registry inline. Use /hydra:add-squad or edit squads/<slug>/squad.yaml.
5. Always validate envelopes with hydra_core.schemas.validate_envelope at squad boundaries.
6. Always log to the per-workflow trace via hydra_core.telemetry.emit.
7. Always gate procedural-memory updates and venom-class capabilities through hydra_core.governance.enforce_constitution before commit/execute.
8. Never modify a rubric's @<version> body in hydra_core/judge/registry.py. Past verdicts pin rubric_id@N for replay determinism. To change a rubric, register @N+1 and update consumers to opt in.
9. Never execute engineering via raw Agent({subagent_type: "engineer", …}) fan-out. Engineering work is the pair-programmer harness stage protocol: emit one typed envelope (PRD/ARCH_RFC/DEV_TASK) per subsystem → the dispatcher runs start_stage → archive_artifact → record_attempt → record_verdict → finalize_stage → finalize_run via _drive_pp_stage_loop, with cross-vendor judges every stage and best-of-N when the squad's invoke.mode is pp_best_of. The typed engineer agent is the generator the harness invokes inside a stage, not a supervisor-level executor. Parallelism uses planner phase_batch_index or the cross-repo fleet — never a fan-out around the supervisor. See plugins/hydra/agents/hydra-supervisor.md § Engineering Execution Contract.

Engineering Standards

• Python 3.11+, Pydantic 2.x, LangGraph optional but recommended.
• Type-annotate everything in hydra_core/.
• Keep hydra_core/ runtime-agnostic — dispatchers are injected, no provider SDK imports.
• Tests under tests/ use pytest. Avoid network or LLM calls in unit tests.
• hermetic suite (E2-26): tests/conftest.py redirects every Hydra state path (HYDRA_HOME, HYDRA_EPISODIC_DB, HYDRA_CHECKPOINT_DB, HYDRA_BACKENDS, HYDRA_EIGHTS_SPOOL, HYDRA_EIGHTS_DEAD_LETTER) into .tmp-pytest/hydra-home/ and sets HYDRA_TEST_NO_DAEMONS=1, which makes MCPStdioDispatcher.call_mcp refuse to fork a stdio daemon. Never write a test that needs the operator's real ~/.hydra; a test that genuinely needs a daemon carries @pytest.mark.live_daemon and runs only under pytest -m live_daemon.
• no-premature-done: do not declare a task done until pytest (the full relevant suite, not just the new test) passes and the build is clean. A frozen contract in a sibling module can break silently if only the new test is checked.

Security

• PII / PHI / financial data is redacted at squad boundaries (governance.redact_for_squad_boundary) unless the receiving squad's squad.yaml has explicit allow-list.
• The healthcare squad's phi-redactor agent runs FIRST on every inbound envelope.
• MCP tools are namespaced and whitelisted per-squad. The dispatcher enforces RBAC at runtime; agents do not self-check.
• In gateway mode, all MCP tools are proxied through hydra_gateway. Tool names follow the pattern mcp__hydra_gateway__{server}__{tool}. Backend specs live in ~/.hydra/backends.json, not ~/.claude.json.
• Each connected system (pair-programmer, TheEights, AgentSmith, ExecutiveSuite, RLM-Creative) can also run independently without Hydra by registering its MCP server directly.

Where To Read More

• CONSTITUTION.md — the immortal head. Rule of faith. Read this first; everything else is downstream.
• docs/MANIFESTO.md — the Hydra Manifesto (Pentecost-not-Legion frame, Three Crowns, TheEights).
• docs/ROADMAP-MANIFESTO.md — six-stage ingestion roadmap (Stage 1 shipped; 2–6 specified).
• HYDRA.md — top-level architecture
• ARCHITECTURE.md — engineer-facing detailed design
• CONTRIBUTING-SQUADS.md — how to add a squad pack
• Enterprise Master AI Orchestration System Architecture.md — upstream research doc grounding the design