create-booboo 0.4.1 → 0.5.0

package/dist/cli.js

@@ -101,6 +101,7 @@ var orgJson = JSON.stringify(
     booboo_org: "1.0",
     title: TITLE,
     root: "core",
+    seed: true,
     agents: [
       { id: "core", name: TITLE, emoji: "\u{1F3DB}\uFE0F", role: "the orchestrator \u2014 routes, never executes", rules: ["rules/GLOBAL.md"], buckets: ["shared"], boot: "You are the orchestrator. Boot with booboo_boot('core'); route work to your branches, never do it yourself." },
       { id: "writer", name: "Writer", emoji: "\u{1F4DD}", role: "drafts content", parent: "core", skills: ["humanizer"], buckets: ["content"] },
@@ -135,6 +136,18 @@ var readme = `# ${name} \u2014 a Booboo brain
 
 A rooted, queryable graph of your system, built with [Booboo](https://github.com/jessedu29260-netizen/booboo) (the unified operational brain).
 
+## First: shape it to your system
+
+The scaffold ships a **sample** organigram (a Writer and a Researcher) so the panel
+demos immediately. It is not yours, and \`org.booboo.json\` is flagged \`"seed": true\`
+to say so.
+
+Open this folder in Claude Code / Cursor and say **"set up my brain"**. Your agent
+reads [ONBOARDING.md](./ONBOARDING.md), looks at your actual project, asks only what
+it cannot infer, proposes a structure for you to correct, and writes the real
+organigram. Everything downstream \u2014 rules, memory buckets, who reports to whom \u2014
+inherits from that one file.
+
 ## Quickstart
 
 \`\`\`bash
@@ -199,6 +212,16 @@ var agentsMd = `# ${TITLE} \u2014 the agent contract
 *Any AI agent working in this folder reads this first, every session. It is the
 operating doctrine for this brain \u2014 the conventions match the setup.*
 
+## 0. Is this brain set up yet? (check first, every session)
+If \`org.booboo.json\` still contains \`"seed": true\`, this brain has NOT been shaped
+for this system \u2014 it is holding the scaffold's sample Writer/Researcher pair, which
+belongs to nobody. **Stop and run \`ONBOARDING.md\` before any other work.** It takes
+one pass: read the project, confirm the structure with the human, write the real org.
+
+Until that is done, do not add agents, write memories against the sample agents, or
+build anything on top of the placeholder shape \u2014 everything downstream inherits from
+the org, so work done against a fake structure has to be redone against the real one.
+
 ## What this folder is
 - \`booboo.config.yaml\` \u2014 build config (layers \xB7 sources \xB7 walls \xB7 wikilinks). Edit to shape the brain.
 - \`org.booboo.json\` \u2014 **SOURCE**: the agent organigram you boot from. Versioned, validated, edited via the panel or a reviewed change \u2014 never ad-hoc.
@@ -230,6 +253,117 @@ End substantial work by reporting plainly: what changed, what you verified again
 `;
 var claudeMd = `@AGENTS.md
 `;
+var onboardingMd = `# Set up this brain \u2014 run once, then delete this file
+
+*You are the orchestrator. This folder is a Booboo brain that has NOT been
+shaped yet: \`org.booboo.json\` still carries \`"seed": true\` and holds a sample
+Writer/Researcher pair that has nothing to do with this system. Your job is to
+replace that sample with the real structure, then clear the flag.*
+
+**Do not fabricate a structure.** Everything below is about finding out what is
+actually here before you write anything down.
+
+## 1. Read before you ask
+
+Most of an organigram is already sitting in the project. Look, in this order:
+
+- \`package.json\` / \`pyproject.toml\` / \`go.mod\` \u2014 what this thing is and is built from
+- \`README\` and any architecture doc \u2014 what it claims to do, for whom, **and how its
+  parts relate**. This is the important one, see the warning below.
+- the top two levels of directories \u2014 the candidate divisions
+- an existing \`CLAUDE.md\` / \`AGENTS.md\` / \`.cursorrules\` \u2014 conventions already agreed
+- \`git log --oneline -40\` and \`git shortlog -sn\` \u2014 what actually gets worked on, and by how many people
+- any \`docs/\`, \`ops/\`, \`infra/\` \u2014 the surfaces that need an owner
+
+**Folders give you the nouns, not the shape.** A directory listing is flat by
+construction, and an org built straight from one is a root with fifteen children
+and no structure \u2014 which is a list, not an organigram. The grouping almost always
+lives in the prose: "X is the contract at the centre, Y and Z feed it, A and B
+render it" is three divisions, and no amount of staring at the folder names will
+tell you that. Read for how the parts RELATE, then group the nouns under it.
+
+Write down what you inferred. You will show it to the human in step 3 as
+statements to correct, which is far easier to answer than an open question.
+
+## 2. Ask only what the repo cannot tell you
+
+Four questions, maximum. Fewer if you already know the answer. Ask them in one
+message, not one at a time:
+
+1. **What does this system DO, in one sentence?** (The root agent's purpose.)
+2. **What are its real divisions?** Not the folders, the *responsibilities* \u2014
+   the things that would each have an owner if this were a company.
+3. **What must never be shared between them?** Secrets, client data, anything
+   personal. These become \`walls:\` and are filtered before anything is emitted.
+4. **What should agents here remember between sessions?** Decisions, incidents,
+   customer facts, research? These become the memory buckets.
+
+If the human says "you decide" \u2014 decide, from step 1, and say what you decided
+and why. Do not stall.
+
+## 3. Propose the shape BEFORE writing it
+
+Print the organigram as a tree, in the message, with one line per agent saying
+what it owns and what it can reach. Something like:
+
+\`\`\`
+core                    the orchestrator \u2014 routes, never executes
+\u251C\u2500 <division>           <what it owns>          reaches: <buckets>
+\u2502   \u2514\u2500 <role>           <what it does>
+\u2514\u2500 <division>           <what it owns>          reaches: <buckets>
+\`\`\`
+
+Then ask one question: **"Does this match how it actually works?"** Structure is
+cheap to fix now and expensive to fix once agents boot from it.
+
+Rules of thumb worth holding:
+- **The root routes, it does not execute.** If the root is doing the work, the
+  org is one layer short.
+- **A division with one child is not a division** \u2014 collapse it.
+- **Buckets follow responsibility, not convenience.** If two agents need the
+  same bucket, that is a signal they are one agent, or that a parent should own it.
+- **Rules inherit downward.** Put a rule as high as it is true, and only there.
+  A rule restated on a child is a rule that will drift.
+
+## 4. Write it
+
+- \`org.booboo.json\` \u2014 the agents, their parents, roles, \`buckets\`, \`rules\`, a
+  \`boot\` line for the root, and a \`cadence\` on every division (see below).
+  **Remove \`"seed": true\`** \u2014 that is the whole point of this step, and the gate
+  in AGENTS.md reads it.
+
+  **Set \`cadence\` on every division: expected HOURS between reports.** Daily is
+  24, weekly 168, monthly 720. This is what the health lamp judges \u2014 silence past
+  about twice the cadence turns a card amber. Leaving it off does not mean "no
+  opinion"; consumers fall back to roughly a day, which is a machine's rhythm, so
+  a division that genuinely reports weekly will sit amber permanently and the
+  board stops meaning anything. Ask the human what each division's real beat is;
+  it is usually the answer to "how often would you expect to hear from them?"
+- \`booboo.config.yaml\` \u2014 set \`layers\` to the planes this system actually has, and
+  \`walls\` to the answer from question 3.
+- \`data.booboo.json\` \u2014 replace the sample nodes, or point \`sources\` at the real
+  database and delete it.
+- \`rules/\` \u2014 create the rule files any agent references. A \`rules:\` entry pointing
+  at a file that does not exist is a rule nobody can read.
+
+## 5. Verify against the running thing
+
+\`\`\`bash
+npm run build     # must print ok \u2014 read the quality line
+npm run panel     # the organigram, as the human will see it
+\`\`\`
+
+Check with your own eyes: every agent has a parent, the tree matches what was
+agreed in step 3, and no rule points at a missing file. \`npm run build\` failing
+or the panel showing an agent you did not intend means step 4 is not finished.
+
+## 6. Close
+
+Delete this file \u2014 it has done its job, and a completed ritual left lying around
+reads as an outstanding one. Then \`booboo_report\` what you set up, and
+\`booboo_remember\` the *reasoning* behind the divisions: the next agent inherits
+the shape from the org, but it inherits the WHY only from you.
+`;
 var files = {
   "booboo.config.yaml": configYaml,
   "data.booboo.json": dataJson,
@@ -238,7 +372,8 @@ var files = {
   "README.md": readme,
   ".gitignore": gitignore,
   "AGENTS.md": agentsMd,
-  "CLAUDE.md": claudeMd
+  "CLAUDE.md": claudeMd,
+  "ONBOARDING.md": onboardingMd
 };
 for (const [f, content] of Object.entries(files)) writeFileSync(path.join(dir, f), content, "utf8");
 console.log(`
@@ -253,6 +388,15 @@ console.log("  npm run mcp        # MCP over stdio (Claude / Cursor / Claude Cod
 console.log("  npm run view       # see your brain in 3D (opens your browser)");
 console.log("  npm run panel      # the organigram \u2014 run your agents like a company");
 console.log("  npm run vault      # the brain as a wiki-linked markdown vault (Obsidian-ready)\n");
+console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+console.log("This scaffold does NOT know your system yet. The two agents in");
+console.log("org.booboo.json are a SAMPLE so the panel demos on first run.\n");
+console.log("  Open this folder in Claude Code / Cursor and say:");
+console.log("      set up my brain\n");
+console.log("Your agent reads ONBOARDING.md, looks at your actual project, asks");
+console.log("what it can't infer, and writes the real organigram. Everything else");
+console.log("\u2014 rules, buckets, who reports to whom \u2014 flows down from that file.");
+console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
 console.log("Your agent's contract is AGENTS.md (CLAUDE.md imports it) \u2014 Claude/Codex read it");
 console.log("automatically in this folder and will follow the brain's conventions.\n");
 console.log("Then edit booboo.config.yaml to point at your own data \u2014 a postgres example is included.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-booboo",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Scaffold a new Booboo brain — `npx create-booboo my-brain`. Zero deps.",
   "license": "MIT",
   "repository": {