spec-print

A printspec is like a 3D printer file for software: any agent, anywhere, reading the same spec must produce equivalent working software. When this skill is invoked, your job is to build the software (print command) or reverse-engineer the spec (create command) — not just render docs.

---

Commands

• /spec-print <spec> — Print (build) software from an existing printspec. See "Print Command" below.
• /spec-print create — Reverse-engineer a printspec from the current codebase. See "Create Command" below.

---

Canonical Printspec Format

Every printspec — whether written by hand or generated by create — MUST follow this format exactly. Sections are required unless marked optional. Order is fixed.

# <Project Name> Printspec

> **Version:** <semver>
> **Runtime:** <e.g. Node 22+, Python 3.12+, Bun 1.x>
> **Primary datastore:** <e.g. SQLite, Postgres, in-memory>
> **Output directory:** <relative path, e.g. `./src` or `.`>

One-paragraph description of what this software does and its core purpose.

---

## Entities

For each entity:

### <EntityName>

| Field | Type | Required | Default | Notes |
|-------|------|----------|---------|-------|
| id    | UUIDv7 | yes | generated | primary key |
| ...   | ...  | ...      | ...     | ...   |

**Indexes:** `<field>` (unique), `<field, field>` (composite), ...
**Lifecycle states:** `DRAFT → ACTIVE → ARCHIVED` (list all valid states)

---

## Functional Requirements

Numbered `FR-NNN`. Priority: P1 (must), P2 (should), P3 (nice).

| ID | Priority | Behavior | Inputs | Outputs | Errors |
|----|----------|----------|--------|---------|--------|
| FR-001 | P1 | <what it does> | <params> | <return value> | <error codes> |
| FR-002 | P1 | ... | ... | ... | ... |

---

## Command / API Surface

| ID | Method | Path / Name | Request Schema | Success | Errors |
|----|--------|-------------|----------------|---------|--------|
| CMD-001 | POST | /resource | `{ field: string }` | 201 | validation_error |
| CMD-002 | GET  | /resource/:id | — | 200 | not_found |

---

## State Machine

### <EntityName> States

```
INITIAL → STATE_A [guard: <condition>]
STATE_A → STATE_B [guard: <condition>]
STATE_B → TERMINAL [guard: <condition>]
STATE_A → FAILED [guard: any error]
```

**Terminal states:** `TERMINAL`, `FAILED`
**Invalid transitions:** any not listed above must throw `invalid_transition`

---

## Determinism Contracts

These rules are absolute. Any agent printing this spec must produce identical behavior.

| Contract | Rule |
|----------|------|
| ID format | UUIDv7, generated at creation time |
| Timestamp format | RFC3339 UTC milliseconds |
| Name validation | `/^[a-z][a-z0-9_-]{2,63}$/` |
| Sort order | `<field> ASC NULLS LAST` |
| Default page size | 20 |
| Max retries | 3, exponential backoff base 500ms |
| Rate limit | <N req/min per user> |

---

## Error Contract

This set is closed. No agent may add or remove codes.

| Code | HTTP | Meaning |
|------|------|---------|
| `validation_error` | 400 | Input failed schema validation |
| `not_found` | 404 | Resource does not exist |
| `duplicate_resource` | 409 | Unique constraint violated |
| `invalid_transition` | 422 | State machine guard rejected |
| `rate_limit_exceeded` | 429 | Too many requests |
| `internal_error` | 500 | Unexpected failure |

---

## Test Plan

Tests MUST be implemented in this order: broken → failure → happy.

| ID | Order | Fixture | Scenario | Assertion |
|----|-------|---------|----------|-----------|
| T-001 | broken | `fixture-missing-field.json` | missing required field | throws `validation_error` |
| T-002 | failure | `fixture-duplicate.json` | duplicate name | throws `duplicate_resource` |
| T-003 | happy | `fixture-valid.json` | valid creation | returns entity with id |

---

## Design & Style

Describes the visual and UX language of the application. Any agent printing this spec must produce UI that matches this profile.

| Attribute | Value |
|-----------|-------|
| UI framework | e.g. React, Vue, SwiftUI |
| Component library | e.g. shadcn/ui, MUI, Tailwind UI, none |
| CSS approach | e.g. Tailwind v4, CSS Modules, styled-components |
| Color scheme | e.g. neutral base + blue accent; dark mode first |
| Typography | e.g. Inter, system-ui; scale: sm/base/lg/xl |
| Spacing system | e.g. 4px base unit, Tailwind default scale |
| Border radius | e.g. rounded-md globally, pill on badges |
| Icon set | e.g. Lucide, Heroicons, custom SVG |
| Motion / animation | e.g. subtle fade transitions, no motion if prefers-reduced-motion |
| Layout pattern | e.g. sidebar + content, stacked cards, data table |
| Tone | e.g. minimal, dense, playful, enterprise |
| Notable conventions | e.g. destructive actions always red, empty states always illustrated |

