Creating Specs

Build an executable spec bundle that AI agents can follow to produce reliable, validated output.

Two Editions

Spec4AI offers two spec editions. Choose based on your project's complexity.

AI Spec

Lightweight bundle for AI apps, creative projects, prompt engineering, and Claude skills.

6 core files:

manifest.md
agent.md
qa.md
status.md
checks/README.md
CHANGELOG.md

Best for: prompt templates, AI agents, chatbots, generative pipelines, Claude skills

Engineering Spec

Comprehensive bundle for traditional software with behaviors, security, tests, UI states, and ops.

22-30+ files across directories:

manifest.md, agent.md, qa.md, status.md
behaviors/ — business rules, state machines
edge_cases/ — edge case specifications
security/ — scope, checks, threat model
tests/ — test matrix, coverage mapping
ui/ — page states, design tokens
ops/ — deployment, health checks
agents/ — agent-specific instructions

Best for: web apps, REST APIs, mobile apps, infrastructure, e-commerce

CLI Quickstart

The sai CLI generates the right scaffold for your project type.

# AI Spec (default)

sai init my-chatbot --type chatbot --lane fullstack

# Engineering Spec

sai init my-webapp --type web-app --engineering --lane fullstack

# Creative AI type (auto-selects AI Spec with creative templates)

sai init my-prompts --type prompt-template --lane data

AI Spec Bundle

The AI Spec is a focused 6-file bundle. Each file has a specific role:

manifest.md

Metadata: spec ID, title, version, artifact type, capabilities, compatibility profile. The entry point for all tooling.

agent.md

Agent instructions: what to build, phases, context rules, contracts (stop rules), and troubleshooting. Creative-AI types get specialized templates.

qa.md

Technical decisions: stack choices, defaults, success criteria. Creative-AI types document model, provider, temperature, and max-tokens.

status.md

Living document: current goal, locked decisions, completed work, next tasks. Updated by the AI agent as it works.

checks/README.md

Validation checklist: does it work? Is it safe? What does “passing” mean for this spec?

CHANGELOG.md

Version history: what changed between releases, following semver conventions.

Engineering Spec Bundle

The Engineering Spec extends the AI Spec with structured directories for comprehensive documentation. Content is added progressively based on the validation tier.

.
├── manifest.md           # Metadata and capabilities
├── agent.md              # Agent workflow and instructions
├── qa.md                 # Stack decisions and success criteria
├── status.md             # Progress tracking
├── CHANGELOG.md          # Version history
├── behaviors/            # Business rules (BR-###) and state machines (SM-###)
│   └── README.md
├── edge_cases/           # Edge case specifications (EC-###)
│   └── EC-001.md
├── security/             # Threat model, scope, security checks
│   ├── scope.md
│   └── checks.md
├── tests/                # Test matrix and coverage mapping
│   └── test-matrix.md
├── ui/                   # Page inventory, UI states, design tokens
│   └── pages-states.md
├── ops/                  # Deployment, health checks, rollback
│   └── deploy.md
└── agents/               # Agent-specific instructions
    ├── agent.md          # Tool-agnostic instructions
    ├── claude.md         # Claude-specific
    └── cursor.md         # Cursor-specific

Validation Tiers

Engineering Specs are validated progressively. Each tier builds on the previous one.

Tier	What It Checks	Required For
Basic	Core files exist, manifest has ID/version, file sizes reasonable	All specs (AI and Engineering)
Behavioral	behaviors/ exists, edge cases have required sections, BR-### numbering	Engineering (behavioral+)
Security	security/ files, In/Out of Scope, Threat Model, Build/Post-Build checks	Engineering (security+)
Full	tests/, ui/, ops/, agents/ directories with proper content	Engineering (full)

Validate & Publish

Before publishing, validate your spec locally and check its completeness score.

# Validate spec structure

sai verify ./my-spec

# Check completeness score (80% minimum to publish)

sai score ./my-spec

# Publish to the marketplace

sai publish

Or create specs directly in the browser at the creator dashboard. See all available artifact types for type-specific templates.