A Claude Code plugin that walks work through spec, plan, implementation and fix, checking the artifact at each boundary. Most of the checking is mechanical: 27 validators that read a file and either pass or name a line. Five judged dimensions survive where no predicate decides the question, and each one says so in its own file.
Most tools of this kind assert that their review gates work. flow doesn't, because nobody has shown that they do.
Every requirement in the design either cites evidence or carries the tag
unsupported+instrumented, naming the ledger field that will decide its fate. A rule (FR-49)
computes, over the trailing 20 executions of a gate, whether a judged dimension found anything its
validators missed. If it found nothing, the report recommends deleting it. The script prints; you
execute.
The predecessor design had eight review dimensions and no validators. It was scrapped after a gap analysis found it took its authority from the system it was built to judge. What replaced it has 27 mechanical checks and five judged ones, and the five carry their own ceilings in writing.
Read this before adopting it.
Whether running the pipeline beats not running it has never been measured. No arm compares flow against a no-flow baseline. FR-49 prunes individual dimensions; it says nothing about the pipeline as a whole.
LLM-reviewer efficacy is unestablished. Classical inspection evidence comes from human reviewers in the 1970s-90s and does not demonstrably transfer; Tufano et al. (ICSE 2025) found no improvement in high-severity detection, no time saved, and no gain in reviewer confidence. The plugin embeds that statement in every specification it touches, hash-checked, so its own output contradicts any claim to the contrary.
An APPROVE verdict records that the validators passed and the dimensions were scored. It records nothing about residual defects. The measured ceiling for requirements inspection is 78% average defect removal, and only inspection combined with static analysis and multi-stage testing crosses 95%.
flow does not claim to find defects, improve code, or prevent escapes. It runs named checks and records what happened.
/plugin marketplace add davdittrich/flow
/plugin install flow@flow
/reload-plugins
Note the flow@flow form: the plugin and the marketplace share a name.
Start a run with the flow skill. It detects the repository regime, then sequences the stages and
evaluates each gate. The three stage skills own their own stages and load on demand.
| Stage | Owner | On pass | On block |
|---|---|---|---|
| 1 regime detection | flow |
2 | — |
| 2 spec write | flow-spec |
3 | — |
| 3 spec gate | flow |
4 | back to 2, same artifact revised |
| 4 plan write | flow-plan |
5 | — |
| 5 plan gate | flow |
6 | back to 4 |
| 6 implementation, one ticket | flow-exec |
7 | — |
| 7 implementation gate | flow |
6 for the next ticket | 8 |
| 8 bounded fix loop | flow-exec |
fix gate, then 6 | epic BLOCKED, control returns to you |
Stage 1 decides how hard to gate. A DESCRIPTION file within two levels means research; ten or
more CI workflows, fifty or more tags, or your own shipped repository means tooling. Anything else
is ambiguous, which asks you once and caches the answer, including a refusal. Until an answer
exists the regime is ambiguous and gates run at research depth, since the rule exists to avoid
under-gating work that is expensive to undo.
Two agents do the work the skills dispatch. flow-reviewer runs the judged dimensions and files
findings against a closed schema; it decides nothing else. flow-implementer changes only the
paths its ticket declares and captures the evidence the implementation gate reads. Neither
certifies itself.
Run the validator suite at any time:
python3 validators/runner.py
It refuses any validator lacking a fixture it must reject. A validator nobody has shown to fail is untested, and the runner says so by name.
Python 3 and its standard library. Nothing else is imported anywhere in the plugin.
git for the validators that read commit topology. Beads for tickets. agy is optional: the
cross-model review and grounded search degrade to a recorded skip when it is absent, quota-exhausted
or timing out, and a skip never blocks a gate.
Model ids in agent frontmatter are checked by nothing. claude plugin validate ignores them, and
the validator that reads dispatch records only checks that a model was named, not that the name
resolves. A wrong id fails mid-run, at dispatch.
claude plugin validate is wrong by default in two ways. Without --strict, a missing description
is a warning and the check passes. With .claude-plugin/marketplace.json present, it validates the
marketplace manifest alone and never opens the skills or agents, printing a tick either way. To
check frontmatter, point it at a copy with that file removed.
skills/ flow (controller), flow-spec, flow-plan, flow-exec
agents/ flow-reviewer, flow-implementer
rubrics/ the five judged dimensions, each with its scope, ceiling and validator boundary
validators/ 27 checks, their fixtures, the contract and the suite runner
schemas/ verdict and fix-record
templates/ spec outline, ticket, gate document, standing sections
ledger.py the instrumentation record, one per gate execution
pruning.md FR-49 in full: why 20, who executes a deletion
agy.py cross-model review and grounded search
Author: Dennis Alexis Valin Dittrich. The design specification and the research behind it live in a separate repository; this one holds the plugin.