---
name: speckit-validator
version: 1.0.0
description: >
  Validate a Spec-Driven Development (SpecKit) project end-to-end. Runs a
  deterministic rule engine (file structure, spec/plan/tasks schema,
  cross-references, env security, code quality, CI config) and produces a
  scored, graded report — optionally enriched with AI analysis. Use whenever
  someone asks to "validate", "audit", "health-check", or "lint" a SpecKit /
  SDD project, or to verify spec ↔ code alignment.
license: MIT
compatibility:
  - github-copilot
  - claude
  - claude-code
  - cli
entrypoints:
  cli: "python -m speckit_validator --root ."
  copilot_prompt: "prompts/validate-speckit.prompt.md"
tools:
  - terminal
  - codebase
  - editFiles
---

# SpecKit Validator Skill

A portable, config-driven validation skill for any Spec-Driven Development
project. It combines a **deterministic Python engine** (objective, repeatable
pass/fail checks) with an optional **AI analysis pass** (qualitative review of
spec quality, spec↔code alignment, and long-term health).

## When to use this skill

Trigger this skill when the user wants to:

- Validate / audit / health-check a SpecKit or SDD project
- Verify all SDD artefacts exist and are well-formed (spec, plan, tasks, checklist, constitution)
- Check that the specification's requirements are actually implemented in code
- Confirm no secrets are committed and CI gates are present
- Generate a quality/health report for a project or PR

## How it works

```
┌──────────────────────────────────────────────────────────────┐
│ 1. Deterministic Engine   →  python -m speckit_validator      │
│    8 check groups, ~40–70 checks, weighted 0–100 score        │
├──────────────────────────────────────────────────────────────┤
│ 2. AI Analysis (optional) →  read artefacts, score 5 lenses   │
│    spec quality · spec↔code · constitution · copilot · health │
├──────────────────────────────────────────────────────────────┤
│ 3. Report                 →  Markdown saved to                │
│    .specify/validation-report.md                              │
└──────────────────────────────────────────────────────────────┘
```

## Procedure (follow in order)

### Step 1 — Run the deterministic engine

From the project root, run and capture both formats:

```bash
python -m speckit_validator --root . --format json
python -m speckit_validator --root .
```

Parse the JSON: `score`, `grade`, `is_healthy`, `p1_failures`, `checks[]`.

If Python is unavailable, perform the checks manually using `docs/checks-reference.md`
as the rule catalogue and mark each finding `[MANUAL]`.

### Step 2 — Read the SpecKit artefacts

Read (note any that are missing):
`.specify/specification.md`, `.specify/plan.md`, `.specify/tasks.md`,
`.specify/checklist.md`, `.specify/memory/constitution.md`,
`.github/copilot-instructions.md`, and the primary source + test files.

### Step 3 — AI analysis (5 lenses)

1. **Specification Quality** — clarity, completeness, measurability (score 1–5 per dimension)
2. **Spec ↔ Code Alignment** — table mapping every FR-xxx to its implementation (file:line) or ❌
3. **Constitution Compliance** — sample naming, provider abstraction, test strategy, secrets
4. **Copilot Chat Readiness** — is `copilot-instructions.md` accurate and complete? (score 1–5)
5. **Long-Term Health** — spec-drift risk, test fragility, biggest technical debt

### Step 4 — Compose and save the report

Merge deterministic results + AI findings into one Markdown report with an
**Executive Summary** and a **Prioritised Action Plan** (P1 blocking / P2
recommended / P3 optional). Save it to the `report_path` from config
(default `.specify/validation-report.md`) using the `editFiles` tool.

## Rules

- Every claim must cite a file, a check name, or a direct quote. No fabrication.
- P1 deterministic failures are always blocking — never downgrade them.
- The FR alignment table must cover **every** FR, not a sample.
- If a file is missing, say so explicitly rather than omitting the section.

## Configuration

Drop a `speckit-validator.config.json` at the project root to tailor the rules
to your stack (see `speckit-validator.config.example.json` and
`docs/customization.md`). With no config, generic SpecKit defaults apply.

## Entry points

| Context                | How to invoke                                         |
|------------------------|-------------------------------------------------------|
| CLI / terminal         | `python -m speckit_validator --root .`                |
| Make                   | `make validate` (after install)                       |
| GitHub Copilot Chat    | attach `prompts/validate-speckit.prompt.md` or `#validate-speckit` |
| Claude / Claude Code   | reference this `SKILL.md`                              |
| Shell wrapper          | `scripts/validate.sh` / `scripts/validate.ps1`        |