flow-next — Claude Code rule: what it does, how to install
flow-next directs AI models to manage fn-N tasks using flowctl instead of markdown TODO lists.
MIT ★ 730 updated 2026-10-29
.cursor/rules/flow-next.mdcWhat flow-next does
The rule triggers when a workspace contains a .flow/ directory or references task identifiers like fn-N. It forces the agent to re-read specs and task states before touching code. Loose markdown checklists and TodoWrite calls are strictly banned. Everything moves through flowctl.
All task operations run through the flowctl script located in the plugin directory or .flow/bin/flowctl. The directive covers task inspection, starting work, and finishing tickets with summary notes and JSON evidence. Spec generation uses $FLOWCTL spec create alongside /flow-next:plan <id>.
Without flowctl present on disk, task execution halts until you run /flow-next:setup. The rule also demands reviewing $FLOWCTL usage before delegating work to external CLI tools like codex exec or claude -p.
What it helps with
- track task lifecycles using the flowctl CLI
- record commit hashes and test commands as task completion evidence
- generate structured specs and link them to execution plans
- prevent loose markdown task lists across project files
Example prompts for the agent
- Check the active task list using flowctl
- Start task fn-2.1 and re-read its spec before making changes
- Mark fn-2.1 as done with summary and evidence json
How to install flow-next
Manually: put the files in place
.cursor/rules/flow-next.mdcFrontmatter: description, globs, alwaysApply
1Plugin marketplace
/plugin marketplace add gmickel/flow-next/plugin install flow-next@flow-next2Manually: put the files in place
.claude/rules/flow-next.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/flow-next.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/flow-next.mdManually: put the files in place
.clinerules/flow-next.mdStep by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules
Questions about flow-next
How to install flow-next in Claude Code?
Run /plugin marketplace add gmickel/flow-next, then run /plugin install flow-next@flow-next.
What does flow-next do?
It enforces task tracking via flowctl inside the .flow/ directory. The AI stops using standard TODO comments or files and tracks progress through formal specs and task IDs.
What should you do if flowctl is not found?
When the shell cannot find the script in plugin paths or .flow/bin/flowctl, invoke /flow-next:setup.
Source text
flow-next.mdc · MIT
---
description: Apply when the workspace contains a .flow/ directory or the conversation involves flow-next, flowctl, or fn-N task ids. Flow-Next task lifecycle and flowctl usage pull directives (Cursor guidance rail).
alwaysApply: false
---
# Flow-Next
This project uses Flow-Next for ALL task tracking. Do NOT create markdown TODOs or use TodoWrite. Re-anchor (re-read spec + task status) before every task.
Resolve flowctl once per shell block, then use `$FLOWCTL` (Cursor sets no plugin-root env var, so the derivation rung is the one that carries here):
```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"
```
- Lifecycle: `$FLOWCTL list` / `show fn-N.M` / `start fn-N.M` / `done fn-N.M --summary-file s.md --evidence-json e.json` (e.json: `{"commits": ["<sha>"], "tests": ["<cmd>"], "prs": []}`)
- BEFORE any other flowctl operation, or when unsure of a flag: run `$FLOWCTL usage` (CLI cheatsheet + orchestration recipes).
- BEFORE bridging work to another model/CLI (`codex exec`, `cursor-agent`, `claude -p`, `grok`) or picking an implementation/review model: run `$FLOWCTL usage` and follow "Orchestration & model steering" exactly.
- Creating a spec: `$FLOWCTL spec create --title "Short title" --json`, then `$FLOWCTL spec set-plan <id> --file plan.md`, then `/flow-next:plan <id>` (Cursor autocomplete may show the hyphenated form `/flow-next-plan`).
- If `flowctl` is not found: run `/flow-next:setup`.
© Gordon Mickel · MIT · gmickel/flow-next