Table of Contents generated with DocToc

spec-validator

Capability: substrate:framework-dev

Harness: agnostic

Validates spec files in tools/spec-loop/specs/ — the counterpart to tools/skill-and-tool-validator/ for the spec side of the framework.

Prerequisites

  • Runtime: Python 3.11+ run via uv; stdlib-only (no runtime dependencies). The dev group pulls pytest, ruff.
  • CLIs: None beyond the runtime.
  • Credentials / auth: None.
  • Network: Runs fully offline against local spec files.

What it checks

For every .md file that carries a YAML frontmatter block:

  1. Required frontmatter keys — title, status, kind, mode, source, acceptance.
  2. Valid status — stable | experimental | proposed | off.
  3. Valid kind — feature | fix | docs | chore.
  4. Valid mode — Triage | Mentoring | Drafting | Pairing | infra.
  5. Non-empty acceptance list — at least one - item entry.
  6. Required body sections — ## What it does, ## Where it lives, ## Behaviour & contract, ## Out of scope, ## Acceptance criteria, ## Validation.
  7. Validation section has a fenced code block — at least one ```…``` block so build-loop backpressure commands are always explicit.

Files without frontmatter (e.g. README.md, overview.md) are silently skipped — they are index/overview docs, not functional specs.

Usage

# Run against the default spec directory
uv run --project tools/spec-validator spec-validate

# Run against a specific directory or file
uv run --project tools/spec-validator spec-validate tools/spec-loop/specs/

# Run the test suite
uv run --project tools/spec-validator --group dev pytest
Suggest a change