---

## Appendix — Constants

These values are law. Never change them in code.

```
MAX_NAME_LENGTH = 64
MIN_NAME_LENGTH = 3
DEFAULT_PAGE_SIZE = 20
MAX_PAGE_SIZE = 100
MAX_RETRIES = 3
BACKOFF_BASE_MS = 500
```

---

Create Command

Invocation: /spec-print create [<output-path>] [-- <scope/focus guidance>]

When create is the argument, reverse-engineer a canonical printspec from the current codebase.

Step 1 — Explore

Using the Glob, Grep, and Read tools, systematically discover:

1. Project identity — package.json / pyproject.toml / Cargo.toml / etc. for name, version, runtime, dependencies
2. Data model — schema files (*.prisma, *.sql, migration files, ORM models, type definitions representing persisted entities)
3. API / command surface — route files, controllers, CLI command definitions, RPC handlers
4. Business logic — service files, domain logic, state machines (look for status, state, enum fields with lifecycle names)
5. Error handling — error classes, error code enums, HTTP status mappings
6. Validation — validators, schema objects (zod, joi, yup, pydantic, etc.), regex constants
7. Tests — test files to extract fixture names and scenario coverage
8. Constants — any file named constants, config, or containing uppercase SCREAMING_SNAKE_CASE values
9. Design & Style — tailwind.config.*, globals.css, theme files, component library config, design tokens, and representative UI components/pages to understand visual language, layout patterns, color scheme, typography, spacing, and interaction style

Explore broadly first (Glob for structure), then drill into key files (Read for content). Do not stop at surface level — follow imports to find the real logic. For design, read at least 3–5 representative UI components or pages to establish patterns — do not infer style from config alone.

Step 2 — Infer

From what you found, infer:

• Entities: fields, types, required/optional, indexes (from unique constraints or index definitions), lifecycle states (from status enums or state machine code)
• FRs: every distinct behavior exposed by the API or service layer — assign P1/P2/P3 based on whether it appears critical (auth, CRUD core), supporting (filtering, pagination), or optional (export, nice-to-have)
• Commands: every HTTP route or CLI command with its method, path, request schema, and response
• State machine: reconstruct from status field values + transition guards in code
• Determinism contracts: extract validation regex, sort clauses, defaults, retry logic, rate limit config
• Error contract: extract all error codes/strings from the codebase — enumerate them exhaustively
• Test plan: from existing tests, extract fixture names and scenarios; classify each as broken/failure/happy
• Constants: collect all uppercase constants with their values
• Design & Style: identify UI framework, component library, CSS approach, color scheme (base + accent, dark/light mode), typography (font family + scale), spacing system, border radius, icon set, animation style, layout patterns, and any notable visual conventions — read actual component/page files, not just config

If something cannot be confidently inferred, mark it ⚠ INFERRED: with your best guess, or ⚠ UNKNOWN: if truly opaque.

Step 3 — Draft

Produce the full printspec following the Canonical Printspec Format above exactly. Rules:

• Use the exact section order and table schemas from the canonical format
• Assign sequential IDs: FR-001, FR-002, ...; CMD-001, ...; T-001, ...
• Every inferred value that isn't explicit in code gets a ⚠ INFERRED: annotation inline
• Every gap (missing validation, ambiguous state transition, undocumented error) gets a ⚠ SPEC GAP: annotation
• Do not invent behavior — only document what exists or can be directly inferred

Step 4 — Write

Write the spec to <output-path> if provided, otherwise to <project-name>.spec.md in the current directory.

Then print a summary:

SPEC CREATED
============
Source:   <cwd>
Output:   <output path>
Entities: <count>
FRs:      <count> (P1: N, P2: N, P3: N)
CMDs:     <count>
States:   <list all state machine states found>
Errors:   <count codes>
Tests:    <count> (broken: N, failure: N, happy: N)
Constants: <count>

⚠ Inferred values: <count> — review before treating as authoritative
⚠ Spec gaps: <count> — listed inline in spec

---

Print Command

Invocation: /spec-print <path-to-spec> | <spec-content> [-- <additional guidance>]

