flow-next-plan

name	flow-next-plan
description	Plan a feature into a flow-next spec with tasks in .flow/. Use when asked to plan, spec out, or break down work (fn-N ids).
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 (fn-135)

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:guide 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="${CODEX_HOME:-$HOME/.codex}/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 (fn-52.10). 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 asking.
• Autonomy ≠ Ralph: neither mode:autonomous nor FLOW_AUTONOMOUS activates ralph-guard hooks or any receipt path — they gate question suppression only.

Option Parsing (skip questions if found in arguments)

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

Research approach: always repo-scout — there is no research-backend choice. --research=grep is accepted as a no-op; any other --research value is ignored.

Review mode:

• --review=codex or "review with codex" or "codex review" or "use codex" → Codex CLI
• --review=rp or "review with rp" or "rp chat" or "repoprompt review" → RepoPrompt chat (via flowctl rp chat-send)
• --review=host or "review with host" or "host review" or "use host" → host-native fresh-context reviewer subagent (fn-123 R5; pins in AGENTS.md model-routing)
• --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 AUTONOMOUS=1: skip every question below — apply the autonomous defaults above and continue.

Check the configured backend and route:

ACTIVE=0
# NO pipelines in the probe — a failed producer masked by a healthy consumer
# fails CLOSED. Capture raw first, rc-checked; parse separately.
RAW="$($FLOWCTL review-backend 2>/dev/null)" || ACTIVE=1        # probe ERROR ⇒ ACTIVE (fail open)
if [ "$ACTIVE" = "0" ]; then
  REVIEW_BACKEND="$(printf '%s' "$RAW" | tr -d '[:space:]' 2>/dev/null)" || ACTIVE=1   # parse ERROR ⇒ ACTIVE
  [ "$REVIEW_BACKEND" = "ASK" ] && ACTIVE=1
fi
[ "${AUTONOMOUS:-0}" = "1" ] && ACTIVE=0        # autonomous NEVER asks — defaults apply
if [ "$ACTIVE" = "1" ]; then
  echo "SETUP-QUESTIONS GATE ACTIVE — STOP. Read references/setup-questions.md before continuing."
fi

review-backend returns: ASK (not configured), or rp/codex/copilot/cursor/claude/host/none (configured).

When the sentinel prints, STOP and Read references/setup-questions.md before any further step — it owns RepoPrompt eligibility, the two question variants, and the empty/ambiguous defaults.

If REVIEW_BACKEND is rp, codex, copilot, cursor, claude, host, or none (already configured): ask nothing — depth defaults apply unless passed, research is repo-scout, review is the configured backend. Show the override hint:

(Tip: --depth=short|standard|deep, --review=rp|codex|copilot|cursor|claude|host|none)

Spec-id scheme (team default)

When Route B mints a brand-new spec, tracker-first is the recommended team default if tracker.specIds=tracker and the bridge is active — the tracker is the distributed allocator (KEY-N-slug / synthetic gh-N / gl-N). Gate lives in steps.md Route B (create-first then --tracker-first; silent flow-first degrade; explicit override wins). Setup owns the one-time question; no runtime nag.

Workflow

Read steps.md and follow each step in order.

Step 1 readiness soft-check (fn-58): existing-spec inputs get an adoption-gated readiness check BEFORE the scout fan-out — warn-not-block, default proceed; repos that never adopted readiness see nothing. Details in steps.md Step 1.

Optional paths: steps.md gates the readiness warning, the Route A refine path, the tracker-first mint, tracker projection, selected review, the interactive next-steps menu, and the HTML render lens after their existing config/choice/route signals. Their references stay cold when the path is not taken; Step 0 remains the only config snapshot.

Step 1 (Research) launches every scout in the depth-appropriate set as parallel multi-agent threads (Codex spawns them concurrently). The set is the steps.md tier table — the full set at STANDARD/DEEP, the full set minus the three web-research scouts at SHORT. A plan whose research skipped a scout inside its own tier, or ran the set sequentially, has broken this. Each scout in the set provides unique signal.

Output

All plans go into .flow/:

• Spec: .flow/specs/fn-N-slug.json + .flow/specs/fn-N-slug.md
• Tasks: .flow/tasks/fn-N-slug.M.json + .flow/tasks/fn-N-slug.M.md
• Render lens (only when artifacts.html.enabled): .flow/artifacts/fn-N-slug/spec.html (steps.md Step 8.5)

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

Output rules

• Only create/update specs and tasks via flowctl
• No code changes
• No plan files outside .flow/
• R-IDs are mandatory on new spec acceptance criteria — use - **Rn:** ... prose prefix format; never renumber after first review cycle; each behavioral R-ID enumerates error/boundary cases or records "no error surface beyond X" (see steps.md R-ID rule)