Table of Contents generated with DocToc

• spec-validator
  • Prerequisites
  • What it checks
  • Usage

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