git:20260819.5ce71da to git:20260911.d23e543

40 added, 733 removed. Audit A to A.

---

name: hydraia

description: Codex-native hydraia pipeline. Use when the user asks to build, add, implement, or change a feature, brings a story/ticket, reports a bug, or wants a branch review. Runs the full spec-drive pipeline on Codex — triage, analyze, spec + threat model, plan + self-review, sub-agent execution, double review, verify — using Codex primitives (apply_patch gate, sub-agents, model routing).

---

# Hydraia (Codex host)

You are running the hydraia spec-drive pipeline on Codex. Host-specific mechanics:

- **Gate:** a `PreToolUse` hook blocks `apply_patch` (and write `shell`) until a plan is

frozen. Do not fight it — freeze the plan, or set the approval marker with user consent.

- **Sub-agents:** spawn executors for plan tasks (they run `gpt-5.6-luna`, cheap). Spawn

reviewers at Phase 5 (they run `gpt-5.6-sol`, frontier). This session (plan/spec/design)

runs `gpt-5.6-sol`.

- **Skills:** invoke supporting skills with `$skill-name`.

+ - **Step files:** the pipeline body lives in `phases/*.md` next to this file, loaded

+ just-in-time. Read one phase file fully, execute it, then load the next only when its

+ `## NEXT` directs you. **Never load two phase files at once.** These phase files are

+ kept **byte-identical** to the Claude orchestrator's `phases/*.md` (CI enforces per-file

+ parity), so they are the shared source of truth that never drifts.

## Host translation table (READ BEFORE the contract)

- The contract below is the shared source of truth, kept byte-identical to the Claude

- orchestrator so it never drifts. It is written in Claude Code's vocabulary. Wherever the

- contract uses a Claude mechanic, execute the Codex equivalent from this table:

+ The contract below (the dispatcher) and the `phases/*.md` it loads are the shared source

+ of truth, kept byte-identical to the Claude orchestrator so they never drift. They are

+ written in Claude Code's vocabulary. Wherever a phase file uses a Claude mechanic, execute

+ the Codex equivalent from this table:

| The contract says (Claude Code) | On Codex, do this |

|---|---|

| `/hydraia:feature`, `/hydraia:story`, `/hydraia:review`, … slash commands | The user invokes `$hydraia`; YOU infer the route in Phase -1 from intent. Treat each `/hydraia:X` as "route = X". |

| "run the **X** skill" / Skill tool | Invoke `$X` (e.g. `$story-analysis`, `$systematic-debugging`, `$performance-tuning`). |

| `AskUserQuestion` | Ask the user inline in plain text and wait for the answer. |

| "dispatch a sub-agent" / Task tool / hydraia-executor | Spawn a Codex sub-agent: **executors** = agent `hydraia-executor` (`gpt-5.6-luna`, cheap) for plan tasks; **reviewers** at Phase 5 = agents `hydraia-reviewer` / `code-reviewer` / `security-reviewer` (`gpt-5.6-sol`, frontier). This orchestrator session runs `gpt-5.6-sol`. |

| named agents (`perf-engineer`, `architect`, `code-architect`, `qa-*`, `db-*`, reviewers) | Spawn the same-named Codex agent if defined under `~/.codex/agents/`; otherwise run that role inline in this session, keeping its model tier (frontier for review/architecture, luna for mechanical execution). |

| `Edit` / `Write` / `apply_patch` before a frozen plan | The `PreToolUse` gate blocks it. Same marker semantics as Claude (frozen plan / `.quick-approved` / `HYDRAIA_ALLOW_DIRECT`). |

+ | `customize.toml` at `skills/hydraia/customize.toml` | The Codex mirror ships it at `~/.codex/skills/hydraia/customize.toml`; the executor-model / reviewer-panel overrides map onto Codex model routing (luna/sol) the same way. |

Model routing is non-negotiable and identical in spirit to Claude: **cheap `gpt-5.6-luna`

executes, frontier `gpt-5.6-sol` plans/specs/designs/reviews.**

Follow this contract exactly:

- ## 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:

- | Intent | Signals | Route |

- |---|---|---|

