Blueprints

Blueprints are visual and structural design artifacts linked to specifications. Architecture diagrams, state machines, data flows, 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 an epic gives every worker in that epic a shared mental model of the interaction flow. An ERD linked to the database epic 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 10 blueprint types. Each serves a different purpose and maps to a different stage of design thinking.

Architecture

Format: Mermaid diagram When to use: When the spec involves multiple services, modules, or layers that interact. The architecture blueprint shows boundaries, data flow 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.

Data Flow

Format: Mermaid diagram When to use: When data transforms as it moves through the system. Request processing pipelines, ETL flows, event propagation chains. Shows what enters, what transforms, what exits.

Use when the path matters more than the structure. Architecture shows components. Data flow shows what happens between them.

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.

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 the ticket’s parent epic. 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.

💡 Link blueprints to epics, not individual tickets. Every ticket in the epic inherits the blueprint context. This is more efficient than linking the same diagram to 5 tickets separately, and it ensures all workers in the same epic share the same visual context.

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.

You can disable blueprint coverage checking in your project’s Quality Standards configuration:


specforge configure planningConfig.requireBlueprintCoverage false

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.