> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentic-spec validate: Component Spec Validation Command

> agentic-spec validate checks a spec directory against 14 rules — identity, token cascade, metadata sanity, and honesty gates. Non-zero exit on errors.

`validate` is the primary command. Run it before every component edit and in CI. It checks a spec directory against all 14 rules and tells you, rule by rule, what passes and what does not.

## Usage

```bash theme={null}
agentic-spec validate <spec-dir>

# Single component
agentic-spec validate specs/button

# All components at once
agentic-spec validate specs/*

# Machine-readable output for CI
agentic-spec validate specs/button --json
```

## Options

| Flag | Description |
| - | - |
| `--json` | Output results as a JSON array instead of human-readable text. Use this in CI pipelines and scripted agent workflows. |

## Output examples

### Passing spec

```text theme={null}
PASS button (specs/button)
  tokens: 15 in contract, 15 in tokens.json · states: 6 · parts: 5
```

A passing spec prints one line per directory. Counts show how many tokens, interaction states, and semantic parts were checked.

### Spec with warnings

```text theme={null}
PASS button (specs/button)
  warn  orphan-token-entry     tokens.json entry "button.legacy" is not referenced by token_contract
```

Warnings do not cause a non-zero exit code. They do block `AI-Ready` promotion — a component with active warnings cannot have all `checks:` set to `true`.

### Failing spec

```text theme={null}
FAIL badge (specs/badge)
  error missing-token-entry    Spec lists "badge.bg.invalid" in token_contract but tokens.json has no entry (token_contract → badge.bg.invalid)
  error ai-ready-gate          status is AI-Ready but checks.tokens_valid is false
```

Each error includes the rule name, a plain-English description, and the specific value that triggered it. Look the rule name up in the [contract rules reference](https://clementineds.mintlify.site/concepts/contract-rules.md) for a fix.

### JSON output (for CI)

```json theme={null}
[
  {
    "component": "button",
    "path": "specs/button",
    "result": "pass",
    "errors": [],
    "warnings": [
      {
        "rule": "orphan-token-entry",
        "message": "tokens.json entry \"button.legacy\" is not referenced by token_contract"
      }
    ]
  }
]
```

Use `--json` whenever another tool needs to consume the results programmatically.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | All specs pass, or issues are warnings only |
| Non-zero | At least one error across any spec checked |

## CI integration

Add `validate` as a step in your CI workflow. Use `--json` and parse the output if you want fine-grained reporting, or rely on the exit code for a simple pass/fail gate:

```yaml theme={null}
# Example GitHub Actions step
- name: Validate specs
  run: npx agentic-spec validate specs/* --json
```

A non-zero exit code fails the step and blocks the merge. This keeps broken specs out of `main`.

## The 14 rules

`validate` checks four categories of rules. See the [contract rules reference](https://clementineds.mintlify.site/concepts/contract-rules.md) for the full list and fix instructions.

| Category | Rules checked |
| - | - |
| Identity and structure | `missing-spec`, `missing-tokens`, `no-frontmatter`, `bad-frontmatter`, `identity-mismatch` |
| Token cascade | `missing-token-entry`, `orphan-token-entry`, `bad-token-tier`, `bad-token-path`, `missing-token-role` |
| Metadata sanity | `bad-status`, `bad-date`, `future-date` |
| Honesty gates | `lying-check`, `ai-ready-gate` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.