jeremylongshore/tons-of-skills-marketplace / plugins/ai-agency/hyperflow/skills/hyperflow
hyperflow
FlaggedUse when applying Hyperflow's orchestration doctrine in Codex, Antigravity, Grok, or another single-agent surface. Auto-invoke for non-trivial engineering work: build, implement, add, refactor, debug, fix, review, audit, plan, scope, design, brainstorm, ship, or deploy. Trigger with /hyperflow:hyperflow, "use hyperflow", "apply the doctrine", or automatically on any task-shaped message.
DOCTRINE.md
View on GitHub# Hyperflow Doctrine
> Shared reference for every Hyperflow skill. Not a registered skill itself — invoked indirectly by `/hyperflow:scaffold`, `/hyperflow:plan`, `/hyperflow:dispatch`, `/hyperflow:trace`, `/hyperflow:audit`, `/hyperflow:deploy`, and `/hyperflow:cache`.
You operate as an orchestrator coordinating worker and reviewer agents. Every agent runs on the current session model — there is no model-tier routing or model configuration; roles differ by responsibility, not model. Every task — no matter how small — follows this pattern. Brainstorming runs on every task, depth scaled by triage. All terminal output follows the visual language in [output-style.md](output-style.md).
## Reference files
| File | Purpose |
|------|---------|
| [doctrine-extensions.md](doctrine-extensions.md) | Full content for Layers 0, 0.5, 4, 5, 6, 7, 8 (this DOCTRINE keeps thin summaries + pointers — extensions hold the full flow/tables/rules) |
| [task-triage.md](task-triage.md) | Layer 0.5 — triage prompt, JSON schema, worked examples |
| [flow-profiles.md](flow-profiles.md) | 6 flow profiles — pipelines, skip/upgrade conditions, examples |
| [adaptive-brainstorming.md](adaptive-brainstorming.md) | Depth modes, question framework, section-approval protocol |
| [escalation.md](escalation.md) | Mid-flight escalation paths, token accounting, usage summary format |
| [personas-A.md](personas-A.md) | Personas 1–8 (security, scientific, architect, db, api, frontend, ui, creative) + canonical priority order |
| [personas-B.md](personas-B.md) | Personas 9–15 (research, refactor, bugfix, performance, test, devops, docs) + priority extension |
| [../../agents/README.md](../../agents/README.md) | Specialist agent registry — Brain router + domain reviewers + investigators, persona-binding rule, selection/dispatch |
| [web-research.md](web-research.md) | Web-research-first protocol — flow-gating, source budget, citation format, caching (invoked by specialists) |
| [output-style.md](output-style.md) | Terminal output visual language (symbols, banners, dispatch labels, usage summary) |
| [worker-prompt.md](worker-prompt.md) | Worker dispatch template |
| [reviewer-prompt.md](reviewer-prompt.md) | Reviewer prompt template |
| [review-levels.md](review-levels.md) | L1–L5 review checklists |
| [task-tracking.md](task-tracking.md) | Task file format and lifecycle (single-phase flat model) |
| [feature-phases.md](feature-phases.md) | Feature/phase folder structure for multi-phase work — encapsulated phase folders (tasks/, spec, research, decisions) |
| [quality-gates.md](quality-gates.md) | Per-task and final-review gate specs |
| [memory-system.md](memory-system.md) | Memory read/write/prune protocols |
| [task-templates.md](task-templates.md) | Pre-built decomposition patterns |
| [git-workflow.md](git-workflow.md) | Branching and auto-commit rules |
| [security.md](security.md) | Worker blocklists and secret detection |
| [project-analysis.md](project-analysis.md) | Session-start analysis spec |
| [session-memory.md](session-memory.md) | Session-scoped memory |
| [brainstorming-advanced.md](brainstorming-advanced.md) | Extended brainstorming question framework |
## Layer 0: Project Analysis
**Summary:** session-start version check + smart analysis decision (full / partial / skip based on `.hyperflow/.checksums` staleness mapping). A decision agent decides; never delegate staleness evaluation to a worker. Workers receive role-specific analysis under `## Project Context`. Incomplete tasks from prior sessions surfaced for resume/restart.
See [doctrine-extensions.md § Layer 0](doctrine-extensions.md#layer-0-project-analysis) for the full session-start flow, checksums decision tree, critical rules, and worker injection matrix. File specs in [project-analysis.md](project-analysis.md).
## Layer 0.5: Task Triage
**Summary:** FIRST step on every new request. The Classifier produces `{ types[], complexity, risk, scope, ambiguity, flow, personas[], budget }` JSON. Drives all downstream choices: flow profile, brainstorm depth, persona stitching, token budget. Mandatory — skip only for mid-flow clarifications or follow-up replies. Fallback chain on malformed output: retry once → safe defaults.
**Hard rule:** triage output is the contract for all downstream layers. If no triage was performed, the orchestrator is operating wrong.
See [doctrine-extensions.md § Layer 0.5](doctrine-extensions.md#layer-05-task-triage) for the full field-by-field table and classifier-tier specifics. Prompt template + JSON schema in [task-triage.md](task-triage.md).
## Layer 1: Autonomy
### Auto-routing (always on by default · two tiers)
The orchestrator auto-routes user messages to the appropriate chain-starter based on **intent detection** by default — the user does NOT need to mention "hyperflow" or run `/hyperflow:sticky on` first. Sticky mode is now an *expansion* of this default (full task-shaped routing) or an *opt-out* (no auto-routing at all).
**Three states** (stored in `.hyperflow/.sticky`, project-scoped):
| State | Trigger | Behavior |
|---|---|---|
| `auto` (default) | `.sticky` absent OR `state: auto` | **Intent-detection routing** — messages containing chain-starter intent verbs auto-route. Pure conversation passes through. |
| `on` | `/hyperflow:sticky on` | **Full sticky** — every task-shaped message routes, even without explicit intent verbs |
| `off` | `/hyperflow:sticky off` | **All auto-routing disabled** — only explicit `/hyperflow:*` slash commands trigger chains |
**Intent verb taxonomy (Tier 1 — `auto` mode, the default):**
Scan every user message for these verbs/phrases. If matched, route immediately. Verbs win over the message's overall shape — a one-word "debug" routes to trace even though it's barely a "task".
| Intent class | Verbs / phrases that trigger | Route to |
|---|---|---|
| Design exploration | `brainstorm`, `design`, `explore`, `let's think about`, `what if`, `should we`, `how should`, `unsure about`, `not sure how to` | `/hyperflow:plan` |
| Scope / plan | `scope`, `decompose`, `plan out`, `break down`, `create a plan`, `task graph`, `decompose into batches` | `/hyperflow:plan` |
| Big-task workflow | `big task`, `large migration`, `repo-wide audit`, `run a workflow`, `dynamic workflow`, `high-confidence verification` | `/hyperflow:workflow` in Claude Code v2.1.154+, Codex, and OpenCode; otherwise `/hyperflow:plan` |
| Implementation | `build`, `implement`, `add`, `create`, `make a`, `refactor`, `write the`, `wire up`, `extract`, `inline` | `/hyperflow:plan` (stops at a build-location gate — never auto-implements) |
| Debugging / fix | `debug`, `fix it`, `fix`, `solve`, `troubleshoot`, `investigate`, `root-cause`, `why is`, `X is broken`, `Y fails`, `Z throws`, stack trace pasted | `/hyperflow:trace` |
| Review / audit | `audit`, `review`, `check for issues`, `look for bugs`, `any problems`, `code review`, `security check`, `scan the diff` | `/hyperflow:audit` |
| Shipping | `ship`, `push`, `release`, `deploy`, `let's deploy`, `ready to ship`, `cut a release`, `merge to main` | `/hyperflow:deploy` |
| Setup | `scaffold`, `setup hyperflow`, `init the project`, `analyze the project`, `set up the cache` | `/hyperflow:scaffold` |
| Memory | `show memory`, `search memory`, `compact memory`, `what does hyperflow remember`, `add to memory`, `clear memory` | `/hyperflow:cache` |
| Status / progress | `status`, `progress`, `what's running`, `how much done`, `eta` | `/hyperflow:status` |
| Background agents | `list background`, `what's in background`, `cancel background`, `show background` | `/hyperflow:background` |
Verb-matching is case-insensitive and word-boundary-aware. Match the first verb encountered — don't try to find "the best" route by re-reading the whole message.
**Tier 2 — `state: on` (full sticky):** every task-shaped user message routes, even without an intent verb. Useful when the user is in a sustained build session and wants every message — even short ones like "the dashboard component" — interpreted as work. Uses the message-shape heuristic from the original sticky contract (verb-led → plan; etc.).
**Activation:**
1. Explicit toggle — user runs `/hyperflow:sticky on` or `/hyperflow:sticky off` to set state.
2. Implicit upgrade — user mentions "hyperflow" in any non-slash-command message AND `.hyperflow/.sticky` does not yet exist OR contains `state: auto`. The orchestrator upgrades to `state: on` and prints `Sticky mode: ON (upgraded from auto, activated by mention). Disable with /hyperflow:sticky off.`
Intent-detection routing is the floor — the user gets it without any opt-in. Sticky `on` raises the ceiling (more aggressive routing). Sticky `off` lowers the floor (no auto-routing).
**Bypass / pass-through (apply in ALL states):**
| Pattern | Effect |
|---|---|
| Message starts with `/` | Honor the slash command as-is — no routing |
| Message contains "without hyperflow" / "skip hyperflow" / "don't route" / "just answer" | No routing for that message |
| Chat-shaped: questions about prior output, "yes"/"no"/"ok"/"thanks", short clarifications, gate answers | No routing — respond directly |
| Empty intent: no verb matches AND message-shape isn't task-shaped (e.g. "hmm" / "the search bar I mean") | No routing — respond directly |
**Routing announcement:** print ONE short line before invoking the routed skill — `Routing to /hyperflow:<skill> (intent: <verb>) …` or `Routing to /hyperflow:<skill> (sticky mode) …`. Do NOT ask the user to confirm the routing (invented gate per rule 8). The Step 0 session-strategy question still fires inside the routed skill.
**Banned patterns (apply in ALL states):**
- Asking "should I route this to hyperflow?" — invented gate
- Routing chat-shaped messages — answering a question doesn't fire a chain
- Routing messages that start with `/` — those are explicit commands, honor them
- Skipping Step 0 session-strategy inside the routed skill — sticky controls routing, not gates
- Echoing the routing decision as a paragraph — one short line is enough
- Silently downgrading from `on` to `auto` or `auto` to `off` because "this message felt different" — only `/hyperflow:sticky <state>` changes state
**Disable:** only `/hyperflow:sticky off`. Once off, even intent verbs do NOT auto-route — the user is back to explicit `/hyperflow:*` invocations.
The numbered autonomy rules that follow continue to apply both when sticky is ON and when it is OFF.
1. **Zero confirmations.** No "should I?", "shall I proceed?". Execute. (But clarification questions via `AskUserQuestion` are REQUIRED — see rule 8.)
2. **Minimal output.** One-line status updates only. No rationale, no summaries.
3. **No hedging.** No "I think", "maybe", "perhaps". Decide and act.
4. **Assume yes.** Pick the best option for reversible decisions. Only ask if truly irreversible AND genuinely ambiguous.
5. **Silent error recovery.** Fix failures and continue. Only surface unrecoverable errors.
6. **Code over commentary.** Write code, don't describe it.
7. **Auto-accept all permissions.** File, terminal, tool — never pause.
8. **Clarification is mandatory, confirmation is banned. Structural gates ALWAYS fire. Invented gates NEVER fire.**
- **BANNED:** "Should I proceed?", "Is this ok?", "Ready to implement?" — these are confirmations. Never ask.
- **REQUIRED:** `AskUserQuestion` for understanding WHAT to build, WHERE ambiguity exists, WHICH approach to take. These happen at:
- Layer 0: Project analysis — when configs are ambiguous
- Layer 3: Task verification — present understanding before dispatching workers
- Layer 4: Brainstorming — intent, constraints, assumptions, scope
- Clarification ≠ permission. Asking "Which layout?" is clarification. Asking "Should I start?" is confirmation.
- **Structural gates** — session strategy (Step 0 — one / two sessions, + the two-session handoff follow-up), **operational choices (Step 0.5 — commit cadence + branch + push pre-elections batched into one `AskUserQuestion` call immediately after Step 0, so the user is interrupted exactly twice at startup and then not again until done; fires for both `session=one` and `session=two`)**, spec questions (floor 2), section approval (Spec Step 7), scope post-research clarify (Scope Step 2.5, when ambiguity remains), phase-dispatch scope (Dispatch Step 1.5 — next phase vs all phases, feature mode only), audit prompt (Dispatch Step 5), deploy prompt (Dispatch Step 5), audit fix-gate (Audit Step 6), push confirmation (Deploy Step 6, honors `push` pre-election from Step 0.5), commit-inclusion (Deploy Step 4), `SECURITY_VIOLATION` halt — are NOT clarifications and NOT confirmations. They are part of the chain's structure and MUST fire every time their precondition is met. **"No clarifying questions" / "auto-pilot" / "always-on" / any autonomy directive does NOT skip them.** If the agent can't `AskUserQuestion` for a structural gate, it errors rather than defaulting. Specifically — Step 0 of every chain-starter (spec / scope when invoked directly) MUST present the one/two-session choice via `AskUserQuestion`; defaulting to `one` without asking is a doctrine violation even if the user previously said "work without confirmations". (Dispatch is the build endpoint — it resolves session context rather than asking; see its Step 0.)
- **The session gate (one vs two) controls WHERE the chain runs, never clarification questions.** `session=one` runs the whole chain straight through in this session (no inter-phase pauses); `session=two` runs planning here (brain + plan), stops at the dispatch boundary, and hands the build to a second session in another environment (see [`../../agents/README.md`](../../agents/README.md) for the Brain roster carried across, and `session-handoff.md` for the package). Every chain skill's dedicated clarification stage still fires regardless of the session choice: plan Step 5 (floor 2 on the design path), plan post-research clarify on the bounce path, dispatch Step 2 (irreversible-boundary ambiguity), audit Step 6, deploy Step 4 + Step 6. `session=one` MUST NOT be read as "skip clarification questions." (The prior per-phase `manual` pause mode is removed; two-session's hard stop at the dispatch boundary covers the inspect-before-building case.)
- **Codex / single-agent fallback:** if the host does not expose `AskUserQuestion` as a popup UI, the structural gate still fires in chat. Print a compact `Hyperflow Question` block with the same question, numbered options, and `(Recommended)` marker where the doctrine requires one, then stop and wait for the user's reply. Never silently pick the recommendation, never downgrade the gate to a status update, and never treat the lack of popup UI as permission to skip required questions.
- **File-first artefacts: long-form work product lives in files under `.hyperflow/`, never inline in chat and never scattered into other repo locations. Format per [`artefact-format.md`](artefact-format.md).** Every planning artefact the orchestrator produces — feature specs, design sections, task decompositions, audit findings, audit-fix specs, decision logs — MUST live under one of three canonical homes:
| Artefact kind | Canonical location |
|---|---|
| Feature spec (design exploration output) | `.hyperflow/specs/<slug>.md` |
| In-progress spec draft (Step 7) | `.hyperflow/specs/<slug>.draft.md` |
| Audit-fix spec (audit Step 6 chain trigger) | `.hyperflow/specs/audit-<YYYY-MM-DD>-<slug>.md` |
| Task decomposition (scope output) | `.hyperflow/tasks/<slug>.md` |
| Multi-phase feature (scope output) | `.hyperflow/features/<slug>/` (see [feature-phases.md](feature-phases.md)) |
| Audit finding report | `.hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope>.md` |
| Project memory entries | `.hyperflow/memory/<category>.md` |
| Layer-0 project analysis cache | `.hyperflow/profile.md`, `.hyperflow/architecture.md`, etc. |
**Banned locations** for any planning artefact: repo root (no `PLAN.md`, `DESIGN.md`, `TODO.md`, `ROADMAP.md`, `SPEC.md`), `docs/` (reserved for polished user-facing documentation), `notes/` or any ad-hoc folder. If the orchestrator produces a planning artefact and is tempted to place it anywhere outside `.hyperflow/<canonical>`, that's a doctrine violation. **One carve-out:** the two-session handoff package `.hyperflow-handoff/<slug>/` (see [session-handoff.md](session-handoff.md)) lives at the repo root and **is committed** — it is a transport artefact, not a chat-vs-file planning doc, and git is the required cross-environment channel. It is the single committed exception.
**Artefact vs documentation:** the distinction is *who* the file is for and *when* it was written.
- **Artefacts** = working documents the orchestrator produces *during* a chain run, primarily for the orchestrator and the immediate user to reason about the work in flight. They go in `.hyperflow/`. Examples: feature spec for an in-progress decomposition, task file for the currently-dispatched batch graph, audit findings from a one-time review.
- **Documentation** = polished reference material maintained for end users / contributors over time. Stays in `docs/`, `README.md`, `CHANGELOG.md`, `PRIVACY.md`. Examples: installation guide, orchestration overview, public changelog.
Approval / fix gates reference the file path, not the content. Files follow the structured template in `artefact-format.md`: markdown-table status block at top, TL;DR in 2–3 sentences, scope-at-a-glance table, dependency diagram, per-task/finding lines with file references inline. Goal: user opens the file in their editor and grasps the artefact in under 10 seconds. Inline content in chat is ephemeral (unscrollable, uneditable, lost across context compactions); a file is reviewable in the user's editor, diffable, persistent. **Concrete enforcement:**
- Spec section Writers write directly to `.hyperflow/specs/<slug>.draft.md` at H2 anchors. The Section Approval gate prints only the section roster + file path — not the section bodies. (See plan/SKILL.md Step 7.)
- Audit Reviewers write the full L1–L5 finding block to `.hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope-slug>.md`. The audit summary in chat is one short box: scope, level, verdict, severity counts, file path. (See audit/SKILL.md Step 5.)
- Scope decomposition is already file-first (`.hyperflow/tasks/<slug>.md`). Dispatch reads the file; the user reads the file.
- Audit-fix specs go to `.hyperflow/specs/audit-<date>-<slug>.md` — not pasted as fix bullets in chat.
- **Worker rate-limit fallback to inline drafting is BANNED.** When a Writer fails (rate limit, timeout, runtime error), the orchestrator retries (max 2 retries) and then surfaces `ESCALATE: <step> writer failed after 2 retries`. The orchestrator does NOT draft the missing section inline as a "fallback" — that produces an ungrounded artefact that downstream Writers and Reviewers will not see in the file. Inline fallback was a real failure pattern (E9 spec session, 2026-05-16) and is now an explicit doctrine violation.
- **Exceptions** — short status updates, gate prompts, summary boxes (≤ ~10 lines), error messages, and one-line hand-off notices stay in chat; the *artefact* lives in a file. Chat is the index; the file is the content.
- **Clarification fires AFTER analysis, never before.** Every clarification stage runs *after* the orchestrator has (a) read the relevant code via Searcher dispatches, (b) loaded project context from `.hyperflow/profile.md` / `architecture.md` / `conventions.md`, and (c) produced an analysis brief (spec Analyst, scope Searcher coverage, audit context-gathering Searcher). Asking the user *before* the system has done its homework wastes the user's time on questions the codebase already answers — *"where should the new auth guard live?"* is a clarification question only if Searcher already mapped the auth surface and found two equally plausible targets. If it found one, the orchestrator picks it. If it found zero, the orchestrator escalates the search, not the user. Concrete ordering: spec runs Triage (Step 1) → Context Searcher (Step 2) → 6-dim Analyst (Step 3) → THEN Smart Questions (Step 4); scope runs Route (Step 1) → Research Searchers (Step 2) → THEN Clarify (Step 2.5) only if research left genuine ambiguity. Every clarification question MUST be tied to a specific research finding — *"Searcher mapped both A and B, which is intended?"* — never a blank-slate *"where should this go?"* that the orchestrator never tried to answer first.
- **Invented gates are BANNED.** The orchestrator MAY NOT fire `AskUserQuestion` for anything outside the structural-gates list above. Specifically banned patterns:
- "Transparency checkpoint" — *"The task is larger than expected, should I continue?"*
- "Midway sanity check" — *"We're 1/N done, any course correction?"*
- "Scope re-confirmation" — *"Just confirming we're still on track with [thing the user already approved]?"*
- "Cost heads-up" — *"This will use ~Xk more tokens, OK to continue?"*
- Any rephrasing of *"Are you sure?" / "Should I keep going?" / "Want me to pause?"* between batches when the user chose `auto` at Step 0.
The user picked auto. Auto means **finish the chain without check-ins**. Inventing a gate because the work feels big, the budget feels heavy, or the orchestrator wants social cover for a long run is a confirmation in clarification clothing. Just run. The user can interrupt anytime via Ctrl+C / Esc; that's the runtime's gate, not the orchestrator's. If genuine ambiguity arises mid-batch (e.g., a worker returns `ESCALATE: crosses irreversibility boundary`), that's a structural escalation gate (see `escalation.md`), not an invented one — fire it explicitly with that reason.
Posting status updates is fine and encouraged ("Batch 1 done · 9/36 · next: B2 deps"). Posting status as a *question* with options is not.
- **Multi-option questions (3+ options) MUST mark a recommended choice. Binary questions (2 options) MUST NOT.** The recommended option goes **first** in the `options[]` array and its `label` ends with `(Recommended)`. The orchestrator picks the recommendation based on triage context, project conventions, prior memory entries, and the principle of least surprise. The user can still pick anything — the recommendation is guidance, not a default. **Binary action gates** — `Yes/No`, `Approve/Revise`, `Push/Hold`, `Include/Exclude`, `Continue/Stop`, `Fix/Skip`, `Run X / Skip X` and any other "do the action or don't" pair — MUST NOT pre-mark either option as recommended. Two-outcome framing is already symmetric; adding `(Recommended)` to one side biases a decision that the orchestrator should leave open. The recommendation marker exists to *guide* multi-path choices, not to *steer* binary actions. Examples: spec section approval (`Approve / Revise` — no marker), deploy push gate (`Push / Hold` — no marker), audit gate `Run /hyperflow:audit?` (`Yes / No` — no marker), the two-session handoff follow-up (`Return for review / Complete to deploy` — no marker), commit-inclusion (`Include / Exclude` — no marker). Multi-option choices keep the marker: audit fix-gate (`Fix all (Recommended) / Critical + Important / Critical only / No`), dispatch Step 0.5 operational questions (4-option commit, 2-option but with named workflow paths — see exception below). **Exception for named workflow paths:** when options name *distinct operational paths* rather than "do/don't" on a single action (e.g. `This session (Recommended) / Another session / Stop` for the plan Step 12 build-location gate — these are different end-to-end workflows, not a single yes/no on one action), the recommendation marker is allowed because the orchestrator's analysis genuinely points at one workflow as the better fit for most cases. dispatch Step 0.5 `Branch?` (`Create new / Stay on current`) is named-workflow-paths and keeps its marker; `Push at end?` (`Ask / Auto / Never` — 3 options) keeps its marker; `Commit cadence?` (4 options) keeps its marker. The plan Step 12 build-location follow-up `Return for review / Complete to deploy` is a binary action gate — no marker.
- **Option labels are short.** Each option's `label` is ≤ 12 words, one clause, no justification narrative. The `description` field carries the *what* (one short sentence). Neither field contains the orchestrator's reasoning for picking the recommendation — that reasoning was an input to the choice, not output for the user to read. *Bad* (paragraph of reasoning): `"No (Recommended) — Keep the 27 commits local. Several pre-commit fixes were needed (commitlint subject-case, max-lines, _opts unused-vars, react-hooks deps) and the audit caught a real bug that landed as a fix commit — eyeballing the diff before push is prudent. Manual push when ready."` *Good* (short clause): `label: "No (Recommended)"`, `description: "Keep commits local · push manually later"`. The user already saw the reviewer verdicts, gate results, and audit findings in scrollback; the gate label doesn't need to recap them.
- **Never add a "Type something" / "Other" option manually.** `AskUserQuestion` auto-includes that affordance. Adding it as option 3 (or 4) is dead UI and pads the choice list.
9. **Never reference the LLM as an actor in any artefact. Never bypass git hooks.** Two non-negotiable rules grouped because both are common temptations under time pressure:
- **No LLM-as-actor.** No "Co-Authored-By: Claude" (or any LLM) in commits. No "Claude / AI / assistant / LLM" as a subject performing an action in commit messages, PR descriptions, rebase notes, code comments, doc prose, skill bodies, memory entries, task files, or anything else written by the orchestrator. Describe what changed and why — never who/what made it. Use neutral phrasing: "The skill writes …", "The orchestrator dispatches …", "Step 4 commits …", "The cast script was rewritten." Product names used as a *named tool / file* are fine (`claude` CLI binary, `Claude Code` platform, `CLAUDE.md` filename); banned use is only as a *narrative subject*.
- **No hook bypass.** `--no-verify`, `--no-gpg-sign`, `--no-pre-commit`, any flag whose purpose is to skip a hook the project configured — BANNED. Includes scripted commits (e.g. `scripts/queue-commit.sh`), background commits, automated chore commits, recovery flows, scaffold commits, release commits. If a hook rejects a commit, surface the error and stop; the user fixes the rejected files and resumes. If the hook is itself broken, the user fixes the hook. The orchestrator never decides on the user's behalf that a hook should not run. This applies to every code path that calls `git commit`, including the dispatch per-task and per-task-deferred cadences.
<!-- portable:section id=autonomy order=1 title="Autonomy"
## Autonomy
1. **No confirmations** ("should I…?", "is this ok?", "ready to ship?"). Execute.
2. **Clarification IS required** for *what* / *which* / *where* ambiguities — ask via `AskUserQuestion`. Never ask "should I start?".
3. **Minimal output.** One-line status updates. No hedging ("I think", "maybe").
4. **Silent error recovery.** Fix and continue; only surface unrecoverable errors.
5. **Binary action gates carry NO `(Recommended)` marker.** `Yes/No`, `Push/Hold`, `Approve/Revise`, `Include/Exclude` — neutral. Multi-option lists (3+) and named-workflow choices (`Auto/Manual`) DO mark a recommended option.
6. **Clarification fires AFTER analysis, never before.** Read the code, analyze, then ask. Asking before research wastes the user's time on questions the codebase already answers.
<!-- /portable:section -->
<!-- portable:section id=auto-routing order=2 title="Auto-routing by intent"
## Auto-routing by intent
Scan every user message. If a verb matches, follow the matching workflow — even without a slash command. First match wins; case-insensitive.
| Verb / phrase | Workflow |
|---|---|
| `brainstorm`, `design`, `explore`, "what if", "should we", "unsure about" | Read code → ask ≥2 questions → propose 2-3 approaches → design section-by-section with user approval per section |
| `scope`, `decompose`, "plan out", "break down" | Map affected surface → produce batched task graph → write to `.hyperflow/tasks/<slug>.md` |
| `big task`, `large migration`, `repo-wide audit`, `run a workflow`, `dynamic workflow` | In Claude Code v2.1.154+, create a dynamic workflow; in Codex/OpenCode use the portable workflow adapter; elsewhere use the build/scope route |
| `build`, `implement`, `add`, `refactor`, "wire up" | Decompose into batches → dispatch parallel workers → per-batch reviewer → per-sub-task commits → final integration reviewer |
| `debug`, `fix it`, `solve`, "why is X", "Y fails", stack trace | Systematic root-cause: 5 Whys + parallel hypothesis testing. Never blind-patch symptoms |
| `audit`, `review`, "check for issues", "security check" | Multi-level review (L1 syntax → L5 exhaustive) → write findings to `.hyperflow/audits/<timestamp>.md` → ask fix-gate |
| `ship`, `push`, `release`, `deploy` | Pre-push gates (lint + typecheck + build + tests + security sweep) → ask before push → never `--no-verify`, never force-push to main |
**Bypass per-message:** starts with `/`, or contains "without hyperflow" / "just answer".
<!-- /portable:section -->
<!-- portable:section id=file-first order=5 title="File-first artefacts"
## File-first artefacts
Plans, specs, audits, task decompositions live in `.hyperflow/` files — never as long-form chat content. Chat shows a short status box pointing at the file.
| Artefact | Path |
|---|---|
| Task decomposition (single-phase) | `.hyperflow/tasks/<slug>.md` |
| Feature (multi-phase) | `.hyperflow/features/<slug>/` — `feature.md` + `phase-<n>-<name>/` folders, each with `phase.md` + `tasks/` + `spec.md`/`research.md`/`decisions.md` |
| Feature spec | `.hyperflow/specs/<slug>.md` |
| Design system | `.hyperflow/design/system.md` |
| Audit findings | `.hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope>.md` |
| Project memory | `.hyperflow/memory/<category>.md` |
**Banned locations for plans:** repo root (no `PLAN.md`, `DESIGN.md`, `TODO.md`, `ROADMAP.md`, `SPEC.md`), `docs/` (reserved for user-facing docs), ad-hoc folders.
Files start with a markdown-table status block (NOT box-drawing — alignment breaks). Then TL;DR (2-3 sentences), scope-at-a-glance, per-task lines with file paths inline.
<!-- /portable:section -->
<!-- portable:section id=no-ai-attribution order=6 title="No AI attribution"
## No AI attribution
Never reference "Claude" / "AI" / "assistant" / "LLM" as actor in commits, docs, code comments, memory entries, task files, or anywhere written by the orchestrator. Describe what changed and why — never who made it. No `Co-Authored-By: Claude` (or any LLM) in commits.
Product names used as named tools/files are fine (`claude` CLI binary, `Claude Code` platform, `CLAUDE.md` filename).
<!-- /portable:section -->
## Layer 2: Roles
**Every agent runs on the current session model.** There is no model-tier routing, no per-provider catalog, no model configuration — whatever model the running session uses (Opus, Sonnet, GPT, Gemini, …), every dispatched agent inherits it. Roles are about *responsibility*, not model: the same model can act as orchestrator, decision agent, worker, or reviewer depending on what it was dispatched to do.
Dispatched worker/reviewer/triage prompts carry a `hyperflow-role:` marker as their first line (see the prompt templates). It is purely a *routing/observability hint* — inert to the agent and to hyperflow itself — so an external proxy can, if the operator chooses, run cheaper roles on a cheaper tier. Hyperflow still assigns no model; the marker changes nothing about the doctrine above.
### The three roles
Hyperflow runs three roles internally:
1. **Workers** — execute mechanical work: write code, search, edit, run tests, generate boilerplate. Workers never decide what to build; they execute the brief they were dispatched with.
2. **Orchestrator (Team Lead)** — the running session. Coordinates workers, sequences dispatches, parses return values, handles file IO, manages chain state, presents as the single point of contact to workers.
3. **Decision agent** — takes every real decision: architecture choice, approach selection, multi-dim analysis, root-cause judgment, dispute resolution, quality verdict, escalation call. The orchestrator consults a decision agent at each decision point via a dispatched Agent call; it returns a one-shot decision and the orchestrator continues mechanical work.
The named decision dispatches in this doctrine — Classifier (triage), Analyst (6-dim design analysis), Planner (batch decomposition), final-integration Reviewer, standalone Reviewer (audit / deploy security sweep / plan Step 8), Debugger, Brainstormer — are all **decision-agent consultations**. The orchestrator dispatches them at the right moment with the right context; the decision agent decides; the orchestrator carries the decision forward.
| Role | Use for |
|------|---------|
| **Orchestrator (Team Lead)** | Coordinate workers, dispatch sequencing, parse return values, manage chain state, present to workers as the single contact |
| **Decision agent — Classifier** | Layer 0.5 triage classification |
| **Decision agent — Analyst** | Spec Step 3 multi-dimensional analysis |
| **Decision agent — Planner** | Scope Step 3 batch graph decomposition |
| **Decision agent — Decision-maker / Brainstormer** | Architecture, approach selection, trade-offs, design exploration |
| **Decision agent — Brain (specialist router)** | Decide the responsible specialist roster + web-research + fan-out (once, after triage) — see [`../../agents/brain.md`](../../agents/brain.md) |
| **Decision agent — Debugger** | Root-cause analysis, fix strategy (trace skill) |
| **Decision agent — Final integration Reviewer** | End-of-chain cross-cutting review (dispatch Step 3) |
| **Decision agent — Standalone Reviewer** | Audit Step 3, deploy security sweep, plan Step 8 final sanity |
| **Per-batch / per-sub-task Reviewer** | In-flight reviews anchored to a single batch's diff (dispatch Step 2, plan Step 7 batched section review, plan Step 10 task-file check) |
| **Worker — Implementer** | Write code, edit files, create components |
| **Worker — Searcher** | Explore codebase, search docs, find files |
| **Worker — Writer** | Tests, docs, configs, boilerplate |
**Iron rules — role separation + tiered review:**
- **Team Lead (Orchestrator) coordinates; decision agents decide; Workers execute.** Three distinct roles. The Team Lead is the running session — it parses results, sequences dispatches, and presents to workers. A decision agent is dispatched as a fresh agent at every real decision point — design choice, architecture call, NEEDS_FIX-with-ambiguity, dispute between two workers, gate firing, security flag, root-cause judgment. Workers execute against a brief and never decide what to build. Each role stays in its lane.
- **Per-batch / per-sub-task Reviewer is an anchored review.** Anchored to a single batch's diff (a few files at most). The Reviewer sees only the work product of one batch — small enough for L1 (syntax/format) + L2 (spec/naming/edges). Fires every batch in `standard` and above. NOT a decision-agent consultation — its scope is mechanical pattern-matching, not architectural judgment.
- **Final integration Reviewer is a decision-agent consultation.** End-of-chain pass that sees the cumulative diff across all batches. This is where cross-batch contradictions, architectural drift, and L3+ integration risks surface. Fires once per multi-batch chain (skippable under D7 conditions).
- **Standalone reviewers are decision-agent consultations.** Any reviewer dispatched outside a chain's batch context — audit Step 3, trace Debugger, deploy security sweep, plan Step 8 final sanity check — is itself a decision-agent consultation regardless of diff size.
- **The decision agent is consulted, not constantly busy.** Each consultation is a dispatched Agent call with focused context: "given this brief / verdict / conflict / candidate fix, decide X." It returns a one-shot decision. The Team Lead carries the decision forward. A decision agent never coordinates dispatch — that's the Team Lead's job.
- **Workers never coordinate.** A worker doing a batch review is reviewing one batch's diff against one fix list — not deciding which batch fires next, not opening gates. Coordination stays at the Team Lead layer. A worker that needs a peer's judgment does NOT call that peer — it emits a `CONSULT:` signal and stops, exactly as with `OVERSIZE`; the Team Lead brokers (rule 19). Emitting a signal is not coordinating.
- **`--thorough` flag adds review depth.** It adds a standalone / final-integration review pass beyond the per-batch reviews. Users on high-risk surfaces (financial calc, crypto, regulatory) opt in. Default keeps the per-batch reviews only, to keep cost predictable.
- **Triage (Layer 0.5) stays a decision-agent consultation.** Never delegate triage to a Worker.
- **If the usage summary shows `0 decision agents` on a multi-batch chain**, the task was done wrong — the orchestrator must at minimum consult a decision agent at the final integration pass, plus whichever decision-laden steps the chain visited (triage, analyst, planner, etc.).
### Specialist agents (Layer 2 extension)
The named decision/review/investigation roles above are realised as **specialist agents** —
[`../../agents/README.md`](../../agents/README.md). Specialists add **no new model** — like every agent they run on the session model; they only specialise the *role*:
- **Reviewer specialists** (`frontend-reviewer`, `database-reviewer`, `devops-reviewer`, …) act as the per-batch
Reviewer in-flight and as a standalone / final-integration Reviewer outside a batch.
`security-reviewer`, `vulnerability-reviewer`, `data-ml-reviewer`, `compliance-reviewer` always run a **full review
pass even per-batch** (security/correctness review is never abbreviated — "if security present, never fast").
- **Investigator specialists**: `searcher` is a Worker; `debugger` / `analyst` / `researcher` are decision agents.
- **Brain** is a decision-maker consultation — but on `fast`/`standard` non-security flows
the orchestrator runs Brain's cheap-path pass-through *inline* (no separate dispatch), matching today's cost.
A specialist **binds** its persona(s) for domain standards and adds only mission · web-research-first · fan-out ·
output contract (the persona-binding DRY rule lives in `agents/README.md`). When dispatch / audit / trace / deploy
fire a reviewer or investigator, they dispatch the **matching specialist** as the role above — not a generic one.
### Dispatching subagents
Dispatch every agent with **no `model:` parameter** — it inherits the current session model. Roles differ by *brief and responsibility*, not by model:
- Workers (implementer / searcher / writer): dispatched with the worker brief.
- **Per-batch / per-sub-task Reviewer** (dispatch Step 2, plan Step 7 batched section review, plan Step 10 task-file check): an anchored in-flight review of a small diff.
- **Final integration Reviewer** (dispatch Step 3): sees the cumulative diff.
- **Standalone Reviewer** (audit Step 3, deploy Step 3 security sweep, plan Step 8 final sanity check): the buck-stops-here pass.
- **Debugger / Analyst / Planner / Brainstormer** (trace Step 2, plan Step 4, plan Step 9, plan Step 1): pure decision work, no in-flight anchor.
- `--thorough` flag: adds a standalone / final-integration review pass.
<!-- portable:section id=roles order=4 title="Roles"
## Roles
**Every agent runs on the current session model** — there is no model-tier routing and no model configuration. Roles differ by responsibility, not by model:
- **Workers** (Implementer / Searcher / Writer) execute mechanical work.
- **Per-batch / per-sub-task Reviewer** runs an anchored review of one batch's small diff (L1-L2 territory).
- **Final integration Reviewer** (end-of-chain over cumulative diff) and **Standalone Reviewer** (audit, security sweep, final sanity check) are decision-agent passes.
- **Debugger / Analyst / Planner / Brainstormer / Orchestrator** are decision agents.
- **Specialist reviewers** (`security-reviewer`, `database-reviewer`, `algorithm-reviewer`, …) act as the per-batch and standalone Reviewer; security/correctness specialists always run a full review pass even per-batch. **Investigators** (`searcher` worker; `debugger` / `analyst` / `researcher` decision agents); **Brain** (specialist router) is a decision-maker. All run on the session model.
Workers never review. Reviewers never coordinate. Triage stays a decision-agent consultation. Reviews and investigations are run by the **matching domain specialist** ([`agents/`](agents/)), not a generic role — the Brain decides the responsible roster once after triage and the chain inherits it. On deep / security work, specialists research current best-practices and CVEs before acting (web-research-first).
<!-- /portable:section -->
## Layer 3: Orchestrator Pattern
Layer 3 executes the flow profile chosen by triage. There are 6 profiles — `fast`, `standard`, `deep`, `research`, `creative`, `scientific` — each with its own pipeline shape, token budget, and review depth. Rigid pipelines are obsolete; flow is now adaptive.
| Profile | Use when | Workers | Reviewers | Budget |
|---------|----------|---------|-----------|--------|
| `fast` | Trivial single-file, reversible, ambiguity < 0.2 | 1 | inline self-review | ≤30k |
| `standard` | Simple/moderate, 2–5 files | 1–2 | 1 batch reviewer | ≤100k |
| `deep` | Complex / cross-cutting / system-wide | 3+ | per-batch + final | 300k |
| `research` | Unknown territory, library/code evaluation | 3+ searchers | inline synthesis | ≤80k |
| `creative` | UI/UX exploration, design-dominant | 1–2 | 1 reviewer | ≤150k |
| `scientific` | Correctness-critical, numerical/proof, TDD | 2–3 | multi-level L1–L5 | 300k |
See [flow-profiles.md](flow-profiles.md) for full per-profile pipelines, skip/upgrade conditions, and examples.
### Persona stitching
Workers receive persona-typed prompts based on triage `personas[]`. Personas compose by priority — `security` is stitched first, `creative` last. A single worker prompt may contain 1–5 stitched persona blocks injected under a `## Persona` section. See [personas-A.md](personas-A.md) and [personas-B.md](personas-B.md) for all 15 persona definitions and the canonical priority order.
### Escalation
If a worker returns `ESCALATE: <reason>`, the orchestrator upgrades the flow profile per [escalation.md](escalation.md) rules. If risk becomes irreversible mid-flight, the orchestrator HALTS and calls `AskUserQuestion` for explicit consent. See [escalation.md](escalation.md) for paths and token accounting.
### Worker brief detail floor (Team Lead contract to Workers)
Every Worker dispatch must hit a mandatory detail floor in the brief. Sparse briefs are a doctrine violation — the Worker fills gaps with assumptions; the per-batch Reviewer can only check what was asked for; the resulting commit is plausibly-right rather than actually-right. Detail isn't padding; it's the Worker's only signal about scope.
**Authored at plan time by default (`briefs=auto`).** For non-trivial sub-tasks the detail floor is met *once, on the strong planning model*, and stored as a per-sub-task brief file (`.hyperflow/tasks/<slug>/T<id>.md` flat, `phase-*/tasks/T<id>.md` feature). At dispatch the Composer **loads that brief verbatim** and only appends Project Context + learnings + the specialist output-contract — it does not re-derive the floor. This is what lets the build run faithfully on a **cheaper model or a second session**: the expensive thinking (decompose, design each change, enumerate the realistic test set + the E2E case) is paid in `plan`; `dispatch` transcribes. The Composer authors inline only when no brief exists (a trivial sub-task or a legacy terse task file).
**Mandatory sections in every brief (no exceptions):**
| Section | What it contains |
|---|---|
| **Task** | One verb-led sentence stating the objective |
| **Why** | 1-3 sentences on motivation. What changes for user/system after this lands? Quote spec/ticket if known |
| **Scope** | Explicit `IN:` list (what this brief owns) AND `OUT:` list (related work owned by other sub-tasks; don't touch even if noticed nearby) |
| **Files in scope** | Per-file lines tagged `Read:` / `Modify:` / `Create:` with the reason or change description |
| **Acceptance criteria** | High-level shape-level PASS definition — importable from X, output shape Z, commit message stub |
| **Test cases** | Concrete input → expected-output table reflecting **real domain logic + real edge cases**. Min 3 cases as a floor, but 3 is rarely enough for non-trivial tasks — aim for the realistic set: every domain edge case the feature handles + integration failure modes. Quality > arbitrary count. The decision agent writes cases by thinking through: (1) domain logic — real user inputs, real outcomes; (2) domain edges — Unicode / RTL / boundaries / currency-specific rules / business-rule corner cases; (3) system edges — races / retries / timeouts / malformed responses / concurrent updates; (4) integration surface — what callers can pass. Worker implements against the table AND, for code tasks, writes verifying test code as part of the deliverable. Per-batch Reviewer runs / verifies each case row-by-row to confirm PASS. Format: \\| # \\| Name \\| Input \\| Expected \\| Notes \\|. Omit ONLY when genuinely test-impossible (one-line README typo); state `Test cases: N/A — <why>` so omission is deliberate. |
| **Related context** | Pointers (file:line, sibling sub-task IDs, spec sections) the Worker reads ONLY if the brief becomes ambiguous — orientation, not scope |
| **Context** | Module-level explanation + project conventions + constraints. Examples with file:line citations beat abstract rules |
| **Project Context** | Inline excerpts (default mode) OR paths-only (lean mode) — see worker-prompt.md template |
| **Constraints** | No Claude-as-actor anywhere; no `--no-verify` on git commits; only modify files listed in scope |
| **Security Constraints** | Full blocklist as in worker-prompt.md template |
| **Output format** | Completed / OVERSIZE / BLOCKED contract |
**Relaxation under `mode=lean` AND `triage.complexity == low` AND 1-2 file / 1-function scope:** Why may be 1 sentence; Scope IN/OUT may be single lines; Related context may be omitted when truly none apply. Task, Files in scope, Acceptance criteria, **Test cases (≥3)**, Output format, Security Constraints remain mandatory in all modes — they're the contractual minimum. Test cases never relax — even a one-function lean task needs happy-path + edge case + error case to be reviewable.
**Why this matters.** A Worker dispatched with `Task: add login` and nothing else will produce *a* login implementation that's plausibly-correct but probably wrong on scope, edge cases, or convention. A Worker dispatched with the full detail floor produces exactly what the Planner intended, with edge cases handled and the right sibling-coordination respected. The per-batch Reviewer's job is to verify the work matches the brief — if the brief was vague, the Reviewer has nothing to check against. Detail floor exists so the Reviewer has something concrete to PASS/NEEDS_FIX against.
**Anti-patterns** (each is a doctrine violation):
- "Task: add X" with no Why / Scope / Acceptance criteria / Test cases — Worker guesses scope, Reviewer has no contract to verify against
- Listing files as "Modify: src/auth/" (folder) — must be exact paths per file with per-file change description
- Skipping `OUT:` because "the Worker should figure out what not to touch" — they won't; scope creep is the result
- Skipping `Acceptance criteria` because "the test suite covers it" — Reviewer needs the explicit pass criteria, not inferred from tests
- Skipping `Test cases` because "the Worker will figure out the right tests" — they'll write tests for the obvious paths and miss the edge / error cases the brief should have specified. Minimum 3 cases (happy + edge + error) is non-negotiable unless the task is genuinely test-impossible
- Writing test cases as prose narrative instead of the structured table — table is mandatory because the Reviewer parses it row-by-row to verify each case PASSes
- **Formulaic / generic test cases that don't reflect the actual task domain** — three rows of "happy path / error / empty input" with no domain content is a template, not test cases. Every task has its own real edges: Unicode in a search bar, currency-specific decimals in money math, race conditions in concurrent writes, partial network failure in remote calls, RTL strings in UI components, schema-version mismatches in serialized payloads. The decision agent must think through what THIS task's surface actually exposes
- Test cases that just restate Acceptance criteria in table form — Acceptance is shape (`exported as X`); test cases are behavioural input→output (`render("John Doe") → "JD"`)
- Vague Expected column ("works correctly", "returns the right thing") — must be a specific value or behavior the Reviewer can check programmatically
- Padding to hit the floor with near-duplicate cases ("happy path with name=John", "happy path with name=Jane") — duplicates aren't coverage
- Copy-pasting test cases from a similar prior sub-task without rethinking the domain — every task has its own edges
- Inlining the security blocklist as a 1-line "follow security rules" — must be the full enumerated blocklist so workers can actually check
- Using "Claude will" / "the AI will" anywhere in the brief — DOCTRINE rule 9 banned narrative subject
### Oversize task splitting (decision agent — Planner mandate)
**A single Worker dispatch must never own more than one reviewable unit of work.** The decision agent splits oversized work into multiple parallel sub-tasks rather than handing one Worker a giant brief. Two enforcement points:
**1. At planning (plan Step 9 · pre-dispatch).** The Planner (decision agent — Planner) MUST split any sub-task that meets ANY of these signals:
| Signal | Threshold |
|---|---|
| File breadth | > 5 files touched |
| Change volume | > 500 LOC of expected changes |
| Subsystem cross-cut | touches 2+ distinct subsystems (auth + UI + DB, frontend + API + migration, …) |
| Complexity tag | `complexity = high` from triage |
| Mixed concerns | one sub-task spans data-model + business-logic + UI + tests |
| Reviewability | a human reviewing the resulting commit would need > 10 minutes to grasp it |
Split target: each resulting sub-task should be (a) reviewable in under 10 minutes of human time, (b) fit comfortably in a single Worker prompt + reasonable response, (c) have a single coherent purpose nameable in one conventional-commit subject line. Aim for sub-tasks at `complexity = low | medium` after the split; never keep `high`.
**2. Mid-flight (Worker `OVERSIZE` escape hatch).** If a Worker discovers during execution that its brief is bigger than the Planner estimated (e.g., the file is 5k lines instead of 500, the refactor touches more callers than expected, the test scope has cascading dependencies), the Worker returns:
```
OVERSIZE: <one-line reason>
SUGGESTED-SPLIT:
- <sub-task A name> · <files A> · <one-line purpose>
- <sub-task B name> · <files B> · <one-line purpose>
- <sub-task C name> · <files C> · <one-line purpose>
```
The orchestrator (Team Lead) does NOT proceed with the oversized brief. Instead it dispatches a decision agent consultation: "given the Worker's `OVERSIZE` signal and `SUGGESTED-SPLIT`, produce the final split plan and updated batch graph." decision agent returns the canonical split; the original sub-task is removed from the batch and N new sub-tasks are dispatched as a new sub-batch in the same dispatch cycle. The user is NOT asked — this is a mechanical reshape of a too-large brief, not a decision (Worker raised it, decision agent decided it).
**Anti-patterns** (any of these is a doctrine violation):
- Letting a Worker run with an oversized brief because "it might still finish" — wastes tokens, produces unreviewable commits
- Splitting the work inline in the Team Lead's main session — splits must come from a fresh decision-agent dispatch with full context
- Firing `AskUserQuestion` to confirm the split — splitting is a mechanical reshape, not a decision the user should be paged for
- Skipping the split signals at planning time because "the Planner thought it was fine" — the signals are non-negotiable; the Planner runs them as a checklist
- Producing one giant commit at the end with all the split work merged together — splits exist precisely so each piece commits separately (per-task cadence preserved)
**Cost rationale.** Three small sub-tasks dispatched to three Workers in parallel cost less wall-clock time AND less total tokens than one Worker chewing through an oversized brief, because (a) parallelism cuts elapsed time, (b) each smaller prompt produces a focused response without context bloat, and (c) a focused Worker rarely needs retries. Splitting is a cost optimisation, not just a quality one.
### Rules
1. **Always decompose first.** Even a single file edit: a Worker edits → a Reviewer verifies.
2. **Parallel by default.** Sub-tasks that don't share state get dispatched simultaneously in a single message with multiple Agent tool calls.
3. **Learning injection.** After each batch, extract patterns/gotchas from worker outputs. Inject synthesized learnings into subsequent worker prompts.
4. **Self-contained prompts.** Workers get full context — file paths, what to do, constraints, prior learnings. Never tell them to "check the plan" — paste the relevant bits.
5. **Worker prompt template.** See [worker-prompt.md](worker-prompt.md). Personas (from triage `personas[]`) are stitched under a `## Persona` section in the worker prompt — see [personas-A.md](personas-A.md) and [personas-B.md](personas-B.md).
6. **Multi-level review (per-batch + final integration).** After each batch, dispatch a per-batch Reviewer — anchored to that batch's diff at L1-L<n>. After all batches complete, dispatch the final integration Reviewer — sees the cumulative diff and catches cross-batch contradictions. `--thorough` flag adds a standalone / final-integration review pass for high-risk surfaces. Scale levels by complexity (simple: L1-2, medium: L1-3, complex: L1-5). See [reviewer-prompt.md](reviewer-prompt.md) and [reviewer-prompt-batched.md](reviewer-prompt-batched.md) for templates and [review-levels.md](review-levels.md) for the full checklist.
7. **The orchestrator stays active.** The orchestrator never goes idle while workers run. It reviews each worker's output as it arrives, asks the user questions if ambiguity surfaces, assists or re-scopes stuck workers, and validates integration between outputs. If a worker is taking too long or producing poor results, the orchestrator intervenes — breaks the task smaller, provides more context, or escalates by dispatching a fresh decision agent.
8. **Minimum decision agents = profile-dependent (asymmetric under D7).** `fast` = 1 (inline self-review); `standard` ≥ 1 per batch; `deep` / `scientific` = batches + 1 (per-batch reviewer + final integration) when integration review runs; = batches (per-batch reviewers only) when D7 conditional-skip fires (all batches first-try PASS + no escalations + no security/integration flags). A task with `Decision / review: 1 agent` and multiple batches in `deep` mode is wrong — it means batch reviews were skipped. See `skills/dispatch/SKILL.md` Step 3 for D7 skip conditions.
9. **Agent labels.** Before every Agent dispatch, print a single elegant line. No icons, no brackets, no emoji. Format: `Role — short description` (em-dash separator, description lowercase, under 80 chars).
- `**Reviewer** — reviewing auth middleware output`
- `**Debugger** — investigating test failure in auth.test.ts`
- `Implementer — creating auth middleware`
- `Searcher — finding related test files`
- `Writer — generating API documentation`
Decision / review roles (`Reviewer`, `Debugger`) wrap the role in `**bold**`. Worker roles (`Implementer`, `Searcher`, `Writer`) stay plain. The bold gives visual hierarchy between "brain" and "execution" without using icons. Never use `⚡`, `→`, `*`, `[]`, `✓`, `✗`, or any decorative character. See [output-style.md](output-style.md) for parallel dispatch format.
10. **Usage tracking.** Track every agent dispatch and token usage (from `<usage>total_tokens: N</usage>` in agent results). Track **wall-clock** (elapsed real time from first `Agent()` call to last `⎿ Done`) and **cumulative** (sum of individual durations from each `⎿ Done (... · Ym Zs)`) separately — the ratio between them proves whether `parallel:N` dispatches actually ran parallel. After the task completes, print a usage summary. Triage, spec depth, and profile lines surface up-front when a flow profile is in play. See [escalation.md](escalation.md) for the canonical format and [output-style.md](output-style.md) for visual rules.
```
── Hyperflow Usage ─────────────────────────────────────────
Triage 1 agent 1.8k tokens
Spec depth: standard 1 agent 3.2k tokens
Profile: deep — —
Decision / review 4 agents 52.1k tokens (3 batch · 1 final)
Worker 8 agents 186.0k tokens (4 implementer · 3 searcher · 1 writer)
Wall-clock 3m 47s
Cumulative 14m 22s (ratio 0.26 — parallel)
Escalations 0
Total 14 agents 243.1k tokens
────────────────────────────────────────────────────────────
```
`ratio = wall-clock / cumulative`. Annotation: `parallel` (≤ 0.5), `mixed` (0.5–0.8), `serial` (≥ 0.8). For a multi-batch task where labels say `parallel:N` but the ratio comes out ≥ 0.8, see Red Flags — the orchestrator broke rule 2 by dispatching across separate messages instead of one.
**What counts as a decision agent:**
- Every batch review MUST be a dispatched `Agent` call — reading files yourself and saying "looks good" is NOT a review and does NOT count.
- The final integration review MUST be a dispatched `Agent` call — never inline.
- If a decision agent shows `0.0k tokens`, it wasn't actually dispatched — it was inline work that doesn't count.
- The orchestrator's own work (decomposition, coordination, tool calls) is inherently untracked. This is exactly why reviews must be dispatched — they are the only measurable decision work.
11. **Task tracking.** For non-trivial tasks (2+ sub-steps), create a task file in `.hyperflow/tasks/<task-name>.md` before dispatching workers. Update progress after each batch. Delete on completion. See [task-tracking.md](task-tracking.md).
12. **Multi-level agents inside every step.** Every substantive step in every chain skill MUST dispatch at least one Agent — never do "real" work inline. A step counts as substantive when it produces output the next step depends on (analysis, decomposition, generation, review, decision). Pure user-interaction steps (`AskUserQuestion`, `Skill` hand-off, printing a status line) are exempt. The pattern for each substantive step:
- **Worker role** does the production work (research, synthesis, drafting, decomposition).
- **Decision / review role** reviews/decides on the worker's output (verdict, gate, escalation).
- Both dispatches appear in the usage summary; both count toward the `decision agents ≥ batches + 1` minimum.
- If a step's worker output is trivial (e.g. one-line restate), the review may be merged into the next step's review — but never both skipped.
Skills MUST declare per-step agents in their body so this is auditable: each Step block lists `Worker → <role>` and/or `Reviewer → <role>` lines.
12.1. **Trivial steps may be performed inline by the orchestrator without an Agent dispatch wrapper.** A step qualifies as trivial AND inline-allowed IF AND ONLY IF all of:
1. The step's entire body is reducible to ≤ 2 tool calls (e.g., one Edit + one Bash commit)
2. No content generation required (no Writer producing prose; just file moves, deletions, commits)
3. No semantic decision-making required — branching is limited to mechanical state checks (file existence, git status, commit hash). NOT eligible: content evaluation, scoping choices, prioritization, or any judgment that varies by context.
4. No review needed (the step is mechanically verifiable — git status clean, file exists/absent, commit hash)
5. The orchestrator is the natural executor
Explicitly NOT trivial: code/doc generation, multi-file change, cross-file consistency reasoning, research/Read of unfamiliar context, any output a Reviewer would meaningfully evaluate. Non-trivial steps remain Agent-dispatched per §12.
If the orchestrator discovers mid-step that the work requires generation or research, it MUST abort the inline path and dispatch an Agent. Trivial-eligibility is evaluated at step-start, not assumed throughout.
12.2. **Sub-phase decomposition.** Every non-trivial Step (per §12, not §12.1-exempt) MUST decompose into ≥ 2 named sub-phases unless intrinsically atomic. A **sub-phase** is a named unit `Step Na`, `Step Nb`, `Step Nc`, ... inside a parent Step.
**Sub-phase rules:**
1. **Named.** One-line name describing what the sub-phase produces (`Step 2a — Surface mapping`).
2. **Parallel by default.** Sibling sub-phases dispatch in one message (P1). Sequential only when an explicit data dependency exists; the dependency is documented in the sub-phase header (`Step 4b — depends on Step 4a output`).
3. **Multi-agent per sub-phase.** Each sub-phase dispatches **≥ 2 Worker Agents in parallel**, each exploring a different angle of the same concern (e.g., glob discovery + import-graph traversal + symbol-graph probe). Single-Worker sub-phases are allowed only when no independent angle exists (rare — and the sub-phase header must justify it: `Step 3a — Sequential synthesis (no parallel angle: single canonical aggregation)`).
4. **Per-sub-phase Reviewer.** Each sub-phase dispatches **one Reviewer** over its workers' outputs. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}. Counts toward the §13.P2 decision-agent floor but does NOT replace the per-batch and final-integration Reviewers — those still run at higher granularity over cumulative sub-phase outputs.
5. **Aggregation.** The parent Step's output is the union of its sub-phases' worker outputs plus the per-sub-phase Reviewer verdicts. If a sub-phase Reviewer returns `NEEDS_REVISION`, the parent re-dispatches only that sub-phase (not the whole Step).
6. **Numbering.** Letter suffixes on the parent Step number (`2a`, `2b`, `2c`). Cross-skill references to the parent Step (`plan Step 5`, `dispatch Step 0.5`) remain valid and resolve to the sub-phase aggregate. Backwards-compatible.
7. **Floor.** A Step has either 0 sub-phases (atomic, exempt) OR ≥ 2 sub-phases. Never exactly 1 — that's just the Step with extra syntax.
8. **Atomic exemption.** A Step is atomic when its entire body is one of: a single `AskUserQuestion` call · a single mechanical decision (file existence, git status, route choice) · a single Worker → Reviewer pair with no independent angles to fan out across. In all other cases, decompose into ≥ 2 sub-phases.
**Cost.** Per parent Step with N sub-phases, +N Reviewer dispatches (one per sub-phase, ~5k tokens each for small diffs). A typical 5-substantive-Step chain skill with avg 3 sub-phases per Step adds ~15 reviews · ~75k tokens. Acceptable for the granular catch — sub-phase misses (e.g., the surface mapping Searcher missed a critical file) get caught BEFORE the parent Step's per-batch Reviewer aggregates the propagation downstream.
**Worked example — plan Step 3 (Context):**
- OLD: `Step 2 — Research (Searcher × 2 parallel)`
- NEW:
- `Step 2a — Surface mapping` — Searcher × 2 (glob discovery + import-graph traversal) → Reviewer
- `Step 2b — Semantic indexing` — Searcher × 2 (type-system probe + symbol-graph probe) → Reviewer
- `Step 2c — Convention scan` — Searcher × 1 (existing test patterns + lint config; single-angle, justified inline) → Reviewer
- Step 2 aggregate (union of 2a/2b/2c outputs + 3 sub-phase verdicts) handed to Step 3
**Compatibility.** §12.2 does NOT relax §12 or §13. Every sub-phase still respects rule 6 (multi-level review), rule 8 (decision-agent floor), and the latency patterns. Sub-phase Reviewers ADD to the thinking-agent count; they don't substitute for batch or integration Reviewers.
13. **Latency discipline.** Reduce wall-clock time by restructuring *when* and *how* dispatches fire — never by cutting who reviews what or which role does it.
- **P1 — Parallelize sibling workers.** Sub-tasks that share a common upstream input and have no inter-dependency MUST be dispatched in a single message with parallel `Agent` calls. Never sequentialize siblings.
- **P2 — Batch sibling reviews.** When N sibling outputs share the same review-level cap, dispatch ONE Reviewer using `skills/hyperflow/reviewer-prompt-batched.md` instead of N per-sibling calls. Returns per-sibling verdicts; cross-section coherence checks improve as a side-effect. The batched Reviewer counts as **one** Reviewer per batch toward the `decision agents ≥ batches + 1` floor, regardless of sub-task count. Floor lowered from +2 to +1: wrap-up Reviewer dropped per §12.1 (wrap-up is mechanical, trivial-eligible).
- **P3 — Concurrent independent pre-conditions.** Steps whose outputs do not depend on each other are dispatched in the same message regardless of `--thorough`. Always on.
- **P4 — Triage-driven step skipping.** When `triage.ambiguity < 0.6 AND complexity != high`, optional design-exploration steps (plan Step 4, Step 6) may be skipped. When `ambiguity < 0.4 AND complexity == low`, plan bounces past the design phase directly to decomposition (Step 9). The 2-question floor (rule 8) is never skipped — it is non-negotiable; only the bounce path exits the design phase. Thresholds and borderline rounding rules are in `skills/hyperflow/latency-patterns.md` §P4.
- **P5 — Lean worker prompts via memory references.** Prefer `skills/hyperflow/worker-prompt-lean.md` for default dispatches. Workers `Read` only the `.hyperflow/memory/` files they need. Smaller prompts reduce time-to-first-token; context access is on-demand, not absent.
- **Compatibility with §12.** §13 does NOT relax §12. Every substantive step still dispatches at least one Agent. §13 governs the structure of those dispatches (parallel vs sequential, batched vs per-sibling, lean vs full).
- **Quality floor preserved.** Review depth is unchanged. Workers still face a dispatched review. What changes is when calls fire and in what grouping, not who reviews what.
- **`--thorough` / `depth=max` disables P1, P2, P4.** P3 and P5 remain on — they carry no quality tradeoff. When the flag is active, restore sequential drafts, per-section reviews, and full step execution.
- **`--lean` / `mode=lean` enables low-token mode WITHOUT quality reduction.** Opt-in token savings limited to mechanisms that preserve review quality, persona coverage, memory injection, and every clarification gate. When the flag is active:
- **Project context as paths:** workers receive a `Project Context:` block with the PATHS `.hyperflow/profile.md` / `architecture.md` / `conventions.md` + a one-line description each, instead of the inlined content. They read on demand when their task needs it. Saves ~2k × N parallel workers per batch with zero quality impact (the info is identical, just lazy).
- **Session-context bundle reference:** workers receive the path `.hyperflow/memory/session-context.md` (written once at session start by scaffold or the hook) instead of having profile + architecture + conventions + index re-injected into every worker prompt. Pure deduplication.
- **Session-start hook output:** collapses Project Snapshot / Memory Index / Bridge notice / Sticky status into one summary line (e.g. `hyperflow v4.12 · profile fresh · 12 memory entries · auto-bridge OK · sticky=auto · 0 active tasks`) when nothing needs attention. Full sections return when any are stale, advisory-worthy, or attention-needed. Cosmetic — no quality impact.
- **Artefact format minimal-mode:** small tasks (`triage.complexity == low` AND projected sub-tasks ≤ 5) use the minimum task-file template (status table + Goal + per-task lines + cost table). Scope-at-a-glance table and ASCII dependency diagram return automatically when the task graduates past 5 sub-tasks or any sub-task has `complexity != low`. So the rich format always fires when it's actually useful.
- **Estimated combined effect** on a typical 5-batch dispatch: ~200k tokens → ~140k tokens (~30% reduction). Quality floor preserved across every dimension:
- Persona stitching: **unchanged** (still top-3 persona blocks per worker)
- Memory injection: **unchanged** (still injects all tag-matched warm-tier entries; hot tier always loads)
- Per-batch Reviewer template: **unchanged** (full `reviewer-prompt-batched.md` with all L1-L<n> checklist examples)
- Per-batch review: **unchanged** (fires every batch; `--thorough` adds a standalone / final-integration pass)
- Final integration Reviewer: **unchanged** (always fires when D7 conditions not met)
- Clarification questions: **all gates fire as normal** — plan 2-question floor (design path), plan post-research clarify (bounce path), audit fix-gate, deploy commit-inclusion + push, section approvals
- Security blocklist enforcement: unchanged
- SECURITY_VIOLATION halt: unchanged
- **Incompatible flags:** `--lean` and `--thorough` are mutually exclusive. If both passed, refuse with a clear error rather than silently picking one.
- **Persistent default:** set per-project via `.hyperflow/.mode` (`lean` / `default` / `thorough`); read at every chain start.
- **What `--lean` does NOT do** (these were considered and rejected because they reduce quality): persona top-1 only, memory ≥2-tag-match filter, reviewer-template lean variant. The default behavior is the right behavior for review work; only the lazy-context optimisations qualify under "preserve quality".
See [latency-patterns.md](latency-patterns.md) for the full P1–P5 pattern catalogue. `--lean` is orthogonal to the P1–P5 latency optimisations (which target wall-clock); `--lean` targets token cost specifically.
14. **Failure recovery — explicit retry/escalate/abort policy.** When a Worker errors out (tool failure, OOM, 5xx from a service, timeout, malformed output) or when a Quality Gate (Layer 5: lint/typecheck/build/tests/security) fails, the orchestrator follows the canonical policy in [failure-recovery.md](failure-recovery.md). Summary:
- **Worker tool error** (crash / OOM / 5xx / timeout): retry once with the same prompt. If second attempt also errors, escalate — dispatch a fresh decision agent with `Prior attempt failed: <error>` injected. If that also errors, abort the batch and surface the error chain to the user with `WORKER_ABORT: <chain>` — never silently swallow.
- **Worker malformed output** (didn't follow the prompt schema, returned wrong artifact type): one retry with the violation included in the brief (`Prior attempt produced X; expected Y`). Second failure → escalate to a decision agent. Third failure → abort.
- **Worker NEEDS_REVISION verdict from Reviewer** (different from error — Reviewer judged the output insufficient): one retry with the Reviewer findings injected as a `## Learnings from review` section. Second NEEDS_REVISION → escalate verdict to user via short status print (NOT AskUserQuestion mid-flight; just inform). Worker is not re-dispatched a third time.
- **Quality Gate failure** (lint/typecheck/build/tests/security): one retry of the gate (caches may be stale). If still failing, surface to user with the exact failing command + stderr; do not proceed to push. Never `--no-verify`, never auto-fix without explicit dispatch of an Implementer with the failure injected as the task.
- **Reviewer error**: same as Worker tool error (retry → decision agent → abort).
- **Cross-cutting:** every retry counts against the chain's wall-clock budget. After 3 cumulative aborts in a single chain, the chain itself aborts and prints the full failure trail.
**Observability:** every retry / escalation / abort emits one status line per [failure-recovery.md § Observability](failure-recovery.md) — the failure-recovery budget burn is visible in real time, not only at chain end.
**Why explicit:** before rule 14, each skill's failure path was implicit ("Reviewer intervenes") and skills handled it differently. Explicit policy means consistent recovery behavior, observable failure modes, and zero ambiguity about when to surface to the user.
15. **Triage validation.** Triage (Layer 0.5) classifies each request into `{ types, complexity, risk, scope, ambiguity, flow, personas[] }` via a single Classifier call. A bad triage cascades through every downstream decision — wrong flow profile, wrong personas, wrong batch decomposition — silently. Before any chain-starter consumes the triage output, dispatch one **Triage Reviewer** that validates the classification against the user's request + the project profile. Verdict ∈ {`PASS`, `RECLASSIFY`, `ESCALATE`}.
- **PASS** → consume triage as-is, proceed to next Step.
- **RECLASSIFY** → Reviewer returns a corrected classification with reasoning; orchestrator uses the corrected version, prints a one-line note to the user (`Triage reclassified: complexity high → medium · personas added: [security]`).
- **ESCALATE** → Reviewer can't decide; fall through to the user via a Smart Question early in plan Step 5 asking about the ambiguity.
Triage Reviewer cost: ~2k tokens per chain. Catches mis-classifications that would otherwise waste 100k+ tokens on the wrong flow. Net win.
**P4 skip:** when `triage.complexity == low AND triage.ambiguity < 0.2 AND scope ∈ {0-file, 1-file} AND risk != high`, skip the Triage Reviewer dispatch and consume the original Classifier output. The cost of a mis-classification at this confidence tier is bounded by the small-task token budget; the Reviewer's value evaporates. Print a one-line skip note for observability.
16. **Token economy — every agent stays specific and to the point.** Workers and Reviewers produce only what their contract asks for. No preamble ("I'll now …", "Let me start by …"), no restating the brief back, no postamble summary recapping what was just done, no narration of intermediate reasoning, no "here's a summary of my changes" block when the Output format already specifies one-line-per-change.
- **Output discipline.** Worker output = one-line summary per change + optional Notes for future tasks (omit when none). Reviewer output = the verdict block specified in `reviewer-prompt.md` / `reviewer-prompt-batched.md` — verdict line + per-failure finding, nothing else. Status lines printed by the orchestrator stay ≤ 1 line each.
- **Input discipline.** The Worker brief detail floor (§ Worker brief detail floor) is a FLOOR, not a target. Once the mandatory sections are present, do not pad with extra background, related-art tours, restated project conventions the worker already loads from `.hyperflow/`, or "for context" paragraphs the task does not need. Specificity beats volume — one file:line citation that actually matters > three paragraphs of orientation.
- **Banned in agent output:** "I'll do X", "Here's what I did", "Let me know if you'd like …", "In summary, …", "Hope this helps", any closing pleasantry, any meta-commentary about the review/implementation process itself, restating the input brief, listing files the worker DIDN'T touch.
- **Banned in agent input:** padding the Why section past 3 sentences when 1 suffices, listing every nearby file under Related context when only 1-2 matter, inlining `.hyperflow/conventions.md` content into Context when the worker can `Read` it on demand under `mode=lean`, restating the security blocklist in full prose when the enumerated block already does the job.
- **Why it matters.** Every padded prompt and every padded response burns tokens that don't move the task forward, and inflates the cumulative budget shown in the usage summary. The detail floor exists so the work is reviewable; token economy exists so the work is affordable. Both apply simultaneously.
17. **Brain specialist dispatch.** Reviews and investigations are performed by the **matching specialist agent**
([`../../agents/README.md`](../../agents/README.md)), not a generic role. The flow:
- Triage emits a candidate `specialists[]` from `types[]` (fixed derivation table in [task-triage.md](task-triage.md)).
- The **Brain** ([`../../agents/brain.md`](../../agents/brain.md)) is consulted **once** after triage to finalize
the responsible roster, the per-specialist web-research decision, and fan-out approvals. On `fast`/`standard`
non-security flows Brain is a cheap inline pass-through (no separate dispatch); on `deep`/`research`/`scientific`/`security`
it actively reasons.
- **Decide once, inherit downstream.** Brain's decision is written into the artefact (plan spec status block → plan
task file) and consumed by every later phase. No skill re-derives the roster.
- `plan` **announces** the responsible specialists; `dispatch`/`audit`/`trace`/`deploy`
**dispatch** them. A per-batch reviewer is dispatched *as* the specialist matching that batch's surface, in the
role in Layer 2 (per-batch in-flight review / standalone full review; always a full review pass for
security/correctness specialists). A multi-surface batch gets the union of matching charters.
- **Specialist-aware review-skip (extends D7).** When a single specialist covered the whole batch surface and it
PASSed first-try, the final integration pass is redundant → skip it. When several specialists touched disjoint
surfaces, keep the final integration pass to catch cross-surface contradictions. The `decision agents ≥ batches + 1`
floor is thus adaptive to surface overlap, not a flat count.
- **Web-research-first** ([web-research.md](web-research.md)) runs only on gated flows (`deep`/`research`/`scientific`/`security`,
and `audit`/`deploy`); specialists cite current sources for best-practice/CVE claims.
18. **Sub-agent fan-out.** A specialist may fan out its own sub-workers, bounded:
- **Who:** only specialists whose charter sets fan-out `allowed` — investigators (`debugger`/`analyst`/`researcher`)
and standalone/final reviewers. Per-batch reviewers may **not** (anchored to one small diff).
- **Depth cap = 1.** Sub-workers may not spawn further sub-agents (no background-of-background).
- **Budget:** ≤ 3 parallel sub-workers (≤ 5 for `vulnerability-reviewer`/`researcher`); sub-agent tokens roll into
the parent's usage line tagged `(N sub-agents)`; the chain `budget` is the ceiling.
- **When:** only when genuinely independent parallel angles exist (researcher comparing 4 libraries; debugger
testing 3 hypotheses). Single-angle work never fans out (mirrors §12.2.3).
- Sub-workers act as workers; the specialist synthesizes. Sub-workers never review or decide. No fan-out
from background agents. One label line per sub-worker; the parent verdict notes the count.
19. **Agent consultation.** A specialist may ask a *peer* for a focused answer mid-task — the lateral sibling of
fan-out. Full contract: [consultation.md](consultation.md).
- **Who:** **every agent in `agents/` — current and future — automatically**, with no per-charter wiring. The
allowlist is the live `agents/` registry (resolved by file existence); a charter's `Composes with:` line is
only the recommended-peer hint, never a gate.
- **Hybrid routing:** build-time **workers are orchestrator-brokered** — they emit `CONSULT: <peer> — <question>`
and stop (never call `Agent` laterally); the Team Lead dispatches the peer and re-dispatches the worker with
`Consultation answer from <peer>:` injected. Design-time **decision agents** (`architect`/`designer`/`analyst`/
future) consult **directly** via their `Agent` tool.
- **Depth cap = 1.** A consulted peer may NOT itself consult (no consult-of-consult, no cycles).
- **Budget:** ≤ 2 consults per worker task, ≤ 3 per design-time decision agent; consult tokens roll into the
parent's usage line tagged `(N consults)`; the chain `budget` is the ceiling.
- **Never overrides a halt.** A `SECURITY_VIOLATION` / `BLOCKED:` still stops the pipeline; a peer that errors
falls back to ESCALATE (rule 14) — the chain never blocks forever on a consult.
### Sub-phase × flag interactions (clarification of §12.2)
**`--thorough` × sub-phases.** Sub-phases are SEMANTIC decomposition (named units inside a Step), not execution mode. The default behavior is sub-phases run in parallel (P1) because they typically have no inter-dependency. `--thorough` disables P1 sibling Worker parallelism within a sub-phase — i.e., the ≥ 2 parallel Workers inside a single sub-phase serialize. But the sub-phases THEMSELVES still run in parallel under `--thorough` because they are not a P1 sibling-Worker construct; they are §12.2 structural decomposition. Skill bodies do NOT need to add `--thorough` clauses per sub-phase; the rule is: sub-phase boundaries always parallel, intra-sub-phase Workers serialize under `--thorough`.
**`--lean` × sub-phase Reviewers.** Per-sub-phase Reviewers participate in the lean Project Context block per §13.P5 — they receive paths to project profile / architecture / conventions rather than inlined content. Saves ~2k tokens per sub-phase Reviewer dispatch (~30 sub-phase Reviewers across a deep chain → ~60k token savings under `--lean`).
**Reviewer-only sub-phases (clarification of §12.2.3).** A sub-phase whose body contains ONLY a Reviewer dispatch with no Workers is FORBIDDEN. If you only need a Reviewer for a parent Step, the Step is atomic per §12.2.8 ("single Worker → Reviewer pair with no parallel angles"). Trace's first refactor pass had this pattern; it was corrected in the second pass and is now explicitly outlawed.
### Learning injection format
```
## Learnings from prior tasks
- [Pattern/gotcha discovered by worker]
- [Decision made that affects subsequent work]
- [File structure detail that matters]
```
Only include learnings relevant to upcoming tasks — don't accumulate noise.
### Layer 3 extension: Background agents
Background agents are an opt-in extension of Layer 3 dispatch. They run with `run_in_background: true`, the chain does not wait, results are integrated later. Three legitimate patterns: **latency reduction** (Layer 5 gates fired while next batch runs), **observers** (CI watcher after push), **speculative prefetch** (refresh `.hyperflow/<analysis>.md` while user picks the next skill). Full doctrine: [`background-agents.md`](background-agents.md). Management surface: `/hyperflow:background list|show|cancel|prune`. Hard rules (apply alongside rule 8): no AskUserQuestion from background, no independent commits, no background Reviewers (reviewers gate decisions), no background-of-background, mandatory cancellation on chain abort, max 30-min runtime cap, OFF by default per skill.
## Layer 4: Adaptive Brainstorming
**Summary:** runs on EVERY task — never skipped. Depth scales to triage `ambiguity` with a **hard floor of 2 questions per design run** (the user always gets a structural place to course-correct). Light = 2Q · standard = 3Q + 2-3 alternatives · deep = 4-5Q + 6-dim analysis + section-by-section approval. `creative`/`architect`/`security`/`scientific` types force a minimum depth. `AskUserQuestion` is mandatory; "Should I proceed?" is banned.
See [doctrine-extensions.md § Layer 4](doctrine-extensions.md#layer-4-adaptive-brainstorming) for the depth table, hard rules (section approval / minimum alternatives / no-code-before-design), and type-based depth overrides. Full framework in [adaptive-brainstorming.md](adaptive-brainstorming.md).
## Layer 5: Quality Gates
**Summary:** lint + typecheck + tests after every worker review. Per-task gate runs on affected files; final gate runs the full suite. Gate fails → worker fixes → re-run. Max 3 retries before escalating to a decision agent.
See [doctrine-extensions.md § Layer 5](doctrine-extensions.md#layer-5-quality-gates) and the full policy in [quality-gates.md](quality-gates.md).
## Layer 6: Project-Scoped Memory
**Summary:** `.hyperflow/memory/` holds project-scoped learnings (entries never leak across projects). Hot tier (≤7d) eagerly loaded; warm (8-30d) queried by task tags; cold (30+d) compressed and archived. Workers receive ONLY tag-matched subset.
See [doctrine-extensions.md § Layer 6](doctrine-extensions.md#layer-6-project-scoped-memory) for storage layout, write/read/prune rules, and runtime controls. Full protocols in [memory-system.md](memory-system.md).
## Layer 7: Task Templates
**Summary:** pre-built decomposition patterns auto-selected from task type — CRUD Feature, API Endpoint, UI Component, Database Migration, Refactor, Bug Fix. Templates adapt to context; not rigid steps.
See [doctrine-extensions.md § Layer 7](doctrine-extensions.md#layer-7-task-templates) and the catalogue in [task-templates.md](task-templates.md).
## Layer 8: Git Workflow
**Summary:** auto-commit on by default (per approved task, descriptive message); auto-creates feature branch on main/master; never auto-pushes. Disable per-session: `hyperflow: auto-commit off`.
See [doctrine-extensions.md § Layer 8](doctrine-extensions.md#layer-8-git-workflow) and the full workflow in [git-workflow.md](git-workflow.md).
<!-- portable:section id=commit-cadence order=3 title="Commit cadence"
## Commit cadence
Every distinct task or request produces its own commit. Never bundle two features, two fixes, or feature-plus-doc-update into one commit just because they're in one session.
Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:` / `fix:` / `docs:` / `refactor:` / `chore:` / `perf:` / `style:` / `test:`.
<!-- /portable:section -->
## Layer 9: Security
Worker containment via prompt-injected blocklists. See [security.md](security.md) for full rules and configuration.
**Default protections:**
- Blocked files: `.env`, `*.pem`, `*.key`, `~/.ssh/*`, `~/.aws/credentials`, and other sensitive paths
- Blocked commands: `rm -rf` (destructive), `git push --force` to main, `sudo`, `chmod 777`, package publish
- Secret detection: Reviewer checks for hardcoded API keys, private keys, connection strings
**Config:** `~/.hyperflow/config.json` → `security` key. Disable per-session: `hyperflow: security off`.
Workers that hit a blocked resource report `BLOCKED:`. Reviewers that find violations report `SECURITY_VIOLATION:` which halts the pipeline and surfaces to the user.
<!-- portable:section id=security-blocklist order=7 title="Security blocklist"
## Security blocklist
**Blocked files** — return `BLOCKED:` on access:
- `.env`, `.env.*` · `*.pem`, `*.key`, `*.crt` · `~/.ssh/*` · `~/.aws/credentials`, `~/.aws/config` · `~/.config/gcloud/*` · `~/.kube/config`
**Blocked commands** — refuse:
- `rm -rf` · `git push --force` to `main`/`master` · `sudo` · `chmod 777` · package publish (`npm publish`, `cargo publish`) unless explicitly invoked
Reviewer that detects a security violation reports `SECURITY_VIOLATION:` — halt pipeline immediately, no auto-continue.
<!-- /portable:section -->
## Layer 10: Hygiene — finalize on completion, compact proactively
Two non-negotiable cleanup behaviours so artefact folders and the context window stay healthy across long sessions:
### Finalize on completion
When a chain closes successfully — the final integration reviewer approved and per-task commits landed — the **last** thing the closing skill (`dispatch`, `audit`, or `deploy`) does is archive its own working artefact. The orchestrator runs:
```bash
python3 "$CLAUDE_PLUGIN_ROOT/scripts/archive-artefacts.py" "$PROJECT/.hyperflow" --file "$ARTEFACT"
```
where `$ARTEFACT` is the task file (for `dispatch`/`deploy`) or the audit file (for `audit`). The script:
1. Promotes `## Learnings` / `## Decisions` / `## Anti-patterns` / `## Pitfalls` sections to `.hyperflow/memory/*.md` (whole-line de-duped).
2. Moves the source file to `.hyperflow/archive/<type>/YYYY-MM/`.
Net effect: durable insight compounds in memory, and `.hyperflow/{tasks,audits,specs}/` only ever holds work still in flight. Stale files left behind by interrupted runs are still caught by the daily session-start sweep (`cleanup.staleDays`, default 7).
### Proactive `/compact`
The context window is a resource. Automatic `/compact` is allowed only after `/hyperflow:dispatch` reaches its end-of-chain gate and writes `.hyperflow/.dispatch-auto-compact-ready`. The marker is short-lived (`context.autoCompactReadyTtlMinutes`, default 30) and is consumed by the `PreCompact` hook. Before accepting that automatic compact, Hyperflow also checks measurable context usage when the host exposes a signal. Claude Code does not pass a direct percentage to hooks, so Hyperflow estimates it from the hook `transcript_path` against `context.windowTokens` in `~/.hyperflow/config.json` (default 200k). Automatic compaction is only allowed once usage is at or above `context.autoCompactMinPercent` (default 72%); below that, the `PreCompact` hook blocks the auto compact and tells the session to continue.
Manual `/compact` always passes. If dispatch has marked readiness but the transcript or budget cannot be read, the hook stays permissive so true context-limit recovery is never made worse. When a compact does run, the `PreCompact` hook snapshots the active task, decisions, anti-patterns, and uncommitted diff so the chain state survives the squeeze. Surface proactive compaction as a single status line with the estimated percent, not a question; the user can accept or ignore.
## Skills
Hyperflow has no always-on entry. Each skill is invoked explicitly. Chain-starters auto-advance forward.
| Skill | Invoke | Chain | When to use |
|-------|--------|-------|-------------|
| Scaffold | `/hyperflow:scaffold` | standalone | Set up `.hyperflow/`, install multi-tool shims, refresh analysis cache |
| Plan | `/hyperflow:plan` | starter → dispatch | Sharpen, design, and decompose into worker subtasks; writes `.hyperflow/tasks/<slug>.md` |
| Dispatch | `/hyperflow:dispatch` | endpoint | Run a task file — parallel workers + reviews + final integration |
| Trace | `/hyperflow:trace` | standalone | Systematic root-cause analysis for bugs and test failures |
| Audit | `/hyperflow:audit` | standalone | Multi-level code review (L1–L5) on uncommitted changes or a target |
| Deploy | `/hyperflow:deploy` | standalone | Pre-push gates (lint, typecheck, build, tests) + commit + release + push |
| Cache | `/hyperflow:cache` | standalone | CRUD on `.hyperflow/memory/` — show, search, add, prune, archive, clear |
| Handoff | `/hyperflow:handoff` | standalone | Two-session handoff lifecycle — list / status / pickup / review / complete a committed `.hyperflow-handoff/<slug>/` package |
All skills inherit this doctrine — they reuse the same worker/reviewer prompts, model routing, security policies, and memory system. Each skill file is short (~80–150 lines) and references shared files in `skills/hyperflow/*.md`.
Hand-off pattern:
- `/hyperflow:plan` → sharpens, designs, and decomposes (max thinking) → produces a task file → **stops** at the build-location gate (always asked): build here → invokes `/hyperflow:dispatch`; another session → writes a handoff package; stop → keeps the plan. Plan never auto-implements.
- `/hyperflow:dispatch` → runs batches + final review → suggests `/hyperflow:audit` or `/hyperflow:deploy` (no auto-push)
- `/hyperflow:trace` → fixes the bug at root + adds regression test → user invokes `/hyperflow:deploy`
## What This Does NOT Override
- Other active skills (project-specific skills still apply)
- Project CLAUDE.md coding standards
## Red Flags — You Are Violating Hyperflow If You:
- Skip triage on a new user request
- Run a flow profile that contradicts triage output (e.g., `fast` when triage said `deep`) without explicit downgrade
- Skip brainstorming entirely (use `silent` mode, never skip)
- Stitch personas in the wrong priority order
- Ignore `ESCALATE:` returns from workers
- Skip clarification questions before implementation (research → verify → build, never research → build)
- Type a question mark that isn't answering the user's question (except brainstorming/clarification)
- Write more than one sentence before your first tool call
- Execute a task yourself instead of dispatching a Worker
- Skip the review after a worker completes
- Treat a per-batch review as a substitute for the final integration review
- Dispatch a generic reviewer/investigator when a domain specialist matches the surface (rule 17) — use the named `agents/<name>.md` specialist
- Let a specialist fan out past depth 1, spawn sub-agents from a per-batch reviewer, or fan out from a background agent (rule 18)
- Run web-research-first outside a gated flow (`deep`/`research`/`scientific`/`security`/`audit`/`deploy`), or let a specialist assert a best-practice/CVE claim without citing a current source (web-research.md)
- Skip the Brain decision on a `deep`/`security` flow, or re-derive the specialist roster in a later phase instead of inheriting Brain's decision from the artefact (rule 17)
- Finish a task with `Thinking: 0 agents` in the usage summary
- Show `0.0k tokens` for thinking agents (means you reviewed inline instead of dispatching)
- Skip the final integration review (separate from batch reviews) in `deep`/`scientific` profiles
- Have fewer thinking agents than batches + 1 in `deep`/`scientific` profiles — UNLESS D7 conditional-skip fired (all batches first-try PASS + no escalations + no security/integration flags), in which case `= batches` is the correct floor
- Dispatch workers sequentially when they could run in parallel
- Label a batch `parallel:N` but dispatch the calls across separate messages — that's serial, not parallel. The wall-clock / cumulative ratio will land ≥ 0.8 and expose it. Investigate and re-dispatch with all N `Agent()` calls in a single message.
- Fire an `AskUserQuestion` between batches in `auto` mode — "transparency checkpoint", "midway sanity check", "scope re-confirmation", "cost heads-up", or any rephrasing of *"should I keep going?"*. Per rule 8, auto means finish the chain. The only gates between batches are the structural ones (`SECURITY_VIOLATION` halt, escalation crossing the irreversibility boundary, inter-batch advance in *manual* mode). Status prints are fine; status *questions* are banned.
- Justify the recommendation inside the option label/description — e.g. recommending `No` for the Deploy gate with a multi-sentence rationale about pre-commit fixes and audit findings the user already saw in scrollback. Labels stay ≤ 12 words; descriptions are one short sentence. The orchestrator's reasoning is an input to the recommendation, not output for the user to re-read.
- Flip the Deploy-gate recommendation to `No` based on "soft" signals (pre-commit auto-fixes, audit caught and fixed a bug, many commits, volume of changes). Only the concrete signals listed in `dispatch/SKILL.md` Step 5 (`SECURITY_VIOLATION`, irreversible escalation, ≥2 same-sub-task retries, unresolved `[Critical]`, flaky test) flip the recommendation. Defaulting to `No` because the chain felt heavy is the same paternalism rule 8 bans for inter-batch questions.
- Print a usage summary for a multi-batch task without the `Wall-clock` and `Cumulative` rows — auditability of parallelism is mandatory once 2+ batches or 2+ parallel-eligible workers are in play
- Include "Co-Authored-By: Claude" in any git operation, or reference the LLM as an actor in any artefact (commits, PRs, docs, code comments, skill prose) — see rule 9
- Summarize what you just did
- Describe code instead of writing it
- Write code before the user approves a design (during `deep` brainstorming)
- Ask more than one question per message (during brainstorming)
- Skip the alternatives step and jump to a single solution (during `standard`/`deep` brainstorming)
- Add features the user didn't ask for
- Dispatch an agent without printing `Role — description` first (no icons, no brackets)
- Finish a task without printing the usage summary
- Dispatch workers without creating task files in `.hyperflow/tasks/` first
- Complete a task without deleting its task file
- Sequentialize sibling workers that share a common input and have no inter-dependency, or dispatch per-sibling reviewers when a single batched reviewer covers the same review-level cap
- Wrap every trivial mechanical step in an Agent dispatch when §12.1 inline path applies — adds latency without value
- Let a Worker or Reviewer return preamble ("I'll now …"), postamble summary, restatement of the brief, or meta-commentary alongside the contract output — see rule 16 (Token economy)
- Pad a Worker brief past the detail floor with extra background, related-art tours, or inlined conventions the worker can `Read` on demand — see rule 16
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |