BUM — Biological Universe Makers

A self-replicating AI agent ecosystem. Each brain is a git repository that autonomously builds and maintains one application (its universe). Brains replicate by forking, communicate through the local filesystem, and evolve by absorbing capabilities developed by their children.

This repo is the brain-template — the gen-0 root from which all other brains are forked.

Prerequisites

• VS Code with GitHub Copilot (agent mode enabled)
• gh CLI installed and authenticated (gh auth login)
• GitHub Copilot CLI (copilot) installed — used by parent agents to dispatch agents inside child workspace directories
• Git configured with push access to GitHub

Core Concepts in 60 Seconds

| Term | What it is | | -------------------- | ------------------------------------------------------------------------------------------------------ | | Brain | A git repo with a .github/ agent brain model + .bum/ genome files | | Universe | The application a brain builds and maintains | | Multiverse | The full tree of brains — root + all descendants | | DNA | .bum/DNA.json — immutable identity + folder/file blueprint. Written once, never changed. | | RNA | .bum/RNA.json — live runtime state: mode, lifecycle, goal, deployment, capabilities | | Epi-genome | .bum/epi-genome.json — system-wide physical constants propagated to all children. Immutable locally. | | DELTA | .bum/DELTA.json — deviation log raised by the child when a target_structure path is structurally unachievable; parent reviews and ratifies genuine deviations via rectify-dna | | Controlled files | Brain model files in .github/ that are system-wide law — every child inherits them identically |

Agent Reference

Every operation in BUM is handled by a named agent. Invoke them in VS Code Copilot using @agent-name or by selecting from the agent picker.

Genome Layer — writes to .bum/

| Agent | When to use | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | @epi-genome-architect | Starting a brand-new root brain (no parent, no .bum/ folder) — brainstorms and writes epi-genome.json | | @morphogen | Writing DNA.json for the first time — interviews you to design the folder/file blueprint, or reverse-engineers it from existing files | | @polymerase | Any time RNA.json needs creating or updating — lifecycle changes, mode transitions, goal updates, deployment status | | @propagator | Pushing epi-genome controlled file updates out to all child brains |

Brain Model Layer — writes to .github/

| Agent | When to use | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | @surgeon | Building or repairing the .github/ brain model — reads epi-genome + DNA as spec, uses Extensions/ as guidelines |

Application Layer — writes project files

| Agent | When to use | | ------------ | ----------------------------------------------------------------------------------------------- | | @developer | Building the application toward DNA.target_structure in development mode — production-ready when all paths exist, conform to descriptions, and DELTA is empty | | @expander | Adding features beyond the current target_structure — plans extensions in tasklist.md first, then builds |

Cross-Brain Operations

| Agent | When to use | | ------------- | ----------------------------------------------------------------------------------------------------- | | @replicator | Spawning a new child brain (forks repo, writes child DNA, clones into Repositories/) | | @merger | Merging a completed task brain back — only valid when child lifecycle is apoptosis | | @integrator | Pulling brain model upgrades from a child up to parent (sub-agent, called by merger) | | @absorber | Pulling new capabilities from RNA.capabilities.developed up to parent (sub-agent, called by merger) | | @pusher | Pushing an absorbed capability downward to sibling children (sub-agent, called after absorb) |

Orientation

| Agent | When to use | | ------------------ | ------------------------------------------------------------------------------------------------ | | @brain-architect | Not sure which agent to use; auditing the brain model for gaps or drift; reviewing after changes |

Workflows

1. Start a New Root Brain (gen-0)

Use this when you have a fresh repo with no parent and want to set up a complete BUM brain from scratch.

Step 1 — Design the epi-genome

@epi-genome-architect

This agent brainstorms with you to decide which brain model files should be system-wide law (controlled files). It writes .bum/epi-genome.json and then automatically invokes polymerase to initialize RNA.json.

Step 2 — Design the DNA

@morphogen

