Kinds reference

A Kind is DNA's unit of identity + composition — the equivalent of a Kubernetes CRD, but for agent behaviour. Every Kind is declared by a *.kind.yaml KindDefinition descriptor; the descriptor format is pinned by kind-definition.schema.json and summarised below. The catalogue on this page is generated from the live registered Kinds (Kernel.auto()), so it cannot drift from the code.

The KindDefinition descriptor

Declarative Kind descriptor — the format of builtin kinds/*.kind.yaml package descriptors AND per-scope kinds/<name>/KIND.yaml documents (one format, one funnel). Canonical copy: docs/schemas/kind-definition.schema.json; a byte-identical runtime copy ships as sdk-py package data (dna/kernel/schemas/) and backs the validation in TypedKindDefinition.from_raw. Parity-critical: the Python hand-rolled validators (models.py KindDefinitionSpec.from_raw) and the TS Zod schema (models.ts KindDefinitionSpecSchema) must accept exactly what this schema accepts (guarded by test_kind_definition_schema.py / kind-definition-schema.test.ts). Editor autocomplete: put # yaml-language-server: $schema=<path-to-this-file> on the first line of a .kind.yaml.

spec fields of a KindDefinition:

Field	Required	Description
alias	yes	Globally unique alias, convention <owner>-<kebab(kind)> (e.g. sdlc-kaizen). Used in dep_filters, templates and cross-kind refs — never bare Kind names.
ascii_icon		Single emoji or character for ASCII tree / compact views.
created_at		Runtime-stamped volatile field (never authored).
default_agent		Fixed Agent name returned by get_default_agent_name for every doc of this Kind.
default_agent_field		Spec field whose value is returned VERBATIM by get_default_agent_name (descriptor-expressiveness D6).
dep_filters		Cross-Kind references: spec field → target Kind ALIAS (never a bare Kind name).
describe		Per-doc one-liner: a template string ("{name} ({status})") or a projection mapping ({"path": "description"}) (descriptor-expressiveness D3).
description_fallback_field		Spec field acting as the Studio card description fallback when metadata.description is absent (D7).
display_label		Human-friendly plural label (e.g. "Kaizens").
docs		Prose explanation of what this Kind IS at the concept level (surfaced by describe_kind).
embed		Spec fields composing the doc's embedding text (semantic search source, F3 D4).
flatten_in_context		True flattens the spec dict into the prompt context.
graph_style		Colors for mermaid/graph visualizations, e.g. {fill, stroke, text_color}.
is_overlayable		A tenant overlay may fork this Kind (false only for structural bootstrap Kinds).
is_root		True only for the scope-root identity Kind (one per scope).
is_runtime_artifact		True for Kinds whose docs are PRODUCED by runtime workflows (eval runs, findings, ...) rather than authored — replication/seed/export tools skip them.
origin	yes	Registry namespace label of the owning extension/package, e.g. github.com/ruinosus/dna/sdlc.
plane		composition = participates in agent composition (writes invalidate scope caches) · record = pure typed document (cacheless writes, never composes into prompts; cannot carry composition signals — the plane lint rejects contradictions).
prompt_target		True if documents of this Kind compose into LLM prompts.
prompt_target_priority		Ordering priority among prompt targets (lower first).
schema		JSON Schema of the Kind's spec dict. Drives Studio form generation + validate_on_parse. New Kinds should ship additionalProperties: false (s-strict-schema-lint ratchet).
schema_fragments		Namespaced schema fragment IDs merged into schema in order (e.g. ["sdlc/workitem-common"]). Python reference implementation only — the TS Zod schema does not consume it yet.
scope_inheritable		Documents of this Kind inherit across scopes (false for per-scope ledgers + structural Kinds).
spec_defaults		Shallow-merge defaults applied as {spec_defaults, spec} BEFORE schema validation in parse() (D5).
storage	yes	Where documents of this Kind live on disk (mirrors StorageDescriptor / storage_dict_to_descriptor).
summary		List-endpoint projection. Dict form {field: default} passes through; list form ["a", "b"] is normalized with per-schema-type defaults (array→[], boolean→false, number/integer→null, else "").
target_api_version	yes	apiVersion namespace of the Kind being DEFINED (globally unique), e.g. github.com/ruinosus/dna/sdlc/v1.
target_kind	yes	CamelCase name of the Kind being defined, e.g. Kaizen. Must be unique across api_versions (i-195).
tenant_scope		Tenant enforcement for this Kind. Undeclared = permissive (base + per-tenant override). Máxima: an inheritable default-of-_lib Kind must NEVER be tenanted.
ui		StudioUIMetadata mapping — generates Studio routes/sidebar/sitemap. Keys are validated strictly (⊆ StudioUIMetadata dataclass fields) by the hand-rolled check AND here (D1).
ui_schema		Per-field widget-hint bag (field → {widget, label, help, language, height, order, ...}). Deliberately permissive — an explicitly UI-owned bag (D4). See docs/KIND-UI-HINTS.md.
updated_at		Runtime-stamped volatile field (never authored) — allowed so write-stamped documents keep validating.
version		Runtime-stamped volatile field (never authored).
volatile_spec_fields		Extra write-/runtime-stamped spec fields excluded from the canonical digest, unioned with the base set {updated_at, version, created_at}.
workitem_common		DEPRECATED back-compat shorthand for schema_fragments: ["sdlc/workitem-common"]. Python-only.

Registered Kinds (70)

Composition plane

Composition-plane Kinds are behaviour that composes into an agent's prompt (skills, souls, guardrails, …) — resolved through the layer/tenant overlay engine.

Kind	Alias	apiVersion
Actor	helix-actor	github.com/ruinosus/dna/v1
Agent	helix-agent	github.com/ruinosus/dna/v1
AgentDefinition	agentsmd-agent	agents.md/v1
Canvas	helix-canvas	github.com/ruinosus/dna/v1
Comment	collab-comment	github.com/ruinosus/dna/collab/v1
EvidencePolicy	evidence-policy	github.com/ruinosus/dna/evidence/v1
Genome	helix-genome	github.com/ruinosus/dna/v1
Guardrail	guardrails-guardrail	github.com/ruinosus/dna/v1
Hook	helix-hook	github.com/ruinosus/dna/v1
KindDefinition	kinddef-kinddefinition	github.com/ruinosus/dna/core/v1
LayerPolicy	policy-layer-policy	github.com/ruinosus/dna/policy/v1
Lesson	lesson-lesson	github.com/ruinosus/dna/lesson/v1
MCPFederation	federation-mcp	github.com/ruinosus/dna/federation/v1
Recognizer	presidio-recognizer	presidio/v1
Research	research-research	github.com/ruinosus/dna/research/v1
SafetyPolicy	helix-safety-policy	github.com/ruinosus/dna/v1
Setting	helix-setting	github.com/ruinosus/dna/v1
Skill	agentskills-skill	agentskills.io/v1
Soul	soulspec-soul	soulspec.org/v1
Tenant	tenant-tenant	github.com/ruinosus/dna/tenant/v1
TenantMembership	tenant-membership	github.com/ruinosus/dna/tenant/v1
TestGuide	testkit-test-guide	github.com/ruinosus/dna/testkit/v1
TestRun	testkit-test-run	github.com/ruinosus/dna/testkit/v1
Theme	helix-theme	github.com/ruinosus/dna/v1
Tool	helix-tool	github.com/ruinosus/dna/v1
UseCase	helix-usecase	github.com/ruinosus/dna/v1
UserProfile	helix-user-profile	github.com/ruinosus/dna/v1
UserRoleAssignment	audit-userroleassignment	github.com/ruinosus/dna/audit/v1

Record plane

Record-plane Kinds are queryable data rows (SDLC work items, research, evidence, audit log, …) — first-class documents you query/count rather than fold into a prompt.

Kind	Alias	apiVersion
ADR	sdlc-adr	github.com/ruinosus/dna/sdlc/v1
AgentSession	sdlc-agent-session	github.com/ruinosus/dna/sdlc/v1
ArchiveProposal	sdlc-archive-proposal	github.com/ruinosus/dna/sdlc/v1
AuditLog	audit-auditlog	github.com/ruinosus/dna/audit/v1
Automation	dna-automation	github.com/ruinosus/dna/automation/v1
Bug	sdlc-bug	github.com/ruinosus/dna/sdlc/v1
Changelog	sdlc-changelog	github.com/ruinosus/dna/sdlc/v1
CognitivePolicy	sdlc-cognitive-policy	github.com/ruinosus/dna/sdlc/v1
Doc	dna-doc	github.com/ruinosus/dna/doc/v1
Epic	sdlc-epic	github.com/ruinosus/dna/sdlc/v1
EvalBaseline	eval-eval-baseline	github.com/ruinosus/dna/eval/v1
EvalCase	eval-eval-case	github.com/ruinosus/dna/eval/v1
EvalRun	eval-eval-run	github.com/ruinosus/dna/eval/v1
EvalSuite	eval-eval-suite	github.com/ruinosus/dna/eval/v1
Evidence	evidence-evidence	github.com/ruinosus/dna/evidence/v1
Feature	sdlc-feature	github.com/ruinosus/dna/sdlc/v1
Forecast	sdlc-forecast	github.com/ruinosus/dna/sdlc/v1
Initiative	sdlc-initiative	github.com/ruinosus/dna/sdlc/v1
Insight	sdlc-insight	github.com/ruinosus/dna/sdlc/v1
Issue	sdlc-issue	github.com/ruinosus/dna/sdlc/v1
Kaizen	sdlc-kaizen	github.com/ruinosus/dna/sdlc/v1
LessonLearned	sdlc-lesson-learned	github.com/ruinosus/dna/sdlc/v1
ModelProfile	modelreg-model-profile	github.com/ruinosus/dna/modelreg/v1
Narrative	sdlc-narrative	github.com/ruinosus/dna/sdlc/v1
PatternInsight	cognitive-pattern-insight	github.com/ruinosus/dna/cognitive/v1
Plan	sdlc-plan	github.com/ruinosus/dna/sdlc/v1
Postmortem	sdlc-postmortem	github.com/ruinosus/dna/sdlc/v1
PreMortem	cognitive-pre-mortem	github.com/ruinosus/dna/cognitive/v1
PromptTemplate	sdlc-prompt-template	github.com/ruinosus/dna/sdlc/v1
Reference	sdlc-reference	github.com/ruinosus/dna/sdlc/v1
Retrospective	sdlc-retrospective	github.com/ruinosus/dna/sdlc/v1
RiskRegister	sdlc-risk-register	github.com/ruinosus/dna/sdlc/v1
Roadmap	sdlc-roadmap	github.com/ruinosus/dna/sdlc/v1
SavedView	sdlc-saved-view	github.com/ruinosus/dna/sdlc/v1
Spec	sdlc-spec	github.com/ruinosus/dna/sdlc/v1
Spike	sdlc-spike	github.com/ruinosus/dna/sdlc/v1
StatusReport	sdlc-status-report	github.com/ruinosus/dna/sdlc/v1
Story	sdlc-story	github.com/ruinosus/dna/sdlc/v1
SynthesisRun	sdlc-synthesis-run	github.com/ruinosus/dna/sdlc/v1
SynthesizerState	sdlc-synthesizer-state	github.com/ruinosus/dna/sdlc/v1
Task	sdlc-task	github.com/ruinosus/dna/sdlc/v1
WorkflowEvent	sdlc-workflow-event	github.com/ruinosus/dna/sdlc/v1