Governed · behaviour-first · scope-frozen
DFlow takes a project from idea to shipped software through controlled phases, freezing scope before implementation and delivering it as a rolling sequence of demoable increments. This overview covers the four adaptation axes, the lifecycle, and exactly how to run it.
The spine
Everything else serves these. They never change with the axes below.
Stories are the unit of delivery: one user-visible behaviour, complete through every layer, demoable on its own. Never layer-only.
You verify by using the running app, not by reading code. Tests encode correctness; humans verify behaviour.
Behaviour verification is necessary but not sufficient, so it is paired with quality + security gates and targeted human review of high-risk diffs.
The in/out boundary locks at Phase 3, before any build, and only re-opens through a governed change exception.
Execution always teaches you something. Corrections apply directly; scope changes route through a 6d exception; ideas get parked. Nothing drifts silently.
AI agents do the work; humans own the decisions, freezes, and trade-offs.
Adapts to you
Declared once in 0b_Product_Brief. They change depth, granularity, and location — never the phase order, the freezes, the vertical-slice rule, or the gates. Toggle them and watch the required set and delivery shape update.
Idea to shipped
A deliberate information-dependency chain. Click a phase. ● marks a freeze.
How to run it
DFlow runs in Claude Code. Plan once, then deliver v1 as a loop of increments. Commands are the skills; the skill is interactive and stops at each freeze for your approval.
Profile, tier, mode and layout are set; features and journeys are mapped; architecture is de-risked with a walking-skeleton spike; then scope freezes and the v1-level definition is written. In incremental mode this ends at "first increment ready" with an increment roadmap; in big-bang it freezes the full story set.
# requirements inline, or run /start-project and answer the prompts
/start-project Build a REST API for team task assignments.
Users: front-end + DevOps. Profile: API. Tier: standard.
Mode: incremental. Layout: mono.
Build the contract-driven UI packet. In incremental mode the design system and index freeze once; per-screen/component/flow contracts freeze per increment.
/ui-contracts
Take the next increment from the roadmap, write its 4b detail and contracts, generate and human-review its vertical-slice stories, then freeze just those.
/plan-increment I1
Implement one frozen story at a time against its packet (not the whole repo). Each story passes tests, CI, and a physical behaviour check, then a defect review, a high-risk-diff security review, and a human-approved PR merge.
/execute-story S01 # implement → In Review /review-story S01 # correctness/quality/tests → Security Review /security-review-story S01 # high-risk diffs → Ready for Human Review # human PR approval + merge to develop → Done
Demonstrate the working increment, capture learnings (apply / 6d / park), refine the backlog and the next increment, then loop to step 3 until every increment ships.
/close-increment I1
/plan-increment I2 # … and so on
# structural check at any phase (tolerates unfilled templates) python3 docs/governance/scripts/validate_project_docs.py --scaffold # only the artefacts due up to phase N python3 docs/governance/scripts/validate_project_docs.py --through-phase 4 # UI contract packet (UI / Hybrid) python3 docs/ui/governance/scripts/validate_ui_contracts.py --ui-root docs/ui # split layout only: freeze-integrity pin (scaffolder vendors it into .dflow/) python3 .dflow/validate_docs_ref.py --impl-dir .
Split layout: planning runs in the docs repo; execution runs in the implementation repo against the commit pinned in .dflow/docs-ref.json, so code is only ever built against frozen docs. See the split-repo explainer.
Stack gates: declare your stack in 2a and the matching stack profile (docs/governance/stacks/{flutter,go,laravel,python,typescript}.md) supplies the architecture, code-quality, design-token, testing, security, and toolchain checks that the git hooks, CI, and the review skills run. Not a separate workflow — configuration the existing gates consume. Each profile ships a ready-to-copy starter CI workflow (docs/governance/stacks/ci/), plus dflow-docs.yml for doc validation and freeze-integrity verify.
Solo posture: for personal projects, declare Governance posture: solo in 0b — lite tier by default, ONE consolidated timestamped approval per freeze gate, and evidence-artefact demos. No gate is removed; posture never changes the phases, freezes, or guards. See guide 36.
Agent cards: the skills load a one-page card per phase (docs/governance/workflow/cards/) — purpose, gate checklist, exact commands — instead of the full specs, escalating to the canonical documents only on gate failure or ambiguity.
Versions: increments are the inner loop; a major version is the outer loop. When all increments ship, /close-version consolidates the carry-forward (parked ideas, deferred features, learnings) into a v-next seed and opens the next version in capture mode. Each version lives in its own folder (docs/outputs/<vN>/) with the kit shared. See the rolling-wave explainer and Version_Lifecycle_Spec.md.
Defect gates before merge
The coding agent, quality reviewer, and security reviewer do bounded work. An orchestrator owns the state transitions; only a human-approved PR can merge the story and close it in Linear.
| State | Trigger | Next action |
|---|---|---|
In Review | Coding agent posts green CI and behaviour evidence | /review-story checks correctness, quality, convention, tests, and scope. |
Changes Requested | Either reviewer returns identified findings | Coding agent fixes on the same story branch in atomic, finding-linked commits. |
Security Review | First review approves | /security-review-story checks the changed high-risk surface. |
Ready for Human Review | Security review passes | Open or update the PR when its head is green; human approves the merge. |
Done | Story branch merges to develop | Post merge evidence and close the Linear tracking mirror. |
Re-review rule. A first-review finding returns directly to the coding agent then the first review. A security finding returns to the coding agent, then through the first review and security review again. The run sequence sets a remediation limit (normally three cycles per gate); a limit breach or scope-boundary change becomes a human-owned Blocked decision, not an endless agent loop.
TDD and branches. Work stays on one story branch until merge. Commit the intended failing test first, then the minimum passing implementation and refactor. A documented red-test commit may exist on the private branch, but review hand-off, PR head, and merge must be green.
Release boundary. The final story has no special authority. Once every milestone story has merged to develop, is Done, and is covered by the increment demo/checkpoint, the orchestrator opens the configured release PR (normally develop to main). Human approval, version tag, release cut, and main-to-develop synchronisation follow; /close-version records the major-version close.
Control
DFlow locks scope once and governs every later change. The delivery mode only sets how often the downstream freezes happen.
End of Phase 3, recorded in 3a. Once, in every mode. The in/out boundary.
End of Phase 5 (UI/Hybrid). Design system once; contracts once (big-bang) or per increment (incremental).
Phase 6: the full story set (big-bang), or per-increment stories with the rest a soft backlog (incremental).
split layout: the impl repo pins the frozen docs commit; a validator refuses unfrozen or drifted packets.
After a freeze: a scope-correction within intent is logged and applied; a scope-expansion needs a 6d change exception with justification, impact, and re-approval.
Machine-enforced. Each approved freeze is registered in a freeze manifest (docs/outputs/.freeze-manifest.json); freeze_guard.py then denies direct edits to frozen artefacts (Claude Code hook) and blocks them at commit time (check-staged, runtime-agnostic, so Codex sessions are covered too). The only way through is an approved 6d recorded with freeze_guard.py except. Tag-backed freezes are also verifiable: freeze_guard.py verify fails on any drift since the freeze tag. See guide 34.
Scope-guarded execution. Every story declares its Allowed Paths; /execute-story activates them via scope_guard.py, and edits outside them are denied (hook) and blocked at commit (check-staged) until the story completes. See guide 35.
No idea lost, no scope drift
There is no separate "future work registry" to maintain — DFlow routes each idea by how it relates to frozen scope. Pick what just came up.
The machinery
Each is a slash command in Claude Code. The increment bookends (/plan-increment, /close-increment) wrap the per-story execution trio; /close-version is the outer-loop bookend at a major-version boundary.
| Skill | Command | What it does |
|---|---|---|
| Start project | /start-project | Orchestrates phases 0–7; mode- and layout-aware. |
| UI contracts | /ui-contracts | Builds and freezes the UI contract packet (UI/Hybrid). |
| Plan increment | /plan-increment | incremental: detail, freeze, and hand off the next increment's stories. |
| Execute story | /execute-story | Implements one frozen story with scope enforcement and CI gates. |
| Review story | /review-story | Defect gate: correctness, quality, conventions, tests. |
| Security review | /security-review-story | Targeted review of the story's high-risk diffs. |
| Close increment | /close-increment | incremental: demo + checkpoint, refine the backlog, loop. |
| Close version | /close-version | major boundary: accept the release, consolidate the v-next seed, freeze/tag, open the next version. |
Tracking (in 0b: markdown-ledger default / linear / none). The markdown story stays canonical; tracking is a mirror and never blocks. The default is repo-native and offline: one append-only issue ledger per story (stories/<ID>.issue.md), every transition and piece of evidence appended (Backlog → In Progress → In Review → Security Review → Ready for Human Review → Done, with Done only after the human-approved merge), last entry = current status, and append-only machine-enforced by the freeze guard (history can only be extended, never rewritten). See guide 38. linear mirrors the same states and evidence to one Linear issue per story (guide 33); none keeps just the 6b table.