Spec v0.3 — Overview

Status: stable (chốt 2026-05-02). Authoritative source: atomprd/specs/atomprd-v0.3.md.

This document supersedes v0.1 (11 atom kinds) and v0.2 (26 atom kinds, flat). v0.3 adds the 2-layer atom model (Intent + Behavior) and per-field provenance.

What’s new vs v0.1 / v0.2

Aspect	v0.1	v0.2	v0.3
Atom kinds	11	26 (consolidated 11 + 17 block primitives)	26
Relations	9	20	20
Per-atom layers	1 (flat)	1 (flat)	2 layers (Intent + Behavior)
Provenance	none	none	Per-field A / B / C / D attribution
acceptance atom	yes (BDD prose)	dropped	dropped (use criterion EARS instead)
constraint atom	yes (generic)	dropped	dropped (use risk or invariant)
domain atom	n/a	yes	renamed host_domain (V2 view name conflict)
Block primitives	conceptual only	first-class atoms	first-class atoms

Conformance

A v0.3-conforming tool MUST:

1. Validate atoms against the discriminated AtomSchema exported by @atomprd/spec (Zod), not a hand-rolled parser.
2. Preserve id immutability across import/export round-trip.
3. Respect the intent + behavior + provenance jsonb fields when present (Layer 2 + per-field provenance) — pass them through unchanged if the tool doesn’t have a Layer 2 editor.
4. Use the 26 atom kind IDs verbatim (no renaming, no shadowing).

A v0.3-conforming tool MAY:

• Implement only a subset of atom kinds (e.g. PM-tier tool focusing on vision + persona + module + feature + criterion).
• Treat unknown atom kinds as opaque jsonb (forward-compatibility for future v0.4+ additions).
• Provide its own UI for Layer 2 (the spec defines shape, not authoring UX).

Versioning

• v0.3.x — additive changes (new optional fields, new atom kinds added to the back of the union).
• v0.4 — first breaking change (e.g. tightening feature.behavior.steps to require trigger). Will ship a migration script.
• v1.0 — public-stable freeze candidate. Until then, AtomPRD is “early access — schema may change”.

The OSS package version (@atomprd/spec) MAY be ahead of this document on point releases. The spec doc is authoritative on shape; the package is authoritative on the executable Zod schemas.

Format Spec marketing version vs OSS spec semver

The public-facing markdown at format.atomprd.dev uses Format-Spec-version numbering (v1.0, v1.1, …) — distinct from the OSS spec semver here. They map:

• Format Spec v1.0 ↔ OSS spec v0.1 (11 atom kinds)
• Format Spec v1.1 ↔ OSS spec v0.2 (26 atom kinds, flat)
• Format Spec v1.2 ↔ OSS spec v0.3 (26 + 2-layer + provenance) ← current

The two streams will be unified once the OSS spec stabilises at 1.0.

Reference packages

Package	Status	Use for
@atomprd/spec v0.3.0	shipped	Zod schemas + 26 atom kinds + 20 relations + 2-layer + provenance types
@atomprd/core	shipped	PrdDocument wrapper + diff + integrity validation
@atomprd/codegen	shipped	CodegenTemplate interface + runTemplate() driver
@atomprd/codegen-senlang v0.3.0	shipped	Bridge: atoms → SenLang Document v0.3 + map + scenarios
@atomprd/codegen-nestjs	scaffold	Atoms → NestJS entities/controllers/migrations
@atomprd/sdk	shipped	Re-exports for downstream consumers
@atomprd/cli	scaffold	atomprd init / validate / gen / mcp
@atomprd/mcp-server	shipped	MCP transport (HTTP + stdio) for IDE / agent integration

Read next

• The 26 atom kinds — full reference.
• IDs — exact regex, hash collision rules.
• Relations — kind-pair matrix.
• Layer 2 schemas — the 5 kinds with structured Behavior.
• Provenance — A / B / C / D map shape.