/flow-next-plan

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-add-oauth, fn-1-add-oauth.2, or legacy fn-1, fn-1.2, fn-1-xxx, fn-1-xxx.2).
user-invocable: false

Flow plan

Turn a rough idea into a spec 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.

**`.flow/` is the only task tracker.** A run that recorded task state in a markdown TODO, a plan file, TodoWrite, or any other tracker has broken this — all task state is read and written via `flowctl`.

Chart boundary

A **ready** (or already-captured) spec whose work is understood stays in plan - chart is too late. An unshaped oversized freeform idea with consequential unknowns is **not** plan input: recommend `/flow-next:chart` first (or `/flow-next:flow --explain` when unsure). Plan decomposes work that is already understood; it does not replace discovery.

Preamble

**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks (here and in `steps.md`) use `$FLOWCTL`:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Leftover copy artifacts (one-line nudge)

Before Step 0, check once whether this repo still carries flowctl copies from an older install layout — the same residue list flowctl exports as `LEGACY_COPY_ARTIFACTS`:

LEFTOVERS=""
for p in .flow/bin/flowctl .flow/bin/flowctl.cmd .flow/bin/flowctl.py \
         .flow/bin/flowctl_bootstrap.py .flow/bin/flowctl-help.txt \
         .flow/bin/flowctl_tracker .flow/templates/spec.md .flow/usage.md; do
  [ -e "$p" ] && LEFTOVERS="${LEFTOVERS}${p}"$'\n' || true
done   # || true: an empty LEFTOVERS (the normal case) must read as success

**None present → say nothing.** Silence is the normal case.

**Any present →** print ONE line: these files are leftovers, nothing reads them (every host resolves flowctl from the plugin install), and they can be deleted by hand or by `/flow-next:setup`. Then continue planning — never ask, never stop, never delete anything here. Plan compares no versions and reads no setup stamps at all; `/flow-next:setup` owns everything about the install.

**Role**: product-minded planner with strong repo awareness. **Goal**: produce a spec 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.** Never write the code that will be implemented.

Code the plan may contain:

• **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 the plan never contains:

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

**A spec that already contains the implementation is not a spec.** A plan carrying a runnable function body, a full module, or a >10-line copy-paste block has broken this.

**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 spec ID `fn-N-slug` (e.g., `fn-1-add-oauth`) or legacy `fn-N`/`fn-N-xxx` to refine existing spec
• Flow task ID `fn-N-slug.M` (e.g., `fn-1-add-oauth.2`) or legacy `fn-N.M`/`fn-N-xxx.M` to refine specific task
• **Resolvable tracker handle** — a tracker key like `wor-17` / `wor-17.2` that `flowctl show` resolves to the linked spec/task. Treated as the existing spec/task, **never** as a new idea (R16). See the handle-recognition rule in Step 1.
• Chained instructions like "then review with /flow-next:plan-review"

Examples:

• `/flow-next:plan Add OAuth login for users`
• `/flow-next:plan fn-1-add-oauth`
• `/flow-next:plan fn-1` (legacy formats fn-1, fn-1-xxx still supported)
• `/flow-next:plan fn-1-add-oauth then review via /flow-next:plan-review`

If empty, ask: "What should I plan? Give me the feature or bug in 1-5 sentences." Under autonomous mode, do not ask — report `NEEDS_HUMAN: no planning input provided` and stop.

FIRST: Parse Options or Ask Questions

Autonomous mode (mode:autonomous / FLOW_AUTONOMOUS)

Parse `$ARGUMENTS` for the literal token `mode:autonomous` (strip it, same shape as capture's `mode:autofix` — a NEW parse branch, never overloading that token). Also honor the env var `FLOW_AUTONOMOUS=1` as a secondary signal (process-level drivers). Either signal → `AUTONOMOUS=1`.

Under `AUTONOMOUS=1`:

• **No setup question is asked.** A question surfaced under `AUTONOMOUS=1` has broken this. Explicit passthrough flags (`--depth`, `--research`, `--review`) win as usual; for anything unset, apply the autonomous defaults: depth = `short`, research = `repo-scout`, review = configured backend (`none` when `REVIEW_BACKEND` is `ASK`).
• **Never hang on a question.** If a genuinely unanswerable ambiguity remains (e.g. empty input), stop cleanly with a one-line `NEEDS_HUMAN: <reason>` report instead of a