Skip to content
Docs

Spec

Spec is the hand-off. Once Vision, Ontology, Architecture, and Screens are populated, you run /spec in the terminal. Claude Code reads every design/*.json file and writes a single design/SPEC.md — a complete design specification another Claude Code session, running in the target project, can read to build the product.

The Spec is not an implementation plan. It doesn't pick a tech stack, prescribe a database schema, define routes, or specify HTTP endpoints. Those decisions belong to the implementer. Denote's contribution ends at the design spec.

What the Spec captures

One Markdown file, design/SPEC.md, with predictable sections:

  • Overview — what's being built, for whom, the core value proposition. Derived from Vision + Intent.
  • Entity Model — every entity from Ontology with attributes, states, relationships.
  • Personas & Roles — each persona's goal, expertise, mental model, scope.
  • Tasks & Flows — every task with trigger, entity touchpoints, ordered steps, state transitions.
  • Screen Inventory & Navigation — every screen from Architecture with hierarchy level, template + variant, path. Plus how users move between them.
  • Screen Compositions — per screen: the zones from Screens (each filled with content chips), the visual cues from Ontology that apply (trait → treatment), priority rules that resolve conflicts.
  • Missing Design Data — what was empty or missing, and what section it would have informed.

Every section starts with a _Source: design/<layer>.json_ pointer so the implementer can trace any claim back to canonical data.

The canvas

[Screenshot TODO: Spec panel showing the recipe portion calculator's SPEC.md rendered — How to Use This preamble visible, an Entity Model table for Recipe, and the start of the Screen Inventory table.]

The Spec panel is a read-only Markdown preview. The entire surface is the rendered SPEC.md — tables, headers, code blocks. It updates live when the file changes on disk (every time /spec runs).

If design/SPEC.md doesn't exist yet, the panel shows an empty state with a prompt to run /spec.

The file written

design/SPEC.md — plain Markdown. Human-readable, machine-readable, renderable in any viewer.

Markdown rather than JSON because the audience is an implementer (Claude Code, or a person). It preserves ordering, supports prose, formats tables, renders cleanly anywhere.

The Spec is fully regenerated each time /spec runs. The previous SPEC.md is overwritten — no merge. Upstream layer files are the source of truth; the Spec is a projection.

The skill

/spec writes the Spec.

  • Reads: design/vision.json, design/ontology.json, design/architecture.json, design/screens.json.
  • Writes: design/SPEC.md.

Behavior:

  • Writes for an implementer who hasn't seen the design. Every concept is defined in the spec itself.
  • Stays in design vocabulary. Entities have attributes and relationships — not columns and foreign keys. Tasks have triggers and steps — not endpoints and request shapes. Screens have hierarchy levels and zones — not routes and middleware.
  • Is concrete, not abstract. "The Expense entity has attributes: amount (number), category (one of: food, travel, office, other)" — not "model the expense entity."
  • Cites every section's source file.
  • Handles partial input. Missing data is recorded in Missing Design Data.

Design vocabulary, not engineering vocabulary

The deliberate boundary that distinguishes the Spec from older "build plan" formats:

Design vocabulary (Spec) Engineering vocabulary (NOT in the Spec)
Entity attribute with type number SQL INTEGER, Prisma Int, TS number
Entity state sequence draft → submitted → approved Database enum, state-machine library
Task with trigger and steps HTTP endpoint, request shape, controller
Screen at level L1 / L2 with template + variant Route definition, router config, middleware
Visual cue has_image → card with thumbnail shadcn Card import, CSS class names
Zone arrangement filters + grid CSS grid template, Flexbox config

The implementer translates the right column from the left. They know the stack — Drizzle or Prisma, react-router or TanStack Router, raw CSS or Tailwind. The Spec doesn't anticipate any of that.

The recipe example

The recipe-scaling tool produces a SPEC.md that looks roughly like this (abbreviated):

Overview

A small web app that lets a home cook scale any recipe to a target serving count on a phone, with optional saved scaling ratios.

Entity Model — Recipe

Attribute Type Required Notes
name text yes Identity
photo text (URL) no Primary visual identity
baseServings number yes Original serving count

Relationships: has many Ingredient, has many ScalingRatio.

Screen Inventory & Navigation

Screen Level Template : Variant Path
Recipes L1 card_grid : with_filters /
Recipe L2 detail_page : with_aside /recipe/:id
Preferences L1 settings : sectioned /preferences

Navigation flow: Home Cook lands on Recipes, taps a card → Recipe, returns via back.

Screen Composition — Recipe

  • Zones: header (Heading, Image), body (IngredientList, ScalingControl), aside (SavedRatios).
  • Cues: has_image → card with thumbnail, has_identity → name as primary label.
  • Per-screen overlay: "save ratio" → popover.

Missing Design Data

  • No screenTouchpoints on the Browse saved scalings task. Implementer should default to the Recipes screen.

The Spec is short because the project is small. The structure is the same regardless of project size.

Staying in sync

The Spec is a derivative. When an upstream layer changes, the Spec is stale.

The activity feed logs a hint when an upstream change lands:

Architecture changed. Spec may be stale. Run /spec to update.

You decide when to regenerate. Previous spec is overwritten; commit history captures prior versions if the project is under version control.

What the Spec is not for

  • New decisions. The Spec projects decisions captured upstream.
  • Hand-authored prose. Capture it in the right upstream layer; regenerate.
  • Implementation detail. Tech stack, database, routing, auth. Implementer territory.
  • Code. The Spec describes the product; the implementer writes the code.

The discipline: the Spec is the hand-off, not the authoring surface.

Where to next