- | Feature / change | "add / build / implement / change X" | Phases 0–6 as written below |

- | User story | "As a … I want … so that …", acceptance-criteria lists, ticket text or a Jira/PDF export | Run the **story-analysis** skill FIRST (interactive PO pass → story artifact with numbered ACs), then Phases 0–3 with that artifact as the primary design input; continue into 4–6 only when the entry point runs the full pipeline |

- | Bug / unexpected behavior | "fails / broken / error / regression / used to work" | **systematic-debugging** skill first — root cause before any fix. Enter the pipeline only if the fix requires new design/behavior; a surgical fix proceeds under that skill's rules (the spec-drive gate still applies) |

- | Performance / DB symptom | "slow / timeout / high CPU / memory climbing / query takes …" | Run the **performance-tuning** skill flow: measured baseline FIRST, dispatch `perf-engineer` (and `db-performance-tuner` when the symptom is DB-shaped, per **db-optimization**), spec carries baseline + numeric target, Phase 6 re-measures against it |

- | New app / greenfield | "from scratch / new app / new service / greenfield" | Run the **greenfield-architect** skill: elicitation → architecture proposals (`architect` + `code-architect`, microservices only with evidence) → confirmed stack → **api-design** contract when an API exists → **adr** records per decision — then Phases 0–6 |

- | Review / audit | "review / audit this branch / this PR" | Phases 5–6 only |

- | Ambiguous | none of the above clearly | `AskUserQuestion` listing the plausible routes — never assume |

- 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.

- ## 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

- 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.

- 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.

