Compound 🧠

Efficient project knowledge and design system management. Retrieve context fast, store learnings without bloat, maintain consistent UI across pages.

Commands

Compound Retrieve

Goal: Get relevant context in <30 seconds with minimal token waste.

Step 1: Index Scan

# List all knowledge files (cached mentally for the session)
find docs -name "*.md" -type f 2>/dev/null | head -50

Step 2: Keyword Extraction

From the current ticket/task, extract 3-5 keywords:

• Entity names (User, Auth, API)
• Technical terms (JWT, WebSocket, migration)
• Domain concepts (billing, notifications)

Step 3: Targeted Grep

# Search for keywords in docs (parallel, fast)
grep -ril "keyword1\|keyword2\|keyword3" docs/ | head -10

Step 4: Smart Read

• Small files (<100 lines): Read fully
• Large files: Read only matching sections (grep -B2 -A5)
• Index files (README, index.md): Skim for pointers

Step 5: Relevance Filter

Only load knowledge that’s directly applicable:

• ✅ “JWT refresh tokens expire after 7 days” (for auth task)
• ❌ “We chose React over Vue” (not relevant to auth)

Output: Mental model of relevant project context, ready to apply.

Compound Store

Goal: Persist valuable learnings without creating duplicates or bloat.

Step 1: Identify Storable Knowledge

Only store what code comments can’t capture:

• ✅ Why we chose X over Y (decision rationale)
• ✅ Non-obvious gotchas discovered during implementation
• ✅ Cross-component relationships not visible in one file
• ✅ External API quirks, rate limits, undocumented behavior
• ❌ What the code does (that’s what code is for)
• ❌ How to run commands (put in README or AGENTS.md)

Step 2: Duplicate Check (CRITICAL)

Before writing ANYTHING, search for existing coverage:

# Check if topic already exists
grep -ril "topic keyword" docs/

# Check similar filenames
find docs -name "*keyword*" -type f

If found:

• Read the existing file
• UPDATE it rather than create new
• Merge new info into existing sections
• Add/update the updated: frontmatter date

Step 3: Choose Location

Step 4: File Format

---
tags: [searchable, terms, here]
updated: 2024-01-23
related: [../arch/auth.md, ../patterns/error-handling.md]
---

# Clear Descriptive Title

## Context
[Why this knowledge exists - 1-2 sentences]

## Key Points
- Bullet points for scannability
- One concept per bullet
- Include specifics (numbers, names, versions)

## Examples (if applicable)
[Code or scenarios that illustrate the point]

## See Also
- [Related doc](../path/to/related.md)

Step 5: Size Management

Per-file limits:

• Target: 50-150 lines per file
• Max: 200 lines (split if larger)
• One focused topic per file

Folder hygiene:

# Check folder sizes periodically
find docs -name "*.md" | wc -l  # Should stay <50 files

# Find potential duplicates (similar names)
ls docs/**/*.md | sort | uniq -d

If docs/ grows too large (>50 files):

1. Consolidate related small files
2. Archive obsolete knowledge to docs/_archive/
3. Merge overlapping content

Compound Design

Goal: Maintain consistent UI across all pages through tracked design tokens, patterns, and component decisions.

Design System Location

All design system knowledge lives in docs/design/:

Compound Design Retrieve

Before building ANY UI component:

# Check for design system folder
ls docs/design/ 2>/dev/null

# Load tokens first (always required)
cat docs/design/tokens.md 2>/dev/null

# Load component patterns if building components
cat docs/design/components.md 2>/dev/null

# Load layout patterns if building pages
cat docs/design/layout.md 2>/dev/null

If no design system exists: Run mise-en-place Phase 2, or create one during first UI work. Don’t proceed with UI without establishing tokens.

Compound Design Store

After making UI decisions, persist them to docs/design/.

Step 1: Check for existing design system

ls docs/design/ 2>/dev/null

If exists, UPDATE the relevant file. If not, create the structure.

Step 2: Store tokens in docs/design/tokens.md

---
updated: 2024-01-23
---

# Design Tokens

## Colors
| Token | Value | Usage |
|-------|-------|-------|
| `--color-primary` | oklch(55% 0.18 250) | CTAs, links, active states |
| `--color-surface` | oklch(98% 0.01 250) | Card backgrounds |
| `--color-text` | oklch(20% 0.02 250) | Body text |
| `--color-muted` | oklch(50% 0.01 250) | Secondary text |
| `--color-border` | oklch(90% 0.01 250) | Borders, dividers |
| `--color-error` | oklch(55% 0.2 25) | Error states |
| `--color-success` | oklch(55% 0.15 145) | Success states |

## Typography
| Token | Value | Usage |
|-------|-------|-------|
| `--font-display` | 'Instrument Serif', serif | Headings |
| `--font-body` | 'Inter', sans-serif | Body text |
| `--font-mono` | 'JetBrains Mono', monospace | Code |
| `--text-xs` | 0.75rem | Small labels |
| `--text-sm` | 0.875rem | Secondary text |
| `--text-base` | 1rem | Body text |
| `--text-lg` | 1.125rem | Emphasis |
| `--text-xl` | 1.25rem | Subheadings |
| `--text-2xl` | 1.5rem | Headings |

## Spacing
| Token | Value | Usage |
|-------|-------|-------|
| `--space-1` | 0.25rem | Tight groupings |
| `--space-2` | 0.5rem | Related items |
| `--space-4` | 1rem | Default gap |
| `--space-6` | 1.5rem | Medium separation |
| `--space-8` | 2rem | Section separation |
| `--space-12` | 3rem | Large separation |
| `--space-16` | 4rem | Major divisions |

