agents and mcp

Agents get the same gates humans use in CI, exposed in files they read first. If an agent can find the contract, it can follow it.

---

File map (consumer project)

File	Role
AGENTS.md (repo root)	Mandatory SpecUI block from specui init
.specui/AGENTS-GUIDE.md	CLI commands, workflow, rules/skills/MCP
.specui/AGENT-DESIGN-RULES.md	7-step sync protocol (normative)
.specui/DOS-DONTs.md	High-leverage do / don't
.specui/SPEC.md + readOrder	Scope and reading sequence
rules/*.md	Custom design rules (specui rules)
skills/*/SKILL.md	Agent playbooks (specui skills)

Per-editor stubs (optional, from init --agent-tools):

Tool	File
Cursor	.cursor/rules/specui.mdc
Claude Code	CLAUDE.md
GitHub Copilot	.github/copilot-instructions.md
Gemini	GEMINI.md
Windsurf	.windsurfrules

Every stub points back to AGENTS.md and .specui/AGENT-DESIGN-RULES.md, so there is one canonical source no matter which editor is in play.

---

Enable on init

npx specui init \
  --agents-md \
  --agent-tools cursor,claude,copilot \
  --starter-kit

Flag	Effect
--agents-md / --no-agents-md	Write SpecUI block to AGENTS.md (default: on)
--agent-tools	Comma list: cursor, claude, codex, copilot, gemini, windsurf
--starter-kit	Seed bundled rules + skills
--seed-rules / --seed-skills	Finer control over bundled templates

To refresh a stale AGENTS.md block, the simplest path is to re-run init in a scratch directory and copy the block over, or open .specui/AGENTS-GUIDE.md and the canonical block from templates/agent-blocks/ and paste it in. init against the current project will refuse to overwrite an existing .specui/ unless you pass --force (which replaces the whole contract).

validate checks that the block is present and matches the current template.

---

Agent workflow (summary)

1. Read AGENTS.md and .specui/AGENTS-GUIDE.md
2. Read the component/pattern folders for the task
3. specui add before any new UI
4. Implement using semantic tokens only
5. specui validate .specui && specui sync
6. Commit .specui/ with the code

The full steps live in .specui/AGENT-DESIGN-RULES.md.

---

Custom rules

List templates:

npx specui rules templates

Add from a template (works in a flat repo or a project with .specui/):

npx specui rules add no-raw-hex --from no-raw-hex
npx specui rules list
npx specui rules show no-raw-hex

Remove:

npx specui rules remove no-raw-hex

Rules live in rules/ at the SpecUI root (flat repo) or as configured for your layout. validate can surface rule issues.

---

Custom skills

Skills are multi-step procedures — register a component, sync design to code, and so on:

npx specui skills templates
npx specui skills add register-new-component --from register-new-component
npx specui skills list

Bundled examples: register-new-component, sync-design-to-code, audit-color-contrast, audit-empty-states, generate-component-spec, theme-diff, tokenize-hardcoded-values.

---

MCP server

SpecUI ships a stdio MCP server so MCP-aware clients can call validate, sync, spec, and friends directly instead of shelling out.

Print the config JSON:

npx specui mcp config

Start the server (stdio):

npx specui mcp start

Install into an editor config:

npx specui mcp install-hook cursor
# also: claude, codeium, windsurf, continue

Restart the editor after install-hook.

HTTP transport is not implemented yet (mcp start --http errors).

---

AI/LLM-friendly docs

The docs site is built so agents and crawlers can ingest every page without parsing HTML. Five pieces work together:

Endpoint	What it is
/llms.txt	Index of every docs page plus a short project summary, grouped by section. This is the entry point LLMs should read first.
/llms-full.txt	The whole docs site as one plain-markdown file — every page concatenated with its title and canonical URL. One fetch, no chrome.
/docs-md/<slug>	A single page as plain markdown. Append .md mentally to any docs URL — /docs/install → /docs-md/install.
/robots.txt	Explicitly allows GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, anthropic-ai, Google-Extended, PerplexityBot, Amazonbot, Bytespider, CCBot, and the standard search bots.
/docs/<slug>/ HTML	Each rendered page carries JSON-LD TechArticle markup and a <link rel="alternate" type="text/markdown" href="/docs-md/<slug>"> tag, so crawlers and agents can find the canonical markdown.

/llms.txt is the recommended starting point; /llms-full.txt is for agents that want the entire corpus in one request. Point your agent at either:

https://logicplanes.github.io/specui/llms.txt
https://logicplanes.github.io/specui/llms-full.txt

The MCP server above (specui mcp start) is the runtime counterpart — for agents that want to call validate, sync, spec, and friends directly instead of reading the docs. Read this page first, then point the agent at the endpoints above for an in-context copy of the standard.

---

Machine-readable validate

For agents and CI parsers:

npx specui validate .specui --json --strict

Exit code 1 when findings include errors (or warnings with --strict).

---

Print the normative standard

npx specui spec
npx specui spec --json

Handy when an agent needs the full SpecUI standard text without browsing the web.

---

Next steps

• Validation — finding types and --strict
• CI/CD — gate PRs
• Scenarios — agent-first