flow-next-work
Execute a Flow epic 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, fn-1.2).
When & Why to Use This Skill
The flow-next-work skill is a professional-grade execution engine designed to streamline complex software development workflows for Claude agents. It solves the problem of 'agent drift' and disorganized task tracking by enforcing a systematic approach to implementing technical specifications. By automating git branch management, mandatory quality gates, and state-based task tracking via the flowctl utility, it ensures that every step of a development plan is executed, tested, and committed with high fidelity and consistency.
Use Cases
- Systematic Feature Implementation: Transforming a markdown technical specification into a series of trackable tasks, ensuring each component is built and verified in the correct order.
- Automated Git Workflow Management: Handling the creation of feature branches or isolated worktrees and performing standardized 'git add -A' commits to maintain repository integrity during complex refactors.
- Quality-Gated Development: Enforcing mandatory test passes and status checks before allowing a task to be marked as 'done' or proceeding to the code review phase.
- Subagent Orchestration: Utilizing a worker subagent model to implement specific tasks with fresh context, preventing context bleed and maintaining high performance during long-running coding sessions.
| name | flow-next-work |
|---|---|
| description | Execute a Flow epic 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, fn-1.2). |
Flow work
Execute a plan systematically. Focus on finishing.
Follow this skill and linked workflows exactly. Deviations cause drift, bad gates, retries, and user frustration.
IMPORTANT: This plugin uses .flow/ for ALL task tracking. Do NOT use markdown TODOs, plan files, TodoWrite, or other tracking methods. All task state must be read and written via flowctl.
CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:
FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"
$FLOWCTL <command>
Hard requirements (non-negotiable):
- You MUST run
flowctl donefor each completed task and verify the task status isdone. - You MUST stage with
git add -A(never list files). This ensures.flow/andscripts/ralph/(if present) are included. - Do NOT claim completion until
flowctl show <task>reportsstatus: done. - Do NOT invoke
/flow-next:impl-reviewuntil tests/Quick commands are green.
Role: execution lead, plan fidelity first. Goal: complete every task in order with tests.
Ralph Mode Rules (always follow)
If REVIEW_RECEIPT_PATH is set or FLOW_RALPH=1:
- Must use
flowctl doneand verify task status isdonebefore committing. - Must stage with
git add -A(never list files). - Do NOT use TodoWrite for tracking.
Input
Full request: $ARGUMENTS
Accepts:
- Flow epic ID
fn-Nto work through all tasks - Flow task ID
fn-N.Mto work on single task - Markdown spec file path (creates epic from file, then executes)
- Idea text (creates minimal epic + single task, then executes)
- Chained instructions like "then review with /flow-next:impl-review"
Examples:
/flow-next:work fn-1/flow-next:work fn-1.3/flow-next:work docs/my-feature-spec.md/flow-next:work Add rate limiting/flow-next:work fn-1 then review via /flow-next:impl-review
If no input provided, ask for it.
FIRST: Parse Options or Ask Questions
Check configured backend:
REVIEW_BACKEND=$($FLOWCTL review-backend)
Returns: ASK (not configured), or rp/codex/none (configured).
Option Parsing (skip questions if found in arguments)
Parse the arguments 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
Review mode:
--review=codexor "review with codex" or "codex review" or "use codex" → Codex CLI (GPT 5.2 High)--review=rpor "review with rp" or "rp chat" or "repoprompt review" → RepoPrompt chat (viaflowctl rp chat-send)--review=exportor "export review" or "external llm" → export for external LLM--review=noneor--no-reviewor "no review" or "skip review" → no review
If options NOT found in arguments
If REVIEW_BACKEND is rp, codex, or none (already configured): Only ask branch question. Show override hint:
Quick setup: Where to work?
a) Current branch b) New branch c) Isolated worktree
(Reply: "a", "current", or just tell me)
(Tip: --review=rp|codex|export|none overrides configured backend)
If REVIEW_BACKEND is ASK (not configured): Ask both branch AND review questions:
Quick setup before starting:
1. **Branch** — Where to work?
a) Current branch
b) New branch
c) Isolated worktree
2. **Review** — Run Carmack-level review after?
a) Codex CLI
b) RepoPrompt
c) Export for external LLM
d) None (configure later with --review flag)
(Reply: "1a 2a", "current branch, codex", or just tell me naturally)
Wait for response. Parse naturally — user may reply terse or ramble via voice.
Defaults when empty/ambiguous:
- Branch =
new - Review = configured backend if set, else
none(no auto-detect fallback)
Do NOT read files or write code until user responds.
Workflow
After setup questions answered, read phases.md and execute each phase in order.
Worker subagent model: Each task is implemented by a worker subagent with fresh context. This prevents context bleed between tasks and keeps re-anchor info with the implementation. The main conversation handles task selection and looping; worker handles implementation, commits, and reviews.
If user chose review, pass the review mode to the worker. The worker invokes /flow-next:impl-review after implementation and loops until SHIP.
Guardrails
- Don't start without asking branch question
- Don't start without plan/epic
- Don't skip tests
- Don't leave tasks half-done
- Never use TodoWrite for task tracking
- Never create plan files outside
.flow/