DNA — Domain Notation of Anything

Kubernetes CRDs, but for agentic behavior.

DNA is a declarative, typed notation for everything that participates in an agentic system — agents, skills, souls, guardrails, tools, policies. Every participant is identified by (apiVersion, kind), validated against a per-Kind schema, and stored as versionable YAML/Markdown. Changing an agent is a file edit, not a deploy.

apiVersion: github.com/ruinosus/dna/v1
kind: Agent
metadata:
  name: greeter
spec:
  instruction: "You are Helio, a friendly assistant."
  skills: [verification-before-completion]   # a real marketplace skill

The runtime is Python (import dna). Every other language reaches the same kernel through the REST and MCP faces, with typed clients generated from the OpenAPI spec — so a client cannot drift from the runtime.

Start here

These docs follow the Diátaxis framework — four kinds of documentation, each with one job.

• Tutorials

  Learning-oriented. Build your first Kind and composed agent prompt in ten minutes.

• Concepts

  Understanding-oriented. Start with the thesis — "CRDs, but for agentic behavior" — then the Kinds model, the five ports, and market fidelity.

• Guides

  Task-oriented. How to add a Kind, write a source adapter, read instance data, and more.

• :material-file-instance: Reference

  Information-oriented. The Python API, the CLI and the Kinds catalog — all generated from source.

The shape of the idea

Claim	Where it lives
The owner names the schema. Standards DNA didn't invent are consumed byte-faithful under their owners' apiVersion.	Market fidelity
Behavior is data, not code. Prompts, personas and wiring are versioned instances, validated on write and composed on read.	The thesis
The kernel knows no Kinds. A microkernel mediates five ports; extensions register Kinds onto it.	Microkernel & ports
Your git log is your SDLC. This repo tracks its own lifecycle as DNA instances, stamped onto every commit.	The SDLC loop
Composes with Spec Kit, doesn't compete. DNA names GitHub Spec Kit the supported spec-driven flow and sits beneath it — capturing a run's spec/plan/tasks + constitution as durable Kinds with memory, governance and board tracking.	Spec Kit — the supported flow

Status

DNA is the extracted core of a production system, not a greenfield prototype: the kernel, the extension mechanism, multi-tenancy, layer composition and the market-format readers/writers run in production today.

It is also pre-1.0: public APIs may still move, and the packages are not yet on PyPI/npm. The full test suite (thousands of tests, including the market-conformance suite and the golden fixtures) gates every change.

The source lives at github.com/ruinosus/dna.