Blueprint Writing

Blueprint Writing

Core Principle: Blueprints Describe WHAT, Not HOW

Blueprints are implementation-agnostic. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.

This is the fundamental distinction in Blueprint:

• Blueprints = WHAT must be true (framework-agnostic, durable, portable)
• Plans = HOW to build it (framework-specific, derived from blueprints)
• Code = the implementation (generated from plans, validated against blueprints)

Why Implementation-Agnostic?

When blueprints avoid prescribing HOW, they become:

• Portable — the same blueprints can drive implementations in different frameworks
• Durable — blueprints survive technology migrations
• Testable — acceptance criteria are about behavior, not implementation details
• Reusable — the same blueprints work for greenfield, rewrites, and cross-framework evaluation

Bad blueprint requirement: "Use React useState hook to manage form state" Good blueprint requirement: "Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values."

Every Requirement Needs Testable Acceptance Criteria

This is the single most important rule in Blueprint writing. If an agent cannot automatically validate a requirement, that requirement will not be met.

The Validation-First Rule

Every requirement must answer: "How would an automated test verify this?"

Acceptance Criteria Format

Each criterion should be:

• Observable — can be checked by reading output, UI state, or logs
• Deterministic — same input always produces same pass/fail result
• Automatable — an agent can write a test that checks this
• Independent — does not depend on subjective judgment

**Acceptance Criteria:**
- [ ] {Action} results in {observable outcome}
- [ ] Given {precondition}, when {action}, then {result}
- [ ] {Metric} meets {threshold} under {conditions}

Hierarchical Structure with Index

Blueprints must be organized as a hierarchy — one index file linking to domain-specific sub-blueprints. This enables progressive disclosure: agents read the index first, then only the sub-blueprints relevant to their task.

The Blueprint Index Pattern

Create a blueprint-overview.md as the entry point:

# Blueprint Overview

## Domains

| Domain | Blueprint File | Summary |
|--------|-----------|---------|
| Authentication | blueprint-auth.md | User registration, login, session management, OAuth |
| Data Models | blueprint-data-models.md | Core entities, relationships, validation rules |
| API | blueprint-api.md | REST endpoints, request/response formats, error handling |
| UI Components | blueprint-ui-components.md | Shared components, accessibility, responsive behavior |
| Notifications | blueprint-notifications.md | Email, push, in-app notification delivery |

## Cross-Cutting Concerns
- Security requirements: see blueprint-auth.md R3, blueprint-api.md R7
- Performance budgets: see blueprint-api.md R12, blueprint-ui-components.md R5
- Accessibility: see blueprint-ui-components.md R8-R10

Why Hierarchical?

1. Context window efficiency — agents load only the domains they need
2. Parallel work — different agents can own different spec domains
3. Review efficiency — humans can review domain-by-domain
4. Cross-referencing — domains link to each other explicitly

Cross-Referencing Between Blueprints

Related blueprints must link to each other. Cross-references prevent requirements from being lost at domain boundaries.

Cross-Reference Patterns

## Cross-References
- **Depends on:** blueprint-auth.md R1 (session tokens required for API access)
- **Depended on by:** blueprint-notifications.md R4 (uses user preferences from this blueprint)
- **Related:** blueprint-ui-components.md R6 (error display components used by this domain)

When to Cross-Reference

• When one domain's requirement depends on another domain's output
• When shared entities are defined in one blueprint but used in many
• When validation criteria span multiple domains
• When out-of-scope items are in-scope for another blueprint

Full Blueprint Format Template

Use this template for every domain blueprint:

# Blueprint: {Domain Name}

## Scope
{One paragraph describing what this spec covers and its boundaries.}

## Requirements

### R1: {Requirement Name}
**Description:** {What must be true — stated in terms of behavior, not implementation.}
**Acceptance Criteria:**
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] {Testable criterion 3}
**Dependencies:** {Other specs/requirements this depends on, or "None"}

### R2: {Requirement Name}
**Description:** {What must be true}
**Acceptance Criteria:**
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
**Dependencies:** {Dependencies}

### R3: ...

## Out of Scope
{Explicit list of things this blueprint does NOT cover. This is critical — it prevents
agents from over-building and clarifies domain boundaries.}
- {Thing explicitly excluded and why}
- {Another exclusion}

