Blueprint Documentation

Greenfield

Starting a new project from scratch. Blueprint decomposes your idea into blueprints, plans the build order, then implements everything automatically.

> /bp:draft
# Blueprint asks what you're building
What are you building?

> A REST API for task management. Users, projects, tasks with priorities
  and due dates, assignments. PostgreSQL.

# Blueprint decomposes into domain blueprints with numbered requirements
Created 4 blueprints (22 requirements, 69 acceptance criteria)
Next: /bp:architect

> /bp:architect
# Reads blueprints, breaks into tasks, maps dependencies into tiers
Generated build site: 34 tasks, 5 tiers
Next: /bp:build

> /bp:build
# The Ralph Loop — implements, validates, commits, repeats
Loop activated — 34 tasks, 20 max iterations.
...
All tasks done. Build passes. Tests pass.
BLUEPRINT COMPLETE — 34 tasks in 18 iterations.

Every line of code traces to a requirement. Every requirement has acceptance criteria. See /bp:draft, /bp:architect, and /bp:build for full command details.

Brownfield

Adding Blueprint to an existing codebase. Use --from-code to reverse-engineer blueprints from your code, then scope the build to the gaps.

> /bp:draft --from-code
# Blueprint explores your codebase and reverse-engineers specs
Exploring codebase... Next.js 14, Prisma, NextAuth.
Created 6 blueprints — 4 requirements are gaps (not yet implemented).

> /bp:architect --filter collaboration
# Only plan the subset you want to build now
Generated build site: 8 tasks, 3 tiers

> /bp:build
# Builds only the filtered tasks
Loop activated — 8 tasks.
...
BLUEPRINT COMPLETE — 8 tasks in 8 iterations.

The --from-code flag tells Blueprint to read your existing code and produce specs that match it, while highlighting gaps. The --filter flag on /bp:architect scopes the build to a specific domain.

/bp:draft Draft

> /bp:draft
What are you building?
> A REST API for task management with users, projects, and tasks.
Created 4 blueprints (22 requirements, 69 acceptance criteria)

/bp:architect Architect

> /bp:architect
Generated build site: 34 tasks, 5 tiers
Next: /bp:build

/bp:build Build

> /bp:build
Loop activated — 34 tasks, 20 max iterations.

═══ Wave 1 ═══
3 task(s) ready:
  T-001: Database schema (tier 0, deps: none)
  T-002: Auth middleware (tier 0, deps: none)
  T-003: Config loader (tier 0, deps: none)

Dispatching 2 grouped subagents...
All 3 tasks complete. Merging...

═══ Wave 2 ═══
2 task(s) ready...
...
═══ BUILD COMPLETE ═══
Waves: 2 | Tasks: 5/5

/bp:inspect Inspect

> /bp:inspect
Gap analysis: 22/22 requirements covered
Peer review: 1 finding (P2 — input validation on PATCH endpoint)
Traced to: blueprint-api.md R14

/bp:research Research

> /bp:research "build a Verse compiler targeting WASM"
Dispatching 4 research agents...
Synthesizing findings...
Research brief saved to context/refs/research-brief-verse-wasm.md

/bp:progress Utility

> /bp:progress
Build site: build-site-api.md
Done: 28/34 | In progress: 2 | Blocked: 1 | Remaining: 3

/bp:gap-analysis Utility

> /bp:gap-analysis
Scanning 4 blueprints against codebase...
Covered: 20/22 | Partial: 1 | Missing: 1
  R14 (input validation): partial — PATCH endpoint missing
  R18 (rate limiting): missing

/bp:revise Utility

> /bp:revise
Detected 3 manual changes since last build.
Updated blueprint-api.md: R14 acceptance criteria refined.
Updated impl-api.md: manual fix logged.

/bp:codex-review Utility

> /bp:codex-review
Reviewing diff against worktree base...
2 findings: 1 P1 (nil pointer in error path), 1 P3 (unused import)

/bp:help Utility

> /bp:help
Blueprint v2.1.0 — Specification-Driven Development

Commands:
  /bp:draft       Draft blueprints from requirements
  /bp:architect   Generate tiered build site
  /bp:build       Auto-parallel build loop
  /bp:inspect     Gap analysis + peer review
  ...