## Border Radius
| Token | Value | Usage |
|-------|-------|-------|
| `--radius-sm` | 4px | Buttons, inputs |
| `--radius-md` | 8px | Cards |
| `--radius-lg` | 12px | Modals |
| `--radius-full` | 9999px | Avatars, pills |

## Shadows
| Token | Value | Usage |
|-------|-------|-------|
| `--shadow-sm` | 0 1px 2px oklch(0% 0 0 / 0.05) | Subtle elevation |
| `--shadow-md` | 0 4px 6px oklch(0% 0 0 / 0.1) | Cards |
| `--shadow-lg` | 0 10px 15px oklch(0% 0 0 / 0.1) | Modals, dropdowns |

## Breakpoints
| Token | Value | Usage |
|-------|-------|-------|
| `--bp-sm` | 640px | Mobile landscape |
| `--bp-md` | 768px | Tablet |
| `--bp-lg` | 1024px | Desktop |
| `--bp-xl` | 1280px | Wide desktop |

Step 3: Store component patterns in docs/design/components.md

---
updated: 2024-01-23
---

# Component Patterns

## Buttons
- **Primary**: solid bg `--color-primary`, white text
- **Secondary**: border only, `--color-primary` border/text
- **Ghost**: no border, subtle hover bg
- **Destructive**: `--color-error` bg, white text
- All: `--radius-sm`, `--space-2` `--space-4` padding

## Cards
- `--color-surface` bg, `--radius-md`
- Padding: `--space-4` to `--space-6`
- Border: 1px `--color-border`
- NO nested cards, NO excessive shadows

## Forms
- Labels above inputs, `--space-1` gap
- Inputs: 1px border, `--radius-sm`, `--space-2` padding
- Focus: 2px ring `--color-primary`
- Error: border `--color-error`, message below

## Navigation
- Header height: 64px
- Sidebar width: 280px (collapsible to 64px)
- Active state: `--color-primary` accent

Step 4: Store layout patterns in docs/design/layout.md

---
updated: 2024-01-23
---

# Layout Patterns

## Container
- Max-width: 1280px
- Padding: `--space-4` (mobile), `--space-8` (desktop)

## Page Layouts
- **Sidebar**: 280px fixed left, fluid content
- **Stacked**: header, main content, footer
- **Centered**: max-width content, centered

## Grid
- 12-column base grid
- Gap: `--space-4` default
- Responsive: 1 col mobile, 2-3 col tablet, 4+ col desktop

Compound Design Sync

When working on a new page in existing project:

1. Load the design system first

   cat docs/design/tokens.md docs/design/components.md docs/design/layout.md 2>/dev/null
   

2. Verify consistency before writing UI

   • Use exact token names from tokens.md (e.g., var(--color-primary))
   • Follow component patterns from components.md
   • Match layout conventions from layout.md

3. Update design system if extending

   • Adding a new color? Update docs/design/tokens.md
   • New component variant? Update docs/design/components.md
   • New layout pattern? Update docs/design/layout.md
   • Never create one-off values—extend the system or reuse existing

Design System Anti-Patterns

❌ Hardcoding values instead of tokens

/* Wrong */
color: #3b82f6;
padding: 16px;

/* Right - use established tokens */
color: var(--color-primary);
padding: var(--space-md);

❌ Creating inconsistent component variants

/* Wrong - different button styles per page */
<button className="rounded-lg px-4">  {/* Page A */}
<button className="rounded-md px-6">  {/* Page B */}

/* Right - one consistent pattern */
<Button variant="primary">

❌ Ignoring existing design system

# Wrong - building UI without checking
# Just start coding...

# Right - always check first
cat docs/design/tokens.md
# Then build using those tokens

❌ Storing design tokens in code comments

/* Wrong - tokens scattered in code */
/* Primary color: #3b82f6, spacing: 16px */

/* Right - centralized in docs/design/tokens.md */

❌ Creating tokens outside the system

/* Wrong - one-off values */
padding: 18px;
color: #4a7c59;

/* Right - use or extend the system */
padding: var(--space-4);  /* existing token */
/* Or add to docs/design/tokens.md first */

Anti-Patterns

❌ Creating near-duplicate files

docs/gotchas/auth-issues.md
docs/gotchas/authentication-problems.md  # DUPLICATE!

❌ Storing obvious information

# How to Start the Server
Run the dev server command  # This belongs in README/AGENTS.md!

❌ Huge monolithic files

docs/knowledge.md  # 500 lines of everything

❌ Vague file names

docs/notes.md
docs/stuff.md
docs/misc.md

❌ Forgetting to update existing files

# Wrong: Create new file
touch docs/gotchas/jwt-issue-2.md

# Right: Update existing
edit docs/gotchas/jwt-refresh-edge-cases.md

Quick Reference

Retrieve Checklist

• List docs structure
• Extract task keywords
• Grep for relevant files
• Read only what’s needed
• Apply context to task

Store Checklist

• Is this code-external knowledge?
• Search for existing coverage
• Update existing OR create focused new file
• Add frontmatter (tags, updated, related)
• Keep file <150 lines
• Verify no duplicates created

Design Retrieve Checklist

• Check for docs/design/ folder
• Load tokens.md first (always required)
• Load components.md if building components
• Load layout.md if building pages
• If no design system, run mise-en-place or create one

Design Store Checklist

• Check if docs/design/ exists
• Create folder structure if missing
• Store tokens in tokens.md
• Store component patterns in components.md
• Store layout patterns in layout.md
• Update updated: date in frontmatter

Design Sync Checklist

• Load all design files before new page
• Use exact token names (var(--color-primary))
• Follow component patterns exactly
• If extending: update the appropriate file in docs/design/
• Never use hardcoded values—extend the system