| name | plan |
| description | Use when a request needs shaping before any code is written — a rough or vague prompt to sharpen, an ambiguous idea to design, or a clear-enough task to decompose. One chain-starter that amplifies the prompt, designs the approach, and decomposes it into a batched task file, skipping whichever phases the request doesn't need, then STOPS at a build-location gate (build here, hand off to another session, or just keep the plan). Plan never implements.
Trigger with /hyperflow:plan, "design this", "plan this", "decompose this", "how should we", "what's the best way to", "break this down", "enhance this prompt".
|
| allowed-tools | Read, Write, Edit, Bash(git:*), Bash(python3:*), Bash(mv:*), Glob, Grep, Agent, AskUserQuestion, Skill |
| argument-hint | <idea, prompt, or task> [--thorough | depth=max] [briefs=auto|terse] [noamplify] |
| version | 2.1.0 |
| license | MIT |
| compatibility | Claude Code native; Codex / OpenCode / Grok via runtime-contract fallbacks |
| tags | ["prompt-engineering","design","brainstorming","planning","decomposition","multi-agent"] |
Plan
One chain-starter that folds three phases — amplify (sharpen the prompt), design (brainstorm and spec the approach), decompose (write the batched task file) — into a single flow, then stops at a build-location gate (Step 12). Each phase skips itself when the request doesn't need it: a clear task bounces straight to decomposition; an already-structured prompt skips amplify.
Plan never implements. It is thinking, not building — no source code is written here, and it does not silently chain into /hyperflow:dispatch. The only writes are to .hyperflow/specs/, .hyperflow/tasks/, .hyperflow/features/, .hyperflow/memory/, and (another-session mode) the committed .hyperflow-handoff/ package. When the task file is ready, plan always asks where to build it (this session / another session / stop) — that gate fires on every run, and the user's choice is the only thing that ever starts a build. It drives Layer 0.5 (Triage), Layer 4 (Brainstorming/Spec), Layer 0 (Project Analysis), Layer 6 (Memory), and Layer 7 (Task Templates).
Plan runs at maximum thinking depth. Engage extended / ultra reasoning across triage, analysis, design, and decomposition — plan is the chain's one think-heavy front door and pays the reasoning cost once so the build runs faithfully. Every substantive step uses tools (semantic spawn / labelled inline workers to do the work, edit/Write to persist artefacts); a plan that exists only in chat is a violation.
Every agent runs on the current session model — there is no model-tier routing and no model configuration. Roles (Classifier, Searcher, Writer, Analyst, Planner, Reviewer) differ by responsibility, not by model.
Runtime contract
Executable operations use runtime-contract.md. Transitions and gates: chain-router.md.
| Need | Semantic op | When present | When absent |
|---|
| Worker / searcher / writer / decision agent | spawn | Host spawn/task/subagent (Claude Agent, Codex collaboration/legacy candidates, OpenCode Task, …) | Labelled inline phase with the same brief; never invent host agent types |
| Reviewer (always separate) | spawn (second call) or sequential phase | Separate child with reviewer charter | Labelled inline reviewer after workers; workers never self-review |
| Structural / clarify questions | structured_question | Prefer AskUserQuestion / host structured UI | Exact Hyperflow Question chat block → end the turn. Never silent-default |
| Hand off to dispatch (only after build-location answer) | skill_continuation | Prefer native Skill | Load skills/dispatch/SKILL.md completely, then continue inline with the same args |
Do not hardcode only multi_agent_v1.spawn_agent or sole worker/explorer types — map via inventory (provider-*.md).
Iron Rules
- Plan never implements. It always stops at the build-location gate (Step 12) and asks where to build — this session / another session / stop. It does NOT silently chain into
dispatch. The gate fires every run, even when a session= / commit= / branch= arg was somehow propagated — never skip it.
- Max thinking, always. Run at maximum reasoning depth (ultrathink) through triage, analysis, design, and decomposition. Plan is the one think-heavy phase; do not shortcut the reasoning to save tokens.
- Always produce the artefacts on disk. Every run that reaches decomposition uses tools to
Write the spec (when the design phase ran) and the task file + briefs. A plan described only in chat — no .hyperflow/tasks/<slug>.md written — is a failed run, not a plan.
- No code in the design phase. Plan produces a prompt, a spec, and a task file;
dispatch executes them.
- Author build-ready briefs (
briefs=auto). Every non-trivial sub-task gets a full, self-contained implementation brief at plan time (Step 9c), stored at .hyperflow/tasks/<slug>/T<id>.md. The strong planning model pays the authoring cost once so the build runs faithfully on a cheaper model or a second session — dispatch transcribes, it doesn't re-derive. Trivial sub-tasks stay terse.
- Project rules win on conflict. A rule in
CLAUDE.md / AGENTS.md / .hyperflow/memory/ overrides a generic persona standard — it is the user's explicit instruction.
- Economy is mandatory. Amplify enhances to the task's level, never inflates a one-line ask into a spec (rubric dim 8).
- Names responsible specialists; never runs their web-research. The
Responsible specialists: annotation is an announcement — each specialist's web-research-first pass fires later inside dispatch, not here.
- No AI attribution in any prompt, spec, task file, or memory entry — describe the work, never the author.
- Failure recovery (rule 14). Worker/Reviewer errors, malformed output, and NEEDS_REVISION cadence follow
../hyperflow/failure-recovery.md. Retry → escalate → abort. Chain budget: 3 cumulative aborts.
Per-Step Agent Map (DOCTRINE rule 12 + 12.2)
Every substantive step dispatches at least one worker via spawn (or a labelled inline worker phase when spawn is unavailable); trivial steps (§12.1) and single-pair atomic steps (§12.2.8) run as noted. All roles run on the session model — the table assigns responsibility, not tier. Reviewers always run as a separate spawn or separate inline phase.
| Step | Sub-phase | Workers | Reviewers / decision agents | Notes |
|---|
| 0 — Setup | atomic | — | — | Silent: parse flags, set max-thinking. NO startup gate, NO questions |
| 1 — Triage | atomic | Deterministic preflight or Classifier | Triage Reviewer | Preflight resolves only inline-fast outside explicit plan; P4-skip Reviewer; P3-concurrent with Step 3 |
| 2 — Amplify (skippable) | atomic | Writer — rewrite prompt | Reviewer — 8-dim rubric, one revision | Skips on clear/structured prompt |
| 3 — Context | 3a + 3b (P1) | Searcher ×2 per sub-phase | Reviewer per sub-phase | 3a surface map · 3b semantic + convention scan |
| 4 — Multi-dim analysis (P4) | 4a + 4b + 4c (P1) | Writer ×1–2 per sub-phase | Reviewer per sub-phase + Analyst synthesis | Skips when ambiguity < 0.6 ∧ complexity ≠ complex |
| 5 — Clarify (gate) | atomic | — | — | structured_question only for material unknowns; bounce path 0–3 |
| 6 — Synthesis + approaches (P4) | 6a + 6b | Writer ×1–2 per sub-phase | Reviewer (batched) | Skips approaches when ambiguity < 0.6 ∧ complexity ≠ complex |
| 7 — Design sections (P1+P2) | 7a + 7b + 7c | Writer ×1–2 per sub-phase (architect authors 7a §1/§2 on architect-typed / complex / multi-subsystem tasks — embeds Mermaid graphs; designer authors the visual/experiential decisions on ui/creative-typed tasks — grounds them in .hyperflow/design/system.md; mobile authors the platform/device decisions on mobile/native-typed tasks — grounds them in ../hyperflow/mobile.md) | Reviewer per sub-phase + 1 batched | File-first; one combined approval gate |
| 8 — Spec finalize | atomic | Writer | Reviewer (final-integration) | Renames draft → .hyperflow/specs/<slug>.md |
| 9 — Decompose | 9a + 9b + 9c | Planner ×1 (9a) · Searcher ×2 (9b) · brief Writer ×1 per non-trivial sub-task (9c) | Reviewer per sub-phase | 9a batch graph → 9b sizing → 9c authors a full build-ready brief per non-trivial sub-task (briefs=auto) |
| 10 — Write task file (P3 w/ 11) | 10a + 10b + 10c | Writer ×2 per sub-phase | Reviewer per sub-phase + 1 final verify | Flat task file or feature/phase tree |
| 11 — Memory (P3 w/ 10) | atomic | Writer appends | Reviewer dup/contradiction check | Concurrent with Step 10 |
| 12 — Build-location gate | atomic | — | — | structured_question (ALWAYS fires): this session → skill_continuation dispatch · another session → write handoff package · stop |
Skippable / bounce summary: Step 2 skips for clear prompts; Step 4 and Step 6-approaches are P4-skippable; Step 5 bounces the design phase (Steps 6–8) entirely when the request is clear, jumping to Step 9. --thorough / depth=max disables P1/P2/P4 (sequential, every step runs, per-section reviewers, standalone final-integration pass added); P3/P5 stay on. No step is a startup gate — plan asks the user nothing until the Step 5 clarify questions, and the build decision waits until Step 12.
Approval Gates
| Gate | When | Format |
|---|
| Smart questions | Step 5, design path | structured_question (prefer AskUserQuestion) — 0–5 material questions, scaled by ambiguity |
| Synthesis + approach | Step 6, after batched review | structured_question — confirm synthesis · pick approach |
| Design section approval | Step 7, one combined gate | structured_question — approve all / revise §N |
| Build location | Step 12, after the task file is written — ALWAYS | structured_question — this session / another session / stop (+ handoff: review / deploy when another session) |
The build-location gate fires on every run (it is the only thing that ever starts a build); the design-phase gates fire at most once each and are skipped on the bounce path. Plan asks no startup gates — the session/build decision and the operational choices (commit cadence · branch · push) are no longer front-loaded. When the user picks "this session," dispatch fires its own operational gate (its Step 0.5) before building. Markers follow DOCTRINE rule 8: multi-option/named-workflow choices carry (Recommended); binary action gates (Approve/Revise) carry none.
Structured-input absence: when structured_question has no host UI, render the exact Hyperflow Question chat block (runtime-contract.md), optionally write a pending-gate checkpoint under .hyperflow/, and end the turn. Never silently pick the recommended option. Never start a build without the build-location answer.
Flow
Step 0 — Setup (silent · max thinking · NO gate)
Plan asks the user nothing at startup. There is no session-strategy gate and no operational gate here — both decisions move to the Step 12 build-location gate (and dispatch owns the operational gate when a build actually starts). Defaulting silently is correct: plan is think-only, so there is nothing to decide until a task file exists.
At Step 0, the orchestrator only:
- Engages maximum thinking depth (ultra reasoning) for the whole run — triage, analysis, design, and decomposition all reason at full depth.
- Parses flags from the args:
--thorough / depth=max (disable P1/P2/P4 — see the skippable summary), noamplify (skip Step 2), briefs=auto|terse (Step 9c). Record them; do not ask about them. GitHub-native pass-through: gh_issue= / pr= / comment= (set by /hyperflow:issue) and spec= (a pre-built spec path, e.g. from /hyperflow:issue or the audit fix-gate) are recorded verbatim — plan never acts on them, it forwards them to dispatch at Step 12.
Then proceed straight to Step 1. Any session= / commit= / branch= / push= args that happen to be present are ignored for gating — the build decision is always made fresh at Step 12.
Step 1 — Triage (Layer 0.5 · P3-concurrent with Step 3)
Step 1 (Classifier) and Step 3 (context Searchers) are independent — dispatch both in one message, wait for both. Under --thorough, run Step 1 first, then Step 3.
Run deterministic preflight per ../hyperflow/task-triage.md. Explicit plan requests always return classifier; dispatch Classifier — triaging request and produce { types[], complexity, risk, scope, ambiguity, flow, personas[], specialists[] }. This drives P4, the bounce gate, Step 5's question budget (<0.2 → 0, 0.2–0.5 → 0–2 material questions, 0.5–0.8 → 2–3, 0.8–1.0 → 4–5), flow profile, and persona/specialist stitching. Persist and propagate as triage=<base64-json>.
Triage Reviewer (rule 15). Skip when complexity IN [trivial, simple], ambiguity < 0.2, scope IN [single-file, multi-file], risk=reversible, and both gated flags are false. Otherwise dispatch **Triage Reviewer** — validating classification against request and project profile. Verdict ∈ {PASS, RECLASSIFY, ESCALATE}. On Reviewer error follow failure-recovery §5.
Step 2 — Amplify / prompt hygiene (atomic · skippable)
Skip when ambiguity < 0.4, OR the incoming prompt is already well-structured (role/task/constraints/output present), OR the noamplify flag is set — print Amplify skipped — prompt already specific. and proceed to Step 4 with the prompt as-is. Amplify exists to sharpen rough input before design; a sharp prompt gains nothing.
Otherwise a single Writer → Reviewer pair with a one-shot revision loop:
Writer — drafting the amplified prompt rewrites the raw prompt into its single strongest version following the skeleton in references/prompt-rubric.md: role · task · context · constraints (persona doctrine from triage personas[] + project rules) · output spec · out-of-scope. Economy is a constraint.**Reviewer** — scoring against the prompt-quality rubric scores all 8 dimensions 1–5. All ≥ 4 → PASS. Any < 4 → NEEDS_REVISION with specifics; the Writer revises once, then ships regardless (no infinite loop). The Reviewer also produces a 2–4 line rationale naming the domain doctrine and project rules it injected.
The amplified prompt becomes the working prompt for analysis and design. Print it once in a copy-ready block with its rationale + a Responsible specialists: line (omit when no specialist applies).
Step 3 — Context exploration (P1 sub-phases · P3-concurrent with Step 1)
Read .hyperflow/profile.md, architecture.md, conventions.md, .hyperflow/memory/index.md before dispatching to surface past learnings. Sub-phases are independent — dispatch in one message, run per-sub-phase Reviewers, then advance. No Step-level coverage Reviewer; a downstream Writer flags MISSING CONTEXT: <subsystem> and the orchestrator redispatches the relevant Searcher (max 2 retries). Do not ask the user what the code reveals.
- 3a — Surface mapping:
Searcher — glob discovery: file tree + entry points; Searcher — import-graph traversal: dependency edges. → **Reviewer**.
- 3b — Semantic + convention scan:
Searcher — type/symbol probe: interfaces, schemas, call sites, re-exports; Searcher — test patterns + lint/config: naming, runner, lint rules. → **Reviewer**.
Step 4 — Multi-dimensional analysis (P4-skippable)
P4 gate: skip entirely (jump to Step 5) when ambiguity < 0.6 AND complexity != complex — round up on the border. --thorough always runs. If run, sub-phases fan out in parallel (P1), then the Analyst aggregates:
- 4a — Intent + technical-fit:
Writer — user-intent: real need + success ∥ Writer — technical-fit: how it fits existing architecture. → **Reviewer**.
- 4b — Scope + risks:
Writer — scope/constraints: MVP vs max, limits ∥ Writer — risks: failure modes, irreversibility. → **Reviewer**.
- 4c — Alternatives:
Writer — alternatives: ≥3 distinct solutions, brief notes (single canonical set). → **Reviewer**.
- 4d — Analyst synthesis (sequential):
**Analyst** — 6-dimension aggregation consolidates 4a/4b/4c into the unified brief; unknowns become Step 5 questions.
Step 5 — Clarify (structured_question · two modes)
Pre-flight: read .hyperflow/memory/project-decisions.md; skip any candidate already answered there (print one line) unless the cached answer conflicts with this task (then ask "decisions say X — does this task change that?").
Bounce gate (decompose-only path): when ambiguity < 0.4 AND complexity IN [trivial, simple], the request is clear — skip Steps 6–8. Ask 0–3 post-analysis questions only for specific unresolved findings, then jump to Step 9.
Design path (everything else): ask via structured_question (prefer AskUserQuestion when present) only when an answer changes implementation. Budget by triage depth: none 0 · light 0–2 · standard 2–3 · deep 4–5. Never stack more than 2 questions per call. Multi-option lists (3+) mark a (Recommended) choice; binary lists carry no marker. If structured UI is missing: Hyperflow Question block, end the turn, resume on the next user message.
After answers, append structural decisions (database, auth, testing, framework defaults) to .hyperflow/memory/project-decisions.md under a category heading with date + source slug — inline write, §12.1-trivial. Skip task-specific answers.
Step 6 — Synthesis + approaches (P3 + P2 · P4-skippable)
Step 5 (synthesis) and 6a both depend on the answers but not on each other — dispatch concurrently (P3); one batched Reviewer covers both (P2). --thorough runs them sequentially.
- Synthesis:
Writer — requirement synthesis produces a one-paragraph "the goal is X, constraints Y, excluding Z."
- 6a — Approach candidates (P4-skip when
ambiguity < 0.6 ∧ complexity != complex): Writer — lightweight candidates ∥ Writer — heavyweight candidates. Each approach: Name · What · Pros · Cons · Fit.
- 6b — Trade-off eval (sequential on 6a):
Writer — fit analysis ∥ Writer — risk analysis scoring each candidate.
**Reviewer** — batched: synthesis + approaches (../hyperflow/reviewer-prompt-batched.md) returns per-draft verdicts; re-dispatch only the failing draft. When 6a/6b are P4-skipped, annotate "Approach: derived from synthesis (ambiguity low)". Then present synthesis + approaches and confirm via structured_question (prefer AskUserQuestion) — recommend one approach, the choice is the user's.
Step 7 — Section-by-section design (P1 + P2 · file-first · one combined gate)
File-first (rule 8): each section Writer writes directly to .hyperflow/specs/<slug>.draft.md at a stable H2 anchor — never returns content for inline paste. Pre-seed the file with 5 H2 headers before dispatching. Run python3 $PLUGIN_ROOT/scripts/resolve-mode.py $PROJECT_ROOT --from-args "$CHAIN_ARGS" once and propagate mode=<default|lean|thorough> (lean → workers get the path-only Project Context block per ../hyperflow/worker-prompt-lean.md).
Sub-phases dispatch in ONE parallel message (P1), each with a per-sub-phase Reviewer firing as it returns; then one batched Reviewer (P2) reads all 5 sections for cross-section coherence. Each section Writer records a Responsible specialist(s): line from the Brain-finalized roster, carried into the Step 8 status block.
System-design tasks produce architecture graphs. On architect-typed / complex / multi-subsystem work the architect agent owns §1/§2 and embeds a Mermaid component/container graph (§1) and a Mermaid data-flow diagram (§2) directly in the draft — the diagram precedes the implementation. The Step 7 approval gate already points the user at the draft file, so the graphs are reviewed there with no extra gate.
Design-time consultation. Any decision agent in this phase may consult a peer directly (its own Agent tool, ≤ 3 consults, depth-1, allowlist = the agents/ registry) per ../hyperflow/consultation.md — e.g. the architect asks motion whether a proposed interaction is feasible before committing it to §2, or the designer asks motion for a motion-heavy screen. Agent-agnostic: future decision agents inherit this without an edit here.
Design-typed tasks ground in the design system. On ui/creative-typed work the designer agent owns the visual/experiential decisions: it first ensures .hyperflow/design/system.md exists (creating it if missing, extending it if present per ../hyperflow/design-system.md), researches ≥2 real-world references in the project's field and combines them with one deliberate signature, applies the matching local taste skill, and records the bound design-system tokens in §3. When a motion surface is in scope (animation / transition / scroll-driven / gesture), the designer brings in the motion agent to author the Motion-language decisions in §3 (compositor-only props, library choice, spring params, reduced-motion fallback per ../hyperflow/motion.md) — composing within §3, not a separate section. No source code is written — only the design system and the spec draft.
Mobile-typed tasks define the platform & device strategy. On mobile / native / responsive-app work the mobile agent authors the mobile decisions — framework choice + rationale (React Native / Flutter / native iOS / Android), app architecture (navigation / offline-first / lifecycle-aware state), the platform accessibility floor (VoiceOver/TalkBack, 44pt/48dp targets, Dynamic Type), and the device-size test matrix + tooling (Maestro/Detox/XCUITest/Espresso) — into §1 (architecture, composing with the architect) and §3 (decisions), grounded in ../hyperflow/mobile.md. No source code is written.
- 7a — Structural: when triage
types includes architect, OR complexity == complex, OR the surface spans ≥ 2 subsystems, dispatch the architect agent to author both sections — architect — §1 Architecture (C4 decomposition + Mermaid component/container graph) ∥ architect — §2 Data flow (Mermaid data-flow diagram per new cross-boundary path); it folds the frontend-at-scale decisions (debounce/virtualize/paginate/cache/code-split/state-topology) into §1 or §3 when a frontend surface is in scope and flags every hard-to-reverse choice for an ADR in §3. Otherwise (clear single-component task) Writer — §1 Architecture ∥ Writer — §2 Data flow. → **Reviewer** (the section reviewer is a separate agent; the architect's reviewer role applies later, on structural change in dispatch/audit).
- 7b — Decisions: when triage
types includes ui OR creative, dispatch the designer agent to author the visual/experiential half — designer — §3 Design decisions (design-system tokens + signature + references) ∥ Writer — §4 Edge cases; the designer ensures .hyperflow/design/system.md exists first and applies the matching taste skill. Otherwise Writer — §3 Key decisions ∥ Writer — §4 Edge cases. → **Reviewer**.
- 7c — File structure:
Writer — §5 File structure. → **Reviewer**.
On batched NEEDS_FIX for a section, re-dispatch only that section's Writer (rewrites its own H2 block). 4+ of 5 sections NEEDS_FIX → the approach is likely wrong; bounce to Step 6 and re-pick. Worker failure: retry (max 2), then ESCALATE — inline drafting in chat is BANNED (violates file-first). --thorough: draft each section sequentially with its own approve/revise gate, then a standalone final-integration Reviewer.
After review passes, fire ONE combined structured_question (prefer AskUserQuestion) — body is a one-line section roster + the file path (NOT the content):
Design draft ready at .hyperflow/specs/<slug>.draft.md
§1 Architecture · §2 Data flow · §3 Key decisions · §4 Edge cases · §5 File structure
Approve all — finalize and decompose
Revise §<N> — send the named section back with your feedback (free-form)
Per-section revise loops only that Writer (max 3 cycles per section); the rest of the file is untouched.
Step 8 — Spec finalize (atomic)
Writer — finalizing spec at .hyperflow/specs/<slug>.draft.md prepends the status block + TL;DR (2–3 plain-English sentences from the synthesis) + Components, appends Trade-offs accepted/rejected to §3, and renames mv .hyperflow/specs/<slug>.draft.md .hyperflow/specs/<slug>.md. Format per ../hyperflow/artefact-format.md: Status table (incl. Specialists row), TL;DR, Components, §1–5. Then **Reviewer** — final spec sanity check (always runs) verifies the status block, TL;DR length, all sections present, H2 ordering 1–5, trade-offs present, no cross-section contradiction, and — when the architect agent authored the design — the Mermaid graphs in §1/§2. No inline-summary fallback — the spec lives in a file.
Step 9 — Decompose (Planner · 9a sequential then 9b/9c parallel)
9a fires first; 9b/9c depend on it and run concurrently.
- 9a — Batch graph:
**Planner** — producing batch graph with the Step 3 context aggregate + triage + applicable templates — when the architect agent authored §1, the Planner consumes its decomposition as the batch-boundary source rather than re-deriving it from ../hyperflow/task-templates.md (CRUD / API / UI / Migration / Refactor / Bug Fix, else bespoke). Per sub-task: Worker role · Read/Modify/Create files · parallel-vs-sequential deps · complexity estimate · ≥1 responsible specialist (from the Brain-finalized triage specialists[], inherited from the spec status block when the design phase ran). Then **Reviewer** — validating decomposition completeness + batch boundaries (every finding maps to ≥1 sub-task; no sub-task spans >1 subsystem without a split; topological ordering). Oversize-split mandate (Layer 3): split any sub-task hitting >5 files, >500 LOC, 2+ subsystems, complexity=complex, mixed concerns, or >10-min human review — until every piece is simple/moderate. Splitting is a cost AND quality optimisation. Mode: Planner emits mode: flat | feature per ../hyperflow/feature-phases.md — feature only when ≥2 sequential dependent stages/milestones exist; a 1-phase "feature" is NEEDS_REVISION.
- 9b — Complexity sizing:
Searcher — LOC estimation ∥ Searcher — subsystem cross-cut check. → **Reviewer**.
- 9c — Per-sub-task briefs (the heavy lift;
briefs=auto default): for each non-trivial sub-task, a Writer — authoring brief T<id> writes the full ../hyperflow/worker-prompt.md body to .hyperflow/tasks/<slug>/T<id>.md — Task · Why · Scope IN/OUT · Files-in-scope with the exact change described (spec-level prose, no code skeletons) · Acceptance criteria · the realistic Test-case set + ≥1 end-to-end/integration scenario (named tool, real input→outcome; or explicit E2E: N/A — <why>) · Related context (file:line patterns to mirror) · Gotchas. Grounded in the Step 3 context aggregate + the spec; names ≥1 responsible specialist. Trivial sub-tasks (1 file ∧ ~≤10 LOC ∧ obvious) get NO brief — only the terse roster line. Brief Writers fan out in parallel (one per non-trivial sub-task), then **Reviewer** — briefs vs design + completeness: every non-trivial sub-task has a brief; every brief carries Acceptance criteria + ≥1 E2E case + a populated specialist; no brief contradicts the spec. briefs=terse skips 9c entirely (one-liner roster only — the legacy output; use when the same strong model will build).
Step 10 — Write task file (P3 sub-phases · concurrent with Step 11)
10a anchors first (status + Goal + Why); 10b/10c run concurrently after. --thorough disables P1 here only (sequential drafts) — P3 (Steps 10 + 11) stays on.
- 10a — Status + Goal + Why:
Writer — status block ∥ Writer — goal + why. → **Reviewer**.
- 10b — Scope + affected files:
Writer — scope-at-a-glance table ∥ Writer — affected-file listing. → **Reviewer**.
- 10c — Execution plan + batches + verification:
Writer — execution plan + batch checklist (terse roster, each non-trivial line carrying a Brief: /T.md pointer) ∥ Writer — open questions + verification plan. → **Reviewer**.
- 10d — Final verify:
**Reviewer** — assembled task file vs design + briefs — every design requirement maps to ≥1 sub-task, no orphans, every sub-task names ≥1 specialist, Specialists status row populated, and roster↔brief consistency (every non-trivial roster line resolves to an existing <slug>/T<id>.md; every brief maps back to a roster line).
Mode branch: flat → the terse roster .hyperflow/tasks/<slug>.md + the brief dir .hyperflow/tasks/<slug>/T<id>.md (one full brief per non-trivial sub-task, written in 9c; template + lifecycle in ../hyperflow/task-tracking.md; brief format in ../hyperflow/artefact-format.md + ../hyperflow/worker-prompt.md); feature → the feature tree per ../hyperflow/feature-phases.md (briefs land in each phase-*/tasks/T<id>.md) (feature.md + phase-<n>-<name>/ folders each with phase.md + tasks/), final-verify additionally checks phase ordering, Depends on references, and one-phase-per-task placement. The status block is updated by dispatch after each sub-task PASS.
Step 11 — Memory (P3 · concurrent with Step 10)
Writer — appending decisions to .hyperflow/memory/decisions.md (skip trivial; for complex features also seed .hyperflow/specs/<feature-slug>.md referenced from the task file) → **Reviewer** — checking memory entries for duplicates/contradictions. Both Writers (Step 10 + 11) derive from the Planner output and are independent — dispatch concurrently.
Step 12 — Build-location gate (ALWAYS fires · plan never auto-implements)
Auto-open (best-effort, before the gate): when viewer.enabled && viewer.autoOpen, run python3 $PLUGIN_ROOT/scripts/open-artefact.py $PROJECT_ROOT/.hyperflow <slug> --type spec and print the opened/available path. This is non-blocking and never gates — a headless/no-browser environment just prints the path; the build-location gate below fires regardless of outcome. Skip silently when autoOpen=false (the default) or viewer.enabled=false.
The task file is written; plan is done thinking. Fire ONE structured_question (prefer AskUserQuestion when present) — this gate fires on every run and is the only thing that ever starts a build. Never skip it, never default it, never silently chain into dispatch, regardless of any propagated args or autonomy directive. No implementation and no source-code edits occur until this gate has an explicit user answer. Q1 is a named-workflow choice → recommended option first with (Recommended):
Plan ready — .hyperflow/tasks/<slug>.md (N batches, M sub-tasks)
Where should this be built?
This session (Recommended) — run /hyperflow:dispatch here now, straight through.
Another session — write a committed handoff package and STOP; a second
session (another environment, e.g. Codex/Gemini) builds it.
Stop — keep the plan only; build later with /hyperflow:dispatch <slug>.
Q2 fires only when Q1 = Another session — binary action gate, NO (Recommended) marker, structural default Return for review:
When the second session finishes building, what should it do?
Return for review — stop after the build; come back to THIS session and run /hyperflow:audit on the diff.
Complete to deploy — the second session continues to /hyperflow:deploy after the build.
Portable-surface fallback (Codex / OpenCode / Grok): when structured UI is absent, print the same gate as a Hyperflow Question chat block, persist a safe pending-gate checkpoint if needed, and end the turn — wait for the user's answer on the next message. Source code remains untouched. If no interactive channel exists, error and stop (never silently default to building).
Branch on the answer (only after the answer is received):
- This session →
skill_continuation into dispatch. When native Skill is available: invoke Skill with skill: dispatch, args: "<slug> triage=… mode=… briefs=…" — appending gh_issue=… pr=… comment=… verbatim when present (the GitHub-native pass-through from Step 0; dispatch's Step 5 PR exit needs them). When Skill is unavailable: load skills/dispatch/SKILL.md completely, then continue inline in the coordinator with the same args and gate contract. Do not pass commit= / branch= / push= — dispatch fires its own operational gate (its Step 0.5) before building. Print Building here — handing to /hyperflow:dispatch…. Do not stop with "Skill tool unavailable".
- Another session → do NOT invoke dispatch. Write the committed handoff package and STOP at the dispatch boundary (full contract:
../hyperflow/session-handoff.md) — create .hyperflow-handoff/<slug>/ with HANDOFF.md (manifest: slug, artefact type/path, resolved chain args, on_complete from Q2, originating commit, Specialists roster), STATUS (planned), a committed copy of the gitignored artefact, and context/ copies of .hyperflow/{conventions,profile,architecture}.md + memory index; git add + commit chore(handoff): plan <slug> for second-session build; then print the start-session-2 instructions.
- Stop → write nothing further. Print
Plan kept at .hyperflow/tasks/<slug>.md — run /hyperflow:dispatch <slug> when you're ready to build.
Anti-Patterns
- Writing code during the design phase, or letting plan implement anything — plan stops at the Step 12 build-location gate, full stop.
- Auto-chaining into
dispatch without firing the build-location gate, or treating a propagated session= arg as permission to skip it — the gate fires every run.
- Front-loading a session-strategy or operational (commit/branch/push) gate at startup — those are gone; the build decision waits for Step 12 and
dispatch owns operational.
- Producing a plan only in chat — every run that decomposes must
Write the task file to .hyperflow/tasks/<slug>.md.
- Shortcutting the reasoning to save tokens — plan runs at max thinking.
- Asking > 5 questions total, asking any question whose answer does not change implementation, or stacking 3+ questions in one call.
- Skipping alternatives unless P4 skip or the bounce path is in effect.
- Asking what the codebase reveals; adding features the user didn't request (YAGNI).
- Sequentializing independent siblings (Steps 1+3, 7a/7b/7c, 9b/9c, 10 + 11) when P1/P3 apply.
- Per-section reviewers when one batched reviewer covers the same review-level cap.
- Single-batch plans for multi-file work; omitting the verification plan.
- Wrapping a §12.1-trivial step (hand-off, memory append) in an Agent dispatch.
Overview
plan is the explicit think-heavy front door. It asks nothing at startup. Triage and context map concurrently; optional analysis and approaches skip on low ambiguity; clear requests can decompose without clarification while ambiguous ones walk the file-first spec. Plan stops at the build-location gate and never implements by itself.
Prerequisites
.hyperflow/ cache (run /hyperflow:scaffold first if missing — improves triage and planning context).- Interactive channel for structural gates: prefer
AskUserQuestion / host structured_question UI; otherwise Hyperflow Question chat fallback. Headless with no channel is rejected at the first gate plan reaches (Step 5 clarify, or Step 12 build-location on the bounce path).
- An idea, prompt, or task. Pure "should we?" design questions exercise the full flow; clear decompositions bounce past design automatically.
Error Handling
| Failure | Behavior |
|---|
structured_question UI unavailable (Codex / OpenCode / Grok) | Emit Hyperflow Question chat block and end the turn. Never silently build. |
| No interactive channel at all (headless) | Refuse at the first gate reached (Step 5 clarify, else Step 12 build-location); print error and exit. Never silently build. |
| Native Skill unavailable on "this session" | Load full skills/dispatch/SKILL.md and continue inline (skill_continuation). Never stop with "Skill tool unavailable". |
| Classifier rejects request (off-topic/abuse) | Stop. Print neutral reason. |
| User picks "revise" on a design section | Loop that Writer with feedback. Max 3 cycles per section, then suggest a different approach. |
| Searcher returns no/empty context | Downstream Writer flags MISSING CONTEXT; redispatch with the gap. Max 2 retries, then proceed with a caveat. |
| User rejects all proposed approaches | Writer drafts a 4th incorporating the stated objection. |
| Batched Reviewer NEEDS_FIX on 4+/5 sections | Approach likely wrong — bounce to Step 6 and re-pick. |
| Planner produces single-batch plan for multi-file work | Reviewer rejects; redispatch with split feedback. |
| Task file write fails (path locked/disk full) | Abort with explicit error; do not reach the build gate. |
| User picks "Stop" at the build-location gate | Leave the task file in place; print the /hyperflow:dispatch <slug> resume hint and exit cleanly. |
| Concurrent dispatch rate-limited | Cap parallel section drafts at 5, concurrent pre-conditions at 2; degrade to sequential — quality unchanged, latency reverts. |
Resources
