# Specverify

> Independent specification verification for AI-ready documents. Two-pass protocol — base (7 universal items, deterministic + LLM, works with ANY framework) then deep (7 analytical + 6 architectural items, LLM reasoning). Triggers on "verify spec", "spec gate", "check my spec", "specverify", "review spec quality", "is this AI-ready", "run specverify". Use BEFORE code generation. Must run in a separate session from the one that wrote the specs — same-session verification is self-certification theater.

- Skill: `frmoretto/specverify-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add frmoretto/specverify-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frmoretto/specverify-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: frmoretto (https://skillmd.com/u/frmoretto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frmoretto/specverify-2

---


# specverify v1.1 — Specification Verification Protocol

## CRITICAL: SEPARATION PRINCIPLE

> **Never verify specs in the same session that wrote them.**
> The model that authored the document cannot effectively attack it.
> specverify must run in a fresh session, or ideally on a different model.
> If called in the same session that generated the specs, WARN the user and proceed with a disclaimer.

---

## What specverify Does

Two-pass verification of specification documents before AI code generation:

| Pass | Name | Items | Method | For whom |
|------|------|-------|--------|----------|
| **base** | Universal Checklist | 7 | Script pre-check + LLM | **Everyone** — any framework, any spec format |
| **deep** | Analytical + Architectural | 7 + 6 | LLM reasoning | Anyone wanting comprehensive verification |

**base** answers: "Can an AI execute this without asking questions?"
**deep** answers: "Will the AI execute it *correctly*? Is the document architecture sound?"

---

## Commands

### `specverify base`

Universal verification. Works with ANY spec format — BMAD, GSD, Spec Kit, Stream Coding, custom. Read [commands/base.md](~/.claude/commands/specverify/commands/base.md).

1. Run `~/.claude/commands/specverify/scripts/precheck.py` on all spec files → deterministic pre-report
2. LLM evaluates 7 universal items using pre-report + document content
3. Score 0-2 per item, total /14, normalized /10
4. Output: score + gap register with severity

**Threshold:** 7/10 minimum for AI-ready.

### `specverify deep`

Comprehensive analysis. Read [commands/deep.md](~/.claude/commands/specverify/commands/deep.md).

Two sections:
- **Analytical Coherence (7 items):** Cross-value consistency, code-spec coherence (incl. data flow traceability), claim credibility, abuse surface, implicit dependencies (incl. build/deploy), interface contract completeness, consumer-provider coverage
- **Document Architecture (6 items):** Type labels, anti-patterns, test cases, error handling, deep links, duplication — follows Stream Coding conventions but surfaces real issues in any spec format

Always runs regardless of base score. If base < 7/10, findings include a caveat.

### `specverify full`

Runs `base` then `deep` in sequence. Read [commands/full.md](~/.claude/commands/specverify/commands/full.md).

---

## Scoring

### Base Score (7 items, 0-2 each, max 14)

| Range | Normalized | Verdict |
|-------|-----------|---------|
| 13-14 | 9-10/10 | AI-ready. Proceed. |
| 10-12 | 7-8.5/10 | Minor revision needed. |
| 7-9 | 5-6.5/10 | Not AI-ready. Significant revision. |
| 0-6 | <5/10 | Fundamental issues. |

### Deep Findings

No numeric score. Findings list with severity: CRITICAL / HIGH / MEDIUM / LOW.

---

## File Structure

```
specverify/
├── SKILL.md              ← You are here
├── commands/
│   ├── base.md           ← 7 universal items
│   ├── deep.md           ← 7 analytical + 6 architectural items
│   └── full.md           ← Combined protocol
├── scripts/
│   └── precheck.py       ← Deterministic pre-checks
└── templates/
    └── report.md         ← Output template
```

---

*specverify by Francesco Marinoni Moretto — MIT License*
*github.com/frmoretto/specverify*