FLOW

A user-driven software-engineering pipeline for Claude Code.

FLOW turns a raw idea into merged, verified code through a chain of small, inspectable steps. Every step caches its output to a local .flow-engineering/ directory in your repo, so the next step — and your future self — can pick up exactly where it left off. You drive it by hand, one /flow-* command at a time; nothing fires autonomously except the debugger.

The design goal is context hygiene: each step pays its context cost once and writes a durable artifact, so you can /clear between steps and never carry the whole pipeline in one window.

The pipeline

/flow-init  (once per repo)
   → /flow-idea → /flow-research → [/flow-prototype] → /flow-prd
   → /flow-kanban → /flow-execute → /flow-verify

Skill	What it does	Output
flow-init	Scaffold .flow-engineering/ + project docs. Run once per repo.	PROJECT/REQUIREMENTS/ROADMAP/STATE.md
flow-idea	Grill a raw idea until it's sharp enough to build.	IDEA.md
flow-research	Cache codebase / domain / assumption research.	RESEARCH.md
flow-prototype (optional)	Design the interface two ways before committing to one.	PROTOTYPE.md
flow-prd	Idea + research → a PRD with numbered decisions (D-XX) and tests (T-XX).	PRD.md
flow-kanban	Break the PRD into wave-ordered, independently-executable tickets.	NN-PLAN.md
flow-execute	The Ralph Loop: implement → review → merge every ticket on a feature branch, then hand off.	feature branch
flow-verify	Walk the PRD as UAT; cascade statuses on all-pass.	VERIFICATION.md

Utilities (any time):

• flow-map-codebase — index a codebase into cached docs (STACK, ARCHITECTURE, STRUCTURE, …) so the steps above read context instead of re-exploring.
• flow-state — reconcile STATE.md / ROADMAP.md from disk + git when they drift.
• flow-debug — systematic root-cause debugging (5-whys → original intent → rewrite-not-patch → verify). The one model-invoked skill: it auto-fires on a bug or test failure.
• flow-test-skill — pressure-test a skill edit with subagents (RED → GREEN → REFACTOR) to prove it actually changes agent behavior.

The Ralph Loop

/flow-execute is the engine. For each ticket it runs three subagents:

• ralph-implementer — strict TDD red-green-refactor inside an isolated git worktree, atomic commits.
• ralph-reviewer — re-runs the tests independently and applies a 6-point rubric (tests / acceptance / scope / decisions / quality / consumer trace), returning a structured verdict.
• ralph-reconciler — reconciles coordination state (ticket status, stale locks, merged tickets) between runs.

Tickets run wave-ordered by their blocked_by dependencies, each in its own worktree, so the orchestrator's context stays lean across a long run.

Coordination backends

FLOW stores all pipeline state — the PRD, tickets, and execution-coordination — as files under .flow-engineering/. The persistence substrate is selectable in config.json:

• local (default) — tickets, status, locks, and review verdicts live as local files; zero GitHub dependency. Ends a run on a local feature branch and asks what to do (open a PR, emit a patch, or nothing).
• github — mirrors tickets to GitHub issues/PRs/labels for teams that coordinate there.

Optional: cross-AI second-opinion gate

/flow-execute can run an adversarial second-opinion review with Codex on top of ralph-reviewer's APPROVE verdicts — a different model catches a different class of issue. It's opt-in and degrades gracefully: if the Codex plugin isn't installed, the gate is skipped silently.

Install

Requires Claude Code. The skills also use git, jq, and python3 (for the requirements sync); the github backend additionally needs the gh CLI.

git clone https://github.com/ocdejong/flow-engineering.git
cd flow-engineering
./install.sh

install.sh symlinks each skill into ~/.claude/skills/ and each agent into ~/.claude/agents/, so a later git pull updates them in place. Use ./install.sh --copy to copy instead of symlink, or --force to overwrite existing files (the default backs them up). Restart Claude Code (or start a new session) to load the skills, then run /flow-init in a repo to begin.

Note: the skills reference each other and their shared resources by ~/.claude/skills/... paths, so they expect to live in ~/.claude/skills/ (which is what install.sh sets up). A drop-in plugin-marketplace install isn't wired up yet — see the design note in .claude-plugin/plugin.json.

Credits

• flow-test-skill adapts the subagent skill-testing approach from obra's writing-skills / testing-skills-with-subagents.

License

MIT © 2026 Olivier de Jong