Hydraia

Hydraia — Agentic Development Pipeline

This skill defines the ONLY approved way to build a feature. Run every phase, in order, automatically. Never ask the user which model, skill, or reviewer to use — those decisions are already made here. Never skip a phase. Never pause for "should I continue?" between phases.

Announce once at the start: "Running the Hydraia pipeline." Then proceed silently through the phases, narrating at most one short line per phase.

Phase -1 — Intent triage (before everything)

Classify the request into exactly ONE route before any other guard runs. Explicit commands skip classification and force their route (/hydraia:feature → feature · /hydraia:story → user story · /hydraia:plan → feature, stopping after Phase 3 · /hydraia:review → review · /hydraia:perf → performance · /hydraia:db → performance, DB-shaped · /hydraia:architect → greenfield · /hydraia:e2e → E2E suite · /hydraia:devops → DevOps config · /hydraia:observability → instrumentation · /hydraia:docs → docs sync). Plain-language requests are classified by signals:

Triage is ONE classification step, not a conversation — at most a single routing question, and only when genuinely ambiguous. Route chosen, proceed to the start-of-run guards below.

Autonomy tier + cost (after route, before the guards)

Once the route is chosen, estimate a tier from cheap signals and show a cost estimate. This maps to hydraia's EXISTING controls — it adds no new enforcement axis.

Early-exit (noop) first. If the route's target is empty, do not spin the pipeline:

• review / graph: if git diff --name-only against the branch point is empty (or the named target does not exist), report "nothing to review", drop the run-complete marker (printf 'brief\n' > <base>/.run-complete), and stop. No Phases 0–6.
• perf / db: if the named symptom target is absent or already within a stated threshold, report and stop.

Tier (feature-shaped routes). Classify from: likely files touched, overlap with the gate.yaml denylist (risk), new-logic vs mechanical, presence of UI surfaces:

• Tier S (trivial): no new logic, no new file, no risk-path, ≤ ~2 files → propose quick-mode (the .quick-approved path) or a Lite review. Minimal ceremony.
• Tier M (standard): default — full pipeline, Full review.
• Tier L (large / risky): many files, risk-path overlap, or a new service → full pipeline + all gates; the human may raise the agent ceiling.

Cost estimate. Read patterns/cost.yaml for the route × tier and state a one-line token estimate (e.g. "≈200k tokens, Tier S"). It is a rough anchor, not a promise.

