Skip to main content
skill CX Codex

flow-next-plan — Claude Code skill: planning and setup

flow-next-plan is a Claude Code skill that turns a feature request or existing spec into repository-based tasks before implementation; it does not write code.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-plan does

Give the skill a freeform request, a spec or task ID, or a tracker handle that flowctl can resolve. It writes a spec and task files under .flow/, which serves as the project’s task tracker. The plan describes contracts, files to change, ordering, and implementation notes; it does not produce working code.

It initializes flowctl, captures project settings, then runs the research agents for the selected depth in parallel. Short depth is the default; choose --depth=standard or --depth=deep for a broader plan. An idea with several consequential unknowns needs discovery first, so the skill points to /flow-next:chart rather than treating it as a ready spec.

Run initialization from the repository root, where flowctl can read the project configuration. Starting from the skill’s own directory will fail to find it. With no request, the skill asks what to plan; autonomous mode stops with NEEDS_HUMAN instead.

What it helps with

  • turn a feature request into a spec and task files
  • plan work from an existing spec ID
  • resolve a tracker handle through flowctl
  • record task order and relevant project files

Example prompts for the agent

  • Plan adding OAuth sign-in to this application.
  • Break down spec fn-1-add-oauth into implementation tasks.
  • Plan fn-1-add-oauth.2 with --depth=standard.

How to install flow-next-plan

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-plan -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-plan/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-plan/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-plan

How do I install flow-next-plan in Claude Code?

Run /plugin marketplace add gmickel/flow-next, then /plugin install flow-next@flow-next.

What does flow-next-plan do?

It researches the repository and creates a spec with implementation tasks under .flow/. It does not write implementation code.

Where does flow-next-plan store its plans?

Specs and tasks go in .flow/, and flowctl makes the changes there. The skill treats that directory as the project’s task tracker.

Source text

SKILL.md · MIT
---
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 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](../../references/working-rules.md) first unless you already have this run; 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 kept outside `.flow/` as the record 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`:

```bash
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:

```bash
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=host` ("host review", "use host": the host-native fresh-context reviewer), `--review=none` or `--no-review` ("no review", "skip review"). `--review=rp` and `--review=export` were removed: say "RepoPrompt review (rp, export) was removed in flow-next 8.0.0; review backends: claude, codex, copilot, cursor, host." once and treat review as nothing configured (`ASK`, below).


Initialize and capture one preflight snapshot before routing or scouting (also under autonomy), from the repository root (never this skill's directory, where flowctl finds no config). Every later config read uses this literal path:

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

Plan asks no setup question: flags win, depth takes its default, and review uses the configured
backend from the snapshot (`.probes.review_backend.value.backend`). When that reads `ASK` (nothing
configured), review is `none` and the handoff says once "no review backend set; run setup or set
review.backend". Show the hint:

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

## Workflow

Read [steps.md](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. Specs and tasks live in `.flow/`; temporary drafts (the `/tmp` bodies steps.md writes) are fine.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
docs-gap-scout docs-gap-scout reads the change you plan to make and lists which docs in the repo will need updating, plus the ones that won't. CX Codex ★ 730repo stars practice-scout practice-scout discovers modern engineering best practices, pitfalls, and GitHub references for an upcoming implementation task. CX Codex ★ 730repo stars observability-scout observability-scout is a Claude Code subagent that checks codebases for observability signals and reports production readiness across six criteria. CX Codex ★ 730repo stars memory-scout memory-scout queries .flow/memory/ for project conventions, architecture patterns, and past bug records relevant to the active task. CX Codex ★ 730repo stars flow-next flow-next is a Claude Code skill for managing project tasks and specs in .flow/, checking statuses, creating tasks, and closing completed work. It shows what is planned and ready. CX Codex +1 ★ 730repo stars github-scout github-scout finds code patterns, implementations, and issue reports on GitHub. Helpful when you need authoritative references before writing code. CX Codex ★ 730repo stars flow-next-prospect flow-next-prospect is a Claude Code skill that finds and ranks ideas from a repository’s contents. It runs when asked to brainstorm what to build next. CX Codex +1 ★ 730repo stars flow-next-map flow-next-map wraps clawpatch map to build a semantic index of functions and modules across ~20 languages. Runs provider-free by default. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open