An opinionated four-phase development lifecycle for Claude Code.
Three commands you type. Four phases that run themselves.
Same order, every time. Language-agnostic —
every project owns its toolchain via repo-local bin/* delegation.
Claude Code is powerful, but undisciplined by default. FLOW imposes structure — not bureaucracy, discipline. Every feature follows the same arc, in the same order, with the same gates.
Zero dependencies. Prime commits .claude/settings.json and four bin/* stubs as project config. .flow.json and .flow-states/ are git-excluded. One state file while you work — Complete deletes it.
Two axes — commit and continue. Four presets from fully manual to fully autonomous. Per-skill override via /flow-prime.
No containers. Native tools only — git, gh, your linter, your test runner. Every command pre-approved during flows. Worktree isolation protects your team's trunk.
N engineers running N flows on N machines simultaneously. Local state per-machine; shared state through GitHub. "Flow In-Progress" label provides cross-engineer WIP detection.
Three commands drive the workflow. Four phases run themselves.
## What / ## Why / ## Acceptance Criteria issue.
Once /flow-start lands, you're inside the lifecycle. Each phase is its own skill, but you don't type them — Claude auto-chains Code → Review → Complete according to your autonomy settings.
bin/flow ci baseline on the integration branch, dependency upgrade, worktree + PR. ci-fixer sub-agent repairs breakage once.
bin/flow ci gate, /flow-commit per task. 100% coverage enforced.
Every skill has two independent axes you can tune:
Start fully manual. As your comfort grows, dial up autonomy per skill. Go fully autonomous when you trust the workflow.
/flow-prime is the configuration front door. Run it in any Claude Code session — the plugin walks you through a preset picker, writes the result to .flow.json at your project root, and installs the required permissions and bin/* stubs. Re-run it anytime to change presets.
| Preset | What it means |
|---|---|
| Fully autonomous | All skills auto for both axes — zero prompts |
| Fully manual | Every diff reviewed, every phase transition confirmed |
| Recommended | Auto where safe (Review), manual where judgment matters (Code) |
| Customize | Choose per skill and per axis |
/flow-prime is user-only — you type it yourself. The model never runs it on your behalf, because priming mutates project config every engineer on the repo will inherit.
Want help dialing it up? Acme AI Consulting helps small engineering teams adopt FLOW — assessment first, coaching as you ratchet up. Book a consultation →
Every commit and every phase transition is gated. No exceptions, no workarounds.
bin/flow ci is the universal gateMust be green before every commit and every phase transition. Keep guardrails under 2 minutes for tight feedback loops.
Code phase cannot advance to Review without it. No gaps, no exclusions.
Test must fail before implementation is written. Test must pass before commit.
Fix the code, not the linter. No exclusions, no suppression comments.
Blocks compound commands, shell redirection, and other footguns before they execute. Enforced as a Claude Code PreToolUse hook — the model can't reach around it.
Your team's trunk is never touched directly. Multiple features run in parallel without colliding.
Corrections don't evaporate at session end. /flow-note captures them to the flow's state file as they happen, and the session-start hook re-surfaces the capture instruction whenever you correct Claude. Two read-only utilities keep the instruction corpus — CLAUDE.md, project rules, and memory — coherent as it grows.
As CLAUDE.md and project rules accumulate across many features, references go stale, constraints duplicate, and content drifts to the wrong destination. Two read-only utilities audit the corpus between features.
/flow-hygieneAudits the instruction corpus itself — CLAUDE.md, rules, and memory. Catches staleness, duplication, and contradictions. Run weekly or after big refactors.
/flow-doc-syncAudits documentation against code behavior — reports drift between what docs say and what code does. Run when docs feel out of date.
No Claude session needed. flow tui reads state files directly and auto-refreshes every 2 seconds. Phase transitions, task progress, and per-phase token cost appear as they happen.
The three-command workflow handles single features. FLOW adds tools for bigger surfaces and existing backlogs.
The planning skills are role-bound to specialized sub-agents. Each persona has its own scope authority and refuses overreach with a ## SCOPE REFUSAL block naming the next tier. No auto-escalation — the user always directs.
Copy, content, and problem statements. Default voice for /flow-explore. Refuses architectural overreach — escalates to Tech Lead.
Extensions of existing architecture and design patterns. Default voice for /flow-plan. Refuses novel design — escalates to CTO.
Novel, around-the-corner work. Escalation terminus — no scope refusal. Invoked on explicit user request during planning.
Describe a project in plain language and FLOW decomposes it into a fully linked GitHub issue graph — epic, sub-issues, blocked-by dependencies, and phase labels. Every issue is filed work-ready with acceptance criteria, file paths, and scope boundaries from real codebase exploration.
/flow-plan add multi-tenant billing
Triage what's open with /flow-issues and /flow-triage-issue, then feed the decomposed graph into /flow-orchestrate. Each issue runs through all 4 phases autonomously. Check progress — or the final tally — in flow tui's Orchestration tab.
Decomposed, filters out in-progress work
/flow-orchestrate builds the execution queue in dependency order
Optional thread-per-feature notifications give your team passive awareness of feature progress — without any active monitoring.
Each feature gets one Slack thread. Every phase posts a reply, building a narrative from start to merge.
Start, Code, Review, Complete — each phase posts its outcome and timing as a thread reply.
Two plugin config fields. No webhook servers, no bot infrastructure. Uses Slack's chat.postMessage API directly.
One catalog grouped by role. Run /flow-skills in any Claude Code session to see the live version.
| Command | What it does |
|---|---|
/flow-issues | Group open issues by label into four sections (Blocked, Other, Vanilla, Decomposed) with mechanical sort and a copy-pasteable command per row |
/flow-triage-issue | PM-lens triage of a single open issue — verdict in {close, decompose} |
/flow-explore | Open a problem-statement conversation (PM voice); file a vanilla ## What / ## Why / ## Acceptance Criteria issue on signal |
/flow-plan | Decompose a vanilla problem-statement issue into a decomposed issue ready for start, or one child per disconnected DAG component when multi-track applies (Tech Lead voice) |
/flow-orchestrate | Process decomposed issues sequentially overnight via flow-start |
| Command | What it does |
|---|---|
/flow-start | Begin a new feature — worktree, PR, state file, plan extraction from issue body sentinels |
/flow-config | Display the per-skill autonomy configuration from .flow.json |
/flow-skills | Display this catalog grouped by role |
| Command | What it does |
|---|---|
/flow-doc-sync | Full codebase documentation accuracy review — reports drift between code and docs |
/flow-hygiene | Audit instruction corpus health — CLAUDE.md, rules, and memory |
These commands are reserved for direct user invocation — type the slash command yourself. The model never invokes them on your behalf.
| Command | What it does |
|---|---|
/flow-prime | One-time project setup — configure permissions, install bin/* stubs, write the version marker |
/flow-abort | Abort the current feature — close the PR, delete the remote branch, remove the worktree, delete the state file |
/flow-continue | Resume a halted autonomous flow — clears _halt_pending so the next assistant turn proceeds |
/flow-reset | Wipe .flow-states/ on this machine — PRs, worktrees, and branches are NOT touched (require per-flow /flow-abort) |
Four phase skills plus the full planning and health catalog, state file infrastructure, session hooks, and reference documentation — one plugin. Marketplace-distributed; updates ship automatically.
Need a sherpa? Acme AI Consulting runs FLOW-adoption engagements for small engineering teams — assessment first, coaching as you ratchet up. Book a consultation →