Hand Claude a fuzzy issue and it will start editing files in the first thirty seconds and often that’s fine. On anything non-trivial it means the plan gets invented on the fly, half-written into the diff, and you find out what Claude thought the task was only when you read the PR. MoFlo’s new --sdd flag puts a spec and a reviewed plan in front of the code, and makes skipping them impossible. You can add it as an argument, or as the default approach for MoFlo.

• GitHub: github.com/eric-cielo/moflo
• npm: npmjs.com/package/moflo — npm install --save-dev moflo

What –sdd does

Add --sdd (or -sd) to a /flo run and the work goes through four stages instead of one:

spec  →  plan  →  implement  →  verify

The spec is the what: problem, goal, scope, and a list of acceptance criteria. The plan is the how: the steps, and for each acceptance criterion, how it gets verified. Both are plain Markdown files, one directory per unit of work. Only after the plan is reviewed does Claude touch your source — and at the end, verify checks the finished change against the criteria the spec set out.

None of that is novel on its own; you could ask Claude to “write a spec first” in any prompt. The difference is that --sdd is enforced, not suggested.

The gate is the whole point

When a run is armed for SDD, a check-before-implement gate blocks every source Write and Edit until a spec exists for the active unit of work and its plan is marked reviewed. There’s no “I’ll skip the ceremony this once” — the tooling won’t let the edit through. That’s deliberate. A spec/plan step that Claude can quietly bypass is a spec/plan step that gets bypassed exactly when the task is hard enough to need it.

There are two review checkpoints inside the cycle:

• A spec must be reviewed before its plan can be written.
• A plan must be reviewed before implementation can start.

Who does the reviewing depends on one setting, sdd.human_checkpoints (default false):

human_checkpoints	Behavior at each checkpoint
false (default)	Autonomous. Claude writes the spec, sanity-checks it, marks it reviewed, and continues — no stop.
true	Claude presents the spec (then the plan) to you and waits for your approval before advancing.

So even in fully-autonomous mode the artifacts still exist and still gate the code — you just aren’t pulled into the loop for each one. Turn checkpoints on when you want eyes on the plan before a line is written.

Where the artifacts live

Specs and plans default to .moflo/specs/<slug>/, which flo init gitignores. They stay local and don’t clutter your history — but by default the spec and plan are appended to the PR body, so the reasoning is still reviewable in the PR without living in the tree.

If you’d rather source-control them, point sdd.specs_dir at a tracked path:

sdd.specs_dir	Committed?	Use when
.moflo/specs (default)	No — gitignored	You want the workflow, not spec files in history
docs/specs, .specs, …	Yes	You want specs reviewed in the PR alongside the code

Create and mutate the artifacts through the flo sdd CLI (flo sdd spec, review, plan, check, list, status) — never hand-write the paths. The CLI builds every path with path.join so it works identically on Linux, macOS, and Windows, and the session-start indexer honors your specs_dir when it loads prior specs into memory.

Two ways to turn it on

--sdd is opt-in. Enable it per run, or make it the default for the project.

Per run — pass the flag:

/flo 1269 --sdd        # or the short form:
/flo 1269 -sd

Project-wide — set it in moflo.yaml:

sdd:
  default: false          # true → every /flo run uses the SDD cycle unless --no-sdd
  human_checkpoints: false # true → pause for your approval at each review checkpoint
  # specs_dir: docs/specs  # optional: a tracked path makes specs reviewable in the PR

With sdd.default: true, every /flo run goes through the cycle; drop --no-sdd on a one-off run to escape it. The flag and the YAML default compose the obvious way — the per-run flag wins.

SDD is also orthogonal to everything else on /flo. It doesn’t care about execution mode or worktrees, so --sdd -s -wt 42 runs the full cycle in a swarm inside a worktree.

Verify-before-done, which you get either way

The verify stage is separable from the spec/plan front half, and unlike --sdd it’s on by default. On a normal run, gh pr create is blocked until the change has actually been verified end-to-end since the last edit. --sdd always implies it; a plain run does it anyway.

Verification runs through the /verify skill: it finds the acceptance criteria (from the plan, or the ticket if there’s no plan), reuses the test run you already did rather than repeating it, maps each criterion to evidence, runs only the checks that aren’t covered yet, and returns a per-criterion PASS/FAIL. Editing source after verifying invalidates it — you re-verify. To skip it for a single run, pass --no-verify; to turn it off for a project, set gates.verify_before_done: false. Docs-only diffs are exempt, so a pure-docs PR never gets blocked.

gates:
  verify_before_done: true   # on by default; --no-verify skips one run

Starting from a fuzzy idea

If the unit of work is still vague enough that you can’t write acceptance criteria, start with /commune. It runs a short back-and-forth to pin the thing down, then hands the result straight into the spec (flo sdd spec "<title>" --from -). It’s the front door to the same spine — you just arrive at the spec with the ambiguity already resolved.

Checking it’s wired up

Run /healer (or /eldar) and look at the SDD + Verify Wiring check. It reports whether the gate cases and hooks are present and which toggles are on, so you can confirm the enforcement is actually live rather than assuming the YAML took effect.

When to reach for it

Not every task earns a spec. A typo fix or a one-line guard doesn’t need a ceremony, and forcing one is just friction. Reach for --sdd when the work is big enough or fuzzy enough that you’d want to agree on what before anyone argues about how — a new subsystem, a change with real acceptance criteria, anything where “Claude built the wrong thing, correctly” is a failure mode you’ve hit before. For everything else, leave it off and let verify-before-done catch the regressions on its own.

MoFlo is MIT-licensed and open to contributions. If you try --sdd and something’s rough, open an issue — I read all of them.

• GitHub: github.com/eric-cielo/moflo
• npm: npmjs.com/package/moflo — npm install --save-dev moflo