Skip to content
Docs

Plan

Plan is the layer where every upstream decision becomes a build plan Claude Code can execute. It reads Vision, Extract, Map, Structure, Layout, and the aesthetic direction from Project Settings, then writes a single Markdown document. Plan is not a summary. It is a translation. Design concepts become engineering concepts. Entities become data models. Tasks become API flows. Pattern assignments become component choices. Architecture becomes routes.

What Plan captures

One file, rendered as Markdown. The sections follow a predictable shape so an engineer or a coding agent can act on it directly.

  • Overview. Problem, outcome, audience, build ambition (prototype or production).
  • Data model. Entities translated into data structures. Attributes become fields with types. States become enums. Relationships become associations or foreign keys.
  • API or data flow. Tasks translated into endpoints (production) or mock handlers (prototype). Mutations become POST or PUT or DELETE. Reads become GET. Branching becomes conditional logic.
  • Routes. Architecture nodes translated into URL routes with their personas and the components they host.
  • Component choices. Each pattern assignment translated into a concrete component composition, with the configuration from governance applied as props.
  • Layout strategy. Per-page region wireframes translated into CSS grid or flex structures, with named regions preserved. Shells become persistent layout wrappers.
  • Theming strategy. The aesthetic direction and the token source translated into a concrete approach: use shadcn defaults, tune shadcn from the direction at build, or import from a referenced file.
  • Out of scope. Non-goals from Vision translated into explicit exclusions so the agent does not go build them anyway.

The plan stands alone. An engineer who has never opened Denote can read design/plan.md and build from it without cross-referencing the other design files.

The canvas

Plan renders as a single-column Markdown document. No interactive graph, no region editor. The entire surface is the rendered plan.

A small status chip at the top shows:

  • Whether the plan is up to date with the upstream layers.
  • Which upstream layers have changed since the last plan generation.
  • A prompt to re-run /generate-plan if any upstream layer is ahead.

You do not usually edit the plan by hand. The plan is a derivative artifact. Editing it directly is possible, but the next /generate-plan run will overwrite those edits unless you capture the reasoning in an upstream layer (a new priority rule in Map, a new region in Layout).

The file written

Plan writes one file: design/plan.md. Plain Markdown. Human-readable, machine-readable, renderable in any viewer.

The file is deliberately Markdown rather than JSON because the audience is an engineer (or a coding agent acting as one). Markdown preserves ordering, supports prose, and formats code blocks for component snippets, data-model definitions, and route tables.

The skill

/generate-plan is the skill that writes the plan.

Reads:

  • design/vision.json, design/intent.json, design/entities.json, design/personas.json, design/tasks.json, design/governance.json, design/architecture.json, design/layout.json, design/aesthetic.json
  • If aesthetic.tokenSource.mode is referenced, the file at tokenSource.path as well

Writes:

  • design/plan.md

Behavior:

  • Decides the build ambition first. If you pass prototype or production as an argument, uses that. Otherwise infers from the audience and constraints in Vision. Asks once when genuinely ambiguous.
  • Translates rather than summarizes. The plan speaks in engineering terms: data models, endpoints, routes, components, CSS grid regions, theming strategies. It does not reference "the governance schema" or "the pattern assignments" because the reader does not need to know those exist.
  • Writes for an engineer who has not seen the design. Every concept is defined in the plan itself.
  • Handles partial input. If Layout is empty, the plan writes reasonable defaults from the pattern assignments and notes that layout decisions were defaulted. A partial plan is better than no plan.
  • Notes explicit exclusions. Non-goals from Vision become "out of scope" entries so the build does not drift.

Where the build ambition comes in

Denote's six structural layers are mode-agnostic. The same entities, patterns, and layouts feed either a prototype or a production build. The mode decision happens at plan generation time, not earlier.

  • Prototype. Clickable demo. Mock data in-memory or in-browser. No auth. No real API. The data model is expressed as TypeScript types. Tasks become client-side handlers. The plan emphasizes the interaction loop.
  • Production. Database. API. Auth. Full stack. The data model is expressed as database schema and ORM models. Tasks become real endpoints. The plan covers validation, auth, and error handling.

The mode is passed to /generate-plan as an argument or negotiated in conversation when the skill runs. Vision influences the default (a solo-designer validation project leans prototype; an audience mention of admin roles or compliance leans production), but the final call is yours.

The recipe example

The recipe portion calculator's upstream layers produce a plan like this. Abbreviated structure shown.

Overview

A small web app that lets a home cook scale any recipe to a target serving count, on a phone, with saved favorite ratios per recipe. Ambition: prototype (clickable demo, localStorage persistence, no backend).

Data model

type Recipe = {
  id: string
  name: string
  photo: string // URL or data URI
  sourceUrl?: string
  baseServings: number
  ingredients: Ingredient[]
  scalingRatios: ScalingRatio[]
}

type Ingredient = {
  name: string
  quantity: number
  unit: 'cup' | 'tsp' | 'tbsp' | 'g' | 'oz' | 'ml'
}

type ScalingRatio = {
  ratio: number
  targetServings: number
  savedAt: string
}

Routes

  • /, Recipes list. Home Cook lands here. Card grid.
  • /recipe/:id, Recipe detail with scaling control.
  • /preferences, Preferences page.

Component choices

  • Recipes list uses a card grid composed of shadcn Card with image-first header, title, and serving count.
  • Recipe detail uses an asymmetric wide-narrow layout. Main region: photo, scaled ingredient list, scaling control. Sidebar: saved scaling ratios as a small list.
  • Scaling control is a number input wired to a derived ingredient quantity calculation.
  • Inline ingredient edit uses an inline expansion surface.
  • Save-ratio confirmation uses a popover near the scaling control.

Theming

Token source: prompt. Tune shadcn from the aesthetic direction at build time. Direction: warm and unfussy, cream background rather than pure white, serif display for recipe names, clean sans-serif for instructions, soft shadows, generous radii, comfortable density.

Out of scope

  • Account, login, cloud sync. All data is local.
  • Recipe storage and discovery. The cook brings the recipe.
  • Meal planning, shopping lists, nutrition.
  • Unit conversion (cups to grams). Portion-only is the explicit scope.

The plan is short because the project is small. The shape of the plan is the same regardless of project size.

Staying in sync

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

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

Governance changed. Plan may be stale. Run /generate-plan to update.

You decide when to regenerate. Regeneration is a single skill invocation. Previous plans are overwritten (the commit history captures prior versions if the project is under version control).

What Plan is not for

  • New decisions. The plan translates decisions captured upstream. It does not invent data models that contradict Extract or routes that contradict Structure.
  • Hand-authored prose. Writing an essay in the plan risks drift with the upstream layers. If something needs to be said, capture it in the right upstream layer (a new constraint in Vision, a new priority rule in Map) and regenerate.
  • Token values. The plan names the theming strategy, not the actual hex values. Token values live at the token source.
  • Code. The plan describes what to build, not the code that builds it. Claude Code writes the code when it acts on the plan.

The discipline is that Plan is the handoff, not the authoring surface. Everything load-bearing is decided upstream.

Where to next