Name: SpecUI
Author: SpecUI

AGENTS.md, the .specui agent docs, custom rules and skills, and the specui MCP server.

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)

Read AGENTS.md and .specui/AGENTS-GUIDE.md
Read the component/pattern folders for the task
specui add before any new UI
Implement using semantic tokens only
specui validate .specui && specui sync
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

Agents & MCP