flow-next-work
Executes tasks from a Flow specification systematically.
Install
mkdir -p .claude/skills/flow-next-work && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/6106" && unzip -o skill.zip -d .claude/skills/flow-next-work && rm skill.zipInstalls to .claude/skills/flow-next-work
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.
Execute a Flow spec or task systematically with git setup, task tracking, quality checks, and commit workflow. Use when implementing a plan or working through a spec. Triggers on /flow-next:work with Flow IDs (fn-1-add-oauth, fn-1-add-oauth.2, or legacy fn-1, fn-1.2, fn-1-xxx, fn-1-xxx.2).Key capabilities
- →Execute tasks defined in Flow specifications
- →Manage git staging for task completion
- →Verify task status via flowctl
- →Run quality checks before task finalization
- →Handle autonomous task execution
How it works
The skill uses a bundled flowctl script to track task state within a .flow/ directory, enforcing specific git workflows and verification steps for each task.
Inputs & outputs
When to use flow-next-work
- →Implementing project specifications
- →Tracking task progress
- →Running quality checks
- →Executing development workflows
About this skill
Flow work
Execute a plan systematically. Focus on finishing.
.flow/ is the only task tracker. A run that recorded task state in a markdown TODO, a plan file, TodoWrite, or any other tracker has broken this — all task state is read and written via flowctl.
Preamble
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in phases.md) 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"
Hard requirements (non-negotiable):
- Every completed task passes through
flowctl doneand a verifieddonestatus. A task treated as finished whileflowctl show <task>still readstodoorin_progresshas broken this. - Staging is the files you changed plus
.flow/(git add -- <files> .flow/), nevergit add -A—.flow/carries the run's task state; files a test run or tool wrote stay out of the diff. A commit whose diff omits the run's.flow/writes has broken this. - Completion is claimed only after
flowctl show <task>reportsstatus: done. A completion claim printed ahead of that read has broken this. flow-next:flow-next-impl-reviewis dispatched only on a green tree. A review sent while tests or Quick commands are red has broken this.
Role: execution lead, plan fidelity first. Goal: complete every task in order with tests.
Autonomous Mode (questions off, no receipt obligations)
Before gates, treat this host-expanded block as literal prompt data, never shell:
<work-arguments> $ARGUMENTS </work-arguments>Strip standalone whitespace token mode:autonomous into WORK_ARGS; preserve
all else verbatim (spaces/quotes/globs). Set/export AUTONOMOUS=1 if found or
FLOW_AUTONOMOUS=1; otherwise set/export AUTONOMOUS=0.
Continue with WORK_ARGS; carry the exported marker into later shell fragments.
If AUTONOMOUS=1: read references/autonomous-defaults.md
before any question, and:
- Branch defaults deterministically to
--branch=newwhen no explicit branch option is present — under autonomy "the user's answer" never exists, and defaulting to the current branch could commit straight to main. A chained spec (flowctl spec chainnames a parent) forks from the parent's remote tip instead of main (phases.md Phase 2). Name the new branch exactly the spec'sbranch_namefield ($FLOWCTL show <spec-id> --json | jq -r '.branch_name') — the branch matrix offlow --auto, its all-done PR probe, and make-pr's branch-match spec detection all key on that name; an ad-hoc name breaks continuity across hops and invocations.
Input
Full request after mode parsing: $WORK_ARGS
Accepts:
- Flow spec ID
fn-N-slug(e.g.,fn-1-add-oauth) or legacyfn-N/fn-N-xxxto work through all tasks - Flow task ID
fn-N-slug.M(e.g.,fn-1-add-oauth.2) or legacyfn-N.M/fn-N-xxx.Mto work on single task - Markdown spec file path (creates spec from file, then executes)
- Idea text (creates minimal spec + single task, then executes)
- Chained instructions like "then review with /flow-next:impl-review"
If no input provided, ask for it.
FIRST: Parse Options
Option Parsing (skip questions if found in arguments)
Parse WORK_ARGS for these patterns. If found, use them and skip corresponding questions:
Branch mode:
--branch=currentor--currentor "current branch" or "stay on this branch" → current branch--branch=newor--new-branchor "new branch" or "create branch" → new branch--branch=worktreeor--worktreeor "isolated worktree" or "worktree" → isolated worktree
Base: --base=<branch> or --base <branch> → DEFAULT_BASE=origin/<branch> (a leading
origin/ is kept once), the branch a new spec branch starts from and the run is compared against
(phases.md Phase 2); an unfetchable branch, or a spec with a chain parent, stops BLOCKED there,
before any branch is created.
Review mode:
--review=<codex|copilot|cursor|claude|host|none>, or the same backend named in words ("review with codex", "host review", "skip review");--no-review=none
(All non-none review modes route through flow-next:flow-next-impl-review, which resolves the
configured/overridden backend — codex, copilot, cursor, claude, or host — itself.)
No-plan (direct spec execution):
--no-planor "no plan" or "skip planning" or "work directly without planning" → setNO_PLAN=1; it pre-answers Phase 1's zero-task fork so the fork's ask never fires when intent is stated- Implementation review, coverage, completion policy and opt-in QA remain unchanged on this route.
- The fork's semantics (ask, autonomous refusal, durable choice, implicit-task mint) live in phases.md Phase 1's gated references/no-plan-route.md, read only when the fork fires
Autonomous mode:
AUTONOMOUS=1→ use the defaults above.
If the options are absent from the arguments
If AUTONOMOUS=1 (autonomous mode): ask nothing — apply the autonomous defaults and continue to the workflow.
Otherwise (interactive): do not ask about the branch. Stay on the current branch when it is
not the default branch, otherwise create a new one (named for the spec's branch_name), and say
which in one line. Never ask about review either: the review step resolves the backend per task
(phases.md Phase 3).
Done when: the branch and review modes are resolved from arguments, these defaults, or the autonomous defaults.
Workflow
Read working-rules.md first unless you already have this run; it holds on every phase and in every worker dispatch.
Once the modes are resolved, read phases.md and execute each phase in order.
Guardrails
- The branch is chosen before the run starts. A run that began on an unresolved branch choice has broken this.
- A plan or spec exists before implementation starts. A run that began with no
.flow/spec has broken this. - Tests run. A task marked done before the focused tests for the code it changed ran has broken this.
- No task is left half-done. A run that ends with a task still
in_progressand noNEEDS_HUMAN/blocked report has broken this. - Task tracking lives in
.flow/viaflowctl. A run tracking tasks in TodoWrite, or writing a plan file outside.flow/, has broken this.
When not to use it
- →When using markdown TODOs or external tracking methods
- →When bypassing the .flow/ directory for state management
Prerequisites
Limitations
- →Requires .flow/ directory for all state tracking
- →Cannot use external tracking tools like TodoWrite
How it compares
It enforces a strict, systematic execution workflow that prevents drift by requiring explicit task completion verification before committing.
Compared to similar skills
flow-next-work side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| flow-next-work (this skill) | 1 | 5mo | Review | Advanced |
| bad | 0 | 7mo | Review | Advanced |
| jira | 11 | 9mo | No flags | Beginner |
| triaging-issues | 5 | 5mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by gmickel
View all by gmickel →You might also like
bad
stephenleo
BMad Autonomous Development — orchestrates parallel story implementation pipelines. Builds a dependency graph, updates PR status from GitHub, picks stories from the backlog, and runs each through create → dev → review → PR in parallel — each story isolated in its own git worktree — using dedicated s
jira
davila7
Use when the user mentions Jira issues (e.g., "PROJ-123"), asks about tickets, wants to create/view/update issues, check sprint status, or manage their Jira workflow. Triggers on keywords like "jira", "issue", "ticket", "sprint", "backlog", or issue key patterns.
triaging-issues
pytorch
Triages GitHub issues by routing to oncall teams, applying labels, and closing questions. Use when processing new PyTorch issues or when asked to triage an issue.
github-project-management
ruvnet
Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning
issue-manage
catlog22
Interactive issue management with menu-driven CRUD operations. Use when managing issues, viewing issue status, editing issue fields, performing bulk operations, or viewing issue history. Triggers on "manage issue", "list issues", "edit issue", "delete issue", "bulk update", "issue dashboard", "issue history", "completed issues".
team-coordination
alinaqi
Multi-person projects - shared state, todo claiming, handoffs