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:

  • How to Use This — a preamble telling the implementer this is a design spec, not an implementation plan.
  • Overview — what's being built, for whom, the core value proposition. Derived from Vision + Intent.
  • Platforms & Surfaces — which product types the project targets and every surface the design covers.
  • Entity Model — every entity from Ontology with attributes, states, relationships, and its visual cues translated into actionable rules.
  • Personas & Roles — each persona's goals, expertise, and mental models.
  • Tasks & Flows — every task with trigger, entity touchpoints, ordered steps, and the screens that carry it.
  • Screen Inventory & Navigation — every screen from Architecture with its level, where it appears, its layout per surface, its purpose, and its route. Mini Apps listed as contained flows with their launchers. Followed by Why these templates and the navigation flow, described per surface.
  • Screen Composition — the shells (with their purpose and Why this pattern), then each page's zones and chips per surface, with the written what-and-why for every zone and chip, item actions, floating action buttons, and overlays.
  • Priority Rules — the conflict resolutions from Ontology.
  • 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. A surface that hasn't been designed yet is labeled exactly that — with an instruction not to invent its layout.

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 right panel shows Write Status: a per-layer checklist of which design files exist and which skill fills each, plus the project skill generator. That generator writes design/skill.md — a curated natural-language summary of the design decisions that Claude Code reads on every interaction while building, so it carries the design context without re-reading every JSON file. It regenerates automatically as the design files change.

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/project.json, design/vision.json, design/ontology.json, design/architecture.json, design/screens.json, and optionally your sources for context.
  • 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.

Platforms & Surfaces

Responsive web: designed for desktop web and mobile web. Every screen appears on both surfaces unless noted.

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 Scaling Ratio.

Screen Inventory & Navigation

Screen Level Layout Purpose Route
Recipes L1 card_grid : with_filters Browse and pick a recipe to scale /
Recipe L3 detail_page : with_aside Scale one recipe and save the ratio /recipe/:id
Preferences L1 settings : sectioned Units and rounding defaults /preferences

Navigation flow: Home Cook lands on Recipes, opens a card → Recipe, returns via the shell nav.

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 hub notes it when an upstream change lands, and the Write Status panel shows which files moved since the last run.

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