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.

Per-Step Agent Map (DOCTRINE rule 12)

Every substantive step dispatches at least one Agent. The orchestrator never does "real" work inline — it only coordinates dispatches and prints status.

Substantive steps = 1, 2, 3, 5, 6, 7, 8. Each appears in the usage summary.

Approval Gates

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=<auto|manual> 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=<mode>".

If the agent cannot present AskUserQuestion (e.g., headless mode), it should print an error and stop — never silently default.

Step 1 — Triage (Layer 0.5)

Agents — Classifier (Opus, thinking-tier).

Dispatch a thinking-tier triage call per task-triage.md. The Classifier produces { types[], complexity, risk, scope, ambiguity, flow, personas[] } JSON. The classification drives:

• 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)
• Persona stitching for worker prompts later (see personas-A.md, personas-B.md)

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

**Classifier** — triaging request
Triage — types: [<types>] · flow: <profile> · ambiguity: <score>

Step 2 — Context Exploration

Agents — Searcher (Sonnet) ⇒ Reviewer (Opus).

1. Dispatch Searcher — mapping context relevant to <idea> (worker). Find existing code, patterns, similar features. Do not ask the user what you can find in the code.
2. Dispatch **Reviewer** — verifying context coverage (thinking-tier). Confirm the Searcher hit the relevant subsystems; if gaps remain, redispatch the Searcher with the missing scope before moving on.

Step 3 — Multi-Dimensional Analysis

Agents — Analyst (Opus, thinking-tier).

Dispatch **Analyst** — 6-dimension exploration with the request + context from Step 2. The Analyst produces a brief covering:

1. User intent — what is the real underlying need?
2. Technical fit — how does this fit existing architecture?
3. Scope — minimum viable vs maximum scope
4. Constraints — time, deps, perf, compatibility
5. Risks — what could go wrong, what's irreversible
6. Alternatives — at least 3 ways to solve this

The Analyst flags which dimensions have unknowns the user must resolve. Those unknowns become the Step 4 question set.

Step 4 — Smart Questions (AskUserQuestion — MANDATORY · floor 2)

Use the AskUserQuestion tool. Never plain text questions. Ask about unknowns from step 3.

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. Question budget:

• light depth (ambiguity 0.0–0.5) — exactly 2 questions
• standard depth (0.5–0.8) — 3 questions
• deep depth (0.8–1.0) — 4–5 questions

Never stack more than 2 questions per AskUserQuestion call.

Every option list MUST mark a recommended choice (DOCTRINE rule 8). The Analyst's leading hypothesis from Step 3 goes first with (Recommended); alternatives follow. The user can pick anything — the marker is guidance, not a default.

Question categories (in order — pick the first N for depth N):

1. Intent clarification — confirm the real goal (always ask)
2. Constraint discovery — what must / must not happen (always ask)
3. Assumption challenging — "you said X, did you mean Y instead?"
4. Scope boundaries — what's IN vs OUT
5. Edge-case stance — how strict on the unhappy paths

If the request feels "completely clear" — ask anyway. The first two questions exist so the user can spot a misalignment the agent missed.

Example structure (DON'T omit the recommendation marker):

?  Where should auth state live?
   Server sessions (Recommended)  — revocable, refreshable, fits this project's DB conventions
   JWT stateless                  — simpler, no DB, harder to revoke