FFFlow — Discipline you can turn up

Born from friction

FFFlow didn't start as a theory. It started as a list of things that kept going wrong.

You've felt these if you've done real work with an AI coding agent. None of them are exotic — they're the daily texture of building software with a capable-but-forgetful collaborator.

plan modeYou ask for a plan and it barrels into implementation instead.
mystery PRsA long unattended run opens five pull requests and you have no idea what any of them touched.
"should work"Code ships that was never actually run — "it should work" in place of "I ran it and watched it work."
/clearThe plan you spent an hour on evaporates the moment you clear the session.
driftThe spec said one thing; the code drifted to another; nobody noticed for three months.
rotCLAUDE.md rots. Tests pass but describe a system that no longer exists.

FFFlow is the accumulated answer to every one of them — encoded as skills you invoke, not advice you're supposed to remember. Every design decision traces back to a specific moment where something broke. That's the whole pedigree. It's not aspirational. It's scar tissue.

What we believe

The principles under the dial.

These hold at every level. Only their strictness scales.

Specs and tests move together.

A spec with no test is a wish. A test with no spec is a black box — it tells you that something must be true without telling you why. When behavior changes, the spec changes in the same pull request as the code. Not later. Not in a follow-up ticket. Together, or it didn't happen.

Three artifacts. Three roles. Three places.

The spec is present tense and evergreen — the contract, in your codebase. The plan is future tense and transient — the route for one change, in scratch space. The issues are imperative — the chess moves, in your tracker. Keep them straight and the whole process gets calm.

Convention over configuration.

Traceability shouldn't require a database or a linking tool. If a file is in the right place with the right name, it's traced. No SaaS, no external index — everything that matters lives in version control, where it can be reviewed, diffed, and blamed like any other code.

Build on what already works.

FFFlow is not a test framework and doesn't want to be one. It orchestrates the tools you already trust — pytest, Vitest, JUnit, cargo, Hypothesis — and audits their output. Standard Gherkin, standard runners. Expressiveness comes from how you use ordinary tools, not a proprietary layer on top.

The view is a domain too.

Hexagonal keeps your backend honest; FFFlow rotates that rule onto the frontend. Your components are the view's domain — pure, presentational, tested in isolation from data and routing. Decompose, story, test, then integrate. A component that reaches into your API layer is a database connection leaking into a domain entity. Forbidden.

Everything lives in the repo.

No external tool you have to keep in sync. No dashboard that's the real source of truth while the code lies. Specs, tests, config, audit state — all version-controlled, all reviewable in a pull request, all survives a fresh checkout. If it matters, it's in the repo.

How the work actually flows

Philosophy is cheap. Here's the lifecycle you run.

The whole loop, as real invocations. Every skill is namespaced under /fff: once installed.

Plan

/fff:plan-chat walks the design and refuses to seal with any open question still unresolved. /fff:plan-breakdown cuts it into 3–8 independently shippable chess moves. /fff:plan-capture writes them to GitHub, Linear, Jira, or plain markdown.

Work

/fff:work-issue executes one chess move end to end: read the spec, write the failing test, make it pass, refactor under green, update the spec in the same PR, run the gates, open the pull request. /fff:work-fanout runs several in parallel across isolated worktrees.

Audit

/fff:audit checks that specs, CLAUDE.md, tests, and architecture still match reality. /fff:audit --plan turns the drift it finds back into a plan — and the loop closes.

It won't quietly ship untested code.

A non-trivial PR either passed a local smoke test or says in its own body why it couldn't run locally. No more "should work."

It won't run away.

After every couple of PRs in an unattended session, it stops and shows you what it did before continuing. No more waking up to five mystery PRs.

The summit

Total specification.

Everything above is reachable without writing a line of Gherkin. But the dial goes somewhere — and it's worth seeing the top.

At L3, FFFlow delivers what it was originally built for: 100% bidirectional traceability between requirements, tests, and source code. Every behavior specified. Every specification tested. Every test traceable to a requirement by ID.

Standard Gherkin 6No dialects. The Rule: block as the unit of specification, mapping each named business rule to the scenarios that prove it.
Requirement IDsThreading from a scenario through the test into the coverage report — so "is this requirement actually tested?" is a query, not a hope.
Property testsFor the rules that must hold across all inputs, not just the handful you thought to write down.
Mutation testsTo verify your tests would actually catch a regression — a green suite that survives a broken implementation was never protecting you.
Four gatesStructure, correctness, coverage, maintainability — any one slips, the merge blocks.

FFFlow's rigor isn't invented from scratch. It stands on a lineage of formal-methods and contract-design work: Eiffel's named assertions, Dafny's pre/postconditions, Alloy's specification classes, EARS's structured requirements, Cockburn's ports-and-adapters, Evans's bounded contexts. FFFlow's contribution is making that lineage practical — reachable by turning a dial, one honest increment at a time, instead of demanded all at once on day one.

Read the full methodology in the docs →

What FFFlow is not

A methodology that claims to do everything does nothing.

Not a test framework. It doesn't run tests. pytest, Vitest, JUnit, cargo do that. FFFlow orchestrates and audits them.
Not a lock-in. Not to a stack — Python, TypeScript, Java, Rust ship today; new ones are cartridges. Not to a tracker — GitHub, Linear, Jira, markdown all first-class. Not to a level — L0 is a valid forever-state.
Not a replacement for judgment. It won't force L3 on a shell script. It won't invent requirements you didn't state. The dial is yours to turn.
Not a custom language. Standard Gherkin. Standard tools. No proprietary syntax to teach the next person who joins.
Not magic. It's scar tissue, systematized. That's the honest pitch — and it's a better one.

Get started

A single plugin. Change nothing about how you work today.

Install it and every skill is namespaced under /fff:. Turn the dial when you're ready.

claude code

> /plugin marketplace add bryonjacob/ffflow-plugin
> /plugin install fff@ffflow

# then, on any project:
> /fff:adopt-ffflow
  detects greenfield vs. brownfield, sets your level
  and stack, and hands off to planning.

Start where you are. Turn it up when the project earns it.