Code DNA: Engineering Excellence for AI Agents

[!CAUTION] Alpha Software: This project is in early alpha. Dragons may be found around. Use with caution and please report any bugs!

Code DNA is the single source of truth for coding standards, architectural principles, and AI-assisted development workflows. It transforms AI agents from "guests" to Resident Architects by injecting Experienced-level engineering DNA into every repository.

🎯 The Mission

As AI agents become core members of the engineering team, we must eliminate "Instruction Drift." Code DNA implements a Global-to-Local (Hub-and-Spoke) model, ensuring that excellence is inherited by every project while preserving domain-specific context.

🏗️ Architecture: Hub & Spoke

1. The Hub (code-dna/)

The "Central Brain" containing modular, version-controlled DNA strands that define the "Law of the Land."

• core/: Language-specific idioms (Go, TypeScript) and general software principles (SOLID, DRY).
• skills/: External vendor capabilities (e.g., mcollina/skills) managed via Git submodules.
• src/: The DNA Engine—the CLI and MCP server that synchronize rules across repositories.
• templates/: Standardized instruction templates for AI interactions (Gemini, Copilot, Cursor, Windsurf, Codex, Claude).

2. The Spoke ([project-repo]/)

Each repository maintains its own lightweight context while inheriting the Global DNA:

• .dna-context.md: Project-specific domain logic.
• AGENTS.md: A "README for AIs" describing the local architecture (Generated by dna init_context).
• .dna/ (Internal): A directory managed by the DNA Engine containing symlinks to the Global Strands.
• Agent Entry Points: Code DNA manages .cursorrules, .windsurfrules, .codexrules, CLAUDE.md, and GEMINI.md to ensure a consistent "Resident Architect" persona.

🌉 The DNA Engine (CLI & MCP)

To maintain portability and clean history, we use a hybrid injection strategy:

1. Symlinks (Local Dev): Global rules are symlinked into the project's .dna/ directory for real-time updates.
2. Git Hygiene: The .dna/ directory is automatically added to .git/info/exclude.
3. Portability: The engine can transition from symlinks to "hard copies" for CI/CD or remote environments.

📓 DNA Sessions: Architectural Audit

Every task is treated as a formal DNA Session to preserve the rationale behind every change. See a "Sneak Peek" of a session in action.

• Path: .dna/sessions/${SESSION_ID}/
• decisions.md: Tracking architectural choices, trade-offs, and the "Why" behind the code.
• discussion-log.vX.md: Capturing the "Vibe" and internal reasoning (Discussion Journaling).
• Auto-Versioning: All plans, RFCs, and session documents are versioned (e.g., plan.v1.md) to preserve the evolution of thought.
• Metadata: Sessions track the DNA version, the driving tool, and external Chat IDs.

🔗 Multi-Repo & Worktree Workflows

Code DNA supports complex tasks that span multiple repositories or use Git Worktrees through a Main/Linked pattern:

1. Main Repo: The primary source of truth for the session and architectural context.
2. Linked Repos/Worktrees: Secondary workspaces affected by the task.
3. Unified Context: The engine symlinks the session folder and the entire .dna configuration across workspaces, centralizing all ADRs, context, and PR drafts.

Git Worktrees Support

When working in a Git Worktree, you can link it back to the main repository to share all DNA state:

# 1. Create your worktree as usual
git worktree add .worktrees/feature-branch -b feature-branch
cd .worktrees/feature-branch

# 2. Link the DNA to the main repository
dna init --main ../..

# 3. Start or switch to a session
dna session start "my-feature"

How it works: dna init --main symlinks the worktree's .dna/ directory to the main repository's .dna/. This means:

• Shared Sessions: Sessions started in a worktree are physically stored in the main repo.
• Shared Context: Improvements to architecture.md or idioms.md in one worktree are immediately visible everywhere.
• Agent Continuity: AI agents (Gemini, Cursor, etc.) maintain full context as you move between worktrees.

🤖 Prompting the DNA: AI Incantations

To get the most out of Code DNA, use these prompts with your AI assistant:

1. Initializing a Repository

"I'm starting a new task in this repository. Please run dna init to synchronize our global standards and dna init_context to analyze the local architecture. Once done, explain how we should structure our work based on the DNA."

2. Starting a Focused Session

"We are starting a complex refactor of the Authentication module. Start a DNA session named 'auth-refactor'. If this work affects the 'identity-provider' service, link it as a linked session. Summarize our strategy in the session manifest."

