Spec

Spec

This phase is thinking, not building. No code until the user approves the design. On approval, the chain advances to scope → dispatch. The user picks the advancement mode at Step 0.

This skill drives Layer 0.5 (Task Triage) and Layer 4 (Brainstorming/Spec) from the doctrine. Multi-level review (L1–L5) runs later during /hyperflow:dispatch per the triage's chosen flow profile.

Iron Rules

• Failure recovery (rule 14). Worker errors, malformed output, NEEDS_REVISION verdicts, and Reviewer errors across every dispatched agent (Classifier, Triage Reviewer, Searchers, Writers, Analyst, batched Reviewer) follow the canonical policy in [skills/hyperflow/failure-recovery.md](../hyperflow/failure-recovery.md). Retry → escalate → abort. Chain budget: 3 cumulative aborts.

Per-Step Agent Map (DOCTRINE rule 12)

Every substantive step dispatches at least one Agent per DOCTRINE rule 12. Trivial steps per §12.1 may be performed inline by the orchestrator.

| Step | Sub-phase | Worker tier | Thinking tier | Notes | |---|---|---|---|---| | 0 — Chain mode | — (atomic) | — | — | AskUserQuestion only (exempt) | | 0.5 — Operational choices | — (atomic) | — | — | AskUserQuestion only (exempt) | | 1 — Triage | — (atomic) | — | Classifier (Opus) · Triage Reviewer (Sonnet) | Atomic per §12.2.8: single Worker → Reviewer pair, no independent angles. Reviewer verdicts: PASS / RECLASSIFY / ESCALATE (DOCTRINE rule 15). Skips on P4 conditions; see body | | 2 — Context Exploration | 2a + 2b (P1 parallel) | Searcher ×2 per sub-phase [P3 concurrent with Step 1] | Reviewer (Sonnet) per sub-phase | P3: Steps 1+2 dispatched in same message; no coverage Reviewer at Step level (D4) | | | 2a — Codebase surface mapping | Searcher ×2 (glob discovery + dependency graph) | Reviewer (Sonnet) | Parallel with 2b | | | 2b — Convention and test pattern scan | Searcher ×2 (test pattern probe + lint/config scan) | Reviewer (Sonnet) | Parallel with 2a | | 3 — Multi-dim analysis | 3a + 3b + 3c (P1 parallel) | Writer ×1–2 per sub-phase | Reviewer (Sonnet) per sub-phase + Analyst (Opus) final synthesis | P4-skippable; --thorough always runs | | | 3a — Intent and technical-fit analysis | Writer ×2 (user-intent angle + technical-fit angle) | Reviewer (Sonnet) | Parallel with 3b and 3c | | | 3b — Scope, constraints, and risks analysis | Writer ×2 (scope/constraints angle + risks angle) | Reviewer (Sonnet) | Parallel with 3a and 3c | | | 3c — Alternatives synthesis | Writer ×1 (single canonical aggregation — no parallel angle) | Reviewer (Sonnet) | Parallel with 3a and 3b; single-Worker justified: one alternatives set | | | 3d — Analyst synthesis | — | Analyst (Opus) consolidating 3a + 3b + 3c into unified 6-dim brief | Sequential — depends on 3a + 3b + 3c all PASS | | 4 — Smart questions | — (atomic) | — | — | AskUserQuestion only (exempt) · floor: 2 always · pre-flight checks .hyperflow/memory/project-decisions.md to skip already-answered questions | | 5 — Requirement Synthesis | — (atomic) | Writer (Sonnet) | Reviewer (Sonnet · batched with Step 6) | Atomic: single canonical one-paragraph restatement; no independent angles | | 6 — Approach proposals | 6a + 6b (sequential; P3 concurrent with Step 5) | Writer ×2 per sub-phase | Reviewer (Sonnet · batched over both Steps 5+6) | P4-skippable; 6b depends on 6a | | | 6a — Approach candidate drafting | Writer ×2 (lightweight-approach angle + heavyweight-approach angle) | Reviewer (Sonnet) | Parallel with Step 5; sequential before 6b | | | 6b — Trade-off and fit evaluation | Writer ×2 (fit-analysis angle + risk-analysis angle) | Reviewer (Sonnet) | Sequential after 6a; depends on 6a candidates as input | | 7 — Design sections | 7a + 7b + 7c (P1 parallel) | Writer ×1–2 per sub-phase [P1] | Reviewer (Sonnet · per-batch) batched over sub-phase aggregate [P2] | One combined user gate after full batch review | | | 7a — Structural sections (Architecture + Data flow) | Writer ×2 (Architecture Writer + Data flow Writer) | Reviewer (Sonnet) | Parallel with 7b and 7c | | | 7b — Decision sections (Key decisions + Edge cases) | Writer ×2 (Key decisions Writer + Edge cases Writer) | Reviewer (Sonnet) | Parallel with 7a and 7c | | | 7c — File structure section | Writer ×1 (single canonical section — no parallel angle) | Reviewer (Sonnet) | Parallel with 7a and 7b; single-Worker justified | | 8 — Spec finalize | — (atomic) | Writer (Sonnet) | Reviewer (Opus · final-pass tier) | Atomic: single canonical finalization; no independent angles | | 9 — Hand off | — (atomic) | — | — | Skill tool invocation — trivial inline per §12.1 (one tool call, no generation, no review) |