The DABI Lifecycle

Every Blueprint project follows four phases. Each phase has a clear input, a clear output, and a validation gate before the next phase begins.

Draft — define the what. You describe what you're building in natural language. Blueprint decomposes it into domain blueprints — structured documents with numbered requirements (R1, R2, ...) and testable acceptance criteria. Each blueprint is stack-independent and human-readable. An optional research phase can ground the design in real evidence before blueprints are written. After the internal reviewer approves, blueprints are sent to Codex for a design challenge that catches decomposition flaws, missing requirements, and ambiguous criteria.

Architect — plan the order. Reads all blueprints, breaks requirements into tasks, maps dependencies, and organizes everything into a tiered build site — a dependency graph where Tier 0 has no dependencies, Tier 1 depends only on Tier 0, and so on. This is what the build loop consumes.

Build — run the loop. The Ralph Loop. Each iteration reads the build site, finds the next unblocked task, loads the relevant blueprint and acceptance criteria, implements the task, then validates (build + tests + acceptance criteria). Pass means commit, mark done, move to the next task. Fail means diagnose, fix, revalidate. At every tier boundary, Codex adversarial review gates advancement. The loop runs until all tasks are done or the iteration limit is reached.

Inspect — verify the result. Gap analysis compares what was built against what was specified. Peer review checks for bugs, security issues, and missed requirements. Everything is traced back to blueprint requirements so you know exactly where any issue originated.

Blueprints as Source of Truth

Most AI coding tools treat the agent as a black box — you prompt, it generates, you hope. Blueprint inverts this. The specification is the product. The code is a derivative. When the spec is clear, the code follows. When the code is wrong, the spec tells you why.

This matters because AI agents are getting better every month, but the fundamental problem remains: without a specification, there is nothing to validate against. Blueprint gives every agent — current and future — a contract to build from and a standard to meet.

Blueprints persist across build cycles. They are not ephemeral prompts — they are versioned, structured documents that drive every downstream decision. When a bug is found, /bp:revise traces it back to the blueprint and updates the specification so the iteration loop can reproduce the fix automatically.

With Codex adversarial review, Blueprint goes further: a second model with different training and different blind spots reviews both the specification and the implementation. Two models disagreeing is a signal. Two models agreeing is confidence.

Scientific Method Applied

Blueprint applies the scientific method — hypothesize, test, observe, refine — to extract reliable outcomes from a stochastic process. Each concept in the methodology maps directly to a step in the scientific method:

The key insight is that non-determinism is not a problem if you have a validation loop. A single LLM pass produces a rough draft. But repeated passes with clear acceptance criteria converge toward correctness — the same way repeated experiments converge toward truth.

The plugin ships with 8 specialized agents, a multi-agent research system, and 13 deep-dive skills covering the full methodology. When Codex is installed, the system operates as a dual-model architecture — Claude builds and Codex reviews — catching classes of errors that single-model self-review cannot detect.

Design Challenge

What it does: An adversarial review of your blueprints focused exclusively on architecture-level concerns. A second model challenges the design before any code is written.

When it triggers: Automatically after Claude drafts blueprints and the internal reviewer approves them during /bp:draft.

How it works: The entire blueprint set is sent to Codex for a design challenge. Codex checks for domain decomposition quality, missing requirements, ambiguous acceptance criteria, implicit assumptions, and cross-domain coherence.

# Flow: draft → internal review → Codex challenge → user review
Claude drafts blueprints
  → Blueprint reviewer approves
  → Codex challenges the design
  → User reviews blueprints + findings

Codex returns structured findings categorized as critical (must fix before building) or advisory (worth considering). Critical findings trigger an auto-fix loop — Claude addresses them, Codex re-challenges, up to 2 cycles. Advisory findings are presented alongside blueprints at the user review gate.

The design challenge is purpose-built to prohibit implementation feedback. No framework suggestions, no file path opinions — only design-level concerns that would cause real problems during the build phase.

Configuration: Controlled by the codex_review setting. Set to off to skip design challenges.

Tier Gate

What it does: A severity-based code review gate that blocks tier advancement when critical defects are found. Codex reviews the diff of every completed tier during /bp:build.

