Skip to main content
rule CX Codex

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

Install into Cursor · Manually: put the files in place All methods and platforms ↓
.cursor/rules/flow-next.mdc
Open on GitHub

What 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.mdc

Frontmatter: description, globs, alwaysApply

Step 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

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set70

The whole set →
tracker-sync tracker-sync projects a flow spec into Linear, GitHub, GitLab, or Jira, then reconciles issue body, status, and comments in both directions. CX Codex +1 ★ 730repo stars flow-next-setup flow-next-setup links a repo to the flow-next plugin: adds versioned docs and config to CLAUDE.md or AGENTS.md. Other agents, such as Codex or Cursor, can then read the same instructions. CX Codex +1 ★ 730repo stars flow The flow command drives a task from idea or bug to ready PR. Works for unattended runs on a ready spec or step-by-step with stops before decisions. CX Codex +1 ★ 730repo stars flow-next-prose flow-next-prose — a skill for Claude and Codex that makes the agent read the prose contract in docs/prose.md before a long reply and draft under rules 1–10. CX Codex +1 ★ 730repo stars flow-next-make-pr flow-next-make-pr is a Claude Code skill that builds a briefing from an aid artifact and opens or updates a PR through gh. It detects the spec from the branch and accepts options for draft state, base branch, and dry runs. CX Codex +1 ★ 730repo stars flow-next-worktree-kit flow-next-worktree-kit is a Claude Code skill that creates, switches, and removes git worktrees and copies .env files between them. It supports parallel feature work without switching branches. CX Codex +1 ★ 730repo stars flow-next-land The flow-next-land skill handles feedback and CI checks for a named pull request, then squash-merges it when authorized and ready. Use it when asked to land a specific PR. CX Codex +1 ★ 730repo stars flow-next-make-pr flow-next-make-pr opens a pull request through gh, with the briefing body rendered by flowctl from the flow-next spec state. Fits repos where PRs are expected to follow a spec. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open