Hydra

Hydra Orchestration Toolkit

Hydra is a Lead-driven orchestration toolkit. You (the Lead agent) make strategic decisions; Hydra handles operational management (dispatch, retry, health checks, result collection).

Sub-agents output semantic intent (done/needs_rework/replan), not routing information. Hydra manages the lifecycle; you decide what happens next.

Why this design (vs. other coding-agent products)

• SWF decider pattern, specialized for LLM deciders. Hydra is the AWS SWF / Cadence / Temporal decider pattern. hydra watch is PollForDecisionTask; the Lead is the decider; lead_terminal_id enforces single-decider semantics.
• Parallel-first, not bolted on. dispatch + depends_on + worktree + merge are first-class. Other products (Factory.ai's Droid, Amp, Claude Code subagents) treat parallelism as open research; Hydra makes it the default.
• Typed result contract. Workers publish a schema-validated result.json (outcome: completed | stuck | error, optional stuck_reason: needs_clarification | needs_credentials | needs_context | blocked_technical). Other products return free-text final messages and require downstream parsing.
• Lead intervention points. hydra reset --feedback lets the Lead actually intervene at decision points instead of being block-and-join. A stale or wrong run is one reset away.

Lead operational rules

Core rules:

• Root cause first. Fix the real implementation problem before changing tests, fixtures, or mocks.
• Do not hack tests to force a green result. If a test is wrong, fix it honestly.
• No silent fallbacks or swallowed errors. Surface failure with outcome=stuck or outcome=error.

Agent launch rule:

• When dispatching Claude/Codex through TermCanvas, start a fresh agent terminal with termcanvas terminal create --prompt "...".
• Do not use termcanvas terminal input for task dispatch — it is not a supported automation path.

Telemetry polling:

• Treat hydra watch as the main polling loop. Do not infer progress from terminal prose.
• Before deciding wait / retry / takeover, query:
  • termcanvas telemetry get --workflow <workflowId> --repo .
  • termcanvas telemetry get --terminal <terminalId>
  • termcanvas telemetry events --terminal <terminalId> --limit 20
• Watch the derived telemetry states: awaiting_contract means the worker has not yet published result.json; stall_candidate means the worker may be hung. Trust derived_status and task_status over terminal prose.

Core workflow

The Lead is the decider — Lead reads the codebase, makes the strategic calls, and dispatches workers for the steps that genuinely need a fresh agent process. There is no "researcher" role: the Lead does the research itself before deciding what to build.

hydra init --intent "Add OAuth login" --repo .
# → { workflow_id, worktree_path }

# (Lead reads the code, reviews related modules, decides the plan.)

hydra dispatch --workflow W --node dev --role dev \
  --intent "Implement OAuth middleware and its tests following the design in CLAUDE.md" --repo .
# → { node_id, assignment_id, status: "dispatched" }

hydra watch --workflow W --repo .
# → DecisionPoint: dev completed

hydra dispatch --workflow W --node review --role reviewer \
  --intent "Independent review of the OAuth change" \
  --depends-on dev --repo .

hydra watch --workflow W --repo .
# → DecisionPoint: review completed

hydra complete --workflow W --repo .

Parallel dev

When the Lead identifies independent work streams, dispatch multiple dev workers with isolated worktrees:

hydra dispatch --workflow W --node dev-frontend --role dev \
  --intent "Frontend OAuth components and their tests" \
  --worktree .worktrees/frontend --repo .

hydra dispatch --workflow W --node dev-backend --role dev \
  --intent "Backend OAuth middleware and its tests" \
  --worktree .worktrees/backend --repo .

hydra watch --workflow W --repo .
# → DecisionPoint: both completed

hydra merge --workflow W --nodes dev-frontend,dev-backend --repo .

Handling agent results

When watchUntilDecision returns a node_completed DecisionPoint:

1. Check outcome:

   • completed — agent finished. Read report_file to decide next step.
   • stuck — agent can't proceed. Read report_file for what's needed.
   • error — Hydra already retried; if still failing, it reports to you.

2. Read the report.md referenced by report_file to decide:

   • Dispatch next node → hydra dispatch ...
   • Reset for rework → hydra reset --workflow W --node dev --feedback "..." --repo .
   • Re-dispatch after reset → hydra redispatch --workflow W --node dev --repo .
   • Complete workflow → hydra complete --workflow W --repo .

Hydra promotes blocked nodes to eligible automatically, but you decide when to dispatch. Check newly_eligible in the DecisionPoint to see what's ready.