Blueprint Format
A SPEC.ZIP blueprint is a ZIP file containing machine-readable specifications and agent context that allows AI coding agents to understand and build an application — without source code.
Core Philosophy
Blueprints are outcome specifications, not source code. They describe what the application does, how it behaves, and how it feels — never howto write the code (file paths, component names, hooks, or CSS classes).
This means the same blueprint can be built by Claude Code, Codex, Cursor, OpenCode, Pi, or any other agentic coder — each agent decides the implementation.
More complexity equals more value. A simple TODO app can be specified in minutes. A real-time collaborative whiteboard with WebSocket sync and CRDT? That is where the blueprint delivers real value.
Directory Structure
Every blueprint follows a consistent directory layout. Blueprints are specifications, not source code — there is no src/ directory.
blueprint-name/ ├── SPEC.md # REQUIRED — Master specification ├── README.md # REQUIRED — Human overview ├── manifest.json # REQUIRED — Machine metadata ├── changelog.md # REQUIRED — Version history ├── LICENSE # REQUIRED — License file ├── DESIGN.md # RECOMMENDED — Design system ├── AGENTS.md # RECOMMENDED — Build guide for agents │ ├── .agents/ # REQUIRED — Agent Skills (dot prefix) │ └── skills/speczip-code-builder/ │ └── SKILL.md # REQUIRED — Embedded execution skill │ ├── .speczip/ # REQUIRED — SpecZip namespace │ ├── tech-stack.json # REQUIRED — Tech stack config │ ├── data-model.json # REQUIRED — Data model │ ├── version.json # REQUIRED — Version tracking │ └── agent-context/ │ └── CONTEXT.md # REQUIRED — Agent read-me-first │ ├── phases/ # OPTIONAL — Multi-phase breakdown │ └── phase-N/ │ ├── AGENTS.md │ ├── SKILL.md │ └── tasks/ │ └── task-NN-name.md │ ├── scaffold/ # OPTIONAL — Starter config files └── resources/ # OPTIONAL — Bundled static assets
Required Files
SPEC.md — Master Specification
The core blueprint file. Written as prose describing behavior and outcomes. Every feature describes the complete end-to-end flow: user action → UI change → API call → database operation → response → UI update.
| Complexity | Length | Sections |
|---|---|---|
| Low | 1–2 pages | Overview, Core Features, User Flow, Tech Stack, Acceptance Criteria, Out of Scope |
| Medium | 3–5 pages | All Low sections + Data Model (SQL DDL), API Design, Auth |
| High | 5+ pages | All Medium sections + multi-phase breakdown, edge-case matrix, user flows |
manifest.json — Machine Metadata
Machine-readable blueprint metadata. Defines title, category, pricing, tech stack, and authorship. The marketplace uses this for filtering, searching, and display.
{
"speczip_version": "1.0.0",
"name": "analytics-dashboard",
"title": "Analytics Dashboard",
"tagline": "Self-hosted metrics with real-time charts",
"category": "saas",
"difficulty": "medium",
"version": "1.0.0",
"license": "MIT",
"price_usd": 39,
"has_design_system": true,
"tech_stack": [
{ "name": "Next.js", "role": "frontend", "version": ">=14.0.0" }
]
}Valid Categories
LICENSE — Blueprint License
Every blueprint carries a license file. The license is determined by price:
| Price | License | Scope |
|---|---|---|
| Free ($0) | MIT License | Use, modify, distribute, sell — free with attribution |
| Premium (> $0) | Custom EULA | Non-exclusive, single-project license. Buyer may build the app but not resell the blueprint. Includes perpetual upgrades. |
README.md
Human-readable overview of the blueprint. What the app does, who it is for, and how to get started. The first file users read when exploring the marketplace.
changelog.md
Version history using semantic versioning. Every new version gets an entry at the top. Patch for bug fixes, minor for new features, major for breaking changes.
Required Directories
.speczip/ — SpecZip Namespace
Configuration files that agents read during build. All files in this directory are JSON or structured Markdown.
.agents/ — Agent Skills
Agent skills conform to the Agent Skills specification. The embedded skill tells the building agent exactly how to execute this blueprint.
.agents/
└── skills/speczip-code-builder/
└── SKILL.md # Build instructions for this blueprintOptional Files
How Agents Use Blueprints
The /speczip:build command is the primary workflow for turning a blueprint into a working application.
- Authenticate — Agent locates the
SPECZIP_TOKEN(from.env,.env.local, or environment variable) - Look up — Agent finds the blueprint by slug via the marketplace API
- Download — Server streams the ZIP file directly (no presigned URLs)
- Extract — ZIP is unpacked to a project directory
- Read SPEC.md — Agent reads the master specification and presents a summary
- Build — Agent builds the application following the spec
Available Commands
/speczip:build <slug>Download and build a blueprint/speczip:search <query>Search the marketplace/speczip:info <slug>View blueprint details without downloading/speczip:customize <slug>Review and modify tech stack before building/speczip:feedback <slug>Submit feedback about a blueprint/speczip:tokenVerify token statusBlueprint Lifecycle
Updates to your own published blueprint publish immediately if validation passes. Submitted blueprints are reviewed by admins before going live.
Questions about the blueprint format?
Reach out to our team for guidance on structuring your blueprints. Click to reveal email