3. Recording Architectural Pivots

"We've decided to move from REST to gRPC for this service to improve performance. Record this decision in our current DNA session and update the draft PR description to reflect this architectural change."

4. Mutation Proposals (Evolving the Hub)

"This new error-handling pattern we just implemented is superior to the one in our Global DNA. Propose a mutation to the Hub using dna mutation propose so it can be reviewed and adopted by other projects. I will approve the queueing when prompted."

5. Automated Reviews

"Perform an outbound DNA review on PR #42. Focus specifically on whether the implementation adheres to our TypeScript 'Resident Architect' idioms and if any new patterns should be proposed as mutations."

6. Saving Sessions for Handoff

"We've finished this part of the task. Please run dna session save with a detailed brain dump of our current context, pending tests, and next steps so I can resume from a fresh chat window later."

7. Resuming Sessions

"I'm resuming a previous task. Please run dna session resume for the session ID '20260305-my-task'. Analyze the handoff and manifest carefully, and then ask me 2-3 clarifying questions about our next steps before you begin."

🤖 Model Agency via MCP (Model Context Protocol)

Code DNA provides an MCP Server wrapper for the dna CLI, enabling:

• Structured Thought Trails: Agents autonomously record decisions in the active session.
• Standards as Resources: Global DNA strands are exposed as MCP Resources (dna://golang-master).
• Automated PR Lifecycle: Agents manage the draft-pr.md autonomously.

🐙 Review & GitHub Integration

• Inbound: Analyze team feedback on PRs and suggest surgical fixes based on Engineering DNA.
• Outbound: Perform automated "First-Pass" reviews on PRs, checking for DNA adherence.

🔄 Lifecycle: Plan-First Mandate

To prevent "Context Bloat" and ensure quality, we follow a tiered execution model:

1. Discovery: Gather project-specific context.
2. Strategy (Mandatory): Propose high-level ADRs and record them in the Session Log. Agents MUST wait for user approval after planning.
3. Execution: Small, verifiable "Test + Code" cycles.
4. Refinement: Surgical linting and documentation.

🚀 Future Strands & Roadmap

We are evolving Code DNA to become an autonomous engineering ecosystem:

1. 🧬 DNA Mutations (Evolution Loop): Allow agents to suggest local architectural improvements back to the Global Hub via dna propose-mutation, creating a continuous feedback loop.
2. 🛡️ The Lead Architect Agent: A specialized agent persona that audits PRs for DNA compliance before they reach human reviewers.
3. 🤖 Automatic Context Sync: Real-time updates to .dna/context/ after successful sessions to ensure agent repository knowledge never goes stale.
4. 🔗 Cross-Repo DNA Grafting: Tools to "graft" proven patterns from one repository to another (e.g., "Graft the auth pattern from Repo-A to Repo-B").
5. 📝 Automated PR Finalization: Transforming ADRs and session logs into perfect, template-compliant PR descriptions automatically.

📋 Prerequisites

1. Node.js (v18+)
2. GitHub CLI (gh): Required for the review tool.
   • Run dna auth link to synchronize your local authentication.
3. Git

🔌 Usage

Installation

Clone this repo and link the CLI:

npm install
npm run build
npm link --force

Available Tools

• dna init: Symlinks global DNA into the current repository.
  • Pro Tip: Run this again to update your repository when the Global DNA version changes.
• dna init_context: Analyzes the repo and initializes architectural context.
• dna session start <name>: Initializes a new DNA session.
  • Use --main /path/to/repo to link this to another project's session.
• dna session list: Lists all DNA sessions in the repository.
• dna session status [id]: Shows the dashboard for a session (manifest, ADRs).
• dna session switch <id>: Sets the active session for the CLI.
• dna session record [id] <decision>: Records an architectural choice.
• dna session save [id] <brain_dump>: Saves the session with a handoff document for AI continuity.
• dna session resume [id]: Resumes a session, loads context, and triggers the mandatory clarification protocol.
• dna session doc [id] <file> <content>: Writes a versioned session document.
• dna session cleanup [id]: Cleans up old document versions.
• dna mutation propose <title> <rationale>: Queues a local improvement for the Global Hub.
• dna review outbound <pr>: Performs an automated review against the DNA.

Gemini CLI Integration

Register the MCP Server:

gemini mcp add code-dna node /Users/vcs/code/code-dna/dist/mcp-server.js --scope user --trust

🧪 Testing

npm test