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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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 .
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:
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.
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
available reasoning level. Default: Codex at xhigh, Claude Opus max
fallback. Runs on a different model family from dev so blind spots
don't overlap. The last line of defense before Lead approves a change.
There is no researcher role: the Lead does the research itself
before dispatching anything. There is no separate tester role either:
dev owns its own test surface, and reviewer provides the cross-model
check that tester used to provide.
You can override the model or reasoning effort per-dispatch via
--model and a project-level role file in .hydra/roles/.
Commands
Command
Purpose
hydra init
Create workflow context
hydra dispatch
Dispatch an agent node
hydra watch
Wait for next decision point
hydra approve
Mark a node's output as approved
hydra reset
Reset a node and downstream
hydra merge
Merge parallel worktree branches
hydra complete
Mark workflow completed
hydra fail
Mark workflow failed
hydra status
Show workflow state
hydra list
List workflows
hydra ledger
Show workflow event log
hydra cleanup
Clean up workflow state
hydra spawn
Direct isolated worker (not a full workflow run)
After hydra dispatch or hydra watch, always watch
After dispatching nodes, always call hydra watch to wait for the next
decision point. Do not poll manually with tick.
Result contract
Sub-agents write a slim result.json with schema_version: "hydra/result/v0.1"
plus a sidecar report.md. The JSON holds only what Hydra needs for routing;
all human-readable content lives in report.md.
report.md is free-form markdown. Recommended sections: summary of what was
done, outputs (file paths + descriptions), evidence (test runs, manual checks),
and a reflection on approach / blockers / confidence.
Ledger
Every workflow action is recorded in .hydra/workflows/{id}/ledger.jsonl.
Use hydra ledger --workflow W --repo . to inspect the event log.
