Plan

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 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 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.

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

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:

1. Engages maximum thinking depth (ultra reasoning) for the whole run — triage, analysis, design, and decomposition all reason at full depth.
2. 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.

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:

1. 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.
2. **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 != 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 aggregation consolidates 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 synthesis produces 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 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 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 is written.

• 7a — Structural: when triage types includes architect, OR complexity == high, 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 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.