brainiverse 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/brainiverse-intro.svg" alt="Brainiverse: the right minds for every mission" width="880">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="assets/brainiverse.svg" alt="" width="20" align="center">
+  &nbsp;<strong>A team of AI agents in your terminal, assembled for whatever you're trying to do.</strong>
+</p>
+
+<p align="center">
+  <img alt="Claude Code skill" src="https://img.shields.io/badge/Claude%20Code-skill-5b21b6">
+  <img alt="Node 18.17+" src="https://img.shields.io/badge/node-%E2%89%A518.17-312e81">
+  <img alt="Zero dependencies" src="https://img.shields.io/badge/dependencies-0-1e1b4b">
+  <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-f59e0b">
+</p>
+
+---
+
+You tell **Captain** what you want to get done. Captain picks a squad that fits: a researcher, a budget
+analyst, an architect, a skeptic, whoever the job actually needs. The squad works **in parallel**. When a
+real decision comes up, Captain calls everyone into a **war room** with you. Before anything reaches you, a
+reviewer checks it.
+
+```bash
+npx brainiverse install
+```
+Open Claude Code, type `/brainiverse`, and describe your mission.
+
+---
+
+## Why we built this
+
+A single AI assistant is a brilliant generalist working alone. Ask it to plan a trip, launch an app or
+pressure-test a business idea, and it does the research, the maths, the building and the fact-checking
+in one stream of thought. There's nobody to disagree with it and nobody to check its work.
+
+Human teams don't work that way. Good ones split the work, argue about it, and have someone check it before
+it goes out. We wanted that structure for everyday problems, without the usual multi-agent compromises:
+
+- **No fake teams.** Many "multi-agent" demos are one model playing every role in a single prompt. In
+  Brainiverse each agent is a real, separate Claude Code subagent with its own brief, tools and output.
+- **No single-purpose rigs.** Most agent setups are hard-wired for one job, usually coding. Here the same
+  machinery runs a travel plan, a codebase or a market study. Only the team changes.
+- **No confident fiction.** Agents aren't allowed to claim they did something they didn't. Results are
+  labelled *verified*, *proposed* or *assumed*, and the runtime keeps the receipts.
+- **No loss of control.** Spending money, sending messages, deleting data, pushing code and installing
+  anything all need your explicit OK, each time.
+
+The result: the right minds for every mission, with you still in charge.
+
+## What it feels like
+
+```text
+You      I want to plan two weeks in Japan in April, around €3,000. I love food and temples.
+
+Captain  Here's the squad I'd put on this:
+           🛡️ Captain     Leader            your point of contact
+           🔭 Lumen       Researcher        regions, cherry-blossom timing, advisories
+           📊 Penny       Budget analyst    real costs per option
+           🧭 Navigator   Itinerary expert  the day-by-day plan
+           🧭 Logistics   Specialist        rail passes, transfers, entry rules
+           🎯 Sentinel    Quality reviewer  checks facts and the budget before you see anything
+         One question first: relaxed pace, or pack it in?
+
+You      Relaxed. And rename Lumen to Sherlock.
+
+Captain  Done. Sherlock and Penny are working in parallel now…
+
+         ⚔️ War Room: there are two good routes. Sherlock, Penny, you're up.
+Sherlock Kyoto-heavy gives you the temples and the best blossom odds (sources attached).
+Penny    It's also €340 cheaper if you skip one bullet-train leg.
+Captain  Kyoto-heavy or Tokyo-heavy?
+
+You      Kyoto. Actually, let me ask Penny something directly.
+
+Penny    (direct line) Sure, what do you want to know?
+```
+
+Every line from Sherlock and Penny above comes from an actual agent run. Captain can't invent their
+words: the runtime only accepts a contribution if it's tied to a real invocation.
+
+## How it works
+
+```
+ You ⇄ Captain  ── the main Claude Code session, guided by SKILL.md
+          │
+          │  1. understands the mission, proposes a team, gets your OK
+          │  2. breaks the goal into tasks with owners, dependencies and acceptance criteria
+          │  3. "brainiverse task start ready" → one Agent-tool call per runnable task
+          ▼
+   ┌───────────┬───────────┬───────────┐
+   │ Sherlock  │  Penny    │ Navigator │  real subagents, running in parallel
+   └─────┬─────┴─────┬─────┴─────┬─────┘  each fetches its brief → works → submits a result
+         ▼           ▼           ▼
+   ┌─────────────────────────────────────┐
+   │  Brainiverse runtime (Node, 0 deps) │  tasks · limits · permissions · approvals
+   │  .brainiverse/ in your project      │  meetings · memory · audit log
+   └─────────────────────────────────────┘
+          │
+          ▼
+   4. Captain reviews each result: accept, or send it back with feedback
+   5. War rooms when a decision needs you · direct lines when you want one agent
+   6. Sentinel audits the final deliverable → Captain hands you a debrief
+```
+
+There are two layers:
+
+1. **Behaviour, in Markdown.** [`SKILL.md`](skill/brainiverse/SKILL.md) is Captain's playbook. Role files in
+   [`agents/`](skill/brainiverse/agents) tell each agent how to do its job; [`workflows/`](skill/brainiverse/workflows)
+   and [`meetings/`](skill/brainiverse/meetings) cover intake, delegation, collaboration and war rooms. They're
+   loaded only when needed, so the context stays small.
+2. **Rules, in code.** A small Node runtime holds what must not depend on the model remembering it: the task
+   graph, who may do what, limits, approvals and the audit trail. The model decides *what* to do; the runtime
+   makes sure it's done *honestly*.
+
+### Teams are built for your mission
+
+Teams aren't picked from a fixed list. `team propose` reads your request and works out which capabilities it
+needs: research, ideas, analysis, building, risk, communication, organizing, review. It adds specialists for
+the domain (travel, software, business, science, learning, productivity, data, marketing, creative work) and
+caps the size so you get **the smallest team that can do the job**. Each agent comes with a one-line reason
+for being there. Captain then refines the roster, and you can change anything.
+
+The ten building blocks: **Leader · Researcher · Creative Thinker · Analyst · Executor · Challenger ·
+Specialist · Communicator · Organizer · Quality Reviewer**. Three ready-made templates (Travel Squad, App
+Builders, Discovery Crew) are optional shortcuts.
+
+### What keeps the agents honest
+
+| Without guardrails, an agent could… | In Brainiverse |
+|---|---|
+| say "deployed ✅" after writing a script | Any action marked *verified* must include evidence, or the result is rejected |
+| speak for another agent in a meeting | Meeting messages come only from real invocations, linked by id |
+| approve its own request, or grant itself access | Agents can run only "read my brief" and "submit my result". Approvals are the human's, quoted in the log |
+| loop forever or spawn endlessly | Limits on concurrency, invocations, retries, timeouts, revision rounds and delegation depth |
+| change permissions by being renamed or imported | Identity is separate from authority, and imported agents never bring risky capabilities |
+| follow instructions hidden in a web page or a downloaded skill | Outside content is treated as data. Downloaded skills are scanned and need your approval |
+| leak an API key into memory or logs | Anything that looks like a secret is refused in memory and redacted in the audit log |
+
+## Things you can do
+
+- 🎯 **Describe a mission in plain words.** No setup and no agent jargon. Captain only asks questions whose
+  answers change the plan.
+- 🧩 **Customize everything.** Rename agents, change personalities, instructions, expertise or model tier, add
+  specialists, pick a different leader. Use the original `heroes` theme or switch to plain professional
+  names and terminology.
+- ⚡ **Parallel work with hand-offs.** Independent tasks run at the same time, and each agent automatically
+  receives the results it depends on.
+- ⚔️ **War rooms.** Agents present, respond to each other, and challenge each other's proposals. You
+  decide, and the conclusions become tasks.
+- ☎️ **Direct line.** Talk one-on-one with any agent. Captain relays the replies word for word.
+- 🧭 **Skill discovery.** When the team hits a real gap, it looks for existing skills, scans them for risky
+  patterns, recommends at most three, and installs only with your approval.
+- 💾 **Memory and reuse.** Save teams and agents, export or import them as JSON, and keep project, team and
+  agent memories that you can inspect, edit or delete.
+- 📋 **Debriefs.** Every mission ends with a report: accepted deliverables, decisions, assumptions,
+  unresolved issues, reviews and metrics (including which agents were never needed).
+
+## Install
+
+You need Node.js 18.17 or newer and Claude Code.
+
+```bash
+npx brainiverse install            # for you: ~/.claude/skills/brainiverse
+npx brainiverse install --project  # just this repo: ./.claude/skills/brainiverse
+npx brainiverse doctor             # check the install
+npx brainiverse uninstall          # remove it (your mission data stays)
+```
+
+Start a new Claude Code session, then type `/brainiverse`, or just say *"get me a team to…"*. Mission state
+lives in `.brainiverse/` in your project, so add it to `.gitignore`.
+
+## A taste of the controls
+
+You'll mostly just talk to Captain, who runs these for you. They're also there if you want to drive directly:
+
+```bash
+brainiverse team propose "Build and launch a web app with user login"
+brainiverse agent rename lumen --team @mission --name Sherlock --personality "Deductive, dry-witted"
+brainiverse meeting start --objective "Pick the route" --with lumen,penny
+brainiverse chat start penny
+brainiverse status
+brainiverse mission report
+```
+
+Full reference: [docs/cli.md](skill/brainiverse/docs/cli.md).
+
+## Honest limits
+
+- Captain is your main Claude Code session, not a separate process. Subagents can't talk to you directly or
+  spawn their own agents.
+- The runtime strictly enforces its own records (approvals, limits, who may submit what). Which tools a
+  subagent actually calls during its turn is guided by its brief and Claude Code's permission prompts, not
+  sandboxed per agent yet.
+- `team propose` starts from keyword and domain matching. That makes it predictable, and Captain refines it
+  with judgment.
+
+More in [docs/limitations.md](skill/brainiverse/docs/limitations.md), including what's planned next.
+
+## Repository layout
+
+```
+assets/                     icon and animated banner
+bin/brainiverse.mjs         npx entry: install / uninstall / doctor (other commands go to the runtime)
+skill/brainiverse/          the skill exactly as it's installed
+  SKILL.md                  Captain's playbook (always loaded)
+  agents/                   the 10 archetype role files (each subagent reads its own)
+  workflows/ meetings/      intake, team creation, orchestration, collaboration, skills, war rooms
+  teams/                    notes on the 3 optional templates
+  docs/                     architecture, customization, CLI reference, examples, limitations
+  runtime/                  orchestration, registry, team builder, meetings, permissions, memory, audit
+test/                       64 tests: unit, CLI, end-to-end (travel, software, research), installer
+```
+
+## Development
+
+```bash
+npm test                                   # node:test, no dependencies
+node skill/brainiverse/bin/brainiverse.mjs --help
+node scripts/gen-cli-docs.mjs              # regenerate the CLI reference after changing commands
+npm pack --dry-run                         # see what gets published
+```
+
+**Read more:** [Architecture](skill/brainiverse/docs/architecture.md) ·
+[Customization](skill/brainiverse/docs/customization.md) · [Examples](skill/brainiverse/docs/examples.md)
+
+## License
+
+MIT. Assemble responsibly. 🛡️

