flow-next-plan

Flow plan

Turn an idea or an existing spec into a spec with right-sized tasks in .flow/, grounded in repo research. Plan writes no code.

Read working-rules.md first; it holds for every step of this skill.

.flow/ is the only task tracker. Every spec and task is created or changed through flowctl. A markdown TODO list, a TodoWrite call, or a plan file outside .flow/ has broken this.

Preamble

flowctl is bundled, not installed globally (which flowctl fails). Define it once; later 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"

Check once for flowctl copies left by an older install layout:

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. Any present: print one line saying nothing reads them and they can be deleted by hand or by /flow-next:setup, then continue. Never ask, stop, or delete here.

No implementation code

The spec states what and why as contracts; each task states how: named files, the repo pattern to follow (file:line), ordering, and non-obvious gotchas. Code in a plan is limited to signatures and interfaces, pointers to existing patterns, a recent or surprising API from docs-scout, and a gotcha from practice-scout. A full function or module body, or a copy-paste block over about 10 lines, has broken this: implementation happens in /flow-next:work with fresh context, and code written here is paid for again there and drifts.

Input

Full request: $ARGUMENTS

Accepts a freeform idea; a spec id fn-N-slug (legacy fn-N, fn-N-xxx); a task id fn-N-slug.M (legacy fn-N.M, fn-N-xxx.M); a tracker handle such as wor-17 that flowctl show resolves (always the existing spec or task, never a new idea; see Step 1); and chained instructions such as "then review with /flow-next:plan-review".

Empty input: ask "What should I plan? Give me the feature or bug in 1-5 sentences." Under autonomy, report NEEDS_HUMAN: no planning input provided and stop.

A ready or captured spec is plan input. An unshaped, oversized idea with several consequential unknowns is not: recommend /flow-next:chart (or /flow-next:flow --explain when unsure) and stop. Plan decomposes understood work; it does not replace discovery.

Options

Autonomy. The literal token mode:autonomous in $ARGUMENTS (strip it) or FLOW_AUTONOMOUS=1 sets AUTONOMOUS=1. Then no question is ever asked: explicit flags win, and anything unset takes its default (depth below, research repo-scout, review the configured backend, none when it is ASK). A genuinely unanswerable ambiguity stops with a one-line NEEDS_HUMAN: <reason>.

Depth. --depth=short ("quick", "minimal"), --depth=standard ("normal"), --depth=deep ("comprehensive", "detailed"). Default SHORT. Depth picks the scout set (Step 1) and the spec sections (Step 4).

Research. Always repo-scout; --research=grep is a no-op and any other value is ignored.

Review. --review=codex ("review with codex", "codex review", "use codex"), --review=rp ("rp chat", "repoprompt review"), --review=host ("host review", "use host": the host-native fresh-context reviewer), --review=export ("export review", "external llm"), --review=none or --no-review ("no review", "skip review").

An option found in the arguments, as a flag or in these words, skips its setup question.

Initialize and capture one preflight snapshot before routing or scouting (also under autonomy). Every later config read uses this literal path:

$FLOWCTL init --json
PLAN_CFG="${TMPDIR:-/tmp}/flow-plan-config-<suffix>.json"
$FLOWCTL preflight --json > "$PLAN_CFG" 2>/dev/null || printf '{"key":null,"value":{}}' > "$PLAN_CFG"

ACTIVE=0
# No pipelines in the probe: capture raw first, rc-checked; parse separately.
RAW="$(jq -er 'if .probes.review_backend.status == "ok" then .probes.review_backend.value.backend else error("review backend probe") end' "${TMPDIR:-/tmp}/flow-plan-config-<suffix>.json" 2>/dev/null)" || ACTIVE=1        # probe error => ACTIVE
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
if [ "$ACTIVE" = "1" ]; then
  echo "SETUP-QUESTIONS GATE ACTIVE — STOP. Read references/setup-questions.md before continuing."
fi

When the sentinel prints, read references/setup-questions.md before any further step. When a backend is configured (rp, codex, copilot, cursor, claude, host, none), ask nothing: flags win, depth defaults, review uses that backend. Show the hint:

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

Workflow

Read steps.md and follow each step in order. Its optional paths (readiness warning, Route A, tracker-first mint, tracker projection, review, next-steps menu) load their references only when the step's condition holds.

Step 1 launches every scout in the depth-appropriate set, in ONE parallel Task call. A plan whose research skipped a scout in its tier, or ran the set sequentially, has broken this.

Output

• Spec: .flow/specs/<spec-id>.json + .md; tasks: .flow/tasks/<spec-id>.M.json + .md.
• No code changes and no plan files outside .flow/.