Confirm once. Present the tier + estimate in a single AskUserQuestion, pre-selecting the review depth for the Phase-3 run-controls picker. The human confirms with one tap or overrides. Honor autoTier config (off → always Tier M, today's behavior). A tier NEVER removes the security floor (Phase 5 mandatory reviewers, threat model) — Tier S only trims optional ceremony, exactly as quick-mode already does.

Start-of-run guards (before Phase 0)

Language gate (first action, before anything else). Call the AskUserQuestion tool once to ask which language the user wants replies in — options: English and Español. Use the answer for all user-facing communication for the rest of the run: narration, the Phase-1 clarifying question, review findings, and the final summary. If the user dismisses the question, default to the language they wrote their request in. This choice does NOT change code, commit messages, spec/plan files, or the credits line — those stay as-is (English, portable). Ask this exactly once per run; /hydraia:resume inherits the prior run's choice if the run log records it, otherwise re-asks.

Storage & commit gate (second action, right after the Language gate). Two AskUserQuestion prompts, asked once per run (like the language gate). Do NOT recommend an option — the user chooses; these are privacy/workflow decisions, not quality ones.

1. Artifacts location — "Where should Hydraia store its artifacts (specs, plans, QA, run logs, and pipeline state)?"
   • In the repo → <repo>/docs/hydraia/ (tracked by git — the default).
   • Outside the repo → ~/.config/hydraia/artifacts/<repo-slug>/ (on this machine, never committed, no .gitignore edits). <repo-slug> = repo dir basename + -
     • the first 6 hex of a hash of the absolute repo root.
2. Auto-commit — "Auto-commit each task as Hydraia goes?"
   • Yes → commit per task (the default).
   • No → executors do NOT commit; all changes are left in the working tree for you to commit as you like.

After the answers: persist both to the GLOBAL config ~/.config/hydraia/config.json under repos["<absolute repo root>"] — do NOT hand-edit that JSON. Use the hy_config_set helper in hooks/config.sh, which merges into the file atomically, preserving every other repo and key:

bash -c '. "$CLAUDE_PLUGIN_ROOT/hooks/config.sh"
hy_config_set "<absolute repo root>" artifactsDir "<docs/hydraia | absolute external path>"
hy_config_set "<absolute repo root>" autoCommit "<true|false>"'

Pass artifactsDir docs/hydraia (or skip it) for in-repo; the absolute external path otherwise. Then create the external dir (with specs/ plans/ qa/ runs/) if chosen, and use the resolved absolute base as the artifacts base for the whole run (see Artifacts base below). If the user dismisses either question, default to in-repo + auto-commit ON (behavior identical to prior versions). /hydraia:resume inherits both from the run log if recorded, otherwise re-asks. The hooks read the same choice via hy_artifacts_dir / hy_repo_config in hooks/config.sh, so the gate, agent caps, plan-check, and summary all resolve to the same base — in-repo or external.

Commit attribution (hard rule, every commit this pipeline makes). Hydraia commits carry a clean, conventional message and NOTHING else. NEVER add a Co-Authored-By trailer for Claude, Hydraia, or any AI; never add a 🤖 Generated with… line; never add any AI-attribution footer. This overrides any default harness commit-trailer behavior and applies everywhere a commit is made — executor per-task commits, qa-automation, spec/plan commits, quick-mode, and any final commit. (The run-summary credits line is separate and unaffected — it is printed to the user, not written into git.)

Artifacts base (path resolution). Wherever this skill names a docs/hydraia/<sub> path (specs, plans, qa, runs, .active-plan, .quick-approved, .run-complete, .heartbeats, config), that path is relative to the resolved artifacts base from the Storage gate — docs/hydraia/ in the repo by default, or the external dir when chosen. Resolve the base once at the gate and use it for the rest of the run; when dispatching a task to a sub-agent, pass the absolute base so the executor writes its heartbeat and any artifacts to the right place. The shown docs/hydraia/... paths below are the default; substitute the resolved base when the user chose external storage.

Model guard. Check the model this session is running on. If it is NOT Opus 4.8 (e.g. Sonnet 5), print this once, then continue anyway — never block:

⚠️ Hydraia runs best with the main session on Opus 4.8. Opus does the planning and both review passes, and is smart enough to delegate execution to Sonnet 5 sub-agents on its own — you don't switch models yourself. Consider restarting the session on Opus 4.8 for full quality. Continuing anyway.

Two modes: design dialogue, then continuous execution. The pipeline has a conversational half and an autonomous half, split at the frozen plan.

• Phases 1–3 (think → design → plan) are INTERACTIVE. This is where design happens, so interaction is expected — not a violation. Run brainstorming as a real dialogue: ask clarifying questions (one at a time), propose 2–3 approaches with a recommendation, present the design, and get the user's approval before writing the spec. Do not compress this into a single question or skip it to "get to the code" — a design reached without dialogue is the exact failure this pipeline exists to prevent.
• Phases 4–6 (execute → review → verify) are CONTINUOUS. Once the plan is frozen, run every remaining phase to completion without pausing. Never insert "should I continue?" checkpoints between execution phases, never stop with the plan half-executed. The ONLY permitted stop here is a genuine BLOCKER a sub-agent cannot resolve — surface it, don't silently spin.

In short: pause to get the design right; never pause once you're building it. (/hydraia:plan stops at the boundary — after Phase 3 — so you can review before the autonomous half begins.)

No proportionality escape (non-negotiable). Token cost, change size, or "this looks trivial / it's just a mirror of existing code" are NEVER reasons for YOU to skip, compress, or inline a phase on your own. Whether a change is small enough to skip the ceremony is the human's decision — never yours to make unilaterally. If you are running the pipeline, run it in full: write the spec, write the plan, delegate execution, run both review passes, run the real build/tests. A runtime gate (hooks/gate.sh) enforces this — editing source code before Phase 3 freezes a plan is blocked — so "compressing the ceremony" does not save effort, it just fails the gate. The two sanctioned ways to skip are the human bypass and Quick-mode below.

Quick-mode (human-gated shortcut, opt-in per change). When a change is genuinely trivial you MAY offer to skip the design ceremony — but the human decides, not you.

• Eligibility (ALL must hold, else do NOT offer — run the full pipeline): no new business logic; no new file; small, localized diff; a mirror of behavior that already exists and works; and it does NOT touch any security surface (authN/authZ, PII/financial data, untrusted/external input, secrets). If security surface is touched, Quick-mode is never eligible — the threat model is not skippable.
• Ask, honestly. Call AskUserQuestion once with a neutral pro/con: "Found a simple, low-risk fix. Skip the spec/plan/double-review ceremony?" — options Run full pipeline and Quick-mode. State plainly: pro — far fewer tokens, faster; con — no spec-drive record, no double review. Do not lead with the token savings or nudge toward skipping.
• On Run full pipeline (or dismissal): run Phases 0–6 normally. Default to this whenever unsure.
• On Quick-mode: write the approval marker with a one-line reason (printf 'reason\n' > docs/hydraia/.quick-approved), make the edit, then — always, non-negotiable — run the project's real build/tests and confirm they pass, and commit with a clear message. Remove the marker afterward (rm -f docs/hydraia/.quick-approved). Never write this marker without an explicit human "yes".

Model policy (already decided — do not surface to the user)

• This main session must run on Opus 4.8. It does all analysis, planning, and both review passes. If the session is not on Opus, tell the user once: "Hydraia's planning and review run best on Opus 4.8 — switch the session model to Opus for full quality," then continue regardless.
• Execution runs on Sonnet 5, via the executor subagents (their model is pinned in their agent definitions). You do not change your own model to execute; you delegate.

Phase 0 — Context (always first)

Honor the effective config. Read docs/hydraia/config.json (per-repo) and ~/.config/hydraia/config.json (global) if present — the dashboard (/hydraia:dashboard) writes these. Per-repo overrides global; an env var overrides both. The hooks already enforce the deterministic toggles (agent caps, spec-drive mode, telemetry, run summary, codegraph auto). YOU honor the prompt-level ones: autoInstallDeps (false → skip the install offer below), reviewMode (single → run only the Superpowers review pass in Phase 5, not both), selfReviewPasses (Phase 3 plan self-review count), qaFunctional (false → skip the qa-functional dispatch in Phase 3, drop the AC-coverage freeze check, and skip qa-automation in Phases 4 and 6), e2eGate (false → skip the Phase 6 E2E gate), docsSync (false → skip the Phase 6 docs-engineer sync), securityGates (false → the human disabled threat model / security scans; note it, do not silently assume they ran), pdfConversion (false → skip markitdown), cavemanInternal, heartbeatStaleSecs (Phase 4 watchdog: seconds before a commit-less task is deemed hung, default 300), maxTaskRetries (Phase 4 watchdog: auto re-push attempts before a stall becomes a blocker, default 2). Defaults apply when a key is absent.

Binding constraints (read first). If docs/hydraia/constraints.md (or the external artifacts base's constraints.md) exists, read it and treat every rule as BINDING for this run — it is the repo's own "we don't do it this way" ledger and overrides default behavior (never the safety gates). The SessionStart hook already injected it as context; reading it here guarantees the full file is honored even if that injection was truncated.

0. Dependency check + one-click install (do this once, silently if all present). The user should never have to run install commands by hand. Detect what is available: command -v codegraph, command -v markitdown, command -v npm, command -v pip (or pip3).
   • If all present → say nothing, continue.
   • If a managed binary is missing but its installer is present (codegraph needs npm, markitdown needs pip), offer to install it inline, once, via AskUserQuestion — e.g. "Hydraia works best with codegraph (fast graph queries) and markitdown (PDF→markdown). Install now?" with options Install now / Skip this run. On Install, run the bundled installer (single source of truth) — resolve its path from the session cache and run it:

     ROOT="$(cat "${HOME}/.cache/hydraia/plugin-root" 2>/dev/null)"
     [ -n "$ROOT" ] || ROOT="$(ls -d "${HOME}/.claude/plugins/cache/hydraia/hydraia/"*/ 2>/dev/null | sort -V | tail -1)"
     "$ROOT/hooks/doctor.sh" --install --yes
     

     The installer is non-interactive and never uses sudo (no hangs). Its last line is machine-readable — RESULT codegraph=<state> markitdown=<state> where state is ok (usable now), installed (present, ready in a NEW session after a PATH refresh), or missing (failed — the installer printed the exact recovery command above it). Read that line and act on it:
     • ok → use the tool this run.
     • installed → tell the user it is ready next session; treat as unavailable for THIS run (degrade to file reads / skip PDF conversion). Do NOT re-offer.
     • missing → surface the one recovery command the installer printed. Do NOT loop or retry the install. On Skip, continue and do not ask again this run.
   • If an installer itself is missing (npm/pip absent, or node/python3/ git), these are system runtimes a plugin must not auto-install — run "$ROOT/hooks/doctor.sh" --check and show the user its per-OS install hints (brew/apt/dnf/winget), then continue degraded. Never block the pipeline on a missing dependency.
1. The session-start hook already bootstrapped the code graph — codegraph init the first time in a project (initialize + index, in the background), or codegraph sync on later sessions. Do not ask the user to sync anything.
2. If codegraph is available, query the code graph to understand existing structure, call sites, and blast radius before proposing anything — prefer graph queries over blind file reads to save tokens. If the graph is unavailable (codegraph not installed, or a first-run index still building), do NOT assume it or invent results: fall back to targeted, minimal file reads for exactly the code you need, and suggest /hydraia:doctor once so it is ready next time. codegraph is an accelerator, never a hard requirement — the pipeline runs without it.
3. If the request references a PDF (spec, ticket export, design doc), convert it with markitdown first (markitdown <file>), and work from the markdown. Never dump raw PDF bytes into context.

Phase 1 — Think before coding (mandatory gate)

Apply the karpathy-guidelines skill. Do not write any code yet. Force the analysis: restate the goal in your own words, list assumptions, name the simplest approach that could work, and identify what could go wrong. Surgical changes over broad rewrites. Ask clarifying questions if the goal is ambiguous — you are in the interactive half of the pipeline (see "Two modes"), so a real back-and-forth here is correct; the deeper design dialogue continues in Phase 2.

Phase 2 — Design + threat model (Superpowers, this session = Opus 4.8)

Use brainstorming, and run it as a real interactive dialogue (this is the interactive half — see "Two modes"). Do the actual brainstorming flow: ask clarifying questions one at a time (purpose, constraints, success criteria), propose 2–3 approaches with trade-offs and your recommendation, then present the design and get the user's approval. Do NOT jump straight from the prompt to a spec or to code — design without dialogue is the failure this phase exists to prevent.

This phase produces a written design spec — a real file, not inline reasoning. Skipping the written spec, or collapsing design into the plan, is a violation of the pipeline. Be exhaustive; explore alternatives and trade-offs; anchor every decision to what the code graph showed in Phase 0.

Write the spec to a file (mandatory artifact). Save the design spec to docs/hydraia/specs/YYYY-MM-DD-<topic>-design.md and commit it. Phase 3 MUST NOT start until this file exists. The spec MUST contain, at minimum:

• Goal — one or two sentences on what this builds and why.
• Chosen approach + rejected alternatives — the 2–3 approaches considered, their trade-offs, and why the chosen one won. Not just the winner.
• Code-graph anchors — the existing structure, call sites, and blast radius from Phase 0 that the design must respect (name the real symbols/files).
• Global constraints — version floors, naming/copy rules, platform limits, and any acceptance criteria, with exact values.
• Threat model + mitigations — see below; folded in so they become plan tasks.
• UX / visual direction (mandatory when the change creates or touches UI) — the chosen style, colour palette, type scale, spacing/layout system, key interaction states, and the accessibility floor, decided HERE via ui-ux-pro-max — not left to markup-writing time. See the frontend-design rule below.

Design approval (interactive gate, mandatory). Present the design to the user and get their approval BEFORE writing the spec file — this is brainstorming's HARD-GATE and it is honored, not skipped. Only pausing to "get to the code faster" defeats the pipeline. The written spec + the adversarial self-review below are in addition to the human approval, not a replacement for it. (Note: this human gate lives entirely in the interactive half; once the plan is frozen and Phase 4 begins, the pipeline runs autonomously to the end.)

Architecture advice (greenfield / from-scratch work). When the request builds a new system, service, or module from scratch — not a surgical change to existing code — first dispatch the architecture agents to propose the shape before the spec: architect (system design, scalability, trade-offs) and code-architect (concrete file/interface/data-flow blueprint anchored to existing patterns). If the work spans multiple services or a monolith split, also use microservices-architect (bounded contexts, communication patterns, resilience). Fold the chosen architecture

• its rejected alternatives (and why) into the spec. For a FULL greenfield run (routed by Phase -1 or /hydraia:architect), the greenfield-architect skill drives this entire step — elicitation, these same agents, the api-design contract, and ADRs. Skip this for small changes to existing code — it is for genuinely new construction.

Design adversarial loop (mandatory, before freezing the spec). After the spec + threat model are drafted, run ONE adversarial pass against them: take the opposing view and try to break the design — unstated assumptions, simpler approach ignored, scalability/failure modes, security holes the threat model missed, spec requirements that contradict each other. Revise the spec to close every real gap the pass finds. This is the design-time analogue of the Phase 5 double review: catching a design flaw here is an order of magnitude cheaper than at review time. One pass only — do not loop forever.

Threat model (mandatory, before planning): using the code graph's blast radius, enumerate the attack surface this change introduces or touches — untrusted inputs, authN/authZ boundaries, PII/financial data handled, external calls, and secrets. Note the OWASP categories at risk. Bake the mitigations into the spec so they become plan tasks, not afterthoughts. Catching a design-level security flaw here is far cheaper than at review time.

Frontend design (HARD GATE when UI is in scope — a precondition for freezing the spec, not a suggestion): visual quality is decided at design time, not patched on at markup-writing time — a landing or screen that reads "flat / generic" was already flat in the spec. This is the ONLY point in the whole pipeline where ui-ux-pro-max runs: the executor subagents in Phase 4 have no Skill tool and cannot invoke it, so if you do not run it HERE, nothing downstream will — the front end ships generic. That is the exact failure this gate exists to stop.

So when this change creates or touches any UI, you (the interactive main thread, which DOES have the Skill tool) MUST invoke ui-ux-pro-max during design and record its output in the spec's UX / visual direction section: the chosen style, palette, type scale, spacing/layout system, key component and interaction states, and the WCAG accessibility floor — concrete values, not adjectives (exact hex, named font pairing, spacing scale). Enforcement: the spec MUST NOT be frozen and Phase 3 MUST NOT start until this section exists and is filled from ui-ux-pro-max output. A spec that reaches Phase 3 with an empty or hand-waved UX / visual direction section for in-scope UI is a gate failure — stop and run the skill. Phase 3 inlines this section verbatim into every UI task and Phase 4 implements it exactly. (Purely back-end / non-visual changes skip this gate entirely.)

Phase 3 — Plan + self-review loop (the "todo bien hechesito" gate)

0. Precondition: the Phase 2 spec file must already exist. If it does not, go back and write it — do not plan without a spec. UI gate: if the change touches any UI, the spec's UX / visual direction section must already be filled from ui-ux-pro-max output (see the Phase 2 Frontend-design hard gate). If it is empty or hand-waved, stop and run ui-ux-pro-max now — do not plan UI tasks against a missing visual system, because Phase 4 executors cannot recover it (they have no Skill tool).

1. Use writing-plans to write the implementation plan, saved to docs/hydraia/plans/YYYY-MM-DD-<feature>.md. Follow the writing-plans structure in FULL — a thin plan is a failed plan. The plan MUST contain:

   • A header: Goal, Architecture (2–3 sentences), Tech Stack, the path of the Phase 2 spec it derives from, and a Global Constraints block (exact values copied from the spec).
   • A File Structure map: every file to be created or modified and its single responsibility, before the tasks.
   • Right-sized tasks: each task is a coherent, independently shippable unit of work — not one micro-edit. Consolidate trivially-related edits into one task. A plan with dozens upon dozens of atomic tasks will fan out into just as many sub-agents in Phase 4 and multiply token cost; the agent-budget cap (HYDRAIA_MAX_AGENTS, default 30) will hard-stop it. Aim well under that ceiling by design.
   • Per-task blocks, each with:
     • Files: — Create: exact/path, Modify: exact/path:line-range, Test: exact/path. Exact paths, never "the relevant file".
     • Interfaces: — Consumes (signatures it uses from earlier tasks) and Produces (exact function names, parameter and return types later tasks rely on).
     • Bite-sized TDD steps (2–5 min each): write failing test → run it, expect fail → minimal implementation → run, expect pass → commit. With the exact test command and expected result per step. Assume the implementer has zero prior context and cannot see the spec or your session — everything they need is in their task block. Write to the weakest plausible executor: the plan must be detailed enough that a cheaper or weaker model (Sonnet 5, Haiku, or an external agent like Codex or Gemini) can implement each task correctly with no judgment calls left open — exact paths, exact signatures, exact test commands. If a task would require the executor to infer intent or make a design decision, it is under-specified — push that decision up into the plan. This is where token cost is won or lost: a fully-specified task executes in one shot on a cheap model; an under-specified one forces a re-dispatch or an Opus rescue, which is the expensive path the plan exists to avoid.

   Literal content, never a description of it. A task that creates a file MUST embed the file's FULL verbatim content in a code block — never "create the file with the appropriate content". A task that edits a file MUST give the exact old_string → new_string (or a unique quoted anchor + the exact text to insert) — never "add error handling here". The executor copies; it does not compose.

   Never point at the spec (or any other document/code) for content the executor must produce. This is the single most common self-containment failure. A task that says "implement per spec §3", "follow the skeleton in the design", "match the existing User validation", or "see the spec for the schema" is NOT self-contained — the executor may be a context-less cheap model (Gemini Flash, Codex, Haiku) that CANNOT and WILL NOT open the spec, so it guesses, truncates, or invents. Inline the actual content into the task, even though it duplicates the spec. Here DRY yields to self-containment: the spec holds design rationale; the task holds everything needed to execute, repeated in full. This is exactly why the plan is a portable hand-off artifact ("execute anywhere" — Codex, Gemini, a second session): portability only holds if every task carries its own content. A runtime hook (hooks/plancheck.sh) scans the frozen plan's task bodies for these reference smells and BLOCKS the gate-arm if it finds any — so a referencing plan cannot reach execution.

   State each task's execution environment — assume nothing from context. A cheap executor does not know your repo's toolchain. Every task that runs anything gives the EXACT command (not "run the tests" but pnpm vitest run src/x.test.ts), the working directory, any dependency/env-var/service precondition, and — if it depends on an earlier task's output — names that task and the files it must find already present. Out-of-order or standalone execution must fail loudly, not silently guess.

   Verify completeness of large literals, not just existence. A cheap model can truncate a long verbatim block. For any sizable inlined file, the task's verification confirms it landed WHOLE — e.g. wc -l file → N or a grep for the exact last line — not merely that the file exists.

   Anchor edits by unique quoted text, never by line number alone. Line numbers drift as earlier tasks change the file; every Modify must carry a unique text anchor the executor can match exactly. State this in the task.

   Every UI task carries its visual direction inline. A task that creates or changes UI MUST embed the concrete decisions from the Phase 2 UX / visual direction section — the exact style, palette values, type scale, spacing, component/interaction states it must produce, and the WCAG accessibility floor to verify. The executor implements these values directly and does NOT invoke ui-ux-pro-max (it has no Skill tool); the inlined direction IS the visual system. Because Phase 4 runs autonomously on a weak executor, "make it look good" or "see the spec for styling" is NOT self-contained — the executor cannot open the spec and will fall back to generic defaults. Inline the values, per the self-containment rule above. A UI task with no visual direction in its body is under-specified and produces flat output.

   Every task carries a runnable verification with its expected output — not only TDD steps. Config, docs, and scaffolding tasks each end with an exact command and the exact output that proves the task landed (e.g. grep -c X file → 2). A task with no way to self-check is under-specified.

   QA cases (parallel, when qaFunctional is on) — ALWAYS a committed document, NEVER inline. Functional QA is produced as a reviewable artifact, not performed in your head. While writing the plan, dispatch the qa-functional agent (Sonnet) with: the spec path, the story artifact path if one exists, and the output path docs/hydraia/qa/YYYY-MM-DD-<slug>-cases.md. It returns Given/When/Then cases plus a traceability matrix (AC → Cases → Test ref, refs start as pending) and a GAPS section. Non-negotiable rules:

   • You (the main agent) MUST NOT write the test cases inline or "apply QA yourself." Dispatch qa-functional; the value is a durable document the human can read, review, and upload to the repo — not ephemeral reasoning.
   • The document is always produced and committed. Even when the run has no formal acceptance criteria, instruct qa-functional to derive implicit ACs from the spec's behavior so a case doc still results. After it returns, commit the file (git add docs/hydraia/qa/<file> && git commit) so it lands in the repo.
   • Surface every GAP to the human BEFORE freezing the plan — gaps are design questions, never things to guess around.
   • The plan must contain the test tasks that implement these cases (see the Phase 4 QA automation rule). The frozen-plan condition below includes "the QA case doc exists and is committed."

2. Self-review the plan (always TWO passes):

   • Pass A: critique your own plan hard. The Haiku test — apply it to every task: could a model with zero context and no permission to make decisions produce EXACTLY the intended result from this task block alone? If any step needs the executor to infer, deduce, or invent, the task is under-specified — reject and push the decision up into the plan. Concretely, reject and revise if ANY task:
     • lacks exact Files: paths, Interfaces:, or independently testable steps, or says vaguely "edit the code / update the component";
     • describes content instead of embedding it — a create-file task without the full verbatim file, or an edit task without the exact old_string→new_string / quoted anchor + literal insert;
     • references the spec, another document, or other code for content it must produce — "follow spec §X", "see the design", "as in the spec", "match the existing X" — instead of inlining that content into the task (the plancheck.sh hook blocks the gate-arm on these, but catch them here first);
     • runs a command without the exact invocation ("run the tests" with no command/dir), or assumes an earlier task's output without naming it, or lacks a completeness check on a large inlined literal (existence only, no line-count / last-line assert);
     • anchors an edit to a bare line number instead of a unique quoted string;
     • lacks a runnable verification with expected output (not just TDD tasks — config/docs/scaffolding too);
     • contains a placeholder — TODO, TBD, ..., "similar to Task N", "add appropriate X", "handle edge cases" — repeat the real content instead;
     • references a name (symbol, file, agent, skill) that no earlier task defines and does not already exist, or uses an inconsistent name/signature across tasks (foo() in Task 3 vs fooBar() in Task 7 is a bug). When qaFunctional is on, also reject if any acceptance criterion lacks BOTH a QA case (in the qa-functional doc) and an implementing task in the plan. Also hunt gaps, hidden coupling (check the graph), missing tests, unstated assumptions, over-broad changes, and drift from the spec. Revise.
   • Pass B: run a second full pass regardless — even if Pass A found nothing, re-audit the whole plan against the same checklist with fresh eyes (Pass A can miss on the first read, and its own revisions introduce new gaps). Revise again if it finds anything.
   • Both passes always run. Stop after the two even if minor nits remain — do not loop forever.

3. The plan is frozen only after the self-review loop converges AND every task has file-level detail AND — when qaFunctional is on — the QA case doc exists and is committed AND (when ACs exist) every AC maps to at least one QA case and one plan task. If it does not, it is not frozen.

4. Open a run log. Create docs/hydraia/runs/YYYY-MM-DD-HHMM-<feature>.md with the original request, the plan path, and a phase checklist (- [ ] Phase 0 … - [ ] Phase 6). Update it at each phase boundary — check the box as each phase completes — so an interrupted run leaves a durable trail of where it stopped. /hydraia:resume reads this file.

5. Arm the spec-drive gate. Only after BOTH the Phase 2 spec file and the frozen plan exist (and NOT before), write the frozen plan's path into the marker file docs/hydraia/.active-plan (e.g. printf '%s\n' "docs/hydraia/plans/<file>.md" > docs/hydraia/.active-plan). The gate.sh hook blocks all source-code edits until this marker exists — which is exactly why no code can be written before Phases 2–3 complete. Do not arm the marker if the spec is missing. (/hydraia:plan stops here and does NOT arm the marker — planning must never authorize edits.) A second hook (plancheck.sh) fires on this arm command and scans the plan's task bodies for reference smells ("follow spec §X", "see the design", etc.); if the plan is not self-contained it BLOCKS the arm — so a plan that would fail on a cheap executor cannot reach Phase 4. If it blocks, inline the referenced content and re-arm.

6. Run-controls picker (LAST interactive step — the human sets the depth before the autonomous half runs). The autonomous half (Phases 4–6) must not pause, so ask here, once, via a single AskUserQuestion with these two questions:

   (a) Review depth — how much of the Phase 5/6 ceremony to run on this change:

   • Full — double review, all matched language reviewers, security gates, QA, E2E, docs sync. (Default; pick when unsure.)
   • Lite — a single review pass, skip the non-core language reviewers and the docs-sync step; QA and the E2E gate still run per the repo's surface.
   • Custom — then a second AskUserQuestion (multiSelect) over the OPTIONAL stages only: 2nd review pass, language/framework reviewers, type-design / performance reviewers, docs sync, extra OWASP pass.

   Security floor (never offered as removable): regardless of profile, security-scan, code-reviewer, silent-failure-hunter, security-reviewer, and one hydraia-reviewer pass ALWAYS run. The picker cannot switch these off — only the human's explicit securityGates=false config can, which is a separate act.

   (b) Closing summary depth — Brief (compact box) or Detailed (adds what shipped, per-agent-type counts, main-vs-sub token split, per-model in/out/cache).

   Record both answers in the run log and honor them in Phases 5–6. On dismissal, default to Full + Brief. This is the only question in the autonomous half's run-up — after it, Phases 4–6 run to completion without pausing.

Phase 4 — Execution (delegated → Sonnet 5)

Use subagent-driven-development. Dispatch a fresh hydraia-executor subagent per task (these run on Sonnet 5). Give each exactly the context it needs from the plan and the graph — never your session history. Execute all tasks continuously. TDD where the plan calls for it. Commit frequently. Tag each executor dispatch's description with a machine-readable [task:<slug>] marker (the same <slug> the executor uses for its heartbeat file). The circuit-breaker hook (hooks/agents.sh) reads this tag to count per-task attempts; without it the breaker falls back to a description hash and still counts, but the tag makes escalation precise.

Dispatch in bounded waves — never fan out the whole plan at once. Each subagent loads its own context, so N parallel agents multiply token cost by ~N. Send at most HYDRAIA_MAX_CONCURRENT (default 6) executors at a time; as they finish, send the next wave. A whole run is also capped at HYDRAIA_MAX_AGENTS (default 30) total dispatches. These limits are enforced at runtime by the agent-budget hook (hooks/agents.sh) — a Task call past the cap is BLOCKED, not throttled silently, so respect the waves rather than firing 100 tasks and retrying blocked ones. If a plan truly needs more than the ceiling, that is the human's call to raise (`export HYDRAIA_MAX_AGENTS=

…(truncated)