Intent DNA

Enterprise safety control plane for AI agent behavior.

Intent DNA lets an organization declare safety policy once, cascade it through Species → Enterprise → Project → Personal → Role → Context → Task, and compile it into deterministic gates for every agent, project, and harness. It governs how agents operate across existing tools and systems; it does not replace your business systems or act as a domain-specific automation runtime.

What It Is

Intent DNA is an enforcement-first control plane for organization-wide agent safety:

• Enterprise / Species policy bundles define shared red lines across projects and teams
• Cascade governance preserves provenance and prevents lower layers from relaxing organization thresholds
• Constraint IR carries policy provenance into hook, SDK-check, and CI strict gates
• RuntimeDecisionEvent evidence records who/what/why/from which policy for every allow/warn/block/escalate/validate decision
• MCP, reports, state, trace, audit, and evolution query or package evidence; they are not the policy source of truth

It governs the agents operating on your systems rather than re-implementing the systems themselves.

The core model is:

Enterprise / Species Policy Bundle
  → Species→Enterprise→Project→Personal→Role→Context→Task Cascade
  → Constraint IR + Provenance Manifest
  → Hook / SDK-check / CI strict gate
  → RuntimeDecisionEvent
  → MCP / report / dashboard / evolution evidence layer

For the architectural model and long-term design, see DESIGN.md.
For the current stage and upcoming work, see ROADMAP.md.
For the schema contract, see spec/schema-spec.md.

Design Principles

• Govern agents rather than re-implementing business systems.
• Declare enterprise safety red lines first, then compile them into native control surfaces.
• Treat Species and Enterprise thresholds as non-relaxable by Project, Personal, Role, Context, or Task layers.
• Keep enforcement points authoritative: hooks, SDK checks, and CI gates make decisions from compiled IR and provenance.
• Treat runtime state, validators, traces, reports, MCP queries, and signals as evidence assets, not policy truth.
• Keep adapters and signal ingestion pluggable so the control plane outlives any single tool.

Quick Start

Option 1: Zero-config guardrails

npm install -g intentdna
cd your-project
dna guard

Option 2: Template-based DNA

dna init --template secure-dev
dna sync

List templates:

dna init --template list

Upgrade an existing template-backed config:

dna init --upgrade <template-name>

How It Works

Intent DNA compiles organization policy to your tool's native control surfaces:

DNA → Cascade provenance → Constraint IR → hooks / SDK checks / CI gates → evidence

Typical outputs include:

| Output | Purpose | |--------|---------| | CLAUDE.md | Behavioral guidance | | .dna/compiled/ir.json | Runtime-readable compiled constraints | | provenance manifest | Policy bundle, cascade layers, winners, and compiled IR hash | | RuntimeDecisionEvent | Enterprise evidence for allow/warn/block/escalate/validate decisions | | .dna/state/sessions/*/handoffs/*.json | Local artifact manifests for workflow handoff facts | | .claude/agents/*.md | Role definitions | | .claude/skills/*/SKILL.md | Workflow entrypoints | | .claude/settings.json or plugin runtime | Hook wiring |

Key idea: prompts can drift, but non-relaxable enterprise thresholds, compiled gates, and provenance-backed runtime evidence make behavior governable.

Supported Workflows

Intent DNA currently focuses on:

• Enterprise Safety Slice: shared policy bundles, cascade provenance, and non-relaxable organization thresholds
• Claude Code / Claude-style harnesses
• Role-based agent workflows
• Template-driven project bootstrap and upgrades
• Deterministic guardrails and stateful enforcement
• Resolver-backed artifact handoff between workflow steps
• Evidence-layer MCP/report/state/trace/audit surfaces
• Dogfood-driven template iteration

Adapter and ecosystem direction are tracked in ROADMAP.md, not duplicated here.

DNA Structure (Advanced)

# .dna.yaml
version: "0.1.0"
id: project_my_app
name: My App
type: project

cascade:
  inherits: ["species:default"]    # Inherit safety baseline
  priority: 100

genes:
  code_quality:
    description: Code quality standards
    codons:
      - type: attract
        target: tested_code
      - type: threshold
        condition: "test_coverage >= 80%"
        action: warn

roles:
  reviewer:
    description: Code reviewer — read only
    tool_permissions:
      allow: [Read, Grep, Glob]
      deny: [Edit, Write]
    scope:
      read: ["**/*"]
    instructions:
      - Never modify source code
      - Give clear PASS/FAIL verdict

workflows:
  dev-pipeline:
    name: Development Pipeline
    steps:
      - id: implement
        role: implementer
        description: Implement the feature
      - id: review
        role: reviewer
        depends_on: [implement]
        description: Review the implementation

Cascade: DNA files inherit and override by priority. threshold codons (safety rules) from Species or Enterprise are red lines: Project, Personal, Role, Context, and Task layers may add stricter rules but cannot relax them.

Genes: Behavioral traits (attract/repel/threshold/weight/sense).

Roles: Agent identities with tool permissions and scope.

Workflows: Multi-step procedures with retry logic.

Supported Environments

• ✅ Claude Code (CLAUDE.md + hooks + agents + skills + settings)
• 🚧 Prompt-style adapters and markdown outputs (.cursorrules, .clinerules, GEMINI.md)
• 🚧 AgentScope (coming soon)

Commands

dna guard                    # Zero-config guardrails
dna init --template <name>   # Start from template
dna sync <file>              # Compile DNA → harness config
dna import .                 # Import existing config → DNA
dna verify                   # Check config integrity
dna feedback --evolve        # Preview marker changes from local classified signals
dna evolve <dna-id>          # Preview marker changes from persisted outcomes
dna sync <file> --evolve     # Mutating path: apply evolved markers before sync

Philosophy

Intent DNA is inspired by biological DNA:

• Genes encode behavioral traits
• Codons are the atomic instructions
• Cascade mimics inheritance and override rules
• Epigenetics learns from experience without mutating source intent

Read more: DESIGN.md

Documentation Map

• DESIGN.md — long-term architecture and design
• ROADMAP.md — current stage, next plan, deferred work
• docs/README.md — Repo-Wiki root and reading paths
• spec/README.md — engineering spec index and status map
• spec/schema-spec.md — schema contract
• docs/references/ — distilled research and implementation references
• docs/workflows/ — operational runbooks
• docs/troubleshooting/ — troubleshooting entry points
• docs/insights/ — strategic and product-thinking documents

License

Apache-2.0

Contributing

Issues and PRs welcome. See ROADMAP.md for planned features.

Related Projects

• Superpowers — 123K users, skill-based agent workflows
• Cline KanBan — Multi-agent task orchestration
• AgentScope — Multi-agent framework from Alibaba

Intent DNA is designed to compile into the native control surfaces those frameworks expose, with current maturity varying by adapter.