The 26 atom kinds

The vocabulary is closed at 26. Pick the kind that fits — don’t bend a note into a criterion.

All 26 kinds

Group	Kind	Prefix	Layer 2	Notes
Top-level	vision	vis_	—	+ problemStatement, valueProposition
	persona	per_	—	+ goals[], painPoints[]
	module	mod_	—	+ status
	feature	feat_	yes	+ userStory, priority, status. Layer 2 = action chain
Domain	entity	ent_	—	(fields stored on separate field atoms)
	field	fld_	—	+ entityId, dataType, required
Runtime semantics	rule	rul_	yes	+ expression, errorMessage. Layer 2 = enforced_at sites
	ui_view	ui_	yes	+ viewType. Layer 2 = multi-screen layout
	integration	int_	—	+ protocol
Content blocks (B1-B11)	description	desc_	—	+ body (markdown or TipTap JSON)
	criterion	cri_	yes	EARS structured. Layer 2 = before_after state diff + api_calls
	task	tsk_	—	+ title, complexity, depends_on[], status
	risk	rsk_	—	+ severity, mitigation, optional STRIDE
	fixture	fix_	yes	+ purpose, payload, linked_criteria[]. Layer 2 = before/after + api_calls
	note	nte_	—	+ body, audience
	decision	dec_	—	ADR-style: question, options[], chosen
	dependency	dep_	—	+ target_atom_id, relation
	invariant	inv_	—	+ rule_id, statement, scope
	out_of_scope	oos_	—	+ items[], reason
	sequence	seq_	—	+ steps: [{actor, action}]
Runtime / DevOps blocks (B12-B17)	service	svc_	—	+ type, language, framework, hosts, ports
	env_var	env_	—	+ scope_service, secret, value_* per env
	vendor	ven_	—	+ category, api_key_env_var, webhook_*, DPA
	host_domain	dom_	—	DNS subdomain → service mapping
	build_step	bld_	—	+ command, working_dir, depends_on
	deploy_target	tgt_	—	+ provider, auto_deploy_branch, scaling

Total: 26 atom kinds, 5 with Layer 2 (feature, ui_view, rule, criterion, fixture).

Five groups

The 26 kinds cluster into five groups by purpose:

• Top-level (4) — project framing: vision, persona, module, feature.
• Domain (2) — your nouns: entity, field.
• Runtime semantics (3) — rule, ui_view, integration.
• Content blocks (11) — descriptive blocks: description, criterion, task, risk, fixture, note, decision, dependency, invariant, out_of_scope, sequence.
• DevOps blocks (6) — runtime + deployment: service, env_var, vendor, host_domain, build_step, deploy_target.

Picking a kind

Some judgment calls:

• Acceptance criteria → criterion (EARS-structured). Don’t use description for criteria. EARS fields are machine-readable; markdown isn’t.
• Generic constraint → risk or invariant. v0.1 had a constraint kind; it was dropped because “constraint” was too vague. risk covers business / operational risks (severity + mitigation); invariant covers must-hold rules (declarative).
• External SaaS → vendor for DPA tracking + the api_key_env_var link. Use integration for the protocol-level descriptor (HTTP API, webhook, SMS).
• Step-by-step short flow → sequence inline. For multi-screen UI flow, prefer ui_view with multiple screens.
• Free-form prose body → description. The only block that allows TipTap / Markdown.
• Internal commentary → note. With an audience field (engineer / pm / designer / all).

See also

• Spec → IDs — how prefixes map to the regex.
• Concepts → Atom model — why a closed vocabulary.
• RFC-000 — Design rationale — the path from 11 kinds (v0.1) to 26 (v0.2+).