- **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=…`), never a reason to loop on blocked dispatches. This

- is also why Phase 3 plans use coarse, consolidated tasks — a plan of 100+ atomic

- tasks is a planning smell, not a parallelism win.

- **Verify each task actually landed before dispatching the next wave (do not trust the

- report alone).** A subagent's summary is not proof — a task can report "done" or

- "delegated" without having committed (this failure is real, not hypothetical). After

- each wave, confirm the work exists in git before moving on: `git log --oneline -<n>`

- shows the expected commits and `git status --porcelain` is clean (or shows only the

- next wave's territory). If a claimed commit is missing, re-dispatch that one task —

- never build the next wave on an unverified one. The check costs a few tokens; a

- corrupted run caught at Phase 6 costs far more.

- **Hung-agent watchdog — heartbeats + auto re-push (no manual nudging).** A real run

- had executors stall silently and need a manual "keep going" message. Detect and

- recover automatically at every wave boundary:

- - Each executor writes a heartbeat on start and after each commit to

- `docs/hydraia/.heartbeats/<task-slug>` (its agent definition does this). The file's

- epoch mtime is the liveness signal; the directory is gitignored.

- - When a wave returns, for every task in it, confirm progress: a **commit exists**

- (the git check above) OR its **heartbeat is fresh** (mtime within

- `heartbeatStaleSecs`, default 300). A task with neither is treated as **hung/failed**

- and is **automatically re-dispatched ("pushed")** — you do not wait for the human to

- poke it. Re-push the SAME task with the same context, up to `maxTaskRetries`

- (default 2). Log each retry in the run log.

- - If a task exhausts its retries without a commit, that is a genuine BLOCKER: stop and

- surface it with the evidence (no commit, stale heartbeat, retry count) — never spin

- on it silently. Bounded waves (`HYDRAIA_MAX_CONCURRENT`) keep a stall from taking the

- whole plan down with it.

- **Frontend rule (hard gate, not optional):** any task that creates or changes UI —

- markup, components, styles, or templates — the executor implements the *UX / visual

- direction* the task carries from the Phase 2 spec (style, palette, type scale, spacing,

- interaction states) EXACTLY, then verifies the WCAG accessibility floor. This is not

- conditional on the executor self-classifying the task as "UI enough" — if the task

- touches anything a user sees, the gate applies. Writing markup first and styling later

- is the failure this prevents. The executor does NOT invoke ui-ux-pro-max itself —

- executor subagents have no Skill tool, so the visual system is decided ONCE at design

- time (Phase 2, below) and inlined into every UI task; the spec is the executor's single

- source of truth. A UI task that reaches Phase 4 with no visual direction is a plan

- defect — the executor reports it BLOCKED rather than inventing a generic look.

- **Auto-commit mode (from the Storage & commit gate):**

- - **Auto-commit ON (default):** each executor commits its task with a clean message

- (no attribution trailer — see the hard rule above). Unchanged behavior.

- - **Auto-commit OFF:** executors write code and run tests but **do not commit** — they

- leave all changes in the working tree and report files touched + test result. Tell

- each dispatched executor explicitly not to commit. Liveness then rests on the

- heartbeat alone (the "commit exists OR heartbeat fresh" check degrades gracefully to

- heartbeat-only), so heartbeats are mandatory in this mode. **Phase 5** reviews the

- working-tree diff (`git diff` including staged + unstaged) instead of branch commits —

- both passes and the security gate see the full uncommitted diff. **Phase 6** runs the

- real tests and confirms against the spec as usual, then reports "N files changed,

- uncommitted — commit them yourself"; it makes no commit. `/hydraia:resume` in this

- mode falls back to the run-log phase checklist + heartbeats for progress (it cannot

- reconstruct per-task state from git); the spec-drive gate and `.active-plan` are

- commit-independent and work the same.

- **Stack best-practices rule:** before writing non-trivial code, the executor

- consults the matching patterns/standards skill so idioms are right the first time —

- **react-patterns** (React), **golang-patterns** (Go), **springboot-patterns**

- (Spring Boot), **python-patterns** (Python), **node-patterns** (Node/TypeScript

- backends), **dotnet-patterns** (C#/.NET), and **coding-standards** (cross-cutting

- naming, structure, and clean-code conventions for any stack).

- **QA automation rule:** plan tasks that implement QA cases are dispatched to the

- `qa-automation` agent (mode: implement) instead of a generic executor. It detects

- the repo's existing test framework from evidence (config files, existing tests) —

- if none exists it reports BLOCKED, because choosing a framework is a plan-level

- decision. It names every test with its case ID (e.g. `TC-1.1`) and fills the

- matrix `Test ref` column with `path/to/test:line` per case, or

- `manual — <reason>` for cases that cannot be automated.

- ## Phase 5 — Code review (depth per the run-controls picker)

- **Honor the review depth the human chose in Phase 3 step 6.** **Full** runs both passes

- below. **Lite** runs only Pass 1 (Superpowers) plus the security floor, skips the

- non-core language reviewers and the OWASP `security-review` extra pass. **Custom** runs

- Pass 1 + whatever optional stages the human checked. In every profile the **security

- floor is mandatory** — `security-scan`, `code-reviewer`, `silent-failure-hunter`,

- `security-reviewer`, and one `hydraia-reviewer` pass always run; the picker cannot

- remove them. Default (no answer recorded) is Full.

- For a Full run, run BOTH passes — do not stop after one.

- **Scope the panel to the diff — do not dispatch every reviewer on every run.** First

- read the actual changed surface (`git diff --name-only` against the branch point).

- Dispatch only the reviewers whose file types are present in the diff — running six

- Opus reviewers on a two-file TypeScript change is wasted money. This is the single

- biggest per-run cost lever, so route deliberately:

- - **Always** (any diff): `security-reviewer`, `silent-failure-hunter`, and

- `code-reviewer` — correctness and security are never file-type-gated.

- - **Only when that language/framework is in the diff:** `typescript-reviewer`

- (`.ts/.js`), `react-reviewer` (`.tsx/.jsx`), `vue-reviewer` (`.vue`),

- `angular-reviewer` (Angular files), `python-reviewer` (`.py`),

- `go-reviewer` (`.go`), `java-reviewer` (`.java`), `csharp-reviewer` (`.cs`),

- `database-reviewer` (SQL/migrations), `type-design-analyzer` /

- `performance-optimizer` only when the diff's nature (new public types, hot paths)

- actually warrants them.

- **Model tiers — buy Opus only where judgment pays.** Correctness- and

- security-bearing reviewers (`hydraia-reviewer`, `security-reviewer`,

- `silent-failure-hunter`, the matched language reviewer) run on **Opus 4.8**.

- Mechanical passes (style/lint-level nits, doc-comment checks) run on **Sonnet** or

- **Haiku** — never spend Opus on a formatting scan.

- 1. **Pass 1 — Superpowers review:** use **requesting-code-review** to dispatch the

- `hydraia-reviewer` subagent (Opus 4.8) against the whole branch.

- 2. **Pass 2 — ECC review:** dispatch the diff-scoped reviewer set above (Opus for the

- correctness/security-bearing ones per the tier rule).

- 3. **Security gate (mandatory, cross-stack — always runs regardless of diff scope):**

- run the ECC security skills over the diff — **security-scan** (secrets, injection,

- unsafe patterns, vulnerable deps) and **security-review** (OWASP Top 10 semantic

- pass). These are language-agnostic and cover Node, C#, React, and Angular even

- though those have no dedicated security skill. For Spring Boot add

- **springboot-security**; for Django add **django-security**. Treat any

- high-severity finding as a blocker.

- 4. **Dedup before you triage.** Pass 1, Pass 2, and the security skills overlap — the

- same issue often surfaces three times. Collapse findings by (file, line, root

- cause) into one entry BEFORE triage, so you spend triage tokens once per real

- problem, not once per report. Then use **receiving-code-review** to triage: fix

- everything correct-and-material; high-severity security findings are

- non-negotiable. Re-review only the changed surface if fixes were substantial (max

- one re-review cycle).

- ## Phase 6 — Verify & close

- Use **verification-before-completion**: actually **run** the project's real build

- and test commands (e.g. `ng build`, `npm test`, `go build ./...`, `pytest`) and

- read their output. Reviewing logic "inline" or "checking the math by hand" is NOT

- verification — if a build/test command exists, you must run it and report the real

- result. Confirm the feature meets the spec from Phase 2 (including the threat-model

- mitigations), and summarize what shipped. If a build or test fails, the run is not

- done — fix and re-run.

- **QA matrix check (when `qaFunctional` is on and a QA case doc exists):**

- dispatch `qa-automation` (mode: verify) against the case doc. Every case must be

- either automated — its `Test ref` points at a real test that ran green in the

- build above — or explicitly `manual — <reason>`. Any `pending`, missing ref, or

- red case means the run is NOT done: fix and re-verify before closing.

- **E2E gate (when `e2eGate` is on AND the repo has an E2E surface):** dispatch

- `e2e-runner` (mode: verify). It runs the critical-flow suite with the real e2e

- command; every non-quarantined critical flow must pass green. A failing critical

- flow means the run is NOT done — fix and re-verify. If the repo has no E2E surface,

- the gate is skipped (note it in the run log); never fabricate a suite to satisfy it.

- **Docs sync (when `docsSync` is on):** dispatch `docs-engineer` (mode: sync). It

- updates any README / API docs / CHANGELOG / ADR-index that drifted from the branch's

- changed surface and reports what changed. This step never blocks the run — stale

- docs do not fail a build; the report tells you what was updated.

+ ## Step-file architecture (how to run this pipeline)

- **Disarm the gate.** Once the run is verified and done, remove the active-plan

- marker so a later unrelated edit is gated again: `rm -f <base>/.active-plan` (where

- `<base>` is the resolved artifacts base — `docs/hydraia/` by default, or the external

- dir if chosen; removing the in-repo path in external mode leaves the gate armed).

- On a genuine blocker that ends the run early, leave the marker so `/hydraia:resume`

- can continue without re-arming.

+ The pipeline body lives in `phases/*.md`, loaded just-in-time. **Read one phase

+ file fully, execute it, then load the next only when its `## NEXT` directs you.**

- **Emit the run summary.** As the final close step, drop the one-shot marker that tells

- the Stop hook to print the transcript-derived run summary (agents dispatched, models

- used, real token usage). **Write the summary depth the human chose in Phase 3 step 6

- as the marker's content** — `printf 'detailed\n' > <base>/.run-complete` for a

- detailed breakdown, or `printf 'brief\n' > <base>/.run-complete` for the compact

- box (default), where `<base>` is the artifacts base resolved at the Storage gate

- (`docs/hydraia/` by default, or the external dir if chosen). Writing the in-repo path

- in external mode drops the marker where `summary.sh` never looks, so the run summary +

- telemetry are silently lost. The hook (`hooks/summary.sh`) reads that first line to pick verbosity,

- then reads the real numbers from the session transcript plus Claude Code's on-disk

- sub-agent transcripts (`<project>/<sessionId>/subagents/agent-*.jsonl`, one per

- dispatched sub-agent, with a `.meta.json` naming its `agentType`) — so sub-agent tokens

- and models are counted, not just the main session. Do NOT hand-write token or agent

- counts yourself; they would be guesses.

+ - **NEVER load two phase files at once.** Do not skip, reorder, or pre-load phases.

+ - Follow each phase file exactly, the way you would a step file.

+ - `phases/model-policy.md` and `phases/token-discipline.md` are always-on

+ reference (summarized below), not sequential steps — consult them as needed.

- **Telemetry logs for EVERY Hydraia route, not just `feature`.** Dropping this marker is

- the last action of every route that does real model work — `feature`, `review`,

- `resume`, `plan`, `story`, `perf`, `db`, `architect`, and the direct-agent commands

- (`e2e`, `devops`, `observability`, `docs`, `graph`). Routes that stop before Phase 6

- (e.g. `plan`/`story` at Phase 3, or a one-shot `graph` query) STILL drop the marker at

- their end so the run is recorded — use `brief` unless the human explicitly chose

- detailed. The Stop hook records only the DELTA since the previous marker this session

- (a per-session cursor prevents double-counting when several commands run back to back),

- so emitting once per command is correct, never inflating. Only the pure utilities

- `dashboard` and `doctor` skip it (no model work to record). The credits line below is

- separate: it is printed only for `feature`, `review`, and `resume`.

+ ## Always-loaded facts (carry these for the whole run)

- **Pre-close security gate (mandatory):** run **repo-scan** and **production-audit**

- to confirm no hardcoded secrets, no vulnerable dependencies, and no obvious

- production-readiness gaps were introduced. Do not report done while a high-severity

- item is open. Only then report done. As the very last line of the run summary,

- print the credits exactly:

+ - **Route → phases** (decided in Phase -1 triage):

+ `feature` 0–6 (full) · `plan` 0–3 then stop · `story` -1–3 (PO-first) ·

+ `perf`/`db` -1–6 (measurement-first) · `architect` -1–6 (greenfield) ·

+ `review` 5–6 · `graph` codegraph only. Ambiguous route → `AskUserQuestion`.

+ - **Autonomy tiers (S/M/L):** derived in Phase -1 from files-touched, `gate.yaml`

+ risk overlap, new-logic-vs-mechanical, and UI presence → maps to review depth

+ and ceremony. `autoTier=off` → always Tier M. **Never removes the security floor.**

+ - **Model policy (summary):** this orchestrator session stays frontier for

+ judgment (triage, design, plan, both reviews). Execution delegates to the

+ Phase-4 executor — cheap by default, overridable via `customize.toml`.

+ Full policy in `phases/model-policy.md`.

+ - **Customization:** an optional `customize.toml` overrides the executor model /

+ dispatch recipe (read in Phase 4) and the Phase-5 pass-2 reviewer panel (read in

+ Phase 5). Precedence: repo `<artifacts-base>/custom/hydraia.toml` > global

+ `~/.config/hydraia/custom/hydraia.toml` > shipped `skills/hydraia/customize.toml`.

+ Unparseable override → warn and fall back to shipped defaults. **The always-on

+ security gate is NOT customizable.**

+ - **Token discipline** is background and always on (summary in

+ `phases/token-discipline.md`): the `caveman` skill compresses internal comms

+ only — never code, specs, or plans.

- — Harness By José Daniel Garcés Ospina | Spec Drive Design First —

+ ## FIRST STEP

- (Shown on every completed `feature`, `review`, and `resume` run. Not shown for

- `plan` or `graph`.)

+ Read fully and follow `phases/phase--1-triage.md` to begin the pipeline.