Skip to content

Architecture

Ankit Jha edited this page May 29, 2026 · 1 revision

Architecture

System Layers

Hydra is structured into three physical layers:

┌─────────────────────────────────────────────────────┐
│  BRAIN — Tier 1                                     │
│  Claude Code CLI                                    │
│  Classifies tasks, orchestrates heads, writes files │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│  ROUTING LAYER                                      │
│  dispatch/route.sh  +  dispatch/decide.sh           │
│  Resolves enum → tier, checks pools, runs fallbacks │
└──────────────────────┬──────────────────────────────┘
                       │
     ┌─────────────────┼─────────────────────┐
     ▼                 ▼                     ▼
┌─────────┐     ┌─────────────┐     ┌─────────────────┐
│ Expert  │     │  Standard   │     │   Grunt         │
│ T2 – T3 │     │  T4 – T8   │     │   T9 – T10      │
│ Claude  │     │ Gemini      │     │  Flash + Qwen   │
│ Thinking│     │             │     │  (local Ollama) │
└─────────┘     └─────────────┘     └─────────────────┘

Orchestration Protocol (5 Steps)

Step 1 — Classify

Read registry/domains.yaml to identify the domain and task type, then look up the enum key. Check registry/routing.yaml to resolve it to a tier number.

Step 2 — Check State

dispatch/route.sh --status
claude_pct Action
≥ 75% Freeze escalations. Do not route new work to Tier 1.
≥ 80% Emergency mode — warn user, route only, no generation.

Step 3 — Dispatch

dispatch/route.sh --enum SIMPLE --prompt "<task>" [--context <file>] [--a2a logs/last_handoff.json]

route.sh handles all fallbacks automatically.

Step 4 — Review

Read the output. Ask: does this compile? match conventions? solve the task?

  • No → escalate one tier
  • Yes → apply to disk, continue.

Step 5 — Rubber Duck

For output from Tiers 2–3 (Claude family), run rubber duck review using a different model family to avoid shared blind spots:

dispatch/route.sh --tier 4 --prompt "Review this for tradeoffs and blind spots:\n<output>"

Skip if claude_pct ≥ 75.


A2A Context Handoff

cat > /tmp/hydra_handoff.json <<HEOF
{
  "from": "claude-orchestrator",
  "task": "<what was asked>",
  "files": ["src/foo.ts"],
  "context": "<key context>",
  "prior_output": "<what was already done>"
}
HEOF
dispatch/route.sh --tier 6 --prompt "<next task>" --a2a /tmp/hydra_handoff.json

Key Files

File Role
CLAUDE.md Master instructions for the Brain (Claude Code)
AGENTS.md Instructions for delegated Antigravity heads
dispatch/route.sh Core router — resolves enum → model, runs fallbacks
dispatch/decide.sh Policy evaluator — determines edit mode and parameters
dispatch/edit.sh Atomic file writer with backup and rollback
registry/routing.yaml The enum file — change tier assignments here only
registry/domains.yaml Domain → enum key mapping (used in Step 1)

Clone this wiki locally