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)

Integration with Other Skills

Collaborative Design in the Draft Phase

The Draft phase (/bp:draft) now embeds brainstorming principles directly. When running in interactive mode (no arguments), the drafter follows a collaborative design process before generating any files:

1. Explore project context — check existing files, docs, commits before asking questions
2. Ask clarifying questions one at a time — understand purpose, constraints, success criteria
3. Propose 2-3 domain decomposition approaches — with tradeoffs and a recommendation
4. Present the design incrementally — section by section, get approval per domain
5. Generate blueprints only after design approval — formalize with acceptance criteria
6. Blueprint review loop — automated reviewer checks quality, up to 3 iterations
7. User review gate — explicit approval before transitioning to Architect phase

This process applies to EVERY project regardless of perceived simplicity. The design can be short for simple projects, but it must happen.

Visual companion: For projects involving visual elements (UI, architecture diagrams), the Draft phase can use a browser-based visual companion to show mockups and diagrams during the design conversation. See references/visual-companion.md.

YAGNI enforcement: During the design conversation and blueprint generation, actively strip requirements the user did not ask for. Smaller blueprints are better blueprints.

With bp:design-system

When DESIGN.md exists at the project root, blueprints for UI domains should reference design tokens in acceptance criteria. This creates a traceable chain: DESIGN.md -> blueprint acceptance criterion -> plan task -> implementation.

Do NOT duplicate DESIGN.md content into blueprints. Reference by section/token name only. If a color changes in DESIGN.md, blueprints should not need updating.

When a blueprint needs a visual pattern not yet defined in DESIGN.md, note it in the acceptance criterion:

- [ ] Component uses card-like container [DESIGN.md: pattern not yet defined — flag for design update]

With bp:validation-first

Every acceptance criterion in a blueprint must map to at least one validation gate. When writing blueprints, think about which gate will verify each requirement:

With bp:context-architecture

Blueprints live in the context/blueprints/ directory. See bp:context-architecture for the full context directory structure, CLAUDE.md conventions, and multi-repo strategies.

With bp:impl-tracking

As blueprints are implemented, progress is tracked in context/impl/ documents. Dead ends discovered during implementation should be recorded to prevent future agents from retrying failed approaches.

Common Mistakes

1. Writing Implementation-Specific Blueprints

Wrong: "Use PostgreSQL with a users table containing columns: id (UUID), email (VARCHAR), ..." Right: "User accounts have a unique identifier and email. Email must be unique across all accounts. Acceptance: creating two accounts with the same email fails with a duplicate error."

2. Vague Acceptance Criteria

Wrong: "System handles errors properly" Right: "When a network request fails, the UI displays an error message within 2 seconds and offers a retry action. Acceptance: simulating network failure shows error banner with retry button."

3. Missing Out of Scope

Every blueprint needs explicit exclusions. Without them, agents will over-build or make assumptions.

4. No Cross-References

Domains do not exist in isolation. If blueprint-auth defines session tokens that blueprint-api uses, both blueprints must cross-reference each other.

5. Monolithic Blueprints

A single 1000-line blueprint file defeats progressive disclosure. Decompose into domains with a clear index.

Summary

Writing blueprints for AI agents follows these rules:

1. WHAT, not HOW — describe behavior, not implementation
2. Every requirement gets testable acceptance criteria — if agents cannot validate it, it will not be met
3. Hierarchical with an index — progressive disclosure for context efficiency
4. Cross-referenced — related domains link to each other
5. Explicitly scoped — out-of-scope section prevents over-building
6. Compact when large — archive resolved content, keep active files under 500 lines
7. Living documents — blueprints evolve through revision as gaps are discovered