# Flow Next

Manage .flow/ tasks and specs.

- Repository: https://github.com/gmickel/flow-next (715 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add gmickel/flow-next --skill flow-next -g -a claude-code -y`
Codex: `npx skills add gmickel/flow-next --skill flow-next -g -a codex -y`
Cursor: `npx skills add gmickel/flow-next --skill flow-next -g -a cursor -y`
Gemini CLI: `npx skills add gmickel/flow-next --skill flow-next -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add gmickel/flow-next`

## Description

Manage .flow/ tasks and specs. Triggers: 'show me my tasks', 'list specs', 'what tasks are there', 'add a task', 'create task', 'what's ready', 'task status', 'show fn-1-add-oauth'. NOT for /flow-next:plan or /flow-next:work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Flow-Next Task Management

Quick task operations in `.flow/`. For planning features use `/flow-next:plan`, for executing use `/flow-next:work`.

## Preamble

**CRITICAL: flowctl is BUNDLED, NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks 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"
```

**Discover all commands/options:**
```bash
$FLOWCTL --help
$FLOWCTL <command> --help   # e.g., $FLOWCTL task --help
```

## Quick Reference

```bash
# Check if .flow exists
$FLOWCTL detect --json

# Initialize (if needed)
$FLOWCTL init --json

# List everything (specs + tasks grouped)
$FLOWCTL list --json

# List all specs
$FLOWCTL specs --json

# List all tasks (or filter by spec/status)
$FLOWCTL tasks --json
$FLOWCTL tasks --spec fn-1-add-oauth --json
$FLOWCTL tasks --status todo --json

# View spec with all tasks
$FLOWCTL show fn-1-add-oauth --json
$FLOWCTL cat fn-1-add-oauth              # Spec markdown

# View single task
$FLOWCTL show fn-1-add-oauth.2 --json
$FLOWCTL cat fn-1-add-oauth.2            # Task spec

# What's ready to work on?
$FLOWCTL ready --spec fn-1-add-oauth --json

# Create task under existing spec
$FLOWCTL task create --spec fn-1-add-oauth --title "Fix bug X" --json

# Set task description and acceptance (combined, fewer writes; unique per-task temp paths)
$FLOWCTL task set-spec fn-1-add-oauth.2 --description "${TMPDIR:-/tmp}/flow-desc-fn-1-add-oauth.2.md" --acceptance "${TMPDIR:-/tmp}/flow-accept-fn-1-add-oauth.2.md" --json

# Or use stdin with heredoc (no temp file):
$FLOWCTL task set-description fn-1-add-oauth.2 --file - --json <<'EOF'
Description here
EOF

The rest: https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/skills/flow-next/SKILL.md