Blueprints

Blueprints are visual and structural design artifacts linked to specifications. Architecture diagrams, state machines, sequence diagrams, API contracts, ADRs — anything that helps agents understand intent beyond what ticket descriptions can convey.

What Is a Blueprint?

A blueprint captures design decisions that don’t fit in ticket descriptions. When a ticket says “Build the login endpoint,” it tells the agent what to build. A blueprint showing the authentication request flow tells the agent how the pieces connect — where the request enters, what validates it, where tokens are generated, how errors propagate.

Agents read blueprints during implementation. A sequence diagram linked to the tickets that implement an interaction gives every worker on them a shared mental model of the flow. An ERD given spec-wide coverage ensures every agent that creates a migration or query understands the schema relationships.

Blueprints are optional. A small spec with 4 tickets doesn’t need one. A spec with 50 tickets across 8 epics needs several — the complexity demands shared visual context that text alone can’t provide.

Blueprint Types

SpecForge supports 14 blueprint types. Each serves a different purpose and maps to a different stage of design thinking.

Fourteen blueprint types: Flowchart, Architecture, State Machine, Sequence, ERD, Mockup, ADR, Component, Deployment, API Contract, Algorithm, Protocol, Glossary, Design System

Architecture

Format: Mermaid diagram When to use: When the spec involves multiple services, modules, or layers that interact. The architecture blueprint shows boundaries, how data moves between components, and where each epic’s work fits in the system.

Use when the agent needs to know where its code lives in the bigger picture. If your spec touches both the API gateway and the auth service, an architecture diagram prevents the agent from building the auth logic in the wrong layer.

Flowchart

Format: Mermaid diagram When to use: When a process has branches, decisions, and outcomes. Onboarding flows, validation pipelines, request-processing paths, decision trees — anything where the path forks based on conditions.

Use when the agent needs to implement branching logic correctly. A flowchart makes every decision point and its outcomes explicit, so agents don’t miss an edge case or invert a condition.

State Machine

Format: Mermaid diagram When to use: When an entity has a lifecycle with defined states and transitions. User accounts (active, suspended, deleted), orders (pending, paid, shipped, delivered), specifications themselves.

Use when the agent needs to implement transition logic. A state machine blueprint directly translates to code — each transition becomes a method, each state becomes a check. Without it, agents invent their own state logic, which rarely matches what you had in mind.

Sequence

Format: Mermaid diagram When to use: When multiple actors interact in a specific order. API call flows, authentication handshakes, webhook processing, multi-step user journeys.

Use when timing and order of interactions matter. The sequence diagram shows who calls whom, in what order, and what responses flow back. This is especially valuable for tickets that implement middleware or orchestration logic.

ERD (Entity Relationship Diagram)

Format: Mermaid diagram When to use: When the spec involves database design. Tables, relationships, cardinality, key fields. Any spec that creates or modifies data models benefits from an ERD.

Use when multiple tickets create or modify tables. Without an ERD, Agent A creates a users table and Agent B creates a sessions table with a slightly different foreign key assumption. The ERD is the single source of truth for schema design.

Mockup

Format: Image or text description When to use: When the spec has UI components. Wireframes, layout descriptions, component hierarchies. Doesn’t need to be pixel-perfect — even a text description of “header with logo left, nav right, hero section below” gives agents layout intent.

Use when “build a dashboard” isn’t specific enough. Agents interpret UI descriptions liberally. A mockup constrains interpretation to what you actually want.

ADR (Architecture Decision Record)

Format: Markdown When to use: When a non-obvious technical decision was made and agents need to understand why. “We chose JWT over session cookies because the API serves both web and mobile clients.” “We use event sourcing for the order system because we need full audit history.”

Use when the decision would seem wrong without context. Agents optimize for common patterns. If your spec deliberately deviates from the common pattern, an ADR prevents the agent from “fixing” your decision back to the default.

Component

Format: Mermaid diagram When to use: When the spec involves a modular system where components have clear interfaces. Plugin architectures, middleware chains, service registries.

Use when agents need to understand the interface contract between components. Each component’s inputs, outputs, and responsibilities should be clear before implementation starts.

Deployment

Format: Mermaid diagram When to use: When the spec includes infrastructure or deployment concerns. Container topology, service mesh layout, CI/CD pipeline stages.

Use when tickets involve infrastructure-as-code or deployment configuration. Without it, agents make assumptions about the runtime environment that may not match your actual setup.