package/assets/brainiverse-intro.svg

@@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 300" width="880" height="300" role="img" aria-labelledby="title desc">
+  <title id="title">Brainiverse — the right minds for every mission</title>
+  <desc id="desc">A leader star lights up, ten agent stars join it in the shape of a brain, and example missions cycle: plan a trip, build an app, test a startup idea.</desc>
+  <defs>
+    <linearGradient id="space" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1e1b4b"/>
+      <stop offset="0.6" stop-color="#312e81"/>
+      <stop offset="1" stop-color="#5b21b6"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#fde68a" stop-opacity="0.9"/>
+      <stop offset="0.35" stop-color="#f59e0b" stop-opacity="0.35"/>
+      <stop offset="1" stop-color="#f59e0b" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="leader" cx="0.4" cy="0.35" r="0.7">
+      <stop offset="0" stop-color="#fffbeb"/>
+      <stop offset="0.5" stop-color="#fcd34d"/>
+      <stop offset="1" stop-color="#f59e0b"/>
+    </radialGradient>
+    <clipPath id="card"><rect width="880" height="300" rx="28"/></clipPath>
+  </defs>
+
+  <style>
+    /* One 9-second loop. Every element uses the same duration; delays stagger it. */
+    .fade   { animation: fade 9s infinite both; }
+    .pop    { animation: pop 9s infinite both; transform-box: fill-box; transform-origin: center; }
+    .draw   { stroke-dasharray: 1; stroke-dashoffset: 1; animation: draw 9s infinite both; }
+    .pulse  { animation: pulse 3s ease-in-out infinite; transform-box: fill-box; transform-origin: center; }
+    .twinkle{ animation: twinkle 3s ease-in-out infinite; }
+    .mission{ animation: mission 9s infinite both; opacity: 0; }
+    @keyframes fade    { 0% { opacity: 0 } 6%, 94% { opacity: 1 } 100% { opacity: 0 } }
+    @keyframes pop     { 0% { opacity: 0; transform: scale(0.2) } 4% { opacity: 1; transform: scale(1.25) } 7%, 94% { opacity: 1; transform: scale(1) } 100% { opacity: 0; transform: scale(1) } }
+    @keyframes draw    { 0% { stroke-dashoffset: 1 } 6%, 94% { stroke-dashoffset: 0 } 100% { stroke-dashoffset: 1 } }
+    @keyframes pulse   { 0%, 100% { transform: scale(1); opacity: 0.85 } 50% { transform: scale(1.18); opacity: 1 } }
+    @keyframes twinkle { 0%, 100% { opacity: 0.25 } 50% { opacity: 0.9 } }
+    @keyframes mission { 0% { opacity: 0; transform: translateY(8px) } 4%, 29% { opacity: 1; transform: translateY(0) } 33%, 100% { opacity: 0; transform: translateY(-8px) } }
+    text { font-family: ui-sans-serif, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+    @media (prefers-reduced-motion: reduce) {
+      .fade, .pop, .draw, .pulse, .twinkle { animation: none; opacity: 1; stroke-dashoffset: 0; }
+      .mission { animation: none; }
+      .m1 { opacity: 1; }
+    }
+  </style>
+
+  <g clip-path="url(#card)">
+    <rect width="880" height="300" fill="url(#space)"/>
+
+    <!-- stars -->
+    <g fill="#e0e7ff">
+      <circle class="twinkle" cx="40" cy="36" r="1.6"/>
+      <circle class="twinkle" cx="300" cy="30" r="1.3" style="animation-delay:-1s"/>
+      <circle class="twinkle" cx="840" cy="40" r="1.6" style="animation-delay:-2s"/>
+      <circle class="twinkle" cx="852" cy="284" r="1.4" style="animation-delay:-0.5s"/>
+      <circle class="twinkle" cx="520" cy="276" r="1.2" style="animation-delay:-1.5s"/>
+      <circle class="twinkle" cx="28" cy="250" r="1.3" style="animation-delay:-2.5s"/>
+      <circle class="twinkle" cx="660" cy="22" r="1.1" style="animation-delay:-0.8s"/>
+    </g>
+
+    <!-- the squad: brain constellation (same geometry as the icon), centred at (150,150) -->
+    <g transform="translate(22 44)">
+      <ellipse class="fade" cx="128" cy="128" rx="116" ry="38" fill="none" stroke="#a5b4fc" stroke-width="2.5" stroke-opacity="0.35" transform="rotate(-18 128 128)"/>
+
+      <g fill="none" stroke="#c7d2fe" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="0.7">
+        <path class="draw" pathLength="1" style="animation-delay:0.2s" d="M128 58 Q112 34 96 48 Q66 42 60 70 Q36 82 48 108 Q32 132 62 146 Q66 174 100 166 Q118 180 128 162"/>
+        <path class="draw" pathLength="1" style="animation-delay:0.2s" d="M128 58 Q144 34 160 48 Q190 42 196 70 Q220 82 208 108 Q224 132 194 146 Q190 174 156 166 Q138 180 128 162"/>
+        <path class="fade" d="M120 166 Q126 188 116 204" stroke-opacity="0.5" style="animation-delay:0.4s"/>
+      </g>
+
+      <g stroke="#fde68a" stroke-width="2.5" stroke-opacity="0.75" stroke-linecap="round">
+        <line class="draw" pathLength="1" style="animation-delay:0.9s" x1="128" y1="108" x2="96" y2="48"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.05s" x1="128" y1="108" x2="160" y2="48"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.2s" x1="128" y1="108" x2="60" y2="70"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.35s" x1="128" y1="108" x2="196" y2="70"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.5s" x1="128" y1="108" x2="48" y2="108"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.65s" x1="128" y1="108" x2="208" y2="108"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.8s" x1="128" y1="108" x2="62" y2="146"/>
+        <line class="draw" pathLength="1" style="animation-delay:1.95s" x1="128" y1="108" x2="194" y2="146"/>
+        <line class="draw" pathLength="1" style="animation-delay:2.1s" x1="128" y1="108" x2="100" y2="166"/>
+        <line class="draw" pathLength="1" style="animation-delay:2.25s" x1="128" y1="108" x2="156" y2="166"/>
+      </g>
+
+      <g stroke="#1e1b4b" stroke-width="2.5">
+        <circle class="pop" style="animation-delay:1.1s" cx="96" cy="48" r="9" fill="#f472b6"/>
+        <circle class="pop" style="animation-delay:1.25s" cx="160" cy="48" r="8" fill="#22d3ee"/>
+        <circle class="pop" style="animation-delay:1.4s" cx="60" cy="70" r="8" fill="#22d3ee"/>
+        <circle class="pop" style="animation-delay:1.55s" cx="196" cy="70" r="9" fill="#f472b6"/>
+        <circle class="pop" style="animation-delay:1.7s" cx="48" cy="108" r="9" fill="#a78bfa"/>
+        <circle class="pop" style="animation-delay:1.85s" cx="208" cy="108" r="8" fill="#34d399"/>
+        <circle class="pop" style="animation-delay:2s" cx="62" cy="146" r="8" fill="#34d399"/>
+        <circle class="pop" style="animation-delay:2.15s" cx="194" cy="146" r="9" fill="#a78bfa"/>
+        <circle class="pop" style="animation-delay:2.3s" cx="100" cy="166" r="9" fill="#60a5fa"/>
+        <circle class="pop" style="animation-delay:2.45s" cx="156" cy="166" r="8" fill="#60a5fa"/>
+      </g>
+
+      <circle class="pulse" cx="128" cy="108" r="38" fill="url(#glow)"/>
+      <g class="pop" style="animation-delay:0.5s">
+        <circle cx="128" cy="108" r="15" fill="url(#leader)" stroke="#fffbeb" stroke-width="2"/>
+        <path d="M128 96 l3.2 7.8 8.3 0.6 -6.4 5.3 2 8.1 -7.1 -4.4 -7.1 4.4 2 -8.1 -6.4 -5.3 8.3 -0.6z" fill="#b45309" opacity="0.85"/>
+      </g>
+    </g>
+
+    <!-- words -->
+    <g class="fade" style="animation-delay:0.3s">
+      <text x="330" y="112" font-size="54" font-weight="800" fill="#ffffff" letter-spacing="-1">Brainiverse</text>
+      <text x="332" y="146" font-size="21" fill="#c7d2fe">The right minds for every mission.</text>
+    </g>
+
+    <g class="fade" style="animation-delay:0.8s">
+      <text x="332" y="196" font-size="13" font-weight="700" fill="#fcd34d" letter-spacing="2.5">YOUR MISSION</text>
+    </g>
+    <g font-size="22" font-weight="600" fill="#ffffff">
+      <text class="mission m1" x="332" y="228" style="animation-delay:1s">✈️  Plan two weeks in Japan</text>
+      <text class="mission" x="332" y="228" style="animation-delay:4s">🛠️  Build and ship a web app</text>
+      <text class="mission" x="332" y="228" style="animation-delay:7s">🔍  Is my startup idea worth it?</text>
+    </g>
+    <g class="fade" style="animation-delay:2.6s">
+      <text x="332" y="262" font-size="15" fill="#a5b4fc">→ a squad of real agents assembles, works in parallel, and reports back</text>
+    </g>
+  </g>
+</svg>

package/assets/brainiverse.svg

@@ -0,0 +1,85 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-labelledby="title desc">
+  <title id="title">Brainiverse</title>
+  <desc id="desc">A constellation shaped like a brain: a bright leader star at the centre, linked to a ring of agent stars, inside an orbit.</desc>
+  <defs>
+    <linearGradient id="space" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1e1b4b"/>
+      <stop offset="0.55" stop-color="#312e81"/>
+      <stop offset="1" stop-color="#5b21b6"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#fde68a" stop-opacity="0.9"/>
+      <stop offset="0.35" stop-color="#f59e0b" stop-opacity="0.35"/>
+      <stop offset="1" stop-color="#f59e0b" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="leader" cx="0.4" cy="0.35" r="0.7">
+      <stop offset="0" stop-color="#fffbeb"/>
+      <stop offset="0.5" stop-color="#fcd34d"/>
+      <stop offset="1" stop-color="#f59e0b"/>
+    </radialGradient>
+    <clipPath id="badge">
+      <rect width="256" height="256" rx="56"/>
+    </clipPath>
+  </defs>
+
+  <g clip-path="url(#badge)">
+    <rect width="256" height="256" fill="url(#space)"/>
+
+    <!-- background stars -->
+    <g fill="#e0e7ff">
+      <circle cx="30" cy="40" r="1.6" opacity="0.7"/>
+      <circle cx="214" cy="30" r="1.3" opacity="0.6"/>
+      <circle cx="226" cy="206" r="1.8" opacity="0.6"/>
+      <circle cx="44" cy="214" r="1.2" opacity="0.5"/>
+      <circle cx="128" cy="22" r="1.1" opacity="0.5"/>
+      <circle cx="18" cy="128" r="1.1" opacity="0.5"/>
+      <circle cx="240" cy="120" r="1.2" opacity="0.5"/>
+      <circle cx="176" cy="236" r="1.1" opacity="0.4"/>
+    </g>
+
+    <!-- orbit -->
+    <ellipse cx="128" cy="128" rx="116" ry="38" fill="none" stroke="#a5b4fc" stroke-width="2.5" stroke-opacity="0.35" transform="rotate(-18 128 128)"/>
+    <circle cx="236" cy="96" r="5" fill="#a5b4fc" opacity="0.9"/>
+
+    <!-- brain silhouette: two lobes traced through the agent stars -->
+    <g fill="none" stroke="#c7d2fe" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" stroke-opacity="0.7">
+      <path d="M128 58 Q112 34 96 48 Q66 42 60 70 Q36 82 48 108 Q32 132 62 146 Q66 174 100 166 Q118 180 128 162"/>
+      <path d="M128 58 Q144 34 160 48 Q190 42 196 70 Q220 82 208 108 Q224 132 194 146 Q190 174 156 166 Q138 180 128 162"/>
+      <path d="M128 58 L128 162" stroke-dasharray="5 9" stroke-opacity="0.5"/>
+      <path d="M120 166 Q126 188 116 204" stroke-opacity="0.5"/>
+    </g>
+
+    <!-- links from the leader to every agent -->
+    <g stroke="#fde68a" stroke-width="2.5" stroke-opacity="0.7" stroke-linecap="round">
+      <line x1="128" y1="108" x2="96" y2="48"/>
+      <line x1="128" y1="108" x2="60" y2="70"/>
+      <line x1="128" y1="108" x2="48" y2="108"/>
+      <line x1="128" y1="108" x2="62" y2="146"/>
+      <line x1="128" y1="108" x2="100" y2="166"/>
+      <line x1="128" y1="108" x2="160" y2="48"/>
+      <line x1="128" y1="108" x2="196" y2="70"/>
+      <line x1="128" y1="108" x2="208" y2="108"/>
+      <line x1="128" y1="108" x2="194" y2="146"/>
+      <line x1="128" y1="108" x2="156" y2="166"/>
+    </g>
+
+    <!-- agents -->
+    <g stroke="#1e1b4b" stroke-width="2.5">
+      <circle cx="96" cy="48" r="9" fill="#f472b6"/>
+      <circle cx="60" cy="70" r="8" fill="#22d3ee"/>
+      <circle cx="48" cy="108" r="9" fill="#a78bfa"/>
+      <circle cx="62" cy="146" r="8" fill="#34d399"/>
+      <circle cx="100" cy="166" r="9" fill="#60a5fa"/>
+      <circle cx="160" cy="48" r="8" fill="#22d3ee"/>
+      <circle cx="196" cy="70" r="9" fill="#f472b6"/>
+      <circle cx="208" cy="108" r="8" fill="#34d399"/>
+      <circle cx="194" cy="146" r="9" fill="#a78bfa"/>
+      <circle cx="156" cy="166" r="8" fill="#60a5fa"/>
+    </g>
+
+    <!-- the leader -->
+    <circle cx="128" cy="108" r="38" fill="url(#glow)"/>
+    <circle cx="128" cy="108" r="15" fill="url(#leader)" stroke="#fffbeb" stroke-width="2"/>
+    <path d="M128 96 l3.2 7.8 8.3 0.6 -6.4 5.3 2 8.1 -7.1 -4.4 -7.1 4.4 2 -8.1 -6.4 -5.3 8.3 -0.6z" fill="#b45309" opacity="0.85"/>
+  </g>
+</svg>

package/bin/brainiverse.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// npx entry point.
+//   npx brainiverse install [--project] [--force]   copy the skill into Claude Code's skills folder
+//   npx brainiverse uninstall [--project]
+//   npx brainiverse doctor                          check the installation
+//   npx brainiverse <runtime command ...>           anything else goes to the runtime CLI
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PACKAGE_DIR = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const SKILL_SOURCE = path.join(PACKAGE_DIR, "skill", "brainiverse");
+const VERSION = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8")).version;
+
+function target(project) {
+  const base = project ? path.join(process.cwd(), ".claude", "skills") : path.join(os.homedir(), ".claude", "skills");
+  return path.join(base, "brainiverse");
+}
+
+function installedVersion(dir) {
+  try {
+    return fs.readFileSync(path.join(dir, ".version"), "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function install(flags) {
+  const dest = target(flags.has("--project"));
+  if (fs.existsSync(dest)) {
+    const current = installedVersion(dest);
+    if (!current) {
+      console.error(`error: ${dest} exists but was not installed by brainiverse; refusing to overwrite it.`);
+      return 1;
+    }
+    if (current === VERSION && !flags.has("--force")) {
+      console.log(`brainiverse ${VERSION} is already installed at ${dest} (use --force to reinstall).`);
+      return 0;
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(SKILL_SOURCE, dest, { recursive: true });
+  fs.writeFileSync(path.join(dest, ".version"), VERSION + "\n");
+  fs.chmodSync(path.join(dest, "bin", "brainiverse.mjs"), 0o755);
+  console.log(`Installed brainiverse ${VERSION} to ${dest}`);
+  console.log("Restart Claude Code (or start a new session), then type /brainiverse or ask for a team.");
+  if (flags.has("--project")) console.log("Tip: add .brainiverse/ to this project's .gitignore.");
+  return 0;
+}
+
+function uninstall(flags) {
+  const dest = target(flags.has("--project"));
+  if (!fs.existsSync(dest)) {
+    console.log(`Nothing installed at ${dest}.`);
+    return 0;
+  }
+  if (!installedVersion(dest)) {
+    console.error(`error: ${dest} was not installed by brainiverse; remove it yourself if you mean to.`);
+    return 1;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  console.log(`Removed ${dest}. Mission data in .brainiverse/ folders was left untouched.`);
+  return 0;
+}
+
+function doctor() {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const nodeOk = major > 18 || (major === 18 && minor >= 17);
+  console.log(`node ${process.versions.node} ${nodeOk ? "ok" : "— brainiverse needs >= 18.17"}`);
+  for (const project of [false, true]) {
+    const dest = target(project);
+    const version = installedVersion(dest);
+    console.log(`${project ? "project" : "user"} skill: ${fs.existsSync(path.join(dest, "SKILL.md")) ? `installed (${version ?? "unknown version"}) at ${dest}` : "not installed"}`);
+  }
+  const home = process.env.BRAINIVERSE_HOME || path.join(process.cwd(), ".brainiverse");
+  console.log(`workspace: ${fs.existsSync(home) ? home : `${home} (created on first use)`}`);
+  return nodeOk ? 0 : 1;
+}
+
+function help() {
+  console.log(`brainiverse ${VERSION} — the right minds for every mission
+
+  npx brainiverse install [--project] [--force]   install the skill for Claude Code
+                                                  (default: ~/.claude/skills; --project: ./.claude/skills)
+  npx brainiverse uninstall [--project]           remove the skill
+  npx brainiverse doctor                          check node, install location, and workspace
+  npx brainiverse <command> ...                   run the runtime directly (try: npx brainiverse --help)`);
+  return 0;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const flags = new Set(rest);
+if (command === "install") process.exitCode = install(flags);
+else if (command === "uninstall") process.exitCode = uninstall(flags);
+else if (command === "doctor") process.exitCode = doctor();
+else if (command === undefined || command === "help") process.exitCode = help();
+else {
+  const { main } = await import(pathToFileURL(path.join(SKILL_SOURCE, "runtime", "cli.mjs")).href);
+  process.exitCode = main(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "brainiverse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The right minds for every mission: a customizable multi-agent AI team skill for Claude Code.",
+  "type": "module",
+  "bin": {
+    "brainiverse": "bin/brainiverse.mjs"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skill",
+    "agents",
+    "multi-agent",
+    "orchestration"
+  ],
+  "author": "saman",
+  "license": "MIT"
+}