OpenParable
Skip to content
← Back to skills

Flow Next

Productivity
flow-next

Flow Next is an Agent Skill for productivity published in the gmickel/flow-next repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/codex/skills/flow-next/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/flow-next, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

FLOWCTL="$HOME/.codex/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Discover all commands/options:

$FLOWCTL --help
$FLOWCTL <command> --help # e.g., $FLOWCTL task --help

Quick Reference

# 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

# Start working on task
$FLOWCTL start fn-1-add-oauth.2 --json

# Mark task done
echo "What was done" > /tmp/summary.md
echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > /tmp/evidence.json
$FLOWCTL done fn-1-add-oauth.2 --summary-file /tmp/summary.md --evidence-json /tmp/evidence.json --json

# Validate structure
$FLOWCTL validate --spec fn-1-add-oauth --json
$FLOWCTL validate --all --json

Common Patterns

"Add a task for X"

  1. Find relevant spec:
# List all specs
$FLOWCTL specs --json

# Or show a specific spec to check its scope
$FLOWCTL show fn-1 --json
  1. Create task:
$FLOWCTL task create --spec fn-N --title "Short title" --json
  1. Add description + acceptance (combined):
# Unique per-task temp paths — written + consumed in this one block
cat > "${TMPDIR:-/tmp}/flow-desc-fn-N.M.md" << 'EOF'
**Bug/Feature:** Brief description

**Details:**
- Point 1
- Point 2
EOF
cat > "${TMPDIR:-/tmp}/flow-accept-fn-N.M.md" << 'EOF'
- [ ] Criterion 1
- [ ] Criterion 2
EOF
$FLOWCTL task set-spec fn-N.M --description "${TMPDIR:-/tmp}/flow-desc-fn-N.M.md" --acceptance "${TMPDIR:-/tmp}/flow-accept-fn-N.M.md" --json

"What tasks are there?"

# All specs
$FLOWCTL specs --json

# All tasks
$FLOWCTL tasks --json

# Tasks for specific spec
$FLOWCTL tasks --spec fn-1-add-oauth --json

# Ready tasks for a spec
$FLOWCTL ready --spec fn-1-add-oauth --json

"Show me task X"

$FLOWCTL show fn-1-add-oauth.2 --json # Metadata
$FLOWCTL cat fn-1-add-oauth.2 # Full spec

(Legacy fn-1.2 / fn-1-xxx.2 still works.)

Create new spec (rare - usually via /flow-next:plan)

$FLOWCTL spec create --title "Spec title" --json
# Returns: {"success": true, "id": "fn-N-spec-title", ...}

ID Format

  • Spec: fn-N-slug where slug is derived from title (e.g., fn-1-add-oauth, fn-2-fix-login-bug)
  • Task: fn-N-slug.M (e.g., fn-1-add-oauth.1, fn-2-fix-login-bug.2)

Legacy formats fn-N and fn-N-xxx (random 3-char suffix) are still supported.

Notes

  • Run $FLOWCTL --help to discover all commands and options
  • All writes go through flowctl (don't edit JSON/MD files directly)
  • --json flag gives machine-readable output
  • For complex planning/execution, use /flow-next:plan and /flow-next:work