Project file structure

A Denote project is a folder on disk with a known shape. Every file is plain text (Markdown or JSON). Every directory has a specific role. This page is the full tree, annotated with what writes each file, what reads it, and whether you can edit it by hand.

The full tree

my-project/
  .git/                         Initialized on first open if missing.
  .claude/
    commands/                   Slash commands Claude Code finds when you type /<name>.
      vision.md
      extract.md
      map.md
      structure.md
      layout.md
      style.md
      generate-plan.md
  intelligence/                 Design knowledge the skills reason from.
    knowledge/
      design-systems/           11 files on tokens, components, governance, surfaces
      interaction-design/       5 files on patterns, disclosure, IA, workflows
      object-oriented-ux/       5 files on entities, relationships, states, ontology
      philosophy/               1 file on design philosophy
      product-strategy/         4 files on opportunities, competition, metrics
      user-understanding/       3 files on JTBD, mental models, research
      visual-design/            5 files on hierarchy, typography, spacing, color
    skills/
      critique/
      design-system-audit/
      flow-mapping/
      ia-audit/
      object-model/
      product-spec/
      visual-critique/
    agents/
      craft-lead.md
      design-builder.md
      design-critic.md
      product-strategist.md
      ux-architect.md
  design/                       Everything Denote's layers author.
    vision.json
    intent.json
    entities.json
    personas.json
    tasks.json
    governance.json
    architecture.json
    layout.json
    aesthetic.json
    plan.md
    skill.md                    Auto-generated summary for Claude Code
    .denote/
      activity.jsonl            Append-only activity log, persists across sessions
  CLAUDE.md                     Regenerated on every project open, custom rules preserved

What each path is for

`.git/`

Every Denote project is a git repository. Denote runs git init on the project folder on first open if .git/ is missing, because Claude Code uses the git root to locate .claude/commands/.

You are expected to commit the design files. The commit history is the project's design history.

Safe to edit: yes, with standard git tooling.

`.claude/commands/`

Slash commands scaffolded into the project on every open. Seven files, one per project-facing skill: vision.md, extract.md, map.md, structure.md, layout.md, style.md, generate-plan.md.

These files define the prompt instructions Claude Code executes when you type /<name> in the embedded terminal.

Safe to edit: no. These files are overwritten on every project open. They encode Denote app behavior, not designer intent. If you want to change a command's behavior, edit Denote's source and re-seed the project. For per-project customization, use the intelligence/ layer (below) instead.

`intelligence/knowledge/`

The reference knowledge the skills and agents read before reasoning. Thirty-four Markdown files organized into seven categories. Each file is a focused treatment of a single topic.

Safe to edit: yes. Idempotent scaffolding only copies files that don't already exist in the project, so your edits are preserved across project opens. Edits are project-scoped; they do not leak back into Denote's defaults.

`intelligence/skills/`

Seven reasoning skills that commands invoke: critique, design-system-audit, flow-mapping, ia-audit, object-model, product-spec, visual-critique. Each has its own directory with a SKILL.md and optional supporting files.

Safe to edit: yes. Same idempotent scaffolding as knowledge/.

`intelligence/agents/`

Five agent definitions for longer-form roles: craft-lead.md, design-builder.md, design-critic.md, product-strategist.md, ux-architect.md.

Safe to edit: yes. Same idempotent scaffolding.

`design/`

Everything Denote's layers author. One file per layer plus two supporting files.

File	Layer	Written by	Notes
`vision.json`	Vision	`/vision`	Goals, constraints, non-goals, audience, competitive context, open questions, scratchpad
`intent.json`	Extract	`/extract`	Problem, outcome, jobs-to-be-done
`entities.json`	Extract	`/extract`	Entities with attributes, states, relationships
`personas.json`	Extract	`/extract`	Personas with goals, frequency, tech comfort, mental models
`tasks.json`	Extract	`/extract`	Tasks as directed graphs of steps
`governance.json`	Map	`/map`	Visual cues, pattern assignments, mental models, priority rules
`architecture.json`	Structure	`/structure`	Nodes (pages) and edges (navigation)
`layout.json`	Layout	`/layout`	Shells, per-page region wireframes, surface patterns
`aesthetic.json`	Style (Project Settings)	`/style`	Aesthetic direction, references, mood, density, tokenSource pointer
`plan.md`	Plan	`/generate-plan`	Final build plan for Claude Code
`skill.md`	(derivative)	auto	Natural-language summary Claude Code reads first

Safe to edit: yes. Every file is human-readable JSON (or Markdown for plan.md and skill.md). Denote picks up hand edits the next time the project is opened. The schemas are enforced on write; malformed hand edits may be rejected or flagged when a skill runs next.

`design/.denote/`

Denote's internal state for the project. Currently one file: activity.jsonl (append-only JSON-Lines log of skill runs, file writes, renames, deletions, dangling-reference warnings, and errors). Persists across sessions.

Safe to edit: no. You can read the log, but Denote appends to it automatically. Manual edits risk corrupting the log format and are not preserved.

`CLAUDE.md`

Project-scoped instructions for Claude Code. Regenerated on every project open based on the files in .claude/commands/, intelligence/, and design/skill.md. A "Custom Rules" marker at the bottom separates the generated content from your own additions.

Safe to edit: yes, below the ## Custom Rules marker. Anything you write below that marker is preserved on regeneration. Anything above it will be overwritten.

File formats

JSON for structured data. Two-space indent, UTF-8, no trailing commas. Every schema is defined in src/shared/schemas/ in the Denote repository; the files under design/ validate against those schemas.
Markdown for prose (plan.md, skill.md, CLAUDE.md, every file in .claude/commands/ and intelligence/). Standard GitHub-flavored Markdown.
JSON-Lines for the activity log (design/.denote/activity.jsonl). One JSON object per line, append-only.

What changes at scaffold time

When you open a project (new or existing), Denote runs scaffoldProject:

Runs git init if .git/ is missing.
Overwrites every file in .claude/commands/ from Denote's current source. Local edits are lost.
Copies missing files from Denote's intelligence/ into the project's intelligence/. Existing files are preserved.
Regenerates CLAUDE.md, preserving everything below the ## Custom Rules marker.

It does not touch design/ at scaffold time. Your design files are only ever written by explicit skill runs or by your own edits.

What Denote never writes

Source code. Denote does not generate components, pages, routes, or any other code. That is Claude Code's job.
Token files. No tokens.json, no globals.css, no tailwind.config.ts. Token values live in the target environment. design/aesthetic.json records only a pointer.
Build artifacts. No dist/, no build/, no compiled output.
Dependencies. No package.json changes, no node_modules/, no lockfiles.

If you see any of those paths, they were created by your build tooling (Claude Code, npm, your editor), not by Denote.

Where to next

FAQ for common questions about project layout and editing.
Troubleshooting for what to do when a file seems wrong.
The two app model for the bigger picture of what writes to this tree and why.