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.
latency-patterns.md
View on GitHub# Latency patterns (P1–P5 + Round 2 L1-L9)
## Purpose
Five orthogonal latency-reduction patterns (P1–P5, round 1) plus nine additional levers (L1–L9, round 2) applied across `plan` and `dispatch`. Round 1 patterns change *when* and *how* calls fire, not the agent count. Round 2 patterns reduce call *count* and eliminate unnecessary review passes — acknowledging that review ceremony around mechanical orchestration steps costs wall-clock without quality return.
## Wall-clock impact
| Pattern | Applies to | Wall-clock win |
|---|---|---|
| P1 — Parallel sibling drafts | plan Step 7, plan Step 3 (context Searchers) + Step 10 (Writer-internal section parallelism) | ~5x on section work |
| P2 — Batched single-pass review | plan Step 7, plan decomposition (Step 9), dispatch | ~5x reviewer calls collapsed |
| P3 — Concurrent independent pre-conditions | plan Step 1+Step 3, Step 5+Step 6, all skills | ~2x on independent steps |
| P4 — Triage-driven step skipping | plan Step 4, Step 6 | up to 100% on low-ambiguity |
| P5 — Lean worker prompts via memory references | all skills | ~30% TTFT reduction |
**Median plan design-phase run (round 1):** ~16 sequential round-trips before → ~6 after. ~60% wall-clock reduction, zero change to which roles review what.
**Dispatch (workhorse, round 1):** P2 alone collapses N per-sub-task Reviewer calls into 1 batched review per batch. On a 3-batch task with 4 sub-tasks per batch: 12 reviewer calls → 3. ~75% reviewer-phase latency reduction.
### Round 2 expected outcomes (median chain: single feature, 3 batches, standard complexity)
| Phase | Round 1 | Round 2 | Cut |
|---|---|---|---|
| Plan (design phase) | 30-45s | 18-28s | ~40% additional |
| Dispatch (per-batch) | 25-40s | 18-28s | ~30% additional |
| Wrap-up | 8-15s | 1-2s (inline) | ~85% |
| End-of-chain gates | 2 round-trips | 1 round-trip | -50% |
**Median chain wall-clock:** round 1 ~90-130s → round 2 ~55-80s. ~35-40% additional reduction on top of round 1's ~50-60%. Cumulative vs pre-round-1 baseline: ~70-75% faster end-to-end.
**Reviewer call count (median chain):** round 1 5-7 calls → round 2 3-4 calls (drop wrap-up Reviewer, skip integration review when green, drop plan context coverage Reviewer).
---
## P1 — Parallel sibling drafts
**What it is:** Draft multiple independent sections simultaneously by dispatching all sibling workers in a single message with parallel `Agent` calls — the same pattern `dispatch` uses for batch workers, applied back to `plan` Step 7 and `plan` decomposition (Step 9).
**When siblings qualify:**
- No inter-dependencies (section A's output is not an input to section B)
- All share the same upstream input (e.g., a single approved approach feeds all 5 design sections)
- Sibling count matches the natural structure: 5 plan design sections (Architecture, Data flow, Key decisions, Edge cases, File structure); do not artificially split to inflate parallelism
**Dispatch pattern:** Fire all sibling Worker agents in one message. Wait for all to return before advancing to the Reviewer step.
**Example:**
```
[plan Step 7] approved approach → single message →
Worker §A (Architecture) ↘
Worker §B (Data flow) → all parallel
Worker §C (Key decisions) →
Worker §D (Edge cases) →
Worker §E (File structure) ↗
→ wait for all 5 → P2 batched review
```
**Why quality is preserved:** The Reviewer still reviews every section. Parallelizing the draft phase does not touch the review phase.
**When to disable:** `--thorough` / `depth=max` flag disables P1 for steps where a prior section's output could meaningfully shape a later section's approach (rare in plan Step 7, common in narrative prose).
**Plan-specific carve-out (critical):** `--thorough` does NOT disable P1 for plan Step 3's parallel context Searchers. Those two Searchers are independent reads — neither's output is an input to the other — so sequencing them provides no quality benefit regardless of flag. `--thorough` only disables P1 where section-order dependency is plausible:
- Step 7 design-section drafts and Step 10 task-file section drafts
- Anywhere else sibling content could cross-influence
**Plan P1 surface under `--thorough`:**
| Plan step | P1 under default | P1 under `--thorough` |
|---|---|---|
| Step 3 — parallel context Searchers | On | **On** (independent reads, no tradeoff) |
| Step 7/10 — Writer section parallelism | On | **Off** (serialized for section coherence) |
If in doubt about whether siblings are truly independent, keep P1 on — the Reviewer catches cross-section conflicts.
---
## P2 — Batched single-pass review
**What it is:** After N parallel drafts complete, dispatch **one** Reviewer with all N sections in its prompt instead of N separate reviewer calls.
**When applicable:** N siblings have completed at the same review-level cap (e.g., all are L3 or all are L5). Do not batch siblings that have different level caps — see "When NOT to use" below.
**Per-sibling verdict format** (Reviewer must return one block per section):
```
§1 Architecture: PASS
§2 Data flow: NEEDS_FIX — [specific feedback]
§3 Key decisions: PASS
§4 Edge cases: PASS
§5 File structure: PASS
```
For each `NEEDS_FIX` section: re-dispatch only that section's Worker; single re-review of just that section. Do not redraft passing siblings.
**Cross-section coherence benefit:** Batched review is strictly better for coherence than sequential per-section review — the Reviewer sees all sections simultaneously and can catch conflicts that per-section passes miss (e.g., a contradiction between §1 Architecture and §5 File structure that neither section alone would reveal).
**Prompt template:** See `skills/hyperflow/reviewer-prompt-batched.md` for the exact prompt structure, verdict format, and NEEDS_FIX handling rules.
**When NOT to use:**
- Siblings have different reviewer-level caps (e.g., some are L3, some require L5 — batch only within the same cap)
- One sibling's content is logically dependent on another sibling's draft completing first (use P1's sequencing to resolve, then batch the independent set)
- The batch would exceed the Reviewer's safe context window — cap at 5 siblings per batch call
**Why quality is preserved:** A single Reviewer pass over N sections is at least as rigorous as N separate passes, and cross-section coherence checking improves.
---
## P3 — Concurrent independent pre-conditions
**What it is:** Dispatch two or more pre-condition steps in the same message when their outputs do not depend on each other.
**Identifying independence:** Step A and Step B are independent if the output of A is not an input to B and the output of B is not an input to A. Both may share an upstream input without losing independence.
**Examples (plan flow):**
| Concurrent pair | Why independent |
|---|---|
| Step 1 Classifier ∥ Step 3 context Searcher | Searcher maps existing context; does not need triage output to begin |
| Step 6 synthesis ∥ Step 6 approaches | Step 5 answers feed both Step 6 synthesis and Step 6 approach drafting; neither sub-part depends on the other's output |
**Dispatch pattern:** Fire both in one message; wait for both before advancing to the dependent step.
**Race-case handling:** If one step fails or returns thin output before the other completes:
- Allow the other to complete
- Reviewer at the next step redispatches the thin result with a better-scoped query informed by the companion output
- Do not re-run both — only the incomplete one
**P3 stays on always.** The `--thorough` flag does not disable P3 — there is no quality tradeoff in running truly independent steps concurrently. Never introduce artificial sequencing between independent steps to appear more thorough.
---
## P4 — Triage-driven step skipping
**What it is:** Skip plan ceremony steps that add no value when the request is already clear and unambiguous.
**Thresholds (round 2 — updated by D8/L8):**
| Condition | Steps skipped | Rationale |
|---|---|---|
| `ambiguity < 0.6 AND complexity != high` | Step 4 (6-dim analysis) + Step 6 (approach proposals) | Nothing ambiguous to analyze; one clear approach exists |
| `ambiguity < 0.4 AND complexity == low` | Design phase (Steps 6-8) | Bounce directly to decomposition (Step 9) — design ceremony adds no value |
**Steps always kept regardless of triage:**
- Step 7 sections (the design walk-through is the deliverable)
- Step 5 questions (2-question floor is a structural gate per DOCTRINE rule 8)
**Borderline rounding rule:** When `ambiguity` lands at or near the threshold (e.g., 0.39, 0.41), **round up** — run the optional steps. The latency win matters on the clearly unambiguous cases; borderline cases keep the full ceremony. Never skip on the fence.
**How this is enforced:** The skill reads `triage.ambiguity` and `triage.complexity` from the triage JSON (see `task-triage.md`) at Step 0, before any step dispatch. Gate logic executes inline in the orchestrator, not inside a Worker.
**When to disable:** `--thorough` / `depth=max` flag disables P4. All steps run regardless of triage scores.
---
## P5 — Lean worker prompts via memory references
**What it is:** Replace inlined context blocks in worker prompts with a 200-token pointer to `.hyperflow/memory/`, letting workers `Read` only what they need rather than receiving everything upfront.
**Why TTFT matters:** Time-to-first-token at the API layer grows with prompt size. Smaller prompts = faster first token = lower wall-clock latency per call, multiplied across every worker in a batch. Token cost is a side benefit; wall-clock is the goal.
**Pointer pattern (replaces inlined blocks):**
```
You have access to project context — read these files as needed:
.hyperflow/ root (project analysis from scaffold Step 1):
- profile.md — project conventions
- architecture.md — system architecture
- conventions.md — naming, patterns, standards
.hyperflow/memory/ (orchestration + accumulated state from scaffold Step 2):
- doctrine.md — orchestration rules (read once if unfamiliar)
- learnings.md — accumulated lessons from prior batches in this run
- decisions.md, pitfalls.md, patterns.md — memory stubs
Your task: <inline task description here>
```
Workers `Read` only the files relevant to their task. Doctrine is read once per session by the first worker that needs it, not re-inlined on every dispatch.
**Prompt template:** See `skills/hyperflow/worker-prompt-lean.md` for the full lean-prompt template — that file is the canonical source. This block is illustrative only.
**Fallback for absent or stub files:** If a referenced file is absent OR appears to be an unpopulated stub (matches a `<!-- to be populated -->` sentinel or has fewer than ~5 meaningful body lines), the worker falls back to a brief inline default for THAT file only — not a wholesale switch to the full prompt. Partial population is the expected failure mode (scaffold creates the directory with stubs); a wholly-missing `.hyperflow/` is the rare edge case.
**P5 stays on always.** The `--thorough` flag does not disable P5 — there is no quality tradeoff in lean prompts. Workers still have access to the full context; they fetch it on demand.
---
## Round 2 patterns (L1-L9)
Round 2 reduces call **count** by eliminating unnecessary review passes. The doctrine floor `review agents ≥ batches + 2` becomes `≥ batches + 1` (L5 drops wrap-up Reviewer), and several Reviewer calls become conditional or are dropped when the work they review is mechanical.
---
### L1 — Lightweight Classifier (D1)
**What it is:** Triage Classifier (plan Step 1) dispatched with a lean, structured-output-only prompt.
**When applicable:** Always — triage produces structured JSON (`types[], complexity, risk, ambiguity, flow, personas[]`). Structured classification requires less reasoning depth than open-ended generation; a focused prompt reduces latency. Inherits the session model like all other agents.
**`--thorough` behavior:** Does NOT change this lever. Lean classification is high-quality for the structured JSON output shape; no accuracy tradeoff justifies a more expensive prompt.
---
### L2 — Combined audit+deploy gate (D2)
**What it is:** Merge the two sequential end-of-chain `AskUserQuestion` calls (audit gate + deploy gate) into a single multi-question call.
**When applicable:** Always at end-of-chain — two sequential user round-trips is pure latency overhead. Branching logic (audit Yes + deploy No → run audit, stop before deploy) is fully preserved.
**`--thorough` behavior:** Does NOT change this lever. No quality tradeoff — questions are identical, branching is identical. The only change is one fewer user round-trip.
---
### L3 — Session-cached context (D3)
**What it is:** `hooks/session-start` concatenates `.hyperflow/profile.md`, `architecture.md`, and `conventions.md` into a single `.hyperflow/memory/session-context.md` bundle at session start. Workers reference the bundle instead of reading three separate files.
**When applicable:** Always when `.hyperflow/` is populated. Mid-session changes to source files do not propagate until next session-start (document the limit). Workers can still `Read` source files directly if they suspect staleness.
**`--thorough` behavior:** Does NOT change this lever. Workers retain full context access; they simply read it from a pre-bundled file rather than three files.
---
### L4 — Drop plan context-Searcher coverage Reviewer (D4)
**What it is:** Remove the Reviewer that reviewed the plan Step 3 Searcher output for coverage completeness.
**When applicable:** Always — in 95%+ of runs, the Reviewer passed with "coverage looks complete". Fallback: if a downstream Writer flags `MISSING CONTEXT: <subsystem>`, redispatch the Searcher with the gap before continuing. Slower on the 5% bad-case path; faster on the 95% good-case path.
**`--thorough` behavior:** RESTORES the coverage Reviewer. Step 3 reverts to Worker + Reviewer pattern for coverage validation.
---
### L5 — Drop dispatch wrap-up Reviewer (D5)
**What it is:** Remove the Reviewer from dispatch Step 4 (delete task file + append memory entry + chore commit). Step 4 executes inline by the orchestrator; no Reviewer dispatch.
**When applicable:** Always for wrap-up — this work is mechanically simple and already validated by per-batch reviewers and the final integration review. Iron rule updates from `≥ batches + 2` to `≥ batches + 1`.
**`--thorough` behavior:** RESTORES the wrap-up Reviewer. Dispatch Step 4 reverts to Worker + Reviewer pattern. Iron rule reverts to `≥ batches + 2`.
---
### L6 — Default L1-L2 cap (D6)
**What it is:** Batched Reviewer level cap defaults to L1-L2 (was L1-L3 in practice). Triage flags `security: bool` or `integration_risk: bool` elevate the cap to L1-L3+ when warranted.
**When applicable:** Standard complexity tasks without security or integration flags. L3 adds integration/security checks; L4 adds perf; L5 adds a11y — most doc edits, small refactors, and config changes don't need L3 review.
**`--thorough` behavior:** Elevates default cap to L1-L3. All batches reviewed at L3 regardless of triage flags.
---
### L7 — Conditional final integration review (D7)
**What it is:** Skip the final integration review when all batches passed first-try AND no escalations AND no security flags fired. Print `"Final integration review skipped — all batches PASSed first try"` and proceed to Step 4.
**When applicable:** Triggered when `all_batches_passed_first_try AND no_escalations AND no_security_flags`. If ANY batch had ≥1 NEEDS_FIX retry, ANY escalation fired, or ANY security flag tripped → integration review runs unconditionally.
**`--thorough` behavior:** Disables the skip entirely. Final integration review always runs regardless of batch outcomes.
---
### L8 — Aggressive P4 thresholds (D8)
**What it is:** P4 triage thresholds tightened — skip multi-dim Analyst at `ambiguity < 0.6` (was 0.4); bounce to decomposition at `ambiguity < 0.4` (was 0.2). Requests at ambiguity 0.4-0.6 operationally rarely benefit from multi-dim analysis. The 2-question floor (Step 5) is preserved non-negotiably.
**When applicable:** Whenever `ambiguity < 0.6 AND complexity != high` (skip multi-dim) or `ambiguity < 0.4 AND complexity == low` (bounce). Borderline rounding rule unchanged: round up on the fence — never skip on ambiguous boundary cases.
**`--thorough` behavior:** Reverts to round-1 thresholds: skip multi-dim at `ambiguity < 0.4`; bounce at `ambiguity < 0.2`. All ceremony runs on higher-ambiguity cases.
---
### L9 — DOCTRINE §12.1 trivial inline (D9)
**What it is:** §12.1 amendment to DOCTRINE §12 — trivial steps (≤ 2 tool calls, no content generation, no decision-making, no review needed, orchestrator is the natural executor) may be performed inline by the orchestrator without an Agent dispatch wrapper. Examples: dispatch Step 4 wrap-up (delete + memory append + commit), plan hand-off invocations.
**When applicable:** Only when ALL five §12.1 criteria are met. Non-trivial steps (any code/doc generation, multi-file change, cross-file consistency reasoning, research/Read of unfamiliar context, Reviewer-eligible output) remain Agent-dispatched per §12. Trivial-eligibility is checked at step-start; if the orchestrator discovers mid-step that the work needs generation/research, it MUST abort the inline path and dispatch an Agent.
**`--thorough` behavior:** Disables §12.1 entirely. All steps Agent-dispatched as in round 1 — no inline execution regardless of triviality.
---
## When to disable
### Round 1 patterns
| Flag | Disables | Keeps |
|---|---|---|
| `--thorough` / `depth=max` | P1, P2, P4 | P3, P5 |
| (none) | — | All five on |
P3 and P5 are always on because they carry no quality tradeoff. P1, P2, and P4 restructure dispatch shape and skip steps; `--thorough` restores sequential drafts, per-section reviews, and full step execution.
**Exception within P1:** plan Step 3's parallel context Searchers stay on even under `--thorough`. They are independent reads with no ordering dependency, so serializing them yields no quality gain. Only P1 surfaces with plausible section-order coupling are serialized by `--thorough` (Step 7 design sections, Step 10 task-file sections).
### Round 2 levers
| Lever | Default | `--thorough` restores |
|---|---|---|
| L1 — Lightweight Classifier | On (lean structured-output prompt) | No change — lean prompt stays |
| L2 — Combined audit+deploy gate | On (1 round-trip) | No change — combined gate stays |
| L3 — Session-cached context | On (bundle) | No change — bundle stays |
| L4 — Drop plan context-Searcher coverage Reviewer | On (no Reviewer) | Step 3 coverage Reviewer restored |
| L5 — Drop dispatch wrap-up Reviewer | On (inline only) | Wrap-up Reviewer restored; iron rule reverts to `≥ batches + 2` |
| L6 — Default L1-L2 cap | On (L1-L2 default) | Cap elevated to L1-L3 default |
| L7 — Conditional integration review | On (skippable when all green) | Integration review always runs |
| L8 — Aggressive P4 thresholds | On (skip at 0.6 / bounce at 0.4) | Reverts to round-1 thresholds (skip at 0.4 / bounce at 0.2) |
| L9 — §12.1 trivial inline | On (inline-allowed) | §12.1 disabled; all steps Agent-dispatched |
---
## Quality preservation
### Round 1 (structural)
Round 1 patterns do not change:
- Which roles review what — Reviewers remain on every Worker output (P2 consolidates calls, does not eliminate them)
- Review level caps — L1–L5 assignments per sub-task are unchanged
- Worker access to context — workers still reach full doctrine and project context via `.hyperflow/memory/` (P5 makes access on-demand, not absent)
- Step coverage on ambiguous requests — P4 skips only on low-ambiguity, and rounds up on borderline cases
What changes is **structure**: when calls fire, in what grouping, with what prompt payload. The quality floor is held by the Reviewer still seeing every output and workers retaining full context access.
### Round 2 (count + tier)
Round 2 acknowledges a narrow tradeoff: **orchestration ceremony** (wrap-up, conditional integration review, trivial inline steps) is relaxed; **implementation work** is not.
What round 2 does NOT change:
- Implementation work still hits a per-batch Reviewer (L5 drops the wrap-up Reviewer, not the batch Reviewer)
- Per-sub-task commit cadence — preserved unconditionally
- SECURITY_VIOLATION halt — preserved unconditionally
- 2-question plan floor (Step 5) — preserved unconditionally even when P4/L8 skip other ceremony
- Borderline rounding rule — preserved (round up on ambiguity boundary; never skip on the fence)
What round 2 relaxes:
- Reviewing mechanical orchestration steps (delete task file, memory append, chore commit) — L5 + L9
- A final integration review that would redundantly check already-green first-try batches — L7
- A coverage Reviewer over a Searcher output that passes at 95%+ rate — L4
- A heavyweight Classifier prompt for structured JSON classification — L1
The net: implementation Reviewer calls are unchanged. Orchestration Reviewer calls drop by 2-3 per median chain. `--thorough` restores L4, L5, L7, L8, L9 for runs where maximum ceremony is warranted.
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: 194k | Updated | Claude CodeCodex | Verified | Install |