Substantive steps = 1, 2, 3, 5, 6, 7, 8. Each appears in the usage summary. Steps decomposed into sub-phases (12.2): 2 (→ 2a, 2b), 3 (→ 3a, 3b, 3c), 6 (→ 6a, 6b), 7 (→ 7a, 7b, 7c). Atomic-exempt steps (12.2.8): 0, 0.5, 4, 9 (AskUserQuestion / single Skill call); 1 (single Classifier, no angles); 5 (single canonical synthesis); 8 (single canonical finalization).

Approval Gates

| Gate | When | Format | |---|---|---| | Chain mode | Step 0, once per chain | AskUserQuestion — auto / manual | | Design section approval | Step 7, one combined gate after batched review | AskUserQuestion — approve / revise per section | | Phase advance (if manual mode) | Step 9, before invoking scope | AskUserQuestion — continue / stop |

Flow

Step 0 — Choose chain mode (FIRST tool call · STRUCTURAL GATE)

This is a structural gate per DOCTRINE rule 8. It MUST fire every time the skill is invoked directly. "No clarifying questions" / "auto-pilot" / "always-on" / any other autonomy directive does NOT skip it. The agent MUST AskUserQuestion here — defaulting to auto without asking is a doctrine violation.

If invoked with a chain-mode= arg (from a prior skill in the chain), skip this step — the previous chain-starter already asked.

Otherwise, before any research, triage, or analysis, ask via AskUserQuestion. Per DOCTRINE rule 8, the recommended option goes first with (Recommended):

How should I advance through the chain after each phase?

  Auto (Recommended)  — chain forward through spec → scope → dispatch with no gates.
                        Fewer interruptions, faster end-to-end.

  Manual              — pause between phases and ask before advancing.
                        More control, more confirmations.

Auto is the recommended default because most users invoking a chain-starter want momentum; Manual exists for high-risk or exploratory work. Wait for the user's answer. Do not proceed without it. Save the chosen mode and propagate via args: "chain-mode=".

If the agent cannot present AskUserQuestion as a popup, use the Codex fallback: print the same gate as a Hyperflow Question chat block with numbered options, then stop and wait for the user's answer. If no interactive channel is available at all, print an error and stop — never silently default.

Step 0.5 — Operational Choices (auto-mode only · STRUCTURAL GATE · fires immediately after Step 0)

When the user picks Auto at Step 0 AND operational args (commit=, branch=, push=) were NOT already propagated, fire ONE AskUserQuestion call with 3 questions covering every operational decision the chain needs. After this batch, the chain runs silently until the end-of-chain audit + deploy gates — user is interrupted exactly twice at startup (chain-mode in Step 0, ops in Step 0.5), never again until done.

Skip when chain-mode=manual (per-phase pauses cover ops decisions) OR when operational args are already propagated (re-asking is an invented-gate violation).

