validation

specui validate is the quality gate for every SpecUI contract. If it passes with --strict, the contract is in good shape; if it doesn't, the output tells you exactly what to fix.

---

Basic usage

npx specui validate .specui
npx specui validate .specui --strict
npx specui validate .specui --json

The path can be:

• A directory: .specui or ./my-app/.specui
• A file inside the contract: validate resolves to the parent folder

For a flat repo, validate from the root where SPEC.md lives:

npx specui validate .

---

Flags

Flag	Effect
--strict	Treat warnings as errors (recommended in CI)
--json	Emit structured findings for tooling
--no-contrast	Skip WCAG contrast checks on TOKENS.yaml
--no-agents-check	Skip AGENTS.md block checks
--target <path>	Explicit contract root

---

What gets checked (overview)

Area	Examples
Required files	SPEC.md, numbered 00–11, AGENT-DESIGN-RULES.md, AGENTS-GUIDE.md, legal files
readOrder	Front matter matches the expected file list
Registry	Component/asset/pattern folders, manifests, broken links
SPEC front matter	Required components/patterns from the preset exist
Tokens	Structure, placeholders, optional contrast
AGENTS.md	SpecUI block present, current, attribution intact
Custom rules	Project rules/ consistency
Catalog drift	Lists in 04-components.md vs the filesystem

Findings come in three severities: error (fails the build), warn (fails with --strict), and info.

---

sync vs validate

Command	Purpose
sync	Rebuild registry.json, report link errors
validate	Full schema + policy checks

Typical sequence after edits:

npx specui sync && npx specui validate .specui --strict

---

doctor

A human-friendly summary before you dig into validate output:

npx specui doctor
npx specui doctor --json   # forwards JSON validate output

It reports the layout (consumer vs flat), AGENTS.md status, counts, rules/skills, sources — then runs validate.

Exits 1 if validate fails.

---

CI recommendation

npx -y @logicplanes/specui@latest validate .specui --strict

See CI/CD.

---

Fixing failures

See Troubleshooting for common codes and fixes.

---

Next steps

• Schema — file-level reference
• Specification — normative rules
• Agents & MCP — --json for agents