Additional Guidance

The user may append natural language guidance after the spec path/content using -- as a separator:

/spec-print path/to/spec.md -- use Postgres instead of SQLite; skip all tests for now
/spec-print path/to/spec.md -- add rate limiting to all endpoints

If additional guidance is present:

• Parse it as overrides or amendments to the spec
• Apply it during Phase 2 (plan) and Phase 3 (build) — it takes precedence over spec defaults where they conflict
• In the BUILD PLAN, list all active guidance under an Amendments: section
• In the BUILD VERIFICATION, list applied guidance under Amendments applied:
• Never silently ignore guidance — if a directive is ambiguous or conflicts with a hard spec contract (e.g. error codes, state machine), flag it as ⚠ GUIDANCE CONFLICT: and ask the user to clarify before proceeding

Phase 1 — Parse the Spec

The user will provide either:

• A file path to a .spec.md or .md file — read it with the Read tool first.
• Inline spec content — use it directly.

Internally extract and hold onto:

• All entities and their fields, indexes, lifecycle states
• All FRs with behavior, inputs, outputs, and errors
• All commands/APIs with request schema, success codes, error codes
• The full state machine: every state, every transition, every guard, every terminal state
• All determinism contracts (validation rules, ID formats, ordering, defaults, retry policy, rate limits)
• All error codes (immutable set)
• All test cases in broken → failure → happy order
• All constants

---

Phase 2 — Plan the Build

Before writing a single file, produce a concise build plan:

BUILD PLAN
==========
Project: <name>
Output directory: <cwd or path from spec>

Structure:
  <list the files/modules you will create, one per line>

Build order:
  1. Data model / schema
  2. Core domain logic + state machine
  3. Services / business logic
  4. API / command surface
  5. Error handling (all codes)
  6. Tests (broken → failure → happy)
  7. Entry point / wiring

Constants to enforce: <list>
Determinism contracts to enforce: <list>
Amendments: <list any active additional guidance, or "none">

Ask the user to confirm the output directory and tech stack if not specified in the spec. If the spec specifies a runtime (e.g. "Node 22+", "SQLite"), use it.

---

Phase 3 — Build

Implement the software. Rules:

Must implement

• Every FR listed in the spec — no skipping P1s without explicit user approval
• Every command/API in the command surface table
• Every error code in the error contract, with the exact code string as specified
• The complete state machine with all transitions and guards exactly as specified
• Every entity in the data model with correct fields, indexes, and lifecycle states
• All determinism contracts (validation regex, ID format, sort order, defaults, rate limits)

Code rules

• Constants from the spec's appendix go into a single constants file/module — they are law
• State machine transitions must be implemented as an explicit transition table or guard function — no implicit/ad-hoc state changes
• Error codes must be a closed enum/object — no string literals scattered through the code
• All IDs use the format specified (e.g. UUIDv7)
• All timestamps use the format specified (e.g. RFC3339 UTC milliseconds)
• Ordering/sorting must match the spec's ordering rules exactly

Test rules

• Implement every test case from the spec's test plan
• Order: broken → failure → happy — never change this order
• Each test uses the fixture name from the spec (create fixture files with the exact names listed)
• Each test asserts the exact failure assertion from the spec

What not to do

• Do not add features not in the spec
• Do not add error codes not in the spec's error contract
• Do not add state transitions not in the spec's state machine
• Do not change constants — they are law

---

Phase 4 — Verify

After building, self-check against the spec:

BUILD VERIFICATION
==================
✓/✗  All FRs implemented:     FR-001 FR-002 ...
✓/✗  All CMDs implemented:    CMD-001 CMD-002 ...
✓/✗  All error codes present: validation_error duplicate_resource ...
✓/✗  State machine complete:  QUEUED STARTING RUNNING PAUSED COMPLETED FAILED CANCELLED
✓/✗  All tests written:       T-001 T-002 ... (broken→failure→happy order)
✓/✗  All constants defined:   <list>
✓/✗  Determinism contracts:   name regex, ID format, sort order, defaults
✓/✗  Amendments applied:      <list each guidance item and how it was applied, or "none">

PRINT COMPLETE
==============
Source: <path or "inline">
Files written: <count>
FRs: <count>  CMDs: <count>  Tests: <count>  Constants: <count>
This software was produced from a printspec. Another agent printing the same spec should produce equivalent software.

Flag any spec gaps (missing fields, ambiguous behavior, underspecified transitions) as ⚠ SPEC GAP: items at the end of the verification block.