When it triggers: Automatically at every tier boundary during the build loop — after all tasks in a tier complete and before the next tier starts.

How it works: Codex reviews the combined diff of all tasks completed in the tier. Each finding is classified by severity:

═══ Tier 0 Complete ═══
Codex reviews diff (T-001, T-002, T-003) ...
Review: 2 findings (1 P0, 1 P3)
Gate: BLOCKED → fix cycle 1/2
Fixing P0: nil pointer in auth middleware ...
Re-review ...
Gate: PROCEED
═══ Tier 1 starting ═══

The review-fix cycle runs up to 2 iterations per tier. After that, the build advances with a warning — the system never deadlocks.

Gate modes are configurable via the tier_gate_mode setting:

Speculative Review

What it does: Runs the Codex tier review in the background while Claude builds the current tier, eliminating gate latency.

When it triggers: Automatically when a tier completes and speculative_review is on (the default).

How it works: When a tier finishes, Blueprint starts the Codex review in a background process. Meanwhile, Claude begins building the next tier immediately. When that next tier finishes and the gate checks for the previous tier's review, the results are already available — cutting tier gate latency to near-zero.

# Speculative review timeline
Tier 0 complete ──────────────────────► Tier 1 complete
     │                                       │
     └── Codex reviews Tier 0 (background) ──►│
                                              │
                         Results ready ◄──────┘
                         before gate runs

If the background review is not done when the gate runs, the system waits up to the configured timeout (speculative_review_timeout, default 300 seconds) and then falls back to a synchronous review.

Configuration: Toggle with speculative_review (on/off). Adjust wait time with speculative_review_timeout.

Command Safety Gate

What it does: A PreToolUse hook that intercepts every Bash command before execution and classifies its safety, preventing destructive operations.

When it triggers: On every Bash command execution during a Blueprint session (configurable via command_gate).

How it works: Commands are checked through a three-stage pipeline:

# Command safety pipeline
Agent runs bash command
     │
     ▼
Fast-path check ──► allowlist (50+ safe commands) → approve
     │           └► blocklist (rm -rf, force push, ...) → block
     │
     ▼ (ambiguous)
Codex classifies ──► safe → approve
     │            └► warn → approve + log
     │            └► block → prevent execution
     │
     ▼ (cached)
Verdict cache ──► normalized pattern match → reuse verdict

The gate integrates with Claude Code's permission system — commands already allowed or blocked in settings bypass the gate entirely. Verdicts are cached by normalized command pattern within the session to avoid redundant API calls.

Configuration: Set command_gate to all (default), interactive, or off. Adjust Codex classification timeout with command_gate_timeout (default 3000ms).

Graceful Degradation

What it does: Ensures Blueprint works fully without Codex installed. All Codex features are additive — they enhance the system but are never required.

When it triggers: Automatically when Codex is not detected on the system.

How it works: When Codex is not installed, the following behavior changes apply:

Blueprint works the same as before Codex integration was added. Codex makes it harder to ship bad blueprints and bad code, but the core DABI lifecycle is fully functional without it.

Blueprint Writing

Convergence Monitoring

Peer Review

Validation-First Design

Context Architecture

Revision

Brownfield Adoption

Speculative Pipeline

Prompt Pipeline

Implementation Tracking

Documentation Inversion

Peer Review Loop

Core Methodology

Settings Reference

File Structure

Blueprint organizes all project context under the context/ directory. Each subdirectory serves a specific role in the DABI lifecycle:

context/
├── blueprints/               # Domain blueprints (persist across cycles)
│   ├── blueprint-overview.md
│   └── blueprint-{domain}.md
├── sites/                    # Build sites (one per plan)
│   ├── build-site-*.md
│   └── archive/
├── impl/                     # Implementation tracking
│   ├── impl-{domain}.md
│   ├── impl-review-findings.md   # Codex review findings ledger
│   ├── impl-speculative-log.md   # Speculative review timing data
│   ├── loop-log.md
│   └── archive/
└── refs/                     # Reference materials (PRDs, API docs)
    ├── research-brief-{topic}.md   # Synthesized research brief
    └── research-{topic}/           # Raw findings + findings board

The scripts/ directory contains the Codex integration shell scripts: