Blueprints Are Sacred

PRDs, ADRs, requirements, product-owner briefs, and designer mockups are the source of truth for FlowForge work. Once ratified, a blueprint is sacred: implementation follows it. The blueprint never gets retrofitted to match the code.

This is the doctrine behind the whole delivery process. It is a discipline FlowForge holds itself to and reinforces with a skill — not a hard programmatic lock on your files — and it is what makes the docs trail trustworthy: if the trail says a feature was designed a certain way, the implementation converges on that design, not the other way around.

The rule

When a gap is discovered between a ratified blueprint and the implementation:

1. Stop. Do not edit the document to match the code.
2. Surface the gap to the founder. State the document’s claim, state the implementation’s behavior, and cite the evidence on each side.
3. The founder decides which side is correct. The implementation may be wrong (fix the code), or the blueprint may need amending (open a ratification cycle). The decision is the founder’s, not the agent’s.
4. Move to the next gap.

Gap-by-gap, never in a batch

The atomic unit of change is one ratified disposition per gap. When reviewing a blueprint against the implementation:

• Surface one gap at a time.
• Discuss it.
• Decide it.
• Update the document or create an implementation ticket.
• Move to the next gap.

Documents are never batch-edited to “reconcile” with code. Quietly editing a blueprint to match what was built is the exact failure mode this doctrine exists to prevent.

Who can amend a blueprint

A ratified blueprint is amendable only by the founder, or through an explicit ratification cycle the founder authorizes. The doctrine governs ratified blueprints — it does not get in the way of normal authoring:

• Founder direct amendments are authorship by the source-of-truth holder, not a violation.
• Pre-ratified drafts — a PRD in DRAFT status, or an ADR in PROPOSED status — are freely editable as part of the spec-authoring loop. The sacred designation attaches at ratification, not at file creation.
• Lifecycle operations — marking a doc deprecated, archiving it, recording sunset metadata — are documentation lifecycle, not content amendment.
• Mechanical fixups — whitespace, code-fence tags, link rewrites that do not change meaning — are not amendments.

When the founder pivots mid-stream

If the founder changes direction — say, “let’s pivot the auth approach to passwordless” — the blueprint is amended before the code change lands. The amendment becomes the new source of truth, and the pull request that implements the pivot cites it. Code-first, document-later is the anti-pattern this doctrine forbids.

How the gate enforces this

The doctrine is the why; the blueprint gate is the how at dispatch time. The gate makes sure the blueprint artifacts actually exist and are linked in the docs trail before feature code is dispatched — so there is always a ratified design for the implementation to follow.

There is a harder edge, too. Ratifying a blueprint is the structural precondition for creating the feature’s tickets: implementation tickets are emitted from the ratified blueprint (flowforge feature emit), and a guard denies a direct, hand-typed gh issue create for implementation work. So a ticket that skips the blueprint is not merely discouraged — there is no ordinary path to create one. This EMIT ⟺ RATIFIED chokepoint is the enforced complement to the warn-by-default gate; see The Blueprint Gate for both, and the enforcement registry described there for what is enforced by construction versus what remains a discipline.

Note

The gate guides and warns by default — it does not silently block your work. Hard enforcement of the gate is opt-in. The doctrine itself is a discipline, upheld by the team and the workflow; the parts that are hard-enforced by construction (like emitting tickets only from a ratified blueprint) are named as such, and the rest is honestly labeled as discipline rather than dressed up as a programmatic guarantee.