flow

FLOW — Software Development Lifecycle for Claude Code

An opinionated 4-phase development plugin for Claude Code that enforces issue-driven, TDD discipline on every feature. Language-agnostic — every project owns its toolchain via bin/format, bin/lint, bin/build, bin/test stubs that FLOW orchestrates.

Every feature. Same 4 phases. Same order. No shortcuts.

Documentation: benkruger.github.io/flow

---

Why FLOW

Claude Code is powerful, but undisciplined by default. FLOW imposes structure. Not bureaucracy — discipline. DAG decomposition for planning, then TDD execution, then four-agent code review, then a clean merge. Every feature, same order.

---

Four Tenets

Unobtrusive

Zero dependencies — pure Markdown skills with a Rust dispatcher. Prime commits .claude/settings.json and the four bin/* delegation stubs (bin/format, bin/lint, bin/build, bin/test) as project config. Each project owns its own toolchain inside those scripts; FLOW provides only the orchestration layer. .flow.json and .flow-states/ are git-excluded. During active development, a single gitignored JSON state file exists at .flow-states/<branch>/state.json. When the feature completes, that file is deleted too. Three commands to set up. One file while you work. Zero when you're done.

Autonomous or Manual

Every skill has two independent axes — commit (show diffs or auto-commit) and continue (prompt before advancing or auto-advance). Start fully manual. Dial up autonomy per skill as comfort grows. Go fully autonomous when you trust the workflow. See Autonomy below.

Safe for Local Env

No containers. No external dependencies. Native tools only — git, gh, your linter, your test runner. Every command is pre-approved in .claude/settings.json so you never see a permission prompt. A global PreToolUse hook blocks compound commands, shell redirection, and other footguns so the model can't reach around the gate. Worktree isolation protects your team's trunk (main, staging, or whatever your repo's default branch is) — multiple features run in parallel without touching it.

N × N × N Concurrent

N engineers running N flows on N machines simultaneously is the primary use case. Local state (.flow-states/, worktrees) is per-machine; shared state (PRs, issues, labels) is coordinated through GitHub. The "Flow In-Progress" label provides cross-engineer WIP detection so /flow-issues shows which issues are already being worked on. Nothing assumes a single active flow.

---

The Workflow

You type three commands. FLOW handles the rest.

The three commands you type

Step	Command	What you get
1	/flow-explore <topic>	A vanilla ## What / ## Why / ## Acceptance Criteria issue filed on GitHub (PM voice)
2	/flow-plan #<issue> or /flow-plan <topic>	An implementation plan attached to a GitHub issue. #N re-plans the existing issue in place; a bare topic synthesizes ## What / ## Why / ## Acceptance Criteria and files a new decomposed issue (Tech Lead voice; mandatory decompose:decompose pass)
3	/flow-start #<issue>	Worktree, PR, plan extraction from the issue body — and the lifecycle begins

/flow-explore add a per-flow budget cap
/flow-plan #1234
/flow-start #1234

The four phases that run after /flow-start

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 based on your .flow.json autonomy settings. You see them as phase transitions, and as approval prompts at any boundary you've kept continue: manual.

1: Start  →  2: Code  →  3: Review  →  4: Complete

Phase	Command	What happens
1: Start	/flow-start	Acquire start lock, run bin/flow ci baseline on the integration branch, upgrade dependencies, commit, unlock, then create worktree + PR. ci-fixer sub-agent repairs any dependency breakage once; subsequent flows inherit the fix via the CI sentinel. Plan is extracted from the issue body's <!-- FLOW-PLAN-BEGIN -->/<!-- FLOW-PLAN-END --> sentinels.
2: Code	/flow-code	Test-first per task, diff review before bin/flow ci, commit per task, 100% coverage enforced.
3: Review	/flow-review	Four cognitively isolated agents in parallel — reviewer, pre-mortem, adversarial, documentation. Parent triages findings and fixes in-scope issues.
4: Complete	/flow-complete	Merge the PR, close issues referenced in the prompt, remove the worktree, delete the state file.