The 3-question batch is identical to scope Step 0.5 — see [scope/SKILL.md § Step 0.5](../scope/SKILL.md#step-05--operational-choices-auto-mode-only--structural-gate--fires-immediately-after-step-0) for the full question + option text + recommended-default logic + chain-arg propagation contract. Spec, scope, dispatch share one canonical definition; whoever fires first (typically spec when it's the chain entry point) owns the batch, the others see the args propagated and skip.

--thorough / depth=max flag: When passed, patterns P1, P2, and P4 are disabled and the original sequential flow runs (one Writer at a time, one Reviewer per section, all steps always run). P3 and P5 stay on — they carry no quality tradeoff. Record the flag at Step 0 and propagate it; every step below that references P1, P2, or P4 should check for this flag before applying the pattern.

Steps 1+2 — Triage and Context Exploration (P3 — concurrent dispatch)

P3 applies: Step 1 (Classifier triage) and Step 2 (Searcher context mapping) are independent — the Searcher does not need the triage output to begin. Dispatch both in a single message, then wait for both to return before advancing to the Reviewer.

If --thorough / depth=max: run Step 1 first (wait for it to complete), then Step 2 sequentially.

Step 1 — Triage (Layer 0.5)

Agents — Classifier (Opus, thinking-tier).

Dispatch **Classifier** — triaging request per [task-triage.md](references/task-triage.md). The Classifier produces { types[], complexity, risk, scope, ambiguity, flow, personas[] } JSON. The classification drives:

• P4 gate — read ambiguity and complexity here; triage-driven skipping applies at Steps 3 and 6 (see below)
• Spec depth at Step 4 — floor: 2 questions always:
• ambiguity 0.0–0.5 → light: 2 questions
• 0.5–0.8 → standard: 3 questions
• 0.8–1.0 → deep: 4–5 questions
• Flow profile for the downstream dispatch phase — fast, standard, deep, research, creative, or scientific (see [flow-profiles.md](references/flow-profiles.md))
• Persona stitching for worker prompts later (full personas defined in DOCTRINE)

Persist the triage output and propagate it forward through chain-mode= triage= args. Print:

**Classifier** — triaging request  [concurrent with Searcher]
Triage — types: [] · flow:  · ambiguity: 

Triage Reviewer (DOCTRINE rule 15)

P4 skip (DOCTRINE §13.P4): before dispatching, check the Classifier's output. If ALL of the following hold — triage.complexity == low, triage.ambiguity if anything was missed.

Fallback: If a downstream Writer flags MISSING CONTEXT: , the orchestrator redispatches the Searcher with the gap before continuing. This trades a small bad-case path penalty for a large good-case path win.

Step 2a — Codebase surface mapping

Agents — Searcher ×2 (Sonnet).

Dispatch in parallel:

• Searcher — glob discovery: mapping file tree and entry points relevant to
• Searcher — dependency graph traversal: tracing import paths and module dependencies

Do not ask the user what you can find in the code. Trust the Searchers' output.

After both Searchers return: **Reviewer** — reviewing surface mapping coverage (Step 2a) (Sonnet · per-sub-phase). Verdict ∈ {PASS, NEEDS_REVISION, ESCALATE}. On NEEDS_REVISION: re-dispatch only Step 2a Searchers with the gap identified.

Step 2b — Convention and test pattern scan

Agents — Searcher ×2 (Sonnet).

Dispatch in parallel (concurrent with Step 2a):

• Searcher — test pattern probe: finding existing test conventions, helpers, and fixture patterns
• Searcher — lint and config scan: reading project config, lint rules, naming conventions

After both Searchers return: **Reviewer** — reviewing convention scan completeness (Step 2b) (Sonnet · per-sub-phase). Verdict ∈ {PASS, NEEDS_REVISION, ESCALATE}. On NEEDS_REVISION: re-dispatch only Step 2b Searchers.

Step 3 — Multi-Dimensional Analysis (P4-skippable)

P4 gate: If triage.ambiguity ' — already answered in project-decisions.md: ``

• If the cached answer conflicts with what the current task requires (e.g., the project decided "no SSR" but this task specifically needs SSR) → surface it as a Smart Question anyway. Frame it as: "project-decisions.md says X — does this task change that?"
• If project-decisions.md does not exist or has no matching entry → include the question normally.

The 2-question floor (below) still applies after skipping. If memoization eliminates all candidates above the floor, the floor questions still fire.

Use the AskUserQuestion tool. Never plain text questions. Ask about unknowns from Step 3 (or from triage + context if Step 3 was skipped).

Hard floor: every spec run asks at least 2 questions, regardless of how confident the triage was. The two minimum questions give the user a structural place to redirect before any decomposition runs. This floor is non-negotiable — P4's bounce-to-scope path (below) is the ONLY way to skip Step 4, and that path exits the spec phase entirely. Never skip or reduce below 2 inside the spec phase.

P4 bounce gate: If `triage.ambiguity

• (recorded , source chain: )

```

1. Do not append ephemeral or task-specific answers (e.g., "use a modal for this feature" is task-specific; "modal pattern via Radix Dialog" is structural if it establishes the project-wide modal approach).

This write is inline (orchestrator tool call) — trivial per §12.1. No Agent dispatch needed.

Steps 5+6 — Requirement Synthesis and Approach Proposals (P3 + P2)

P3 applies: Step 5 (Synthesis Writer) and Step 6 (first sub-phase 6a Writers) both depend on Step 4 answers but not on each other. Dispatch Step 5 Writer and Step 6a Writers in a single message, then proceed through 6b (sequential on 6a output), then wait for everything to return before dispatching the batched Reviewer.

P2 applies: After Step 5 Writer and Step 6 sub-phases (6a + 6b) all return, dispatch ONE Reviewer using reviewer-prompt-batched.md to review both drafts in a single pass, returning per-draft verdicts.

If --thorough / depth=max: run Step 5 (Writer → Reviewer) sequentially, then Step 6 sub-phases sequentially (6a Writer → Reviewer, then 6b Writer → Reviewer).

Step 5 — Requirement Synthesis

1. Dispatch Writer — drafting requirement synthesis (concurrent with Step 6 Writer). The Writer produces a one-paragraph restatement: "So the goal is X, with constraints Y, excluding Z."
2. (Reviewed in the batched pass below.)
3. After the batched Reviewer approves, print the synthesis and ask for explicit confirmation via AskUserQuestion before moving on.

Step 6 — Propose 2–3 Approaches with Trade-offs (P4-skippable)

P4 gate: If triage.ambiguity "). Per the DOCTRINE tier split, per-batch reviewers default to Sonnet because the diff is small (one synthesis paragraph + 2–3 approach paragraphs). --thorough escalates to Opus. The Reviewer returns:

§1 Synthesis:  PASS
§2 Approaches: NEEDS_FIX — [specific feedback]

On NEEDS_FIX for either draft: re-dispatch only that Writer (or the failing Step 6 sub-phase); single Opus re-review of just that draft. The passing draft is accepted as-is.

After the batched Reviewer approves: present the synthesis and approaches to the user. Recommend one approach, but the choice is the user's. Ask via AskUserQuestion.

Step 7 — Section-by-Section Design (P1 + P2 · file-first · one combined gate)

File-first artefact rule (DOCTRINE rule 8 file-first clause): every section Writer writes its draft directly to .hyperflow/specs/.draft.md — never returns the section content for the orchestrator to paste inline. The Reviewer reads sections from the file. The approval gate references the file path, not the content. Inline pasting of section text into chat is a doctrine violation — chat output is ephemeral and unscrollable; a file is reviewable, editable, and persistent across sessions.

P1 applies at sub-phase level: All 3 sub-phases share the same upstream input (the chosen approach) and have no inter-dependencies. Dispatch sub-phases 7a, 7b,

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeremylongshore
• Source: jeremylongshore/claude-code-plugins-plus-skills
• License: MIT
• Homepage: https://tonsofskills.com

Install and usage instructions live in the source repository linked above.