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.
  .gitignore                    Scaffolded if missing, with .denote/ entries appended.
  .claude/
    commands/                   Slash commands Claude Code finds when you type /<name>.
      vision.md
      ontology.md
      architecture.md
      screens.md
      spec.md
      critique.md
  .denote/                      Per-machine Denote state, gitignored.
    CLAUDE.user.md              Snapshot of build-mode CLAUDE.md while design mode is active.
  intelligence/                 Design knowledge the skills reason from.
    knowledge/
      design-systems/           Tokens, components, governance, surfaces, patterns
      interaction-design/       Disclosure, IA, workflows, design-tool patterns
      object-oriented-ux/       Entities, relationships, states, ontology
      philosophy/               Design philosophy
      product-strategy/         Opportunities, competition, metrics
      user-understanding/       JTBD, mental models, research
      visual-design/            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
    catalog/                    Generated JSON exports of system-level catalogs.
      template-variants.json
      pattern-library.json
      content-types.json
      shell-patterns.json
  design/                       Everything Denote's layers author.
    vision.json
    ontology.json
    architecture.json
    screens.json
    SPEC.md
    .denote/
      activity.jsonl            Append-only activity log, persists across sessions
  CLAUDE.md                     Regenerated on design mode toggle (custom rules preserved) or owned by you in build mode.

What each path is for

`.git/`

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

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

Safe to edit: yes, with standard git tooling.

`.gitignore`

Scaffolded on first open if missing. Denote appends two entries it insists on: design/.denote/ (activity log) and .denote/ (build-mode CLAUDE.md snapshot). If a .gitignore already exists, the missing entries are appended; nothing is removed. The rest of the file is yours.

Safe to edit: yes. Denote only ensures the two .denote/ entries are present.

`.denote/`

Project-root Denote state, separate from design/.denote/ (which holds the activity log). Currently one file:

CLAUDE.user.md — Snapshot of your build-mode CLAUDE.md, written when you toggle from build to design. Restored to CLAUDE.md when you toggle back to build. Deleted after a successful restore.

Only exists while design mode is active. Build mode "consumes" the snapshot on the way in.

Safe to edit: no. Denote owns the snapshot lifecycle. Gitignored because it's per-machine state.

`.claude/commands/`

Slash commands scaffolded into the project on every open. One per project-facing skill plus critique: vision.md, ontology.md, architecture.md, screens.md, spec.md, critique.md.

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

Safe to edit: no. These files may be overwritten on project open. They encode Denote app behavior, not designer intent. For per-project customization, use the intelligence/ layer (below) instead.

`intelligence/knowledge/`

The reference knowledge the skills and agents read before reasoning. 34 Markdown files organized into 7 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 opens. Edits are project-scoped; they don't 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.

`intelligence/catalog/`

Generated JSON exports of system-level catalogs that skills reference for canonical IDs and metadata:

template-variants.json — the 48-variant catalog (20 templates × 2–3 variants each).
pattern-library.json — the 20 templates with metadata.
content-types.json — the chip content-type catalog (icons, labels).
shell-patterns.json — the 5 shell patterns.

Regenerated by npm run build:catalog in the Denote source tree; copied into projects on scaffold.

Safe to edit: no — overwritten on the next scaffold. To customize, change the source TS in Denote and re-export.

`design/`

Everything Denote's layers author.

File	Layer	Written by	Notes
`vision.json`	Vision	`/vision`	Goals, constraints, non-goals, audience, competitive context, open questions, scratchpad
`ontology.json`	Ontology	`/ontology`	Single file: intent + entities (with inline visual cues, states, relationships) + personas + tasks + priority rules
`architecture.json`	Architecture	`/architecture`	Top-level `screens[]` (each with `template + variant`) + `edges[]` (typed navigation)
`screens.json`	Screens	`/screens`	Top-level `shells[]` + `compositions[]` (zones with content chips) + `globalOverlays[]`
`SPEC.md`	Spec	`/spec`	Design specification for the implementer. Fully regenerated each run.

Safe to edit: yes for the upstream .json files. Every file is human-readable JSON or Markdown. Denote picks up hand edits the next time the project is opened. Schemas are enforced on write; malformed hand edits may be rejected or flagged when a skill runs next. SPEC.md is regenerated on every /spec run — hand edits will be overwritten, so capture upstream changes in the relevant layer file instead.

`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, errors). Persists across sessions.

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

`CLAUDE.md`

Project-scoped instructions for Claude Code. Two distinct shapes depending on the project's current mode (controlled by the top-bar mode chip — see Design and Build mode).

Design mode (default). Denote-managed thinking-partner template, regenerated on project open and on every toggle into design mode. First line is the marker . Ends with a ## Custom Rules section that preserves anything you write below it across regenerations.
Build mode. Yours. First line is . The rest is whatever you put there. On first build switch, Denote writes a minimal starter; subsequent switches restore whatever you last had.

The marker contract. Denote reads the first  HTML comment to determine the project's current mode on load. If missing (legacy projects), Denote treats the project as being in design mode and adds the marker on the next regeneration.

Safe to edit:

In design mode, below the ## Custom Rules marker only. Anything above is regenerated; your edits are lost.
In build mode, anywhere. The whole file is yours; Denote snapshots it to .denote/CLAUDE.user.md when you switch back to design mode.

File formats

JSON for structured data. Two-space indent, UTF-8, no trailing commas. Schemas defined in src/shared/schemas/ in the Denote repository.
Markdown for prose (SPEC.md, CLAUDE.md, every file in .claude/commands/ and intelligence/). Standard GitHub-flavored Markdown.
JSON-Lines for the activity log. 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.
Ensures .gitignore contains design/.denote/ and .denote/. Creates the file if missing; appends missing entries if it exists.
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 .md files are preserved; intelligence/catalog/*.json files always overwrite (they're generated, not designer content).
Regenerates CLAUDE.md if the project is in design mode, preserving everything below the ## Custom Rules marker. Projects in build mode are left alone.

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 doesn't generate components, screens, routes, or any other code. Implementer territory.
Token files or style values. No tokens.json, no globals.css, no tailwind.config.ts. Denote captures zero aesthetic intent.
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 — common questions about project layout and editing.
Troubleshooting — what to do when a file seems wrong.
The two app model — the bigger picture of what writes to this tree and why.