API Contract

Format: OpenAPI spec or text description When to use: When the spec defines APIs that other systems (or other tickets) will consume. Request/response shapes, error formats, authentication requirements, versioning.

Use when multiple tickets implement different sides of the same API. The contract ensures the endpoint ticket and the client ticket agree on the shape. This is the single most important blueprint type for avoiding integration bugs.

Algorithm

Format: Mermaid diagram or pseudocode When to use: When a ticket implements a non-trivial computation — ranking, scheduling, deduplication, a scoring formula. The blueprint pins the exact steps, inputs, and edge cases.

Use when the correctness of a computation matters more than its structure. Agents left to infer an algorithm from a one-line description often miss an edge case or reorder steps in a way that changes the result.

Protocol

Format: Mermaid diagram or text description When to use: When components communicate over a defined protocol — message formats, handshakes, retry and acknowledgement rules, ordering guarantees. Common for queue consumers, real-time channels, and inter-service messaging.

Use when the wire contract between parties must be exact. A protocol blueprint keeps the producer ticket and the consumer ticket agreeing on message shapes and sequencing.

Glossary

Format: Markdown When to use: When the domain has terms that agents could interpret inconsistently. A glossary pins the vocabulary — what “account” versus “workspace” means, what a “session” is — so every worker uses the same names.

Use when domain language is ambiguous and consistency across tickets matters. Without it, one agent’s Account is another agent’s Workspace, and the integration seams don’t line up.

Design System

Format: Markdown or image When to use: When UI work must follow shared tokens and components — colors, spacing, typography, button and form variants. The design-system blueprint keeps every UI ticket visually consistent.

Use when multiple tickets build UI that must look like one product. It gives every UI agent the same tokens to reach for instead of inventing a slightly different shade of blue.

How Blueprints Affect Implementation

Blueprints aren’t just documentation — they’re part of the agent’s implementation context.

When a work session starts for a ticket, the agent receives the ticket’s own context (steps, acceptance criteria, file expectations) plus any blueprints linked to that ticket, plus spec-wide blueprints (coverageType: all). This means:

An agent implementing a database migration sees the ERD
An agent building an endpoint sees the sequence diagram and API contract
An agent writing a state transition sees the state machine

The agent uses these as reference during implementation. A sequence diagram doesn’t replace ticket steps — it supplements them with the visual context that steps can’t convey.

💡 Give a blueprint spec-wide coverage (coverageType: all) when every ticket benefits — an architecture diagram or ERD, say — instead of attaching it ticket by ticket. When a blueprint is only relevant to a handful of tickets, use link_blueprint_to_tickets to attach it to exactly those. Blueprints belong to the specification; they attach to the whole spec or to specific tickets — nothing in between.

Blueprint context injection: linked and spec-wide blueprints flow into the ticket work session alongside ticket data

Blueprint Coverage

The Planning Review optionally checks blueprint coverage — a minimum ratio of blueprints to epics. The default is 1:2 (one blueprint for every two epics).

Why does this exist? Because the correlation between blueprint presence and implementation quality is strong. Specs with blueprints produce fewer review failures, fewer dependency conflicts, and fewer cases where agents “interpreted the intent differently.”

Coverage isn’t about hitting a number. It’s about asking: “Does every epic have enough visual context for agents to implement correctly?” Small epics with 2-3 straightforward tickets might not need a blueprint. Large epics with cross-cutting concerns almost certainly do.

Blueprint coverage is a cross-validation check during planning, not a configure key — you adjust it in your project’s Quality Standards configuration (dashboard).

Practical Patterns

Start with architecture + ERD. These two cover the most ground. Architecture shows where things live. ERD shows what the data looks like. Together, they give agents 80% of the structural context they need.

Add sequence diagrams for integration epics. Any epic where multiple components interact benefits from a sequence diagram. Auth flows, payment processing, webhook handling — these are where agents most often build pieces that don’t fit together.

Use ADRs for non-obvious decisions. If you’re choosing Drizzle over Prisma, or event sourcing over CRUD, or WebSockets over polling — write a one-paragraph ADR. Agents default to the popular choice. If yours is deliberately different, tell them why.

Mockups for any UI work. Even rough ones. “Build a settings page” without a mockup produces wildly different results across agents. “Build a settings page with sidebar navigation, grouped by category, toggle switches for boolean options” with a wireframe produces consistent results.