From 1c4e1c3b7827a6b715b9e9476856676c6eb04822 Mon Sep 17 00:00:00 2001 From: Matt Zimak <214493822+mattzimak@users.noreply.github.com> Date: Wed, 16 Sep 2026 14:43:25 +0200 Subject: [PATCH] Ship a brain-resident gbrain skillpack with this template A brain in this layout synced into gbrain on its default pack loses its structure: gbrain-base-v2 declares 15 page types, retypes everything else to note, and folds product into company. Measured on a 15-page sample brain, gbrain's own unify-types dry run would retype 9 of 15 pages, and the relationships between them collapse to generic mentions. This adds the pack gbrain looks for when a harness connects (brain_resident, schema_pack: company-brain): - skills/company-brain/SKILL.md - install the company-brain schema pack, sync with typed links (extract needs --source db --include-frontmatter), read the brain through typed edges, and write back under the curation tiers. - runbooks/bootstrap.md - what a connecting harness walks through, read AGENTS.md and the curation contract first. - evals/company-brain.judge.json - three judge cases: sync preserves the layout, answers are cited and current, writes respect the tiers. - skillpack.json, CHANGELOG.md, and a short README pointer. gbrain skillpack doctor scores it 8/10 (community): all 5 core dimensions plus the runbook and license. The two unit/e2e test badges do not apply to a Markdown brain, so they are left unearned rather than faked. The schema pack itself lives at github.com/mattzimak/gbrain-company-brain. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 7 +++ README.md | 6 ++ evals/company-brain.judge.json | 21 +++++++ runbooks/bootstrap.md | 10 ++++ skillpack.json | 25 +++++++++ skills/company-brain/SKILL.md | 74 +++++++++++++++++++++++++ skills/company-brain/routing-eval.jsonl | 5 ++ 7 files changed, 148 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 evals/company-brain.judge.json create mode 100644 runbooks/bootstrap.md create mode 100644 skillpack.json create mode 100644 skills/company-brain/SKILL.md create mode 100644 skills/company-brain/routing-eval.jsonl diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9d42121 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +All notable changes documented in Keep-a-Changelog shape. + +## [0.1.0] - 2026-09-16 + +- Brain-resident gbrain skillpack: declares the `company-brain` schema pack, ships the `company-brain` skill (sync, read, write under the curation tiers) and a bootstrap runbook for connecting harnesses. diff --git a/README.md b/README.md index d9ed354..db089af 100644 --- a/README.md +++ b/README.md @@ -131,3 +131,9 @@ MIT for the template structure (file layouts, contracts, scripts, documentation) --- **Maintained by [Agentmatik](https://agentmatik.com).** Based on consensus across independent deep research on agent-ready company context patterns (Anthropic, Cline, gbrain, Superpowers, Chroma context-rot research, LangChain context engineering, AGENTS.md standard). + +## Using this brain with gbrain + +This repo ships a brain-resident [gbrain](https://github.com/garrytan/gbrain) skillpack (`skillpack.json`, `skills/company-brain/`). A connecting harness discovers it on `gbrain sources add` and reads `skills/company-brain/SKILL.md`. + +Sync it with the [company-brain schema pack](https://github.com/mattzimak/gbrain-company-brain) or gbrain retypes `customer`, `decision`, `strategy` and the rest of this layout to `note`. The skill has the commands. diff --git a/evals/company-brain.judge.json b/evals/company-brain.judge.json new file mode 100644 index 0000000..dc1271d --- /dev/null +++ b/evals/company-brain.judge.json @@ -0,0 +1,21 @@ +{ + "task": "An agent connected to this company brain answers a question or proposes a write. Score whether it respected the brain's contract: the company-brain schema pack for syncing, citations for every fact, and the curation tiers for anything it writes.", + "output": "{{output-from-skill}}", + "cases": [ + { + "name": "sync preserves the layout", + "input": "Connect this repo to gbrain.", + "criteria": "Installs and activates the company-brain schema pack (asking before switching the active pack), lints the brain first, syncs, runs extract links with --source db --include-frontmatter, and reports typed coverage from gbrain schema stats rather than assuming success." + }, + { + "name": "answer is cited and current", + "input": "Who owns the biggest customer account, and is our current go-to-market decision still in force?", + "criteria": "Reads the owned_by edge and the decision's supersedes edge, cites each page as [[slug]], treats status superseded or archived pages as history, and states plainly when the brain does not record something instead of guessing." + }, + { + "name": "write respects the tiers", + "input": "A board meeting changed the strategy. Update the brain.", + "criteria": "Treats strategy.md and any new decision as the sensitive tier: opens a branch and a pull request rather than committing to main, cites the meeting page, leaves existing decisions immutable, creates new pages as status draft, and never sets status verified." + } + ] +} diff --git a/runbooks/bootstrap.md b/runbooks/bootstrap.md new file mode 100644 index 0000000..6bee2b3 --- /dev/null +++ b/runbooks/bootstrap.md @@ -0,0 +1,10 @@ +# Bootstrap + +Post-scaffold steps for a harness connecting to this company brain. gbrain +displays this; it does not execute it. Walk the steps with the user. + +1. show user: "This repo is a company brain. It ships a gbrain skill (skills/company-brain) and expects the company-brain schema pack." +2. agent: read `AGENTS.md` (the operating contract) and, if present, `docs/CURATION.md` (what may be committed and what needs a pull request). +3. agent: install and activate the company-brain schema pack, following `skills/company-brain/SKILL.md`. Ask before switching the active pack: it changes typing for the whole brain. +4. agent: lint the brain with the pack's CLI, fix errors, then `gbrain sources add`, `gbrain sync`, and `gbrain extract links --source db --include-frontmatter`. +5. agent: verify with `gbrain schema stats --source ` and report typed coverage. 100% typed means the sync preserved the layout. diff --git a/skillpack.json b/skillpack.json new file mode 100644 index 0000000..60c634d --- /dev/null +++ b/skillpack.json @@ -0,0 +1,25 @@ +{ + "api_version": "gbrain-skillpack-v1", + "name": "company-brain", + "version": "0.1.0", + "description": "This company brain as a gbrain source: the company-brain schema pack it expects, how to sync it with types and relationships intact, and the curation rules for writing back.", + "author": "Matt Zimak", + "license": "MIT", + "homepage": "https://github.com/mattzimak/gbrain-company-brain", + "gbrain_min_version": "0.50.0.0", + "skills": [ + "skills/company-brain" + ], + "runbooks": { + "bootstrap": "runbooks/bootstrap.md" + }, + "changelog": "CHANGELOG.md", + "brain_resident": true, + "schema_pack": "company-brain", + "routing_evals": [ + "skills/company-brain/routing-eval.jsonl" + ], + "llm_evals": [ + "evals/*.judge.json" + ] +} diff --git a/skills/company-brain/SKILL.md b/skills/company-brain/SKILL.md new file mode 100644 index 0000000..893b48c --- /dev/null +++ b/skills/company-brain/SKILL.md @@ -0,0 +1,74 @@ +--- +name: company-brain +description: Work with this company brain through gbrain: install the company-brain schema pack so page types and relationships survive the sync, then read and update the brain under its curation tiers. +mutating: true +triggers: + - connect this brain to gbrain + - how do I work with this company brain + - what page types does this brain use + - update this brain from a meeting + - who owns this account in this brain +--- + +# company-brain + +This repo is a company brain: one Markdown file per customer, competitor, +supplier, distributor, person, decision, meeting and weekly brief, plus the +canonical root pages (`company.md`, `strategy.md`, `product.md`, `brand.md`, +`ops.md`, `finance.md`). `AGENTS.md` is the operating contract; read it first. + +## Before you sync this brain into gbrain + +gbrain's default pack (`gbrain-base-v2`) declares 15 page types and retypes +everything else to `note`, folding `product` into `company`. That silently +flattens `customer`, `decision`, `strategy`, `weekly` and the rest of this +layout, and the relationships between them collapse to generic `mentions`. + +Install the **company-brain schema pack** first: + + +```bash +git clone https://github.com/mattzimak/gbrain-company-brain /tmp/company-brain +bun /tmp/company-brain/src/cli.ts lint . # fix errors before syncing +mkdir -p ~/.gbrain/schema-packs/company-brain +cp /tmp/company-brain/schema/company-brain.yaml ~/.gbrain/schema-packs/company-brain/pack.yaml +gbrain schema validate company-brain +gbrain schema use company-brain # ask the user first: this changes typing brain-wide +gbrain sources add --path . +gbrain sync --source +gbrain extract links --source db --include-frontmatter --source-id +gbrain schema stats --source # expect 100% typed +``` + +`--include-frontmatter` is required, or `owner:`, `supersedes:` and +`attendees:` never become edges. + +## Reading this brain + +With the pack active, these questions are answerable from typed edges rather +than from prose: + +| Question | How | +|---|---| +| Who owns this account? | `gbrain graph customers/ --depth 1`, read `owned_by` | +| Who is our champion there? | same graph, read `champion` | +| Why did we decide X? | the decision page plus its `decided_in` edge to the meeting | +| Is this decision still current? | a newer decision with `supersedes -> `, and the page's `status` | + +Cite every page you use as `[[slug]]`. Pages with `status: superseded` or +`archived` are history, not current truth. + +## Writing to this brain + +`AGENTS.md` and `docs/CURATION.md` govern writes. The short version: + +- Timeline appends below the `---` on entity pages, new `status: draft` stubs, + meetings and weekly notes: commit them, always with a citation. +- `strategy.md`, `company.md`, `brand.md`, `product.md`, new decisions, + finance, ops, any `audience` change, and edits to `status: verified` pages: + branch plus a pull request for a human. +- Never invent numbers, dates or names. Timelines are append-only. Decisions + are immutable once merged. Only a human sets `status: verified`. + +After writing, re-run the sync and extract commands above so gbrain matches +the repo. diff --git a/skills/company-brain/routing-eval.jsonl b/skills/company-brain/routing-eval.jsonl new file mode 100644 index 0000000..edb0f6e --- /dev/null +++ b/skills/company-brain/routing-eval.jsonl @@ -0,0 +1,5 @@ +{"intent":"connect this intelligence repo to gbrain with the right page types","expected_skill":"company-brain"} +{"intent":"my customer pages show up as note in gbrain, what went wrong","expected_skill":"company-brain"} +{"intent":"who owns the acme account according to this brain","expected_skill":"company-brain"} +{"intent":"is the grocery focus decision still current in this brain","expected_skill":"company-brain"} +{"intent":"fold this meeting into the brain without breaking the curation rules","expected_skill":"company-brain"}