---

name: flow-next-plan description: Create structured build plans from feature requests or Flow IDs. Use when planning features or designing implementation. Triggers on /flow-next:plan with text descriptions or Flow IDs (fn-1-abc, fn-1-abc.2, or legacy fn-1, fn-1.2).

Flow plan

Turn a rough idea into an epic with tasks in .flow/. This skill does not write code.

Follow this skill and linked workflows exactly. Deviations cause drift, bad gates, retries, and user frustration.

IMPORTANT: This plugin uses .flow/ for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via flowctl.

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

CopyFLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"
$FLOWCTL <command>

Pre-check: Local setup version

If .flow/meta.json exists and has setup_version, compare to plugin version:

CopySETUP_VER=$(jq -r '.setup_version // empty' .flow/meta.json 2>/dev/null)
PLUGIN_VER=$(jq -r '.version' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json")
if [[ -n "$SETUP_VER" ]]; then
  [[ "$SETUP_VER" = "$PLUGIN_VER" ]] || echo "Plugin updated to v${PLUGIN_VER}. Run /flow-next:setup to refresh local scripts (current: v${SETUP_VER})."
fi

Continue regardless (non-blocking).

Role: product-minded planner with strong repo awareness. Goal: produce an epic with tasks that match existing conventions and reuse points. Task size: every task must fit one /flow-next:work iteration (~100k tokens max). If it won't, split it.

The Golden Rule: No Implementation Code

Plans are specs, not implementations. Do NOT write the code that will be implemented.

Code IS allowed:

• Signatures/interfaces (what, not how): function validate(input: string): Result
• Patterns from this repo (with file:line ref): "Follow pattern at src/auth.ts:42"
• Recent/surprising APIs (from docs-scout): "React 19 changed X — use useOptimistic instead"
• Non-obvious gotchas (from practice-scout): "Must call cleanup() or memory leaks"

Code is FORBIDDEN:

• Complete function implementations
• Full class/module bodies
• "Here's what you'll write" blocks
• Copy-paste ready snippets (>10 lines)

Why: Implementation happens in /flow-next:work with fresh context. Writing it here wastes tokens in planning, review, AND implementation — then causes drift when the implementer does it differently anyway.

Input

Full request: $ARGUMENTS

Accepts:

• Feature/bug description in natural language
• Flow epic ID fn-N-xxx (e.g., fn-1-abc) or legacy fn-N to refine existing epic
• Flow task ID fn-N-xxx.M (e.g., fn-1-abc.2) or legacy fn-N.M to refine specific task
• Chained instructions like "then review with /flow-next:plan-review"

Examples:

• /flow-next:plan Add OAuth login for users
• /flow-next:plan fn-1-abc
• /flow-next:plan fn-1 (legacy format still supported)
• /flow-next:plan fn-1-abc then review via /flow-next:plan-review

If empty, ask: "What should I plan? Give me the feature or bug in 1-5 sentences."

FIRST: Parse Options or Ask Questions

Check configured backend:

CopyREVIEW_BACKEND=$($FLOWCTL review-backend)

Returns: ASK (not configured), or rp/codex/none (configured).

Option Parsing (skip questions if found in arguments)

Parse the arguments for these patterns. If found, use them and skip questions:

Research approach:

• --research=rp or --research rp or "use rp" or "context-scout" or "use repoprompt" → context-scout (errors at runtime if rp-cli missing)
• --research=grep or --research grep or "use grep" or "repo-scout" or "fast" → repo-scout

Review mode:

• --review=codex or "review with codex" or "codex review" or "use codex" → Codex CLI (GPT 5.2 High)
• --review=rp or "review with rp" or "rp chat" or "repoprompt review" → RepoPrompt chat (via flowctl rp chat-send)
• --review=export or "export review" or "external llm" → export for external LLM
• --review=none or --no-review or "no review" or "skip review" → no review

If options NOT found in arguments

Plan depth (parse from args or ask):

• --depth=short or "quick" or "minimal" → SHORT
• --depth=standard or "normal" → STANDARD
• --depth=deep or "comprehensive" or "detailed" → DEEP
• Default: SHORT (simpler is better)

If REVIEW_BACKEND is rp, codex, or none (already configured): Only ask research question. Show override hint:

CopyQuick setup: Use RepoPrompt for deeper context?
a) Yes, context-scout (slower, thorough)
b) No, repo-scout (faster)

(Reply: "a", "b", or just tell me)
(Tip: --depth=short|standard|deep, --review=rp|codex|none)

If REVIEW_BACKEND is ASK (not configured): Ask all questions (do NOT use AskUserQuestion tool):

CopyQuick setup before planning:

1. **Plan depth** — How detailed?
   a) Short — problem, acceptance, key context only
   b) Standard (default) — + approach, risks, test notes
   c) Deep — + phases, alternatives, rollout plan

2. **Research** — Use RepoPrompt for deeper context?
   a) Yes, context-scout (slower, thorough)
   b) No, repo-scout (faster)

3. **Review** — Run Carmack-level review after?
   a) Codex CLI
   b) RepoPrompt
   c) Export for external LLM
   d) None (configure later)

(Reply: "1a 2b 3d", or just tell me naturally)

Wait for response. Parse naturally — user may reply terse ("1a 2b") or ramble via voice.

Defaults when empty/ambiguous:

• Depth = standard (balanced detail)
• Research = grep (repo-scout)
• Review = configured backend if set, else none

Workflow

Read steps.md and follow each step in order. The steps include running research subagents in parallel via the Task tool. If user chose review:

• Option 2a: run /flow-next:plan-review after Step 4, fix issues until it passes
• Option 2b: run /flow-next:plan-review with export mode after Step 4

Output

All plans go into .flow/:

• Epic: .flow/epics/fn-N-xxx.json + .flow/specs/fn-N-xxx.md
• Tasks: .flow/tasks/fn-N-xxx.M.json + .flow/tasks/fn-N-xxx.M.md

Never write plan files outside .flow/. Never use TodoWrite for task tracking.

Output rules

• Only create/update epics and tasks via flowctl
• No code changes
• No plan files outside .flow/