Speckit Validator

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:

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