Architecture

Three layers

┌─────────────────────────────────────────────────────────────┐
│  Agent Interface (AGENTS.md, CLAUDE.md)                     │
│  ─ How any LLM picks up this repo and behaves like a senior │
│    designer                                                 │
└─────────────────────────────────────────────────────────────┘
                             ▲
                             │ reads from
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  Skills + Agents + Commands                                 │
│  ─ Task-specific playbooks (skills/)                        │
│  ─ Persona-specific reviewers (agents/)                     │
│  ─ User-invocable shortcuts (commands/)                     │
└─────────────────────────────────────────────────────────────┘
                             ▲
                             │ cites
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  Knowledge Base (knowledge/)                                │
│  ─ Structured, deduplicated, model-readable                 │
│  ─ Generated by tools/extractors/ from refs/                │
│  ─ Hand-written overrides marked with `<!-- hand-written -->`│
└─────────────────────────────────────────────────────────────┘
                             ▲
                             │ derived from
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  Source Material (refs/)                                    │
│  ─ Sparse-cloned upstream design systems                    │
│  ─ READ-ONLY. Never edit.                                   │
│  ─ Refresh via `git -C refs/<repo> pull`                    │
└─────────────────────────────────────────────────────────────┘

Why model-agnostic?

The user invokes design work from multiple agent surfaces (Claude Code, Codex CLI, sometimes Cursor). Knowledge encoded in markdown + JSON survives across:

• Claude Code's skill system
• Codex CLI's AGENTS.md convention
• Generic prompt context for any LLM

Encoding the same knowledge as Claude-specific skill files would lock it in. We use the skill system for ergonomics, but the source of truth is plain markdown.

Knowledge file contract

Every file under knowledge/ follows this shape:

---
title: <human-readable title>
source: <upstream URL or "hand-written">
extracted_at: <ISO date, omit if hand-written>
applies_to: [<framework or scope tags>]
---

# <title>

<single, focused topic. Under 400 lines.>

If a file is generated, it must include the source path so a human can trace it back.

Extractor contract

Each extractor in tools/extractors/:

1. Reads from a single refs/<source>/ directory.
2. Writes to a single knowledge/<category>/ directory.
3. Is idempotent — running twice produces the same output.
4. Never overwrites files marked <!-- hand-written -->.
5. Documents its source paths in its own header.

Skill file contract

skills/<skill-name>/
├── SKILL.md          # Claude Code skill manifest (frontmatter + body)
├── PLAYBOOK.md       # Step-by-step process (read by any agent)
├── TEMPLATE.md       # Output template, if applicable
└── examples/         # Worked examples

Codex CLI reads PLAYBOOK.md directly. Claude Code uses SKILL.md for invocation, but both files share the same content — SKILL.md is PLAYBOOK.md with frontmatter wrapping.

Why not vector embeddings?

Considered, rejected for this version:

• Knowledge fits well under 50K tokens once curated. Direct file reads are faster and cheaper than vector retrieval.
• Markdown is grep-able and human-auditable. Vectors are not.
• Future: if knowledge grows past ~100K tokens, add an optional embedding index in tools/index/ without changing the source-of-truth layer.

Refresh cadence

Action	When
git -C refs/<repo> pull	Monthly, or when a new feature in upstream is referenced
./tools/extractors/run-all.sh	After any refs/ update
Hand-written knowledge/ review	Quarterly, or after major ecosystem shifts