Documentation
README
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 (Agents to do the work, 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.
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 asession=/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
Writethe spec (when the design phase ran) and the task file + briefs. A plan described only in chat — no.hyperflow/tasks/<slug>.mdwritten — is a failed run, not a plan. - No code in the design phase. Plan produces a prompt, a spec, and a task file;
dispatchexecutes 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 insidedispatch, 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 Agent; 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.
| 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 | Classifier | Triage Reviewer | 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 ≠ high |
| 5 — Clarify (gate) | atomic | — | — | AskUserQuestion; design path floor 2 · 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 ≠ high |
| 7 — Design sections (P1+P2) | 7a + 7b + 7c | Writer ×1–2 per sub-phase (architect authors 7a §1/§2 on architect-typed / high-complexity / 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 | — | — | AskUserQuestion (ALWAYS fires): this session → Skill 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 | AskUserQuestion — 2–5 questions (floor 2) |
| Synthesis + approach | Step 6, after batched review | AskUserQuestion — confirm synthesis · pick approach |
| Design section approval | Step 7, one combined gate | AskUserQuestion — approve all / revise §N |
| Build location | Step 12, after the task file is written — ALWAYS | AskUserQuestion — 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.
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) andspec=(a pre-built spec path, e.g. from/hyperflow:issueor 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.
Dispatch Classifier — triaging request per ../hyperflow/task-triage.md, producing { types[], complexity, risk, scope, ambiguity, flow, personas[], specialists[] }. This drives: the P4 gates (Steps 4/6) and bounce gate (Step 5); the question budget at Step 5 (0.0–0.5 → 2, 0.5–0.8 → 3, 0.8–1.0 → 4–5); the downstream flow profile (../hyperflow/flow-profiles.md); and persona/specialist stitching. On a gated flow the responsible specialist roster is finalized once via the Brain (DOCTRINE rule 17) and inherited by every later phase. Persist and propagate as triage=<base64-json>.
Triage Reviewer (rule 15). P4-skip when ALL of complexity == low, ambiguity < 0.2, scope ∈ {0-file, 1-file}, risk != high — consume the Classifier output as-is and print the skip line. Otherwise dispatch **Triage Reviewer** — validating classification against request and project profile (reads the request + .hyperflow/profile.md). Verdict ∈ {PASS, RECLASSIFY (use corrected triage, print one line), ESCALATE (add ambiguity to Step 5's queue)}. On Reviewer error follow failure-recovery §5 — never consume unvalidated triage.
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 promptrewrites the raw prompt into its single strongest version following the skeleton inreferences/prompt-rubric.md: role · task · context · constraints (persona doctrine from triagepersonas[]+ project rules) · output spec · out-of-scope. Economy is a constraint.**Reviewer** — scoring against the prompt-quality rubricscores all 8 dimensions 1–5. All ≥ 4 →PASS. Any < 4 →NEEDS_REVISIONwith 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 != high — round up on the border (0.59 → run). --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 aggregationconsolidates 4a/4b/4c into the unified brief; unknowns become Step 5 questions.
Step 5 — Clarify (AskUserQuestion · 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 == low, the request is clear — skip the design phase (Steps 6–8). Ask 0–3 post-analysis questions tied to specific findings the Searchers surfaced (no floor — zero when research is conclusive), then jump to Step 9. Print That's clear enough to skip the design phase — decomposing directly.
Design path (everything else): ask via AskUserQuestion, floor of 2 questions always (the two minimums give the user a place to redirect even when the request looks unambiguous). Budget by triage depth: light 2 · standard 3 · deep 4–5. Never stack more than 2 questions per call. Multi-option lists (3+) mark a (Recommended) choice (the Analyst's leading hypothesis first); binary lists carry no marker. Question order: intent → constraints → assumptions → scope → edge-case stance (pick the first N for depth N).
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 synthesisproduces a one-paragraph "the goal is X, constraints Y, excluding Z." - 6a — Approach candidates (P4-skip when
ambiguity < 0.6 ∧ complexity != high):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 analysisscoring 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 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 / high-complexity / 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