Orchestration

How a request becomes a coordinated multi-agent run.

The chain, triage, per-phase agent dispatch, parallelism accounting, and failure handling — everything that turns a single user request into a set of committed, reviewed sub-tasks.

The chain

Start with a rough idea: amplify rewrites it into the strongest prompt, then hands off to spec. From there spec → scope → dispatch are chain-starters — invoking any of them auto-advances forward through the rest. audit and deploy are gates — never auto-invoked; they fire only on an explicit user Yes to a gate question. scaffold is a one-time project setup (run once per repo), so it sits before the flow rather than inside it.

Two skills sit outside the chain:

Layer 0.5 — triage

Every chain-starter begins with a thinking-tier Classifier dispatch (Layer 0.5 in the doctrine). It returns:

That JSON drives every downstream decision:

Spec → scope → dispatch

Spec

The chain-starter asks at Step 0 whether to advance auto (no gates between phases) or manual (confirm before each). The choice propagates to every downstream skill via the Skill tool’s args parameter. In Codex App/CLI, where that host handoff may not exist, Hyperflow treats the handoff as inline continuation and keeps running the next skill in the same thread.

On Codex App/CLI, /hyperflow:* messages are skill aliases rather than native slash commands. If the host does not expose a popup question UI, every required AskUserQuestion gate renders as a concise Hyperflow Question chat block with numbered options and waits for the answer. The fallback applies to Amplify handoff, Spec questions, Scope ambiguity, Dispatch audit/deploy gates, Audit fix gates, Deploy commit-inclusion, and push confirmation.

Then:

• Classifier — triage JSON (see above)
• Searcher (worker) + Reviewer (thinking-tier) — context exploration
• Analyst (thinking-tier) — 6-dimension brief: intent, technical fit, scope, constraints, risks, alternatives
• AskUserQuestion ×N — design questions, floor 2, scaled by ambiguity; every option list marks a (Recommended) choice
• Writer + Reviewer — requirement synthesis
• Writer + Reviewer — 2–3 alternative approaches with trade-offs
• Writer + Reviewer per design section — 5 sections, each approved by the user
• Writer + Reviewer — final spec file at .hyperflow/specs/<slug>.md
• Hand off to scope

Every step that produces output dispatches at least one Agent (DOCTRINE rule 12). In Codex, Hyperflow maps those dispatches to Codex subagents when available; when subagents are not exposed in the session, the single foreground agent runs the worker/reviewer phases inline with labels and continues. Pure user-interaction steps (AskUserQuestion, Skill hand-off) are exempt.

Scope

• Chain-mode check (skipped if invoked by spec with the arg already set)
• Searcher × 2 (parallel) + Reviewer — research: affected files, related tests, conventions
• Planner (thinking-tier) — produces the batch graph
• Writer + Reviewer — emits .hyperflow/tasks/<slug>.md with the expanded ## Status block that dispatch will keep updating and status will read
• Writer + Reviewer — appends decisions to .hyperflow/memory/
• Hand off to dispatch

Dispatch

The workhorse. Per batch:

• Print the batch header — Batch N — parallel:K or serial:K
• Dispatch all K sub-tasks of the batch in a single message with K parallel Agent tool calls. The runtime executes them concurrently. (Calls across separate messages run serial — see Parallelism below.)
• As each worker returns:
  • Reviewer (thinking-tier) — reviews at L1–L<n> based on flow profile
  • On PASS → commit this sub-task immediately, then update the task file’s ## Status block (tick [ ] → [x], increment done/total, add tokens, refresh wall-clock + ETA)
  • On NEEDS_FIX → re-dispatch worker with the fix list (max 3 retries)
  • On SECURITY_VIOLATION → halt the chain immediately
• After the batch: synthesize learnings, run Layer 5 quality gates (lint / typecheck / tests). If a gate fixes something, it lands as a small extra commit — never amends per-sub-task commits.

After all batches complete:

• Final integration review (thinking-tier, separate from per-batch reviewers, over the cumulative diff)
• Writer + Reviewer wrap-up — delete task file, append memory, chore(memory): commit
• AskUserQuestion — “Run /hyperflow:audit?” (Yes/No, recommended toggles with flow profile)
• AskUserQuestion — “Run /hyperflow:deploy?” (Yes/No, recommended toggles with gate state)

Both gates respect DOCTRINE rule 8 (structural gates always fire). The orchestrator never auto-invokes audit or deploy.

After dispatch

Audit (gated)

If the user said Yes to the audit prompt — or invoked /hyperflow:audit directly:

• Resolve scope (provided target, or git diff HEAD + --staged)
• Searcher + Reviewer — context coverage
• Reviewer at L1–L<n> — structured [Critical] / [Important] / [Suggestions] / [Praise] findings
• Writer + Reviewer — appends durable patterns to .hyperflow/memory/learnings.md
• Print the review block
• Fix gate — “Audit found N issues — apply fixes?”

On any Fix … choice, audit builds a spec file at .hyperflow/specs/audit-<timestamp>.md from the chosen findings and invokes Skill with skill: scope, args: "chain-mode=auto spec=<path>" — the chain runs again to fix what the audit caught.

Deploy (gated)

If the user said Yes to the deploy prompt — or invoked /hyperflow:deploy directly — gates run in order, halting on first failure:

Then:

• Commit — uncommitted worker-introduced changes go in (asks before including pre-existing user changes)
• Release — runs scripts/release.sh if present
• AskUserQuestion — “Push to origin/<branch>?” (Yes/No, recommended toggles with gate state; never force-pushes to main)

Parallelism — provable from the numbers

Parallel dispatch is a prompt-discipline property — multiple Agent calls in Claude Code, or multiple Codex subagent calls when exposed, should be issued together so independent work runs concurrently; the same calls across separate messages run serial. The doctrine mandates parallel-when-possible (rule 2), but enforcement is at the prompt layer.

To make parallelism auditable from the output alone, every batch prints a footer:

And the usage summary at task end:

ratio = wall-clock / cumulative. Thresholds:

If a batch is labelled parallel:N but the ratio lands ≥ 0.8, that is a DOCTRINE rule 2 violation — the calls went out across separate messages instead of one.

Live progress

While a dispatch chain is in flight (or after it completes, while the task file still exists), /hyperflow:status shows:

The data comes from the task file’s ## Status block that dispatch keeps updated after every sub-task PASS — no process watcher, no IPC, just markdown. ETA is avg_per_subtask × pending (×1.1 if the next batch is sequential); shows (computing) while fewer than 3 sub-tasks are done.

Commit cadence — one per sub-task

Every approved sub-task produces its own conventional commit:

A batch of 3 parallel sub-tasks produces 3 commits, not one. Quality-gate fix-ups land as small extra commits on top; memory writes become a separate chore(memory): at wrap-up. Surgical history — bisectable, surgically revertible.

Handling failures

Compaction

Chain state survives a context compact.

Long chains eventually approach the host context limit. Hyperflow checks the current context estimate before letting an automatic compact happen:

• Claude Code’s PreCompact payload includes transcript_path, not a direct context percentage, so Hyperflow estimates usage from the transcript against context.windowTokens in ~/.hyperflow/config.json.
• Automatic compaction is allowed only at or above context.autoCompactMinPercent (default 72%). If the estimate is lower, the hook blocks the auto compact and the session continues.
• Manual /compact always passes. If the transcript or budget cannot be read, the hook stays permissive so true limit recovery is not made worse.
• A PreCompact hook snapshots the volatile state to .hyperflow/.precompact.md right before compaction — active task file(s), structural decisions, hot anti-patterns, and the uncommitted git diff --stat.
• The SessionStart hook (which also fires on the compact trigger) re-injects that snapshot immediately after, then consumes it. The orchestrator comes out of the compact still knowing the task, the decisions, and the quality rules.

The hook only blocks an automatic compact when the estimate is confidently below threshold. It does not block manual compaction, unknown-estimate compaction, or unscaffolded projects; if .hyperflow/ isn’t present the snapshot is skipped silently.

Auto-archive

Finished work cleans itself up.

.hyperflow/{tasks,audits,specs}/ would grow forever if every run left its files behind. A daily-gated session-start step keeps the project tidy:

• For each *.md in those folders older than cleanup.staleDays (default 7), the archiver extracts the ## Learnings / ## Decisions / ## Anti-patterns (or ## Pitfalls) sections and appends them — whole-line de-duped — to .hyperflow/memory/learnings.md / decisions.md / anti-patterns.md. Then the source file moves to .hyperflow/archive/<type>/YYYY-MM/.
• Anything under .hyperflow/archive/** older than cleanup.pruneDays (default 30) is deleted; empty directories collapse.
• A marker (.hyperflow/.last-cleanup) gates the walk to once per 24h per project — repeat session-starts are free.

Tune or disable in ~/.hyperflow/config.json:

Force a run on demand:

Net effect: durable learnings compound in memory, and the working folders only ever hold what’s still in flight.

References