Interviews you about the brain's name, mandate (birth_goal), type (service or task), and the complete folder/file blueprint (target_structure). Writes .bum/DNA.json. This file is permanent — it is never changed after this step.

Step 3 — Build the brain model

@surgeon

Reads the genome files, reads Extensions/ as guidelines, and builds the complete .github/ brain model — agents, skills, instructions, prompts, hooks, and copilot-instructions.md.

Step 4 — Build the application

@developer

Implements every folder and file in DNA.target_structure. Iterates until all paths exist and each file does what its description says. The project is production-ready when all target_structure paths exist, pass description conformance, and DELTA.json is empty.

2. Extend Beyond target_structure

Once the project structure fully matches DNA.target_structure and DELTA is empty:

@expander

Tell the expander what you want to add. It plans the extension as an ordered checklist in tasklist.md, gets your confirmation, then builds. The plan always precedes implementation.

3. Spawn a Child Brain

To create a new service or task brain that branches off from this one:

@replicator

You'll be asked for: child name, birth goal, type (service or task). The replicator forks the repo on GitHub, writes the child's DNA.json, clones it into Repositories/<child-name>/, and updates your epi-genome.json topology. After that, open the child workspace and run @morphogen (to finalize target_structure if needed) then @surgeon (to adapt the inherited brain model to the child's domain).

4. Update RNA State

Any time mode, lifecycle, goal, or deployment status needs changing:

@polymerase

Examples:

• "Mark this brain as dormant" — lifecycle transition
• "Update goal to: focus on the checkout flow refactor" — goal update
• "Deployment succeeded, status is healthy" — deployment update
• "A new .github/ file was created, sync capabilities" — capabilities sync

Lifecycle rules:

| Brain type | Valid lifecycle states | | ---------- | ---------------------------------- | | service | active ↔ dormant → retired | | task | active → dormant → apoptosis |

Mode transition rules:

| Brain type | Who can change mode | | ---------- | --------------------- | | service | Human only | | task | Parent agent or human |

5. Merge a Task Brain Back

When a task brain finishes its work, set its lifecycle to apoptosis (via @polymerase in the child workspace), then from the parent:

@merger <child-name>

Merger will:

1. Verify: task brain, lifecycle = apoptosis, no children of its own
2. Run @integrator — pulls brain model upgrades from child
3. Run @absorber — pulls qualifying new capabilities up to parent
4. git merge the child's code into parent
5. Delete the child repo and remove it from topology

6. Absorb a Child's Capabilities (Without Merging)

If a living child has developed useful skills you want the parent and future children to inherit:

@absorber <child-name>

Absorber evaluates each entry in RNA.capabilities.developed against the absorption threshold (must benefit multiple children, benefit newly born children, fall within parent's domain). After absorbing, it prunes the absorbed entries from the child's RNA.json.

To push the newly absorbed capability to existing siblings immediately after:

@pusher <capability-name>

7. Propagate Epi-Genome Changes

When you update a controlled file or add a new one to epi-genome.json:

@propagator

Propagator iterates all children in epi-genome.children, overwrites their epi-genome.json and all literal controlled files, and commits with [epi-propagation] tag — the only tag that bypasses the immutability guard. Semantic entries (path: null) are flagged for each child's surgeon to generate.

8. Repair a Broken Brain Model

If .github/ is missing files, has frontmatter drift, or controlled files don't match their epi-genome specs:

@surgeon

Surgeon reads all three genome files, audits .github/, and fixes everything: resolves semantic entries, corrects frontmatter mismatches, creates missing required files (hooks, copilot-instructions.md), then updates RNA.capabilities.inherited.

For an audit-only diagnosis before any changes:

@brain-architect

File Reference

.bum/DNA.json — Immutable Identity

Written once by morphogen. Never modified.

{
  "name": "my-brain",
  "born_at": "2026-03-17T00:00:00Z",
  "parent_repo": null,
  "generation": 0,
  "birth_goal": "Build and maintain the payments API",
  "type": "service",
  "target_structure": {
    "description": "Root of the universe.",
    "children": {
      "src": { "description": "...", "children": { ... } }
    }
  }
}

.bum/RNA.json — Live Runtime State

Written and updated by polymerase.

{
  "mode": "development",
  "lifecycle": "active",
  "goal": "Current working goal",
  "deployment": {
    "status": "pending",
    "environment": null,
    "error_log": null,
    "last_deployed": null
  },
  "issues": { "open_count": 0, "last_checked": "..." },
  "capabilities": {
    "inherited": [ ... ],
    "developed": [ ... ]
  }
}

.bum/epi-genome.json — System-Wide Constants

Written by epi-genome-architect at root-brain birth. Propagated to all children by propagator. Immutable locally — only the root can update it.

{
  "schema_version": 1,
  "propagated_at": "2026-03-17T00:00:00Z",
  "controlled_files": [ ... ],
  "children": [ { "name": "child-a", "local_path": "Repositories/child-a", "github_url": "..." } ],
  "parent": null
}

.bum/DELTA.json — Structural Deviation Log

Created by the developer when a target_structure path is structurally unachievable. Pruned by the parent via rectify-dna. Production-readiness is blocked while entries remain.

{
  "last_updated": "2026-03-17T00:00:00Z",
  "deviations": {
    "src/controllers/payment.controller.ts": {
      "attempted": "src/controllers/payment.controller.ts",
      "blocker": "Framework enforces flat handler pattern — class-based controllers are not valid.",
      "built_instead": "src/handlers/payment.handler.ts",
      "built_instead_description": "Flat async handler achieving the same intent."
    }
  }
}

Immutability Rules

| File | Rule | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | .bum/DNA.json | Written once by morphogen. Never modified. | | .bum/epi-genome.json | Immutable locally. Only updated via [epi-propagation] commits from root. | | target_structure files | Not locked; parent may update target_structure via rectify-dna prompt. | | Controlled files in .github/ | Must match their epi-genome.json header spec. Pre-commit hook validates sha256 + frontmatter. |

Development vs Production Mode

| Mode | Behavior | | ------------- | --------------------------------------------------------------------------------------------------------------------- | | development | Active building — developer, expander, replicator all operate. Brain accepts parent updates. | | production | Dormant until stimulated. Responds to GitHub Actions failures, parent invocations, user commands. No active building. |

Service brains transition between modes by human decision only. Task brains are controlled by their parent.

Repo Structure

brain-template/
├── .github/
│   ├── copilot-instructions.md    ← global philosophy
│   ├── agents/                    ← all 13 BUM agents
│   ├── skills/                    ← domain skills
│   ├── instructions/              ← file-pattern rules
│   ├── prompts/                   ← user-facing entry points
│   └── hooks/                     ← lifecycle enforcement
├── .bum/                          ← genome files (created at init)
├── Repositories/                  ← gitignored, cloned child repos
├── Parent/                        ← gitignored, cloned parent repo
├── Extensions/                    ← mandatory guidelines for brain model creation
├── BUM.md                         ← full system specification
└── README.md                      ← this file

Extensions/ is the law for brain model creation. Every agent that writes .github/ files (surgeon) reads Extensions/skills/agent-customization/references/ before creating anything.

Quick-Start Cheatsheet

| Goal | Command | | --------------------------- | ------------------------------------------------------------------ | | Bootstrap a new root brain | @epi-genome-architect → @morphogen → @surgeon → @developer | | Extend beyond target_structure | @expander | | Spawn a child brain | @replicator | | Update lifecycle/mode/goal | @polymerase | | Merge a finished task brain | @merger <child-name> | | Absorb child capabilities | @absorber <child-name> | | Push capability to siblings | @pusher <capability-name> | | Sync epi-genome to children | @propagator | | Repair broken brain model | @surgeon | | Audit brain model health | @brain-architect | | Not sure what to do | @brain-architect |