Skip to content
Docs

The intelligence system

The intelligence system is the body of design knowledge that ships with Denote and travels with every project. Thirty-four knowledge files encoding design philosophy and methodology, organized into seven categories. Seven skills that run inside Claude Code. Five agent definitions that orchestrate longer tasks. Together they are the reasoning layer behind extraction, pattern recommendation, critique, and code generation. They ship with Denote, and they are yours to edit.

Why Denote needs an intelligence system

A structure-first tool is only as good as the knowledge it brings to bear. Pattern recommendations are opinions. Governance rules encode judgment. Critique requires an aesthetic vocabulary. Without a coherent, editable knowledge base, every AI call would reach for a different source and the output would drift.

The intelligence system pins the knowledge in place. It is the source every skill and agent reads. When you run /extract, the skill reads the same extraction knowledge file Claude Code will read later when it builds. The thinking and the building are working from the same text.

What is in the system

The full system lives under intelligence/ inside your project directory and is copied there from Denote when the project is created.

Knowledge files (intelligence/knowledge/). Thirty-four Markdown files across seven categories: design-systems, interaction-design, object-oriented-ux, philosophy, product-strategy, user-understanding, and visual-design. Each file is a focused treatment of a single topic: visual hierarchy, typography systems, spatial systems, color theory, component anatomy, design tool patterns, OOUX methodology, governance principles, pattern catalogs, critique rubrics, and more. Every skill and agent declares which knowledge files it reads. Nothing is hidden in a prompt.

Skills (intelligence/skills/). Seven skills. /vision, /extract, /map, /structure, /layout, /generate-plan, and /critique. Each skill is a Markdown file with a role, inputs, outputs, and the knowledge files it needs. When you type a slash command in the embedded terminal, Claude Code loads the skill's Markdown and runs it.

Agents (intelligence/agents/). Five agent definitions. Design Builder (builds UI following the methodology), Design Critic (reviews UI against the knowledge), Craft Lead (audits the codebase for design system violations), plus two more. Agents are longer-form roles that wrap multiple skills and knowledge files, used when a single skill is not enough.

All three layers are plain Markdown. You can open any file in a code editor, read it, understand exactly what Claude Code will do, and edit it.

Two roles for the system

The intelligence system serves two audiences at once.

Inside Denote

When you work in a layer, the intelligence system powers the AI in that layer. The Vision sidebar's proposed items come from the /vision skill reading the vision knowledge files. The Map layer's pattern recommendations come from the /map skill reading the pattern catalog and governance principles. The critique results come from the Design Critic agent reading the critique rubrics.

The AI in the app is not freehanded. It is always grounded in the same knowledge files.

Inside Claude Code

When Claude Code builds, it reads the same knowledge files as project context. A project's CLAUDE.md points at intelligence/ and instructs Claude Code to follow the methodology and design system rules captured there.

This means the principles that guided the design now govern the implementation. The extraction methodology used to produce entities.json is the same methodology Claude Code uses when it reasons about the entities at build time. The visual hierarchy knowledge that drove Map's pattern assignments is the same knowledge Claude Code uses when it chooses which element should be the L1 focus on a page.

The design thinking and the building are literally reading from the same files.

The intelligence system is editable

The default system is opinionated. You can agree or disagree with it. Either way, you can change it.

Every knowledge file, skill, and agent under intelligence/ is a Markdown file in your project directory. You can:

  • Edit a knowledge file to change how a concept is described. Adjust the pattern catalog. Add a new pattern. Rewrite the critique rubric.
  • Edit a skill to change its inputs, outputs, or the knowledge files it reads. Add a new skill by dropping a Markdown file in intelligence/skills/.
  • Edit an agent to change how it orchestrates work. Add a new agent.

The edits persist. They affect both Denote (when you run the skill from the embedded terminal next time) and Claude Code (when it builds). There is no sync, no rebuild, no re-import. The files are the source of truth.

System-level versus project-level

The intelligence system ships with Denote as a starting point. When you create a project, Denote copies the current system into the project's intelligence/ folder. From that moment, the copy is yours.

  • System-level changes (edits to the Denote-wide defaults) only affect projects created in the future. Existing projects keep the copy they were seeded with.
  • Project-level changes (edits to intelligence/ inside a specific project) only affect that project. They travel with the project folder; they do not leak back into Denote's defaults.

This is the same shape as the governance schema: a default that is shared until a project decides otherwise. It gives you a clean, opinionated starting point without locking you into it.

The recipe example

The recipe portion calculator sample uses the default intelligence system as shipped. No edits.

When someone ran /extract on the Vision, the extraction skill loaded intelligence/knowledge/ooux-methodology.md and intelligence/knowledge/entity-modeling.md. The output (Recipe, Ingredient, Serving, ScalingRatio) is what those knowledge files produce.

When /map ran, the mapping skill loaded the pattern catalog and the governance principles. It fired the image-attribute visual cue on Recipe and assigned card_grid for the browse context. These assignments are directly traceable to the rules in those knowledge files.

When Claude Code later builds, it reads the same knowledge files. The typography decisions it makes on the detail page follow intelligence/knowledge/typography-systems.md. The spatial decisions follow spatial-systems.md. The recipe app and the knowledge files do not disagree, because they are the same text.

How to think about editing the system

Start by reading, not by editing. The defaults are opinionated. Understand the opinion first.

Edit when you disagree. If the critique rubric pushes back on a decision you know is right for your product, adjust the rubric. If a pattern in the catalog does not fit your domain, rewrite it or add one.

Edit when you specialize. A finance product, a developer tool, and a consumer utility draw on overlapping but different vocabulary. Add project-specific knowledge files to intelligence/knowledge/ for your domain.

Do not edit to remove opinions. An intelligence system without opinions is a prompt. The whole point of the system is that it takes a stance. Your edits should refine the stance, not erase it.

Where to next