flow-next
Manage development tasks and specs directly from the CLI using the flowctl utility.
Install
mkdir -p .claude/skills/flow-next && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/4993" && unzip -o skill.zip -d .claude/skills/flow-next && rm skill.zipInstalls to .claude/skills/flow-next
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →List tasks and specs
- →Create new tasks
- →Update task status
- →Validate task structure
How it works
It interacts with the local .flow/ directory using the bundled flowctl script to manage task lifecycle.
Inputs & outputs
When to use flow-next
- →List all pending tasks
- →Create a new task under a spec
- →Check task status
- →View task descriptions
About this skill
Flow-Next Task Management
Quick task operations in .flow/. To build or plan a feature use /flow-next:flow; it picks the route.
Preamble
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks use $FLOWCTL:
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:
$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 (unique per-task temp paths)
echo "What was done" > "${TMPDIR:-/tmp}/flow-summary-fn-1-add-oauth.2.md"
echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > "${TMPDIR:-/tmp}/flow-evidence-fn-1-add-oauth.2.json"
$FLOWCTL done fn-1-add-oauth.2 --summary-file "${TMPDIR:-/tmp}/flow-summary-fn-1-add-oauth.2.md" --evidence-json "${TMPDIR:-/tmp}/flow-evidence-fn-1-add-oauth.2.json" --json
# Validate structure (one spec; repo-wide through a counts-and-errors projection)
$FLOWCTL validate --spec fn-1-add-oauth --json
$FLOWCTL validate --all --json | jq '{valid, total_specs, total_tasks, total_errors, total_warnings, root_errors, failing: [.specs[] | select(.errors | length > 0) | {spec, errors}]}'
Common Patterns
"Add a task for X"
-
Find relevant spec:
# List all specs $FLOWCTL specs --json # Or show a specific spec to check its scope $FLOWCTL show fn-1 --json -
Create task:
$FLOWCTL task create --spec fn-N --title "Short title" --json -
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 tasks, projected (add --spec fn-1-add-oauth for one spec)
$FLOWCTL tasks --json | jq -c '[.tasks[] | {id, title, status, spec}]'
# Ready tasks for a spec
$FLOWCTL ready --spec fn-1-add-oauth --json
"What's next?"
$FLOWCTL brief
brief is orientation only: it omits blocked and dependency-waiting tasks, so never answer a task listing from it.
"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:flow or /flow-next:capture)
$FLOWCTL spec create --title "Spec title" --json
# Returns: {"success": true, "id": "fn-N-spec-title", ...}
Close a spec as won't-do
$FLOWCTL spec close fn-1-add-oauth --retire superseded --by fn-2-sso --json
Pick the reason that is true: superseded (another spec replaced it), delivered-elsewhere (it shipped
under another spec or pull request) or moot (it is no longer needed, including a decision not to build
it). Name each successor with --by. Its never-run tasks read retired, not done.
Before closing any spec: read references/declined.md; it decides whether the
close earns a .flow/memory/declined/ file.
ID Format
- Spec:
fn-N-slugwhere 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 --helpto discover all commands and options - Every write goes through a flowctl subcommand, except the
.flow/memory/declined/*.mdfile above, which has no flowctl verb. A session that edits.flow/JSON or task markdown by hand has broken this. - Every read comes from
.flow/state, via--json(detect,list,specs,tasks,show,ready) orcatfor markdown. An answer assembled from files skimmed by hand has broken this. - A task marked complete is closed with
flowctl donecarrying both--summary-fileand--evidence-json. A bare status flip has broken this. - Requests that need real planning or execution are handed off to
flow-next:flow-next-flow, which picks the route. Improvising them here has broken this.
When not to use it
- →When using /flow-next:plan or /flow-next:work commands
Prerequisites
Limitations
- →All writes must go through flowctl
- →Requires local .flow/ directory
How it compares
It provides a CLI-based management interface instead of manual file editing.
Compared to similar skills
flow-next side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| flow-next (this skill) | 1 | 5mo | Review | Beginner |
| github-project-management | 4 | 9mo | Review | Advanced |
| create-plans | 1 | 11mo | Review | Intermediate |
| phasing | 1 | 10mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by gmickel
View all by gmickel →You might also like
github-project-management
ruvnet
Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning
create-plans
glittercowboy
Create hierarchical project plans optimized for solo agentic development. Use when planning projects, phases, or tasks that Claude will execute. Produces Claude-executable plans with verification criteria, not enterprise documentation. Handles briefs, roadmaps, phase plans, and context handoffs.
phasing
WellApp-ai
Group slices into risk-optimized phases with timeline generation
code-task-generator
mikeyobrien
Generates structured .code-task.md files from descriptions or PDD implementation plans. Auto-detects input type, creates properly formatted tasks with Given-When-Then acceptance criteria.
wg
graphwork
Use this skill for task coordination with WG. Triggers include "wg", task graphs, multi-step projects, tracking dependencies, coordinating agents, or when you see a .wg directory.
run-tasks
JeremyKalmus
Orchestrate task execution via beads and sub-agents. Gets ready work from beads, spawns appropriate agents based on labels, monitors completion, and updates status. Use after /approve-spec has created tasks.