{"_id":"@aynorica/bum","name":"@aynorica/bum","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aynorica/bum","version":"0.1.0","type":"module","description":"Brain Update Manager — install and update VS Code Copilot brain models","bin":{"bum":"bin/bum.js"},"dependencies":{"commander":"^12.0.0"},"scripts":{"build":"echo 'No build step — ships raw ESM'","lint":"node --check bin/bum.js"},"engines":{"node":">=18"},"keywords":["copilot","brain","bum","vscode"],"license":"MIT","gitHead":"2c50c77b291dc8b2f5920c28500a062224791b55","_id":"@aynorica/bum@0.1.0","_nodeVersion":"25.6.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-Euu9FpC9RF4q2fyiAIc6TM5uml3vShVsH47iMH5JAn3PAUmwM9YXtyqWQanqe52z3gFXgKFY5upCSXfVWWhD8g==","shasum":"545b66e50c31b01d9d9813201160cdceeca52cb7","tarball":"https://registry.npmjs.org/@aynorica/bum/-/bum-0.1.0.tgz","fileCount":8,"unpackedSize":25803,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCes5wc4gfma0du1W4AKVJ1fdTLuhUXGyx2+nczcwi+4gIgUzxfYrZUe9sPyfXdPDiEgcwbt9ax2MsNorKMtaNkXnI="}]},"_npmUser":{"name":"aynorica","email":"Amirdeilamizadeh1996@gmail.com"},"directories":{},"maintainers":[{"name":"aynorica","email":"Amirdeilamizadeh1996@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bum_0.1.0_1773880926967_0.481169477163381"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T00:42:06.851Z","0.1.0":"2026-03-19T00:42:07.121Z","modified":"2026-03-19T00:42:07.278Z"},"maintainers":[{"name":"aynorica","email":"Amirdeilamizadeh1996@gmail.com"}],"description":"Brain Update Manager — install and update VS Code Copilot brain models","keywords":["copilot","brain","bum","vscode"],"license":"MIT","readme":"# BUM — Biological Universe Makers\n\nA 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.\n\nThis repo is the **brain-template** — the gen-0 root from which all other brains are forked.\n\n---\n\n## Prerequisites\n\n- VS Code with GitHub Copilot (agent mode enabled)\n- `gh` CLI installed and authenticated (`gh auth login`)\n- GitHub Copilot CLI (`copilot`) installed — used by parent agents to dispatch agents inside child workspace directories\n- Git configured with push access to GitHub\n\n---\n\n## Core Concepts in 60 Seconds\n\n| Term                 | What it is                                                                                             |\n| -------------------- | ------------------------------------------------------------------------------------------------------ |\n| **Brain**            | A git repo with a `.github/` agent brain model + `.bum/` genome files                                  |\n| **Universe**         | The application a brain builds and maintains                                                           |\n| **Multiverse**       | The full tree of brains — root + all descendants                                                       |\n| **DNA**              | `.bum/DNA.json` — immutable identity + folder/file blueprint. Written once, never changed.             |\n| **RNA**              | `.bum/RNA.json` — live runtime state: mode, lifecycle, goal, deployment, capabilities                  |\n| **Epi-genome**       | `.bum/epi-genome.json` — system-wide physical constants propagated to all children. Immutable locally. |\n| **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` |\n| **Controlled files** | Brain model files in `.github/` that are system-wide law — every child inherits them identically       |\n\n---\n\n## Agent Reference\n\nEvery 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.\n\n### Genome Layer — writes to `.bum/`\n\n| Agent                   | When to use                                                                                                                             |\n| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `@epi-genome-architect` | Starting a brand-new root brain (no parent, no `.bum/` folder) — brainstorms and writes `epi-genome.json`                               |\n| `@morphogen`            | Writing `DNA.json` for the first time — interviews you to design the folder/file blueprint, or reverse-engineers it from existing files |\n| `@polymerase`           | Any time `RNA.json` needs creating or updating — lifecycle changes, mode transitions, goal updates, deployment status                   |\n| `@propagator`           | Pushing epi-genome controlled file updates out to all child brains                                                                      |\n\n### Brain Model Layer — writes to `.github/`\n\n| Agent      | When to use                                                                                                         |\n| ---------- | ------------------------------------------------------------------------------------------------------------------- |\n| `@surgeon` | Building or repairing the `.github/` brain model — reads epi-genome + DNA as spec, uses `Extensions/` as guidelines |\n\n### Application Layer — writes project files\n\n| Agent        | When to use                                                                                     |\n| ------------ | ----------------------------------------------------------------------------------------------- |\n| `@developer` | Building the application toward `DNA.target_structure` in development mode — production-ready when all paths exist, conform to descriptions, and DELTA is empty |\n| `@expander`  | Adding features beyond the current target_structure — plans extensions in `tasklist.md` first, then builds |\n\n### Cross-Brain Operations\n\n| Agent         | When to use                                                                                           |\n| ------------- | ----------------------------------------------------------------------------------------------------- |\n| `@replicator` | Spawning a new child brain (forks repo, writes child DNA, clones into `Repositories/`)                |\n| `@merger`     | Merging a completed task brain back — only valid when child lifecycle is `apoptosis`                  |\n| `@integrator` | Pulling brain model upgrades from a child up to parent (sub-agent, called by merger)                  |\n| `@absorber`   | Pulling new capabilities from `RNA.capabilities.developed` up to parent (sub-agent, called by merger) |\n| `@pusher`     | Pushing an absorbed capability downward to sibling children (sub-agent, called after absorb)          |\n\n### Orientation\n\n| Agent              | When to use                                                                                      |\n| ------------------ | ------------------------------------------------------------------------------------------------ |\n| `@brain-architect` | Not sure which agent to use; auditing the brain model for gaps or drift; reviewing after changes |\n\n---\n\n## Workflows\n\n### 1. Start a New Root Brain (gen-0)\n\nUse this when you have a fresh repo with no parent and want to set up a complete BUM brain from scratch.\n\n**Step 1 — Design the epi-genome**\n\n```\n@epi-genome-architect\n```\n\nThis 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`.\n\n**Step 2 — Design the DNA**\n\n```\n@morphogen\n```\n\nInterviews 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.\n\n**Step 3 — Build the brain model**\n\n```\n@surgeon\n```\n\nReads the genome files, reads `Extensions/` as guidelines, and builds the complete `.github/` brain model — agents, skills, instructions, prompts, hooks, and `copilot-instructions.md`.\n\n**Step 4 — Build the application**\n\n```\n@developer\n```\n\nImplements 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.\n\n---\n\n### 2. Extend Beyond target_structure\n\nOnce the project structure fully matches `DNA.target_structure` and DELTA is empty:\n\n```\n@expander\n```\n\nTell 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.\n\n---\n\n### 3. Spawn a Child Brain\n\nTo create a new service or task brain that branches off from this one:\n\n```\n@replicator\n```\n\nYou'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).\n\n---\n\n### 4. Update RNA State\n\nAny time mode, lifecycle, goal, or deployment status needs changing:\n\n```\n@polymerase\n```\n\nExamples:\n\n- \"Mark this brain as dormant\" — lifecycle transition\n- \"Update goal to: focus on the checkout flow refactor\" — goal update\n- \"Deployment succeeded, status is healthy\" — deployment update\n- \"A new .github/ file was created, sync capabilities\" — capabilities sync\n\n**Lifecycle rules:**\n\n| Brain type | Valid lifecycle states             |\n| ---------- | ---------------------------------- |\n| `service`  | `active` ↔ `dormant` → `retired`   |\n| `task`     | `active` → `dormant` → `apoptosis` |\n\n**Mode transition rules:**\n\n| Brain type | Who can change mode   |\n| ---------- | --------------------- |\n| `service`  | Human only            |\n| `task`     | Parent agent or human |\n\n---\n\n### 5. Merge a Task Brain Back\n\nWhen a task brain finishes its work, set its lifecycle to `apoptosis` (via `@polymerase` in the child workspace), then from the parent:\n\n```\n@merger <child-name>\n```\n\nMerger will:\n\n1. Verify: task brain, lifecycle = apoptosis, no children of its own\n2. Run `@integrator` — pulls brain model upgrades from child\n3. Run `@absorber` — pulls qualifying new capabilities up to parent\n4. `git merge` the child's code into parent\n5. Delete the child repo and remove it from topology\n\n---\n\n### 6. Absorb a Child's Capabilities (Without Merging)\n\nIf a living child has developed useful skills you want the parent and future children to inherit:\n\n```\n@absorber <child-name>\n```\n\nAbsorber 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`.\n\nTo push the newly absorbed capability to existing siblings immediately after:\n\n```\n@pusher <capability-name>\n```\n\n---\n\n### 7. Propagate Epi-Genome Changes\n\nWhen you update a controlled file or add a new one to `epi-genome.json`:\n\n```\n@propagator\n```\n\nPropagator 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.\n\n---\n\n### 8. Repair a Broken Brain Model\n\nIf `.github/` is missing files, has frontmatter drift, or controlled files don't match their epi-genome specs:\n\n```\n@surgeon\n```\n\nSurgeon 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`.\n\nFor an audit-only diagnosis before any changes:\n\n```\n@brain-architect\n```\n\n---\n\n## File Reference\n\n### `.bum/DNA.json` — Immutable Identity\n\nWritten once by `morphogen`. Never modified.\n\n```json\n{\n  \"name\": \"my-brain\",\n  \"born_at\": \"2026-03-17T00:00:00Z\",\n  \"parent_repo\": null,\n  \"generation\": 0,\n  \"birth_goal\": \"Build and maintain the payments API\",\n  \"type\": \"service\",\n  \"target_structure\": {\n    \"description\": \"Root of the universe.\",\n    \"children\": {\n      \"src\": { \"description\": \"...\", \"children\": { ... } }\n    }\n  }\n}\n```\n\n### `.bum/RNA.json` — Live Runtime State\n\nWritten and updated by `polymerase`.\n\n```json\n{\n  \"mode\": \"development\",\n  \"lifecycle\": \"active\",\n  \"goal\": \"Current working goal\",\n  \"deployment\": {\n    \"status\": \"pending\",\n    \"environment\": null,\n    \"error_log\": null,\n    \"last_deployed\": null\n  },\n  \"issues\": { \"open_count\": 0, \"last_checked\": \"...\" },\n  \"capabilities\": {\n    \"inherited\": [ ... ],\n    \"developed\": [ ... ]\n  }\n}\n```\n\n### `.bum/epi-genome.json` — System-Wide Constants\n\nWritten by `epi-genome-architect` at root-brain birth. Propagated to all children by `propagator`. **Immutable locally** — only the root can update it.\n\n```json\n{\n  \"schema_version\": 1,\n  \"propagated_at\": \"2026-03-17T00:00:00Z\",\n  \"controlled_files\": [ ... ],\n  \"children\": [ { \"name\": \"child-a\", \"local_path\": \"Repositories/child-a\", \"github_url\": \"...\" } ],\n  \"parent\": null\n}\n```\n\n### `.bum/DELTA.json` — Structural Deviation Log\n\nCreated 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.\n\n```json\n{\n  \"last_updated\": \"2026-03-17T00:00:00Z\",\n  \"deviations\": {\n    \"src/controllers/payment.controller.ts\": {\n      \"attempted\": \"src/controllers/payment.controller.ts\",\n      \"blocker\": \"Framework enforces flat handler pattern — class-based controllers are not valid.\",\n      \"built_instead\": \"src/handlers/payment.handler.ts\",\n      \"built_instead_description\": \"Flat async handler achieving the same intent.\"\n    }\n  }\n}\n```\n\n---\n\n## Immutability Rules\n\n| File                           | Rule                                                                                            |\n| ------------------------------ | ----------------------------------------------------------------------------------------------- |\n| `.bum/DNA.json`                | Written once by `morphogen`. Never modified.                                                    |\n| `.bum/epi-genome.json`         | Immutable locally. Only updated via `[epi-propagation]` commits from root.                      |\n| `target_structure` files       | Not locked; parent may update `target_structure` via `rectify-dna` prompt.                      |\n| Controlled files in `.github/` | Must match their `epi-genome.json` header spec. Pre-commit hook validates sha256 + frontmatter. |\n\n---\n\n## Development vs Production Mode\n\n| Mode          | Behavior                                                                                                              |\n| ------------- | --------------------------------------------------------------------------------------------------------------------- |\n| `development` | Active building — developer, expander, replicator all operate. Brain accepts parent updates.                          |\n| `production`  | Dormant until stimulated. Responds to GitHub Actions failures, parent invocations, user commands. No active building. |\n\nService brains transition between modes by human decision only. Task brains are controlled by their parent.\n\n---\n\n## Repo Structure\n\n```\nbrain-template/\n├── .github/\n│   ├── copilot-instructions.md    ← global philosophy\n│   ├── agents/                    ← all 13 BUM agents\n│   ├── skills/                    ← domain skills\n│   ├── instructions/              ← file-pattern rules\n│   ├── prompts/                   ← user-facing entry points\n│   └── hooks/                     ← lifecycle enforcement\n├── .bum/                          ← genome files (created at init)\n├── Repositories/                  ← gitignored, cloned child repos\n├── Parent/                        ← gitignored, cloned parent repo\n├── Extensions/                    ← mandatory guidelines for brain model creation\n├── BUM.md                         ← full system specification\n└── README.md                      ← this file\n```\n\n`Extensions/` is the law for brain model creation. Every agent that writes `.github/` files (`surgeon`) reads `Extensions/skills/agent-customization/references/` before creating anything.\n\n---\n\n## Quick-Start Cheatsheet\n\n| Goal                        | Command                                                            |\n| --------------------------- | ------------------------------------------------------------------ |\n| Bootstrap a new root brain  | `@epi-genome-architect` → `@morphogen` → `@surgeon` → `@developer` |\n| Extend beyond target_structure | `@expander`                                                     |\n| Spawn a child brain         | `@replicator`                                                      |\n| Update lifecycle/mode/goal  | `@polymerase`                                                      |\n| Merge a finished task brain | `@merger <child-name>`                                             |\n| Absorb child capabilities   | `@absorber <child-name>`                                           |\n| Push capability to siblings | `@pusher <capability-name>`                                        |\n| Sync epi-genome to children | `@propagator`                                                      |\n| Repair broken brain model   | `@surgeon`                                                         |\n| Audit brain model health    | `@brain-architect`                                                 |\n| Not sure what to do         | `@brain-architect`                                                 |\n","readmeFilename":"README.md","_rev":"1-2e146392cceea5651091a61e27dfba0c"}