Blueprint Quality Rubric

This is the review standard for every blueprint on SpecZip — the literal checklist reviewers use in the Pending Review step. Reviewers approve, reject, or request changes by citing specific checklist item IDs (e.g. SPEC-2).

How Reviewers Use This Rubric

Every submitted blueprint goes through the review queue. Admins walk this checklist item by item; the review screen links directly to each item below.

Rejections and change requests must cite specific checklist item IDs. A review that says “doesn’t meet standards” without an item reference is not actionable — a review that says “SPEC-2: FR-4 has no Acceptance block” is.

An A+ blueprint passes every item. Anything else does not ship.

The Checklist

SPEC.md — Master Specification5 checklist items Agent Context — .speczip/4 checklist items Phases & Tasks3 checklist items Packaging4 checklist items

SPEC.md — Master Specification

The master spec is the contract. It describes observable behavior and outcomes — never implementation.

SPEC-1

Overview is ≤5 sentences

States what the app does, who it is for, and the core differentiator. If it takes more than five sentences, the scope is probably unfocused.

SPEC-2

Requirements numbered FR-N with Acceptance blocks

Every functional requirement carries an FR-N identifier and an Acceptance block describing observable outcomes (Given/When/Then or an explicit bullet list).

SPEC-3

Non-functional requirements present

Performance, security, accessibility, and platform constraints are called out explicitly — at least where relevant.

SPEC-4

Out of Scope section included

Explicitly lists what the blueprint does not cover, so agents and buyers share the same expectations.

SPEC-5

No implementation detail

No file paths, component names, library APIs, CSS classes, or code. Blueprints are outcome specifications, not source code.

Agent Context — .speczip/

The .speczip/ files orient the building agent. They must be consistent with the SPEC and cheap to consume.

CTX-1

CONTEXT.md ≤500 words

The agent read-me-first file. An agent should be oriented in under a minute — anything longer is ignored.

CTX-2

tech-stack.json: name + role + version + reasoning

Every entry includes the technology name, its role (frontend, backend, database…), a version constraint, and why it was chosen.

CTX-3

data-model.json matches SPEC.md

Tables, columns, types, and relationships in the data model agree with the spec. A mismatch is an automatic reject.

CTX-4

requirements.json present

API keys (with purpose and free-tier availability), external services, and platform notes. Empty arrays are valid; the file is not.

Phases & Tasks

Complex blueprints are split into phases and tasks an agent can complete without guessing.

PHASE-1

Phases required above 60 minutes

Any blueprint estimated to build in more than 60 minutes is split into phases, each independently completable.

PHASE-2

Required task sections present

Every task file has: Context or Overview, Given/When/Then (or equivalent), File Ownership, Negative Constraints, Browser Validation, and Quality Gates.

PHASE-3

Exclusive file ownership

No two tasks write the same file. Each file has exactly one owning task per phase, so parallel agents never collide.

Packaging

The ZIP must validate and display correctly in the marketplace on first download.

PKG-1

manifest.json enums valid

Category and difficulty come from the canonical lists (see the Blueprint Format page). Free-text values are rejected.

PKG-2

changelog.md with a 1.0.0 entry

Initial uploads ship with a 1.0.0 entry at the top. Every subsequent version adds an entry before upload.

PKG-3

DESIGN.md for UI blueprints

Anything with a user interface ships a design system: colors, typography, layout, components, do's and don'ts. CLI tools and services are exempt.

PKG-4

Single top-level ZIP layout

All entries live under one top-level directory matching the blueprint slug. No loose files at the ZIP root, no nested wrappers.

The technical file and directory requirements behind these items are defined on the Blueprint Format page. Automated checks in the blueprint validator already enforce a subset of this rubric (file presence, manifest enums, task sections, ZIP layout); reviewers cover the judgment calls the validator cannot.

Disagree with a review decision?

Reply to the review with the checklist item IDs you believe your blueprint satisfies and why. Click to reveal email