AGENTS.md & llms.txt | Cynosure Design System

Overview

The Cynosure Design System ships two machine-readable context files that give AI coding tools accurate, up-to-date knowledge about the system's conventions:

File	Location	Format	Purpose
`AGENTS.md`	Site root (`/AGENTS.md`)	Markdown	Full AI coding tool context — project structure, component anatomy, JS/SCSS conventions, tokens, build commands
`llms.txt`	Site root (`/llms.txt`)	Plain text	LLM-optimized summary — stack, token values, block list, shared utilities, doc links

AGENTS.md

AGENTS.md is designed for AI coding assistants that read a context file from the project root. It gives the AI enough knowledge to generate correct Cynosure components without additional explanation.

It contains:

Code

# Cynosure Design System — AGENTS.md

## Project structure       # directory layout: src/handoff/, js/, blocks/, components/, pages/
## Component anatomy       # 4-file structure (.js config, template.hbs, style.scss, script.js)
## Handlebars conventions  # Bootstrap utilities, property bindings, template rules
## JavaScript conventions  # two-layer architecture, @shared annotation, multi-instance pattern
## SCSS conventions        # c- BEM prefix, token usage, @public/@export aliases
## Design tokens           # key CSS custom property names and values
## Figma MCP workflow      # how to pull design context using the Figma Desktop MCP
## WordPress integration   # handoff-wordpress CLI and config
## Build commands          # npm run start, build:components, fetch
## Key files               # paths to main.js, main.scss, handoff.config.js, theme.css
## Common mistakes         # hardcoded colors, missing @shared docs, wrong class patterns

Downloading AGENTS.md

Bash

curl -O https://cynosure.handoff.com/AGENTS.md

Or download directly.

Using with Cursor

Bash

# Place at the root of your implementation project
cp AGENTS.md /path/to/your/wordpress-theme/AGENTS.md

Then in Cursor, reference it with @AGENTS.md in any chat message. Or pin it permanently for files that match the Cynosure patterns:

Markdown

<!-- .cursor/rules/cynosure-design-system.md -->
---
globs: ["**/*.hbs", "**/script.js", "**/style.scss", "**/*.php"]
---
@AGENTS.md

Using with GitHub Copilot

GitHub Copilot reads AGENTS.md from the repository root automatically in agent mode. In Copilot Chat, reference it explicitly:

Code

Please read AGENTS.md in the project root before answering — it contains the 
Cynosure Design System conventions for components, JavaScript, and SCSS.

Using with Claude Code

Claude Code reads AGENTS.md automatically from the project root when it detects the file. No additional configuration is needed.

llms.txt

llms.txt follows the llms.txt specification — a plain text file at the site root that summarizes a project's content in a format optimized for LLM consumption.

The Cynosure llms.txt is structured as:

Code

# Cynosure Design System

> Stack description

## Stack
[template engine, CSS framework, JavaScript approach, build tool]

## Design Tokens
[token CSS file URLs and key values]

## Blocks
[list of all block names and one-line descriptions]

## Shared JavaScript Utilities
[every file in js/components/ with trigger and purpose]

## Components
[list of element components]

## Documentation
[links to all guideline and foundation pages]

## WordPress Integration
[handoff-wordpress CLI reference]

## Build Commands
[npm run start, build:components, fetch]

Using llms.txt for prompting

Bash

# Fetch the current llms.txt
curl https://cynosure.handoff.com/llms.txt > cynosure-context.txt

# Include as context in a prompt
cat cynosure-context.txt | pbcopy
# Paste into ChatGPT or Claude as context before your question

Or reference it directly in a prompt:

Code

Please read https://cynosure.handoff.com/llms.txt for context on the 
Cynosure Design System before answering my question about this component.

Keeping these files up to date

Both files should be regenerated when:

New blocks or components are added or removed
Brand color tokens change in Figma (run npm run fetch)
New shared JavaScript utilities are added to js/components/
Build commands or project structure changes

The files are maintained in src/handoff/AGENTS.md and src/handoff/public/llms.txt. A future enhancement would auto-generate them as part of npm run build:app.