The Spec Standard

An executable build contract. Not just a prompt.

Two Editions

Spec4AI supports two editions. Both use the same specmeta format and are validated by the CLI.

AI Spec

6 core files. Lightweight bundle for AI agents, prompt templates, creative projects, and Claude skills. The default when you run sai init.

Engineering Spec

22-30+ files with behaviors, security, tests, UI states, ops, and agent configs. Use sai init --engineering.

Anatomy of a Spec

QA (Inputs)

Structured prompts that gather requirements without ambiguity. No more “I hope the AI guesses right”.

Contracts (Locks)

Explicit Schema (SQL/Prisma) and API definitions (OpenAPI) that act as hard constraints for generation.

Checks (Proof)

Automated smoke tests and validation scripts to prove the generated code actually runs and meets requirements.

Status (Memory)

A local state file that tracks decisions and context, preventing “drift” when you update the spec later.

Validation Tiers

The CLI validates specs in cumulative tiers. Each tier adds rules on top of the previous one.

Tier	Rules	What It Checks
Basic	7	Core files exist, manifest has ID/version, file sizes reasonable
Behavioral	+5	behaviors/ exists, edge cases structured, BR-### numbering
Security	+7	security/ files, In/Out of Scope, Threat Model, Build/Post-Build checks
Full	+4	tests/, ui/, ops/, agents/ directories with proper content

Scoring

Every spec gets a completeness score out of 100. A minimum of 80% is required to publish to the marketplace.

Standard Scoring (100 points)

Manifest (ID, title, version, descriptions)20

Agent (workflow, context rules, contracts)20

QA (stack fields, decisions, success criteria)20

Status (goal, decisions, next tasks)15

Security (scope, checks)15

README (setup, features, content)10

Creative-AI Scoring (100 points)

Types with the is-creative-ai trait use a modified scoring profile.

Agent (workflow, prompt design)20

Manifest15

QA (model, provider, config)15

Creative AI (prompt quality, model spec, output criteria)12

Status10

Security8

Other (README, requirements, contracts, performance)20

Compatibility Profiles

Specs declare their runtime needs explicitly.

Stack: e.g., Next.js 15, React 19
Runtime: e.g., Node 20, Python 3.11
Infrastructure: e.g., Postgres 16, Redis 7

Artifact Types

Every spec declares an artifact type that determines templates, validation rules, and scoring. Spec4AI supports 47 types across 10 categories — from web apps and REST APIs to prompt templates and AI workflows.

See the full reference at Artifact Types.