## Cross-References
- See also: blueprint-{related-domain}.md — {why it is related}
- Depends on: blueprint-{dependency}.md R{N} — {what is needed}
- Depended on by: blueprint-{dependent}.md R{N} — {what depends on this}

Template Rules

1. Number requirements sequentially (R1, R2, R3...) — agents reference them by ID
2. Every requirement gets acceptance criteria — no exceptions
3. Out of Scope is mandatory — explicit exclusions prevent scope creep
4. Cross-References section is mandatory — even if it says "None"
5. Scope section is one paragraph — concise boundary description

Greenfield Pattern: Reference Material → Blueprints

When building from scratch, you start with reference materials and derive blueprints from them.

Flow

context/refs/              context/blueprints/
├── prd.md          →      ├── blueprint-overview.md
├── design-doc.md   →      ├── blueprint-auth.md
├── api-draft.md    →      ├── blueprint-api.md
└── research/       →      ├── blueprint-data-models.md
    └── ...         →      └── blueprint-ui.md

Process

1. Place all reference materials in context/refs/
2. Run blueprint generation — agent reads all refs, decomposes into domains
3. Agent produces:
   • blueprint-overview.md — index with domain summaries
   • One blueprint-{domain}.md per identified domain
   • Cross-references between related domains
4. Human reviews blueprints for completeness and correctness
5. Iterate — refine blueprints based on review feedback

Greenfield Prompt Pattern

The first prompt in a greenfield pipeline (typically 001-generate-blueprints-from-refs.md) should:

• Read all files in context/refs/
• Decompose reference material into domains
• Generate blueprints following the template above
• Create blueprint-overview.md as the index
• Cross-reference related blueprints

Rewrite Pattern: Old Code → Reference Docs → Blueprints

When rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code — you always extract blueprints first.

Flow

Existing codebase          context/refs/              context/blueprints/
├── src/            →      ├── ref-apis.md      →     ├── blueprint-overview.md
├── tests/          →      ├── ref-data-models.md →   ├── blueprint-auth.md
└── docs/           →      ├── ref-ui-components.md →  ├── blueprint-api.md
                           └── ref-architecture.md →   └── blueprint-data.md

Process

1. Agent explores the existing codebase and generates reference documents
2. Reference docs capture the current system's behavior, APIs, data models, and UI patterns
3. Agent generates blueprints from reference docs — implementation-agnostic requirements
4. Validate blueprints against existing code — verify acceptance criteria match current behavior
5. Proceed with normal DABI — blueprints drive the new implementation

Rewrite Prompt Pattern

Rewrites typically use more prompts because of the reverse-engineering step:

• 001: Generate reference materials from old code
• 002: Generate blueprints from references + feature scope
• 003: Validate blueprints against existing codebase
• 004+: Plans and implementation

The key difference from greenfield: step 003 validates that your blueprints actually describe what the old system does, before you start building the new one.

Blueprint Compaction

When implementation tracking or blueprint files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context.

When to Compact

• Implementation tracking file exceeds 500 lines
• Blueprint file has many resolved/completed requirements mixed with active ones
• Agent is spending too much context window on historical information

How to Compact

1. Identify resolved content: completed tasks, resolved issues, archived dead ends
2. Archive removed content to a separate file (e.g., impl/archive/impl-domain-v1.md)
3. Preserve in the compacted file:
   • All active/in-progress tasks
   • All open issues
   • Recent dead ends (last 2-3 sessions)
   • Current test health status
   • Active cross-references
4. Target: under 500 lines in the active file

Compaction Rule

Never delete information — move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations.

Gap Analysis

Gap analysis compares what was built against what was intended, identifying where blueprints, plans, or validation fell short.

How to Perform Gap Analysis

1. Read blueprints (intended behavior) and implementation tracking (what was built)
2. For each blueprint requirement, check if acceptance criteria are satisfied
3. Classify each requirement:

4. Report gaps with: which blueprint, which criterion, what is missing
5. Feed gaps into revision — update blueprints if needed, then re-implement

Gap Analysis as Feedback

Gap analysis is not a one-time activity. Run it:

• After each implementation iteration
• Before starting a new session (to prioritize work)
• When convergence stalls (to identify what is blocking progress)