---
name: Plan
slug: plan
category: Automation
description: Amplifies vague prompts, designs approaches, and decomposes tasks into build-ready files before any code is written. Use to sharpen requirements, explore design options, and produce batched task briefs for implementation.
github: "https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/ai-agency/hyperflow/skills/plan"
language: Python
stars: 2560
forks: 368
install: "git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills"
added: 2026-07-19T06:55:11.259Z
last_synced: 2026-07-28T07:00:20.861Z
canonical_url: "https://dirskills.com/skills/plan"
---

# Plan

Amplifies vague prompts, designs approaches, and decomposes tasks into build-ready files before any code is written. Use to sharpen requirements, explore design options, and produce batched task briefs for implementation.

**Install:** `git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills`

## 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 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`](../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:

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`](../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`](../hyperflow/flow-profiles.md)); and persona/specialist stitching. On a gated flow the responsible specialist roster is finalized once via the [Brain](../../agents/brain.md) (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`](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`](../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`](../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`](../../agents/architect.md) 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`](../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`](../../agents/designer.md) 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`](../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`](../../agents/motion.md) agent to author the Motion-language decisions in §3 (compositor-only props, library choice, spring params, reduced-motion fallback per [`../hyperflow/motion.md`](../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`](../../agents/mobile.md) 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`](../hyperflow/mobile.md). No source code