README

BLADE

Blueprint-Led Acceptance-Driven Engineering

> "If you can't delete your code and regenerate it from specs, you don't have specs — you have comments."

What if your code was disposable?

Not in a careless way. In a deliberate way. What if the real product of software development wasn't the code at all, but the specification that produced it?

That's BLADE.

BLADE is a methodology where blueprints are the durable product and code is a disposable artifact — generated from specs, validated by tests, and thrown away whenever you want a fresh start. No technical debt. No legacy systems rotting in production. No "only Dave understands this part" situations. Just clean specifications that can produce working software in any language, any framework, any time.

The idea is simple: describe what a system does (not how), nail down every behavior with acceptance criteria, and let AI generate the implementation. Then — and here's the part that makes people nervous — you can delete all the code and regenerate it from the same blueprint. If the tests pass, you've proven the blueprint is complete. If they don't, the blueprint needs work, not the code.

See It In Action

BLADE ships with a complete proof-of-concept: the Mars Rover project. One blueprint. Multiple products. All generated, all verified, all disposable.

The same behavioral specification produced a TypeScript CLI, a React web app, and a vanilla JavaScript version — each one independently generated, each one passing all 62 tests, each one traceable back to the exact same acceptance criteria.

The Mars Rover Simulator — a React app generated entirely from a behavioral blueprint.
The same blueprint also produced a CLI tool and a vanilla JS version.

Every behavior documented in the blueprint — commands, boundary handling, tips — appears in the product.

How It Works

BLADE follows a strict sequence. You can't skip steps, because each phase builds on the last:

shell

   Idea                Blueprint              Product
 ┌─────────┐        ┌─────────────┐        ┌───────────┐
 │ Problem  │───────▶│ Behavioral  │───────▶│ Code +    │
 │ + Needs  │        │ Specs       │        │ Tests     │
 └─────────┘        └──────┬──────┘        └─────┬─────┘
                           │                     │
                    ┌──────▼──────┐              │
                    │   Human     │◀─────────────┘
                    │   Answers   │  (questions that need
                    └─────────────┘   human judgment)

Phase 1 — Idea. You describe the problem. What needs solving, for whom, and why. No implementation details. Just the raw need.

Phase 2 — Blueprint. AI decomposes the idea into a full behavioral specification: components, contracts between them, and acceptance criteria for every behavior. The blueprint describes what the system does — never how. No language. No framework. No architecture decisions. Just behavior. A review process flags ambiguities, and any decisions that need human judgment get captured in /human-answers/ so they survive across regenerations.

Phase 3 — Product. AI generates the implementation from the blueprint. Every acceptance criterion becomes a test. Every contract becomes an integration test. The output is working code with full traceability back to the spec — you can trace any test failure directly to the acceptance criterion it validates.

And then, whenever you want: delete the product and regenerate it. Different language. Different framework. Same blueprint. Same tests. Same behavior.

The BLADE Test Convention

Every test is named after the acceptance criterion it validates. This isn't a suggestion — it's how traceability works:

typescript

// TypeScript
describe('AC-001: Execute turn left command', () => { ... })
describe('EC-001: Move blocked by boundary', () => { ... })
describe('ER-001: Invalid command is ignored', () => { ... })

// Go
func TestTurnLeftAC001(t *testing.T) { }
func TestBoundaryBlockEC001(t *testing.T) { }
func TestInvalidCommandER001(t *testing.T) { }

python

# Python
def test_turn_left_ac001(): pass
def test_boundary_block_ec001(): pass
def test_invalid_command_er001(): pass

When a test fails, you don't just know what broke — you know which specification is violated. AC-001 takes you straight to the blueprint's acceptance criteria. No detective work.

Quick Start

BLADE runs inside Claude Code. You talk to Claude, and it follows the methodology using the format templates in this repository.

1. Capture an idea

shell

Create the idea for [your project].

Follow the idea format in format/IDEA.md
Output to projects/[your-project]/idea/

2. Generate a blueprint

shell

Create the blueprint for [your project] with a [CLI/API/Web] interface.

Follow the blueprint format in format/BLUEPRINT.md
Output to projects/[your-project]/blueprint/

3. Generate a product

shell

Create the product in [TypeScript/Go/Python/etc].

Follow the product format in format/PRODUCT.md
Read the blueprint from projects/[your-project]/blueprint/
Output to projects/[your-project]/product/

4. Verify the product

shell

Verify the product against the blueprint.

Read the blueprint from projects/[your-project]/blueprint/
Read the product from projects/[your-project]/product/
Output a verification report to projects/[your-project]/VERIFICATION.md

5. Regenerate (the whole point)

bash

rm -rf projects/[your-project]/product/    # Delete the code. All of it. Don't be scared.
# Now run step 3 again. Maybe in a different language this time.

For the full walkthrough with real examples, see the User Guide.

For detailed narratives of BLADE in action:

Mars Rover Case Study — From a single paragraph to five working products
Touch Typer Case Study — A Guitar Hero-style typing game: one blueprint, Go terminal app + TypeScript web app

Repository Structure

shell

blade/ # You are here # Detailed walkthrough for getting started # Mars Rover: one blueprint, five products # Touch Typer: one blueprint, two platforms # Instructions for Claude Code # The methodology # BLADE principles and philosophy # How to capture ideas # How to expand ideas into requirements # How to create behavioral specifications # How to generate implementations # Copy-paste templates for contracts, components, criteria # Project scaffolds (CLI, API, Web — Go, TypeScript) # Developer personas that shape code quality # "The Craftsman" — quality gates, coding philosophy # Workflow automation scripts class="hl-number">1-create-blueprint.md class="hl-number">2-create-product.md class="hl-number">3-verify-product.md # Your projects live here # Proof-of-concept: 1 blueprint → 5 products # Behavioral specification (the durable part) product-typescript/  # CLI implementation (disposable) # React web app (disposable) # Vanilla TypeScript web app (disposable) # Vanilla JavaScript web app (disposable) # Full game: 1 blueprint → 2 platforms # Game spec with 10 components, 7 contracts product-go/       # Terminal app (Go + Bubble Tea) # Browser app (TypeScript + PixiJS + WebGPU) # Research notes and management summaries

Why BLADE?

The old way	BLADE
Code is the product	The blueprint is the product
Specs rot and fall behind the code	Specs are the source of truth — code follows them
Tests verify the implementation works	Tests verify the implementation matches the spec
Refactoring is risky and scary	Regeneration is routine and safe
Knowledge lives in senior devs' heads	Knowledge lives in blueprints and human-answers
"Legacy system" is inevitable	Legacy is impossible — just regenerate
Upgrading frameworks takes months	Upgrading frameworks means regenerating in the new one
Technical debt compounds silently	Technical debt can't exist if code is disposable

What's Inside a Blueprint?

A blueprint isn't just a README with some bullet points. It's a structured decomposition:

shell

blueprint/
├── problem/
│   ├── statement.md          # What are we solving and why
│   └── scope.md              # What's in, what's out, what we assume
├── architecture/
│   ├── principles.md         # Error handling, state management, extensibility
│   └── decomposition.md      # Component tree with responsibilities and data flow
├── contracts/
│   └── [name].md             # Boundaries between components with examples
├── components/
│   └── [name]/
│       ├── description.md    # What this component does
│       ├── acceptance.md     # AC-xxx, EC-xxx, ER-xxx criteria
│       └── contracts.md      # What it provides and consumes
├── review/
│   ├── issues.md             # Problems found during review
│   └── questions.md          # Decisions that need a human
└── human-answers/
    └── Q-xxx.md              # Captured human decisions (persist forever)

Every acceptance criterion follows Given/When/Then format. Every component has 3-7 criteria. Every contract has concrete examples. There's no ambiguity left for the code to invent.

Developer Personas

BLADE products aren't just "generated code." They're shaped by developer personas — fictional engineers with real opinions about quality, style, and craft. The persona defines quality gates (complexity limits, coverage thresholds, function length caps) and coding philosophy.

The Mars Rover products were built by Jan Eriksen, a 15-year veteran who hiked the Pacific Crest Trail, codes on a vintage CRT monitor, and will fail your build if cyclomatic complexity exceeds 10. See personas/jan-eriksen.md for the full character.

Contributing

BLADE is a methodology, not a framework. There's no package to install. To use it:

Clone this repo

Install Claude Code

Start with the User Guide

Build something, delete it, rebuild it. That's the test.

"Blueprints are durable. Products are disposable."