Blueprint Creator
Create exhaustive BLUEPRINT.md files by expanding a SPEC.md into maximum implementation detail.
The SPEC defines the contract. The Blueprint fills every corner of that contract so an AI agent
can translate it directly into code without a single judgment call.
Pipeline position: SPEC.md → BLUEPRINT.md → Code
Prerequisite: SPEC.md Must Exist
Before doing anything else, verify that a SPEC.md exists. Check in this order:
- File in working directory: Look for
SPEC.md (or similar: spec.md, SPEC_*.md) in the
current project directory or /mnt/user-data/uploads/.
- Provided in chat: Check if the user pasted or attached spec content in this conversation.
- Referenced by name: Check if the user mentioned a spec they created previously.
If SPEC.md is found: Acknowledge it, summarize its scope in 2-3 sentences, and proceed to
Phase 1.
If SPEC.md is NOT found: Stop and tell the user:
"I need a SPEC.md before I can generate the Blueprint. The Blueprint expands a spec into
exhaustive detail — without the spec, there's nothing to expand. Would you like me to use the
spec-creator skill to generate a SPEC.md first? I'll walk you through the brainstorming process,
and once we have a solid spec, I'll pick up the Blueprint from there."
Do NOT proceed with Blueprint generation without a SPEC.md. This is a hard gate.
What the Blueprint Adds (The Delta)
The SPEC is a portable implementation contract with enough precision to implement. The Blueprint
is that same contract exploded into exhaustive detail. Here's the concrete delta:
| SPEC Level |
Blueprint Level |
| Field has type and default |
Field has type, default, exact validation rule, error on invalid, cross-ref to every usage site |
| "Suggested response shape" |
Complete canonical example with every field populated, plus variant examples for edge cases |
| Prose description of algorithm |
Pseudocode + decision table + sequence diagram + edge case table |
| Named error category |
Full error catalog entry: code, message template, trigger condition, recovery, blast radius |
| State transition described in text |
State transition table with every trigger × every state combination |
| "Normalize to lowercase" |
Exact normalization pipeline: input → step 1 → step 2 → output, with 3+ examples including edge cases |
| Config key with default |
Config key with default, validation, dynamic reload behavior, and trace to every behavioral impact |
Read expansion-patterns.md for the full expansion rulebook.
Quality Bar
The Blueprint's quality bar is: Could an AI agent implement every behavior by mechanically
translating Blueprint content into code, without ever needing to make an interpretive decision?
Read quality-bar.md for the detailed rubric. Key markers:
- Every validation rule has explicit valid/invalid examples
- Every error has a code, message template, HTTP status (if applicable), and trigger condition
- Every algorithm has both pseudocode AND a decision table for branching
- Every data transformation has input → output examples (minimum 3, including edge cases)
- Every sequence of operations has a numbered step-by-step or diagram
- Every configuration key traces to the exact behaviors it affects
- Cross-references are exhaustive — every entity/field links to everywhere it's used
Workflow
Phase 1: SPEC Ingestion and Gap Analysis
After confirming SPEC.md exists:
Read the entire SPEC. Parse every section, entity, config key, state, error class, and
algorithm.
Build an expansion inventory. For each SPEC section, identify what's at "spec level" and
needs Blueprint-level expansion. Categorize into:
- Entities needing validation rules (fields with types but no validation detail)
- Algorithms needing decision tables (pseudocode with branching)
- Integrations needing full examples ("suggested shapes" → exact canonical examples)
- Error classes needing full catalog entries (named categories → code + message + trigger)
- Config keys needing behavioral traces (key → where it affects behavior)
- States needing transition tables (prose transitions → matrix)
- Flows needing sequence diagrams (described processes → step-by-step)
Present the expansion plan. Show the user what you found:
"I've analyzed the SPEC. It has N sections, M entities, K config keys, and J error classes.
Here's my expansion plan: [summary of what needs to be expanded per section]. Before I start,
are there areas you want me to go especially deep on, or areas where the spec-level detail is
already sufficient?"
Phase 2: Targeted Brainstorming
Unlike the SPEC brainstorming (which discovers requirements), Blueprint brainstorming fills
granular detail. The questions are specific and operational.
Ask questions one round at a time, 3-6 questions per round. Focus on areas where the SPEC
left deliberate flexibility that the Blueprint needs to lock down.
Read brainstorm-patterns.md for the questioning framework. Common areas:
- Validation edge cases: "The SPEC says
poll_interval_ms is an integer with default 30000.
What should happen with: zero? Negative? Float? String? Extremely large values?"
- Error message specifics: "The SPEC names
missing_workflow_file as an error class. What
should the error message say exactly? Should it include the path that was tried?"
- Sequence ambiguities: "The SPEC says reconciliation runs before dispatch on every tick.
If reconciliation itself fails, should the tick continue to dispatch or abort entirely?"
- Boundary behaviors: "The SPEC says workspaces are reused. If a workspace exists but is
corrupted (e.g., missing .git), what happens?"
When to stop brainstorming:
Stop when you can fill in every cell of every decision table, every field of every error catalog
entry, and every step of every sequence diagram without inventing anything.
Phase 3: Drafting the BLUEPRINT.md
Read section-templates.md for the canonical Blueprint section structure. Then
draft the full document.
Blueprint Section Structure:
1. Document Header (references SPEC, scope statement)
2. System Context (expanded from SPEC system overview)
3. Entity Catalog (every entity with full field specifications)
- Per entity: field table with type, required/optional, default, validation,
normalization, usage cross-references
4. Configuration Bible (every config key fully specified)
- Per key: type, default, validation rule, valid/invalid examples,
dynamic reload behavior, behavioral impact trace
5. State Transition Matrix (full state × trigger grid)
6. Sequence Specifications (per major operation)
- Per sequence: numbered steps, decision points, error branches
7. Integration Specifications (per external system)
- Per integration: exact request/response examples, pagination walkthrough,
error response examples, normalization pipeline with examples
8. Error Catalog (every error fully specified)
- Per error: code, message template, trigger condition, recovery action,
blast radius, operator visibility
9. Validation Rules Compendium (every validation in one place)
10. Algorithm Detail (expanded pseudocode + decision tables)
11. Edge Case Encyclopedia (organized by subsystem)
12. Cross-Reference Index
13. Implementation Checklist (expanded from SPEC, more granular)
Drafting rules — critical for exhaustive Blueprint quality:
Every field gets a full specification row. Not just type and default, but: validation rule,
what happens on invalid input, normalization steps, and cross-reference to every section that
reads or writes this field.
Every branching path gets a decision table. If an algorithm has an if/else, it gets a
table: Condition | Input State | Action | Result State | Side Effects.
Every data transformation gets examples. Minimum 3 examples: happy path, edge case, and
error case. Format: Input → [Step 1] → [Step 2] → Output.
Every error gets a catalog entry. Code, message template (with variable slots), HTTP status
(if applicable), trigger condition (exact), recovery action, blast radius (one item? one
component? whole system?), operator visibility (how the operator learns about it).
Every sequence gets numbered steps. No prose descriptions of flows. Step 1, Step 2, Step 3.
Each step names the actor, the action, the input, and the output. Decision points branch into
labeled paths.
Every "suggested" or "recommended" shape becomes canonical. If the SPEC said "suggested
response shape," the Blueprint provides THE response shape with every field, every type, every
possible value documented.
Cross-references are exhaustive. The Entity Catalog links to every section that uses each
entity. The Config Bible links to every behavior each key affects. The Error Catalog links to
every operation that can produce each error.
Edge cases are organized by subsystem, not scattered throughout. A dedicated Edge Case
Encyclopedia section collects every "what if" scenario the SPEC didn't explicitly cover.
The Implementation Checklist is more granular than the SPEC's. Where the SPEC says
"Workspace manager with sanitized per-issue workspaces," the Blueprint says: "Workspace
sanitization function: input ABC-123 → output ABC-123. Input feat/my branch → output
feat_my_branch. Input ../../etc/passwd → output ______etc_passwd. Validate: output
contains only [A-Za-z0-9._-]."
Output format:
- Default: single monolithic
BLUEPRINT.md file
- If the draft exceeds ~2500 lines, offer to split into logical files:
BLUEPRINT.md (core document)
ERROR_CATALOG.md (full error specifications)
EDGE_CASES.md (edge case encyclopedia)
SEQUENCES.md (sequence diagrams and step-by-step flows)
- Always include a cross-reference index regardless of split
Phase 4: Self-Review
Before presenting the Blueprint, run a self-review. Read
self-review-checklist.md for the full checklist.
Self-review process:
Mechanical translation test. Pick 3 random sections. For each, ask: "Could I translate
this into code line-by-line without making ANY interpretive decisions?" If the answer is no,
the section needs more detail.
Coverage check. Walk through every SPEC section. Does the Blueprint have a corresponding
expansion? If a SPEC section was not expanded, was that a conscious decision (explain why) or
an oversight (fix it)?
Consistency check. Do entity field names match between Entity Catalog, Config Bible, Error
Catalog, and Sequence Specifications? Inconsistency here causes implementation bugs.
Example completeness check. Does every validation rule have valid AND invalid examples?
Does every transformation have at least 3 examples? Does every error have a trigger scenario?
Produce Review Summary:
- SPEC sections covered vs. total
- Entity fields fully specified vs. total
- Error catalog entries vs. SPEC error classes
- Decision tables created
- Edge cases documented
- Cross-references built
- Gaps found and fixed during review
- Remaining
[TBD] markers
- Confidence assessment
Iteration
When the user requests changes:
- Apply changes surgically — the Blueprint is large, don't regenerate entirely
- If a change affects an entity field, update it in Entity Catalog AND trace through every
cross-reference to update dependent sections
- If a change adds a new error, add a full catalog entry AND update the relevant sequence's error
branch AND update the Edge Case Encyclopedia
- Re-run self-review on modified sections
- Present a changelog
Anti-Patterns to Avoid
- The copy-paste trap. The Blueprint is NOT the SPEC with more words. Every section must add
concrete detail the SPEC didn't have. If you can't identify the delta, the section doesn't
belong.
- The novel trap. Don't write prose where a table suffices. Decision tables, field
specification tables, and example pipelines are more precise than paragraphs.
- The completionism trap. Some SPEC sections (like Problem Statement, Goals/Non-Goals) don't
need Blueprint expansion — they're already at maximum useful detail. Don't pad them.
- The tech-stack trap. The Blueprint is language-agnostic. Don't specify
Zod or Pydantic
or JsonSchema. Specify the validation RULE; let the implementing agent pick the tool.
- The orphan trap. Every piece of detail must trace back to a SPEC section. If you're adding
detail that doesn't correspond to anything in the SPEC, either the SPEC has a gap (flag it) or
the detail is out of scope.
1---2name: blueprint-creator3description: >4 Create exhaustive BLUEPRINT.md files — the implementation bible that expands a SPEC.md into5 maximum granular detail so an AI coding agent can translate it line-by-line into code with zero6 interpretation. This skill REQUIRES a SPEC.md to already exist. Use this skill whenever the user7 wants to create a blueprint, implementation blueprint, detailed spec, "bible" document, or says8 "create the blueprint", "expand the spec", "make it more detailed", "generate BLUEPRINT.md", or9 "I need every detail spelled out." Also trigger when the user has a SPEC.md and wants to go10 deeper before implementation. The Blueprint is the final artifact before code — it takes the11 portable implementation contract (SPEC.md) and fills in every edge case, validation rule, error12 message, sequence, and example so nothing is left to judgment. Works for any software domain.13 If no SPEC.md exists, this skill MUST redirect the user to generate one first using the14 spec-creator skill.15triggers:16 - "create a blueprint"17 - "expand this spec into a blueprint"18 - "implementation bible"19 - "BLUEPRINT.md"20metadata:21 source: https://skillmd.com/skills/praxstack/blueprint-creator22---2324# Blueprint Creator2526Create exhaustive BLUEPRINT.md files by expanding a SPEC.md into maximum implementation detail.27The SPEC defines the contract. The Blueprint fills every corner of that contract so an AI agent28can translate it directly into code without a single judgment call.2930**Pipeline position:** `SPEC.md` → `BLUEPRINT.md` → Code3132## Prerequisite: SPEC.md Must Exist3334Before doing anything else, verify that a SPEC.md exists. Check in this order:35361. **File in working directory:** Look for `SPEC.md` (or similar: `spec.md`, `SPEC_*.md`) in the37 current project directory or `/mnt/user-data/uploads/`.382. **Provided in chat:** Check if the user pasted or attached spec content in this conversation.393. **Referenced by name:** Check if the user mentioned a spec they created previously.4041**If SPEC.md is found:** Acknowledge it, summarize its scope in 2-3 sentences, and proceed to42Phase 1.4344**If SPEC.md is NOT found:** Stop and tell the user:4546> "I need a SPEC.md before I can generate the Blueprint. The Blueprint expands a spec into47> exhaustive detail — without the spec, there's nothing to expand. Would you like me to use the48> spec-creator skill to generate a SPEC.md first? I'll walk you through the brainstorming process,49> and once we have a solid spec, I'll pick up the Blueprint from there."5051Do NOT proceed with Blueprint generation without a SPEC.md. This is a hard gate.5253## What the Blueprint Adds (The Delta)5455The SPEC is a portable implementation contract with enough precision to implement. The Blueprint56is that same contract exploded into exhaustive detail. Here's the concrete delta:5758| SPEC Level | Blueprint Level |59|---|---|60| Field has type and default | Field has type, default, exact validation rule, error on invalid, cross-ref to every usage site |61| "Suggested response shape" | Complete canonical example with every field populated, plus variant examples for edge cases |62| Prose description of algorithm | Pseudocode + decision table + sequence diagram + edge case table |63| Named error category | Full error catalog entry: code, message template, trigger condition, recovery, blast radius |64| State transition described in text | State transition table with every trigger × every state combination |65| "Normalize to lowercase" | Exact normalization pipeline: input → step 1 → step 2 → output, with 3+ examples including edge cases |66| Config key with default | Config key with default, validation, dynamic reload behavior, and trace to every behavioral impact |6768Read [expansion-patterns.md](./expansion-patterns.md) for the full expansion rulebook.6970## Quality Bar7172The Blueprint's quality bar is: **Could an AI agent implement every behavior by mechanically73translating Blueprint content into code, without ever needing to make an interpretive decision?**7475Read [quality-bar.md](./quality-bar.md) for the detailed rubric. Key markers:7677- Every validation rule has explicit valid/invalid examples78- Every error has a code, message template, HTTP status (if applicable), and trigger condition79- Every algorithm has both pseudocode AND a decision table for branching80- Every data transformation has input → output examples (minimum 3, including edge cases)81- Every sequence of operations has a numbered step-by-step or diagram82- Every configuration key traces to the exact behaviors it affects83- Cross-references are exhaustive — every entity/field links to everywhere it's used8485## Workflow8687### Phase 1: SPEC Ingestion and Gap Analysis8889After confirming SPEC.md exists:90911. **Read the entire SPEC.** Parse every section, entity, config key, state, error class, and92 algorithm.93942. **Build an expansion inventory.** For each SPEC section, identify what's at "spec level" and95 needs Blueprint-level expansion. Categorize into:96 - **Entities needing validation rules** (fields with types but no validation detail)97 - **Algorithms needing decision tables** (pseudocode with branching)98 - **Integrations needing full examples** ("suggested shapes" → exact canonical examples)99 - **Error classes needing full catalog entries** (named categories → code + message + trigger)100 - **Config keys needing behavioral traces** (key → where it affects behavior)101 - **States needing transition tables** (prose transitions → matrix)102 - **Flows needing sequence diagrams** (described processes → step-by-step)1031043. **Present the expansion plan.** Show the user what you found:105106 > "I've analyzed the SPEC. It has N sections, M entities, K config keys, and J error classes.107 > Here's my expansion plan: [summary of what needs to be expanded per section]. Before I start,108 > are there areas you want me to go especially deep on, or areas where the spec-level detail is109 > already sufficient?"110111### Phase 2: Targeted Brainstorming112113Unlike the SPEC brainstorming (which discovers requirements), Blueprint brainstorming fills114granular detail. The questions are specific and operational.115116Ask questions **one round at a time**, 3-6 questions per round. Focus on areas where the SPEC117left deliberate flexibility that the Blueprint needs to lock down.118119Read [brainstorm-patterns.md](./brainstorm-patterns.md) for the questioning framework. Common areas:120121- **Validation edge cases:** "The SPEC says `poll_interval_ms` is an integer with default 30000.122 What should happen with: zero? Negative? Float? String? Extremely large values?"123- **Error message specifics:** "The SPEC names `missing_workflow_file` as an error class. What124 should the error message say exactly? Should it include the path that was tried?"125- **Sequence ambiguities:** "The SPEC says reconciliation runs before dispatch on every tick.126 If reconciliation itself fails, should the tick continue to dispatch or abort entirely?"127- **Boundary behaviors:** "The SPEC says workspaces are reused. If a workspace exists but is128 corrupted (e.g., missing .git), what happens?"129130**When to stop brainstorming:**131132Stop when you can fill in every cell of every decision table, every field of every error catalog133entry, and every step of every sequence diagram without inventing anything.134135### Phase 3: Drafting the BLUEPRINT.md136137Read [section-templates.md](./section-templates.md) for the canonical Blueprint section structure. Then138draft the full document.139140**Blueprint Section Structure:**141142```1431. Document Header (references SPEC, scope statement)1442. System Context (expanded from SPEC system overview)1453. Entity Catalog (every entity with full field specifications)146 - Per entity: field table with type, required/optional, default, validation,147 normalization, usage cross-references1484. Configuration Bible (every config key fully specified)149 - Per key: type, default, validation rule, valid/invalid examples,150 dynamic reload behavior, behavioral impact trace1515. State Transition Matrix (full state × trigger grid)1526. Sequence Specifications (per major operation)153 - Per sequence: numbered steps, decision points, error branches1547. Integration Specifications (per external system)155 - Per integration: exact request/response examples, pagination walkthrough,156 error response examples, normalization pipeline with examples1578. Error Catalog (every error fully specified)158 - Per error: code, message template, trigger condition, recovery action,159 blast radius, operator visibility1609. Validation Rules Compendium (every validation in one place)16110. Algorithm Detail (expanded pseudocode + decision tables)16211. Edge Case Encyclopedia (organized by subsystem)16312. Cross-Reference Index16413. Implementation Checklist (expanded from SPEC, more granular)165```166167**Drafting rules — critical for exhaustive Blueprint quality:**1681691. **Every field gets a full specification row.** Not just type and default, but: validation rule,170 what happens on invalid input, normalization steps, and cross-reference to every section that171 reads or writes this field.1721732. **Every branching path gets a decision table.** If an algorithm has an `if/else`, it gets a174 table: Condition | Input State | Action | Result State | Side Effects.1751763. **Every data transformation gets examples.** Minimum 3 examples: happy path, edge case, and177 error case. Format: `Input → [Step 1] → [Step 2] → Output`.1781794. **Every error gets a catalog entry.** Code, message template (with variable slots), HTTP status180 (if applicable), trigger condition (exact), recovery action, blast radius (one item? one181 component? whole system?), operator visibility (how the operator learns about it).1821835. **Every sequence gets numbered steps.** No prose descriptions of flows. Step 1, Step 2, Step 3.184 Each step names the actor, the action, the input, and the output. Decision points branch into185 labeled paths.1861876. **Every "suggested" or "recommended" shape becomes canonical.** If the SPEC said "suggested188 response shape," the Blueprint provides THE response shape with every field, every type, every189 possible value documented.1901917. **Cross-references are exhaustive.** The Entity Catalog links to every section that uses each192 entity. The Config Bible links to every behavior each key affects. The Error Catalog links to193 every operation that can produce each error.1941958. **Edge cases are organized by subsystem**, not scattered throughout. A dedicated Edge Case196 Encyclopedia section collects every "what if" scenario the SPEC didn't explicitly cover.1971989. **The Implementation Checklist is more granular than the SPEC's.** Where the SPEC says199 "Workspace manager with sanitized per-issue workspaces," the Blueprint says: "Workspace200 sanitization function: input `ABC-123` → output `ABC-123`. Input `feat/my branch` → output201 `feat_my_branch`. Input `../../etc/passwd` → output `______etc_passwd`. Validate: output202 contains only `[A-Za-z0-9._-]`."203204**Output format:**205206- Default: single monolithic `BLUEPRINT.md` file207- If the draft exceeds ~2500 lines, offer to split into logical files:208 - `BLUEPRINT.md` (core document)209 - `ERROR_CATALOG.md` (full error specifications)210 - `EDGE_CASES.md` (edge case encyclopedia)211 - `SEQUENCES.md` (sequence diagrams and step-by-step flows)212- Always include a cross-reference index regardless of split213214### Phase 4: Self-Review215216Before presenting the Blueprint, run a self-review. Read217[self-review-checklist.md](./self-review-checklist.md) for the full checklist.218219**Self-review process:**2202211. **Mechanical translation test.** Pick 3 random sections. For each, ask: "Could I translate222 this into code line-by-line without making ANY interpretive decisions?" If the answer is no,223 the section needs more detail.2242252. **Coverage check.** Walk through every SPEC section. Does the Blueprint have a corresponding226 expansion? If a SPEC section was not expanded, was that a conscious decision (explain why) or227 an oversight (fix it)?2282293. **Consistency check.** Do entity field names match between Entity Catalog, Config Bible, Error230 Catalog, and Sequence Specifications? Inconsistency here causes implementation bugs.2312324. **Example completeness check.** Does every validation rule have valid AND invalid examples?233 Does every transformation have at least 3 examples? Does every error have a trigger scenario?2342355. **Produce Review Summary:**236 - SPEC sections covered vs. total237 - Entity fields fully specified vs. total238 - Error catalog entries vs. SPEC error classes239 - Decision tables created240 - Edge cases documented241 - Cross-references built242 - Gaps found and fixed during review243 - Remaining `[TBD]` markers244 - Confidence assessment245246## Iteration247248When the user requests changes:249250- Apply changes surgically — the Blueprint is large, don't regenerate entirely251- If a change affects an entity field, update it in Entity Catalog AND trace through every252 cross-reference to update dependent sections253- If a change adds a new error, add a full catalog entry AND update the relevant sequence's error254 branch AND update the Edge Case Encyclopedia255- Re-run self-review on modified sections256- Present a changelog257258## Anti-Patterns to Avoid259260- **The copy-paste trap.** The Blueprint is NOT the SPEC with more words. Every section must add261 concrete detail the SPEC didn't have. If you can't identify the delta, the section doesn't262 belong.263- **The novel trap.** Don't write prose where a table suffices. Decision tables, field264 specification tables, and example pipelines are more precise than paragraphs.265- **The completionism trap.** Some SPEC sections (like Problem Statement, Goals/Non-Goals) don't266 need Blueprint expansion — they're already at maximum useful detail. Don't pad them.267- **The tech-stack trap.** The Blueprint is language-agnostic. Don't specify `Zod` or `Pydantic`268 or `JsonSchema`. Specify the validation RULE; let the implementing agent pick the tool.269- **The orphan trap.** Every piece of detail must trace back to a SPEC section. If you're adding270 detail that doesn't correspond to anything in the SPEC, either the SPEC has a gap (flag it) or271 the detail is out of scope.