/hydra

name: hydra
description: Use when a task should run through Hydra's Lead-driven workflow for multi-agent orchestration, or when an existing workflow must be inspected or cleaned up.

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.

Agent role guidance

The role file (in `.hydra/roles/<name>.md` or shipped builtin) declares an ordered `terminals[]` list of CLI / model / reasoning_effort triples. Hydra always picks `terminals[0]` for now; future fallback logic walks the list. The Lead chooses **which role** to dispatch — the role file chooses **which CLI** to invoke and at what reasoning level.

**lead** — The Hydra decider itself. Not dispatched by `hydra dispatch`; this role file codifies what the Lead terminal (the one holding the `lead_terminal_id` lock and talking to the human) is supposed to be. Default: Claude Opus at max reasoning.

**dev** — Writes code AND the tests that cover it. A dev-produced change is not complete until its test surface covers the new behavior. Default: Claude Opus at max reasoning, codex fallback.

**reviewer** — Independent cross-model second opinion at the highest