Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ucsd-decorator",
"version": "2.3.0",
"version": "2.4.0",
"license": "MIT",
"description": "Build and edit UC San Diego web pages on the Decorator 5 design system without damaging the shared page chrome. Provides one writable canvas, a pinned source of truth for markup, and a CI-checkable chrome contract.",
"author": {
Expand Down
643 changes: 97 additions & 546 deletions .cursorrules

Large diffs are not rendered by default.

643 changes: 97 additions & 546 deletions .github/copilot-instructions.md

Large diffs are not rendered by default.

643 changes: 97 additions & 546 deletions AGENTS.md

Large diffs are not rendered by default.

32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,37 @@
# Changelog

## 2.4.0

### Changed

- **`CLAUDE.md` is half the size, and its detail moved to a new
`DECORATOR.md`.** The generated `CLAUDE.md` had grown to 49,901 characters,
past the 40,000 at which Claude Code warns that a memory file will impact
performance, and Claude Code loads all of it in every session. The rule files
now hold what must apply in every session, 24,739 characters. A section that
also carries measurements, tables, or a procedure for one kind of task keeps
its rule and ends with a line naming that task: "Before you copy a template,
read this section in full in `DECORATOR.md`." `DECORATOR.md` holds those
sections whole. Nothing imports it, because an `@` import loads at launch too
and would not have shrunk anything. `AGENTS.md`, `.cursorrules`, and the
Copilot instructions shrink the same way.
- **Component library READMEs compile into `DECORATOR.md`.** The rule files
keep the "Project component libraries" section, with what a library relaxes
and what it never does, and list each library with a pointer to its README.
- `sync` adds `DECORATOR.md` to a project an earlier release set up, where the
manifest does not list it yet.

### Added

- **On-demand markers in `rules/`.** `<!-- on-demand: before you … -->` inside a
section moves what follows it to `DECORATOR.md`. Above a rule's first
section, it moves the rest of the rule. `test/rules.test.mjs` checks that
every pointer lands on a section, and holds the compiled `CLAUDE.md` to
25,000 characters.
- `sync` and `check` print a note when a project's `canvas-rules/` push
`CLAUDE.md` past 40,000 characters. A marker in a project's canvas rule fails
`sync`, because those rules load in full.

## 2.3.0

### Added
Expand Down
645 changes: 98 additions & 547 deletions CLAUDE.md

Large diffs are not rendered by default.

731 changes: 731 additions & 0 deletions DECORATOR.md

Large diffs are not rendered by default.

46 changes: 37 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ canvas, runs `verify`, and suggests next prompts. Later sessions read

It works in Claude Code, Cursor, Copilot, and any agent that reads `AGENTS.md`,
because the interview is a rule — `rules/60-getting-started.md` — compiled into
every instruction file. For a chat AI with no kit installed, such as TritonGPT,
every instruction file, with its full text in `DECORATOR.md`. For a chat AI with no kit installed, such as TritonGPT,
paste the **Starter interview prompt** from the guide's
[Start here](https://developer.ucsd.edu/design/decorator/user-guide/#start)
section instead.
Expand Down Expand Up @@ -136,6 +136,11 @@ canvas rules" section at the end of `CLAUDE.md`, `.cursorrules`,
skips the README. Every tool picks the rules up the same way it picks up the
kit's, and `check` fails in CI if a file there changed without a `sync`.

Those files load in full in every session, so keep a canvas rule to what must
hold every time. `sync` and `check` print a note when a project's rules push
`CLAUDE.md` past 40,000 characters, the size at which Claude Code warns that it
will impact performance.

The compiled section limits those rules to the canvas and ranks them below the
kit's own. A rule file that anyone can add is not a review, so a chrome
instruction in one gets refused rather than followed, just like a chrome
Expand All @@ -151,13 +156,14 @@ saying when and how to use it.
```
canvas-components/
shadcn/
README.md compiled into the rule files by sync
README.md compiled into DECORATOR.md by sync
dist/app.css
dist/app.js
```

`sync` compiles each library's README into a "Project component libraries"
section. That section relaxes three Decorator look-and-feel rules inside the
`sync` lists each library in a "Project component libraries" section of the
rule files, and compiles its README into `DECORATOR.md`, where agents read it
before using the library. That section relaxes three Decorator look-and-feel rules inside the
canvas: agents may use the library's components and classes, its icon set, and
its heading styles. Typography stays on brand (Roboto, Teko, Brix Sans, or
Refrigerator Deluxe), and no chrome,
Expand Down Expand Up @@ -265,7 +271,7 @@ templates/ Dependabot config, workflow, and the canvas-rules/
and canvas-components/ READMEs written into projects
scripts/lib/rules.mjs the renderer, shared by the CLI and the compiler
scripts/compile-rules.mjs rules/ -> CLAUDE.md, AGENTS.md, .cursorrules,
.github/copilot-instructions.md
.github/copilot-instructions.md, DECORATOR.md
scripts/check-library.mjs validates library/ against the sync contract
scripts/pin-decorator.mjs dependency-free Decorator pinning, npm only
contracts/ portable chrome regions, selector rules, and
Expand All @@ -279,8 +285,8 @@ test/ including the AGENTS.md refusal, the replayed
RELEASING.md how a version reaches npm
```

`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md`
are **generated**. Edit `rules/` and run:
`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`, and
`DECORATOR.md` are **generated**. Edit `rules/` and run:

```bash
node scripts/compile-rules.mjs
Expand All @@ -289,16 +295,38 @@ node scripts/compile-rules.mjs
`--check` verifies the committed output is current; `npm test` runs it along with
the library contract and the CLI tests.

### What loads every session, and what loads on demand

Claude Code loads all of `CLAUDE.md` at the start of every session and warns
once it passes 40,000 characters, and an `@` import would not help, since an
imported file loads at launch too. So the four rule files hold only what must
hold in every session. Detail that one kind of task needs, such as measurements,
tables, or a procedure, goes below a marker in its section of `rules/`:

```md
<!-- on-demand: before you copy `two-column.html` or `three-column.html` -->
```

The rule files keep what sits above the marker and, in place of the rest, a
line telling the agent to read that section in full in `DECORATOR.md` before
that task. `DECORATOR.md` gets the whole section, and nothing imports it. A
marker above a rule's first section moves the rest of that rule. Write the
trigger as the task, starting "before you" or "when". `test/rules.test.mjs`
holds the compiled `CLAUDE.md` to 25,000 characters, leaving a project's
canvas rules room under the warning. Past that, move detail behind a marker
rather than raise the budget.

## Using the skill without the CLI

**Claude Code** — install as a plugin (`/plugin marketplace add UCSD/decorator-kit`),
or copy `skills/ucsd-decorator/` into a project's `.claude/skills/`.

**Cursor, Copilot, Antigravity** — the compiled instruction files are picked up
automatically once present at the project root.
automatically once present at the project root, with `DECORATOR.md` beside
them.

**Any tool that reads `AGENTS.md`** — read this repository's copy in place, in a
checkout beside your project. Do not copy it in: your repository's own
checkout beside your project, along with the `DECORATOR.md` it points to. Do not copy it in: your repository's own
`AGENTS.md`, if it has one, is the more specific contract and the more important
of the two. `add` will not write that file for the same reason.

Expand Down
79 changes: 63 additions & 16 deletions bin/cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,14 @@ import { execFileSync } from "node:child_process";
import { cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { CANVAS_COMPONENTS_DIR, CANVAS_RULES_DIR, renderRuleFiles } from "../scripts/lib/rules.mjs";
import {
CANVAS_COMPONENTS_DIR,
CANVAS_RULES_DIR,
MEMORY_FILE_WARN_CHARS,
ON_DEMAND_FILE,
TARGETS,
renderRuleFiles,
} from "../scripts/lib/rules.mjs";

// Installs the UC San Diego Decorator contract into a project.
//
Expand All @@ -18,8 +25,9 @@ import { CANVAS_COMPONENTS_DIR, CANVAS_RULES_DIR, renderRuleFiles } from "../scr
//
// ── Why `add` exists, and why it will not write AGENTS.md ──────────────────
//
// The kit compiles one rule set into four files, one per tool. Three of those
// names are unambiguous. `AGENTS.md` is not: it is also the conventional name
// The kit compiles one rule set into four files, one per tool, plus the
// DECORATOR.md all four point into. Three of those four names are
// unambiguous. `AGENTS.md` is not: it is also the conventional name
// for a repository's own agent contract, and a project that already has one has
// something more specific and more important than this kit's generic rules.
//
Expand Down Expand Up @@ -175,14 +183,49 @@ async function writeManifest(managed) {

async function renderFor(managedOnly) {
const exclude = managedOnly ? [] : [PROJECT_CONTRACT];
const { outputs } = await renderRuleFiles({
return renderRuleFiles({
rulesDir: RULES_DIR,
note: NOTE,
exclude,
canvasRulesDir: path.join(cwd, CANVAS_RULES_DIR),
canvasComponentsDir: path.join(cwd, CANVAS_COMPONENTS_DIR),
});
return outputs;
}

const RULE_FILES = new Set(TARGETS.map((target) => target.file));

/**
* The paths `sync` and `check` operate on: the manifest's list, plus
* DECORATOR.md wherever a rule file is managed.
*
* DECORATOR.md arrived in 2.4.0, and every rule file points into it. A project
* an earlier release set up lists the rule files in `manages` and not this
* one, and `sync` touches nothing outside that list — so it would refresh
* CLAUDE.md and leave every pointer in it aimed at a file that isn't there.
*/
function managedPaths(manifest) {
const manages = [...manifest.manages];
if (!manages.includes(ON_DEMAND_FILE) && manages.some((entry) => RULE_FILES.has(entry))) {
manages.push(ON_DEMAND_FILE);
}
return manages;
}

/**
* Say so when a project's own canvas rules or libraries push CLAUDE.md past
* the size Claude Code warns about. It loads all of CLAUDE.md in every
* session; the kit's own rules stay well under this, so the rest is the
* project's.
*/
function warnIfLarge(outputs, projectChars) {
const size = outputs.get("CLAUDE.md")?.length ?? 0;
if (size <= MEMORY_FILE_WARN_CHARS) return;
const chars = (count) => count.toLocaleString("en-US");
console.log("");
console.log(`Note: CLAUDE.md is ${chars(size)} characters. Claude Code loads all of it in every`);
console.log(`session and warns about a memory file over ${chars(MEMORY_FILE_WARN_CHARS)}. Of that, ${CANVAS_RULES_DIR}/`);
console.log(`adds ${chars(projectChars.canvasRules)} and ${CANVAS_COMPONENTS_DIR}/ adds ${chars(projectChars.componentLibraries)}. Keep in ${CANVAS_RULES_DIR}/ only what`);
console.log("must hold in every session.");
}

async function scaffoldCanvasDirectories() {
Expand Down Expand Up @@ -399,7 +442,7 @@ async function init() {
const decoratorInstalled = install([DECORATOR_PACKAGE]);
const kitInstalled = install([KIT_SPEC]);

const outputs = await renderFor(true);
const { outputs } = await renderFor(true);
for (const [relativePath, contents] of outputs) await put(relativePath, contents, { force: true });
await publishSkill();
await scaffoldCanvasDirectories();
Expand Down Expand Up @@ -438,7 +481,7 @@ async function init() {
}

async function add() {
const outputs = await renderFor(false);
const { outputs } = await renderFor(false);
for (const [relativePath, contents] of outputs) await put(relativePath, contents);
await publishSkill();
await scaffoldCanvasDirectories();
Expand Down Expand Up @@ -517,34 +560,38 @@ async function managedFiles() {

async function sync() {
const manifest = await managedFiles();
const managesContract = manifest.manages.includes(PROJECT_CONTRACT);
const outputs = await renderFor(managesContract);
const manages = managedPaths(manifest);
const managesContract = manages.includes(PROJECT_CONTRACT);
const { outputs, projectChars } = await renderFor(managesContract);
for (const [relativePath, contents] of outputs) {
if (!manifest.manages.includes(relativePath)) continue;
if (!manages.includes(relativePath)) continue;
await put(relativePath, contents, { force: true, allowContract: managesContract });
}
if (manifest.manages.includes(SKILL_DEST)) await publishSkill();
await writeManifest(manifest.manages);
if (manages.includes(SKILL_DEST)) await publishSkill();
await writeManifest(manages);
console.log("");
printReport();
console.log("");
console.log(
`Managed files are current with ucsd-decorator-kit@${VERSION}, ${CANVAS_RULES_DIR}/, and ${CANVAS_COMPONENTS_DIR}/.`,
);
warnIfLarge(outputs, projectChars);
}

async function check() {
const manifest = await managedFiles();
const outputs = await renderFor(manifest.manages.includes(PROJECT_CONTRACT));
const manages = managedPaths(manifest);
const { outputs, projectChars } = await renderFor(manages.includes(PROJECT_CONTRACT));
const stale = [];
warnIfLarge(outputs, projectChars);

for (const [relativePath, contents] of outputs) {
if (!manifest.manages.includes(relativePath)) continue;
if (!manages.includes(relativePath)) continue;
const current = await readFile(path.join(cwd, relativePath), "utf8").catch(() => null);
if (current !== contents) stale.push(relativePath);
}

if (manifest.manages.includes(SKILL_DEST)) {
if (manages.includes(SKILL_DEST)) {
const destination = path.join(cwd, SKILL_DEST);
if (!(await exists(destination))) stale.push(`${SKILL_DEST}/`);
else {
Expand Down Expand Up @@ -580,7 +627,7 @@ async function check() {
process.exitCode = 1;
return;
}
console.log(`${manifest.manages.length} managed paths are current with ucsd-decorator-kit@${VERSION}.`);
console.log(`${manages.length} managed paths are current with ucsd-decorator-kit@${VERSION}.`);
}

async function drift() {
Expand Down
18 changes: 10 additions & 8 deletions library/tritonai/ucsd-decorator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,9 @@ canvas, name the file and the region, and stop. When asked to record a canvas
rule, add a file there and run `sync` — never edit the compiled section.

**Component libraries live in `canvas-components/`,** one folder per library
with a `README.md`, compiled in by `sync` under "Project component libraries".
When that section exists, you may build canvas UI from those libraries — their
with a `README.md`. `sync` lists them under "Project component libraries" in
the rule files and compiles each README into the project's `DECORATOR.md` —
read a library's section there before using it. When that section exists, you may build canvas UI from those libraries — their
classes, icons, and the headings inside their components — instead of only
Decorator ones. Typography stays on brand: Roboto, Teko, Brix Sans, or
Refrigerator Deluxe. Library styles stay inside the
Expand Down Expand Up @@ -174,12 +175,13 @@ template, never from recall.
## Starting a new project

When a developer asks to get started — "help me get started", "where do I
begin", "start a new project" — run the kickoff interview in the project
rules ("Getting started — the kickoff interview", from
`rules/60-getting-started.md`) before writing any markup. Ask its six questions
in one message, recommend a layout and modules with links to the Decorator Kit
Developer Guide at `https://developer.ucsd.edu/design/decorator/user-guide/`,
let the developer pick the layout, save `BRIEF.md`, then build. Where
begin", "start a new project" — run the kickoff interview before writing any
markup. Its full text is "Getting started — the kickoff interview" in the
project's `DECORATOR.md`, compiled from the kit's `rules/60-getting-started.md`.
Ask its six questions in one message, recommend a layout and modules with links
to the Decorator Kit Developer Guide at
`https://developer.ucsd.edu/design/decorator/user-guide/`, let the developer
pick the layout, save `BRIEF.md`, then build. Where
`AskUserQuestion` is available, use it for the multiple-choice questions — it takes up to four per call.

## Building a page
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "ucsd-decorator-kit",
"version": "2.3.0",
"version": "2.4.0",
"type": "module",
"description": "Agent-facing contract for building on the UC San Diego Decorator 5 design system.",
"keywords": [
Expand Down
Loading
Loading