A Claude Code plugin that gives any repository a shared, versioned team brain. Intent, agreed rules, decisions and lessons live in git, load into every session, and are enforced by hooks. When one developer corrects the AI, the whole team inherits the correction by pull request.
Project intent ✓ Purpose stated ✓ Owner stated ✓ boundaries stated (We do not) Constraints ✓ 9 constraint(s), each traced with Why: ✓ exceptions are approved and time-bound Decisions ✓ 4 decision(s), each with a cost and a rejected alternative Lessons ✓ 5 lesson(s) Sensitive paths ✓ 5 pattern(s) brain-check: brain is sound
Repogenic/team-brain:initThe problem
The repository is the genome. The brain is how the team’s judgment gets inherited.
Teams adopting AI coding tools hit the same wall. Each developer’s prompts, corrections and habits live in their own session and disappear with it. The senior engineer who tells the AI “never touch the payments schema without a migration plan” teaches one session, not the team. New joiners start from zero. Reviewers cannot see what the AI was told.
Earlier attempts each solved part of it. The brief was to keep only what we still agreed on and make it work in any repository:
How it was delivered
Team Brain is what happens when RepoGenics is pointed at its own history: four earlier attempts were the variation, practice was the selection, and only the survivors were inherited.
“Take the best, use just what we still agree on.” The plugin’s own intent/project-intent.md states its purpose, owner and five things it deliberately does not do.
TeamBrain (Mar), intent-drive-starter (Jul), the IDE plugin (Sep) and a portable kit (Sep) each tried a different shape of the same idea.
What held up in real use stayed. The seven-question ritual, up-front constraint documents and pasted prompts did not, and why is recorded as ADRs.
Built on intent-drive-starter unchanged, so teams keep the feature loop they learned. Past bugs became regression tests and one-line lessons.
Hooks that ask instead of block, fail open, judge only the command that runs, and a no-AI checker that never reports green from the wrong folder.
What we built
/team-brain:init lays down a small set of plain files without overwriting anything the team already has. CLAUDE.md imports them, so they are in context from the first prompt; AGENTS.md carries the same rules to Copilot, Cursor and Codex. Hooks enforce the parts that matter, and three skills feed what the team learns back into git.
Why the system exists, who owns it, the primary tradeoff and what it deliberately does not do.
Rules the team actually agreed on. Every bullet carries Why:. Exceptions are named, approved and time-bound.
Architecture decisions with what was gained, what was given up, what was rejected and how to roll back.
/team-brain:decideChecked cost and rejected alternative presentOne-line corrections the team does not want to repeat, each with where it came from.
/team-brain:rememberChecked warns past 60 linesFeature gate, sensitive paths, destructive commands, brain validation. Risk becomes an approval prompt, not a surprise.
An independent reviewer agent checks the change against intent, constraints, lessons, decisions and sensitive paths, not just the diff.
Run end to end on a fresh repository with the plugin installed from GitHub. Each step is reproducible.
claude plugin install team-brain@team-brain from the live marketplace, version 1.0.0.CLAUDE.md and AGENTS.md kept and extended.brain/check.sh fails: Purpose and Owner are empty. On purpose.The guardrails
A guard that fires on everything gets switched off, so false positives are treated as bugs. The command guard looks at the command word that actually runs, after stripping quoted text, so a commit message that mentions git push --force is not a force push. Two false positives from the earlier plugin are now permanent regression tests.
The proof
Hooks run on every developer’s laptop, not on one controlled server. So the suite runs with jq, python3 and node each removed in turn, then with none of them, and in GitHub Actions on both Ubuntu and macOS, where BSD tools broke an earlier version.
main.| 68 tests passing | VERIFIEDbash tests/run.sh reports 68 passed, 0 failed with jq present, with only python3, with only node, and with no JSON parser at all. |
|---|---|
| Ubuntu and macOS CI | VERIFIEDGitHub Actions runs the suite on ubuntu-latest and macos-latest, plus the repository’s own brain-check job. All three succeeded on main. |
| Installs from the marketplace | VERIFIEDclaude plugin marketplace add kendallmark3/team-brain then claude plugin install team-brain@team-brain in a clean Claude Code 2.1.310 config: installed, enabled, all seven skills present. |
| Plugin manifest valid | VERIFIEDclaude plugin validate . passes. Remaining warnings: no icon yet, and a root CLAUDE.md that is intentional, because the repo dogfoods its own brain. |
| Init never overwrites | VERIFIEDTests run init over existing CLAUDE.md, AGENTS.md and lessons, then run it again: team content kept, exactly one managed block, re-run is byte-identical. |
| Fresh repo end to end | VERIFIEDInit, check fails, Purpose and Owner filled, check passes, session hook announces the brain. Run against the installed copy of the plugin. |
| Team adoption and effect | NOT YETNo team has used it on a live codebase yet. Fewer repeated corrections and faster onboarding are the expected benefit, not a measured one. A pilot repository with before and after review data is the next step. |
| Hooks in a live interactive session | NOT YETHook scripts are tested directly with the JSON Claude Code sends. A recorded interactive session showing the approval prompt firing is still to be captured. |
What changed along the way
The most valuable part of the build was deciding what to leave out. Each “dropped” item below was tried in an earlier version and replaced with something lighter that teams actually kept using.
brain/decisions.md, so the next version starts from these reasons instead of rediscovering them.The first fresh-repo run counted the template’s example decision as a real one. Fixed, and the fix became a test. A blank feature file created by init would have gated the whole repo the day the brain merged; init no longer creates it.
The old hook parsed JSON with sed and broke on escaped quotes. Team Brain reads JSON with jq, python3 or node, falls back to a portable sed reader, and splits commands in pure bash because macOS sed ignores \n.
Five of those lessons are in the plugin’s own brain/lessons.md. The next engineer, or the next AI session, inherits them on the first prompt.
Why these technologies
One install gives every repository on a machine the skills and hooks, and a version bump reaches the whole team. The repo is its own marketplace, inherited unchanged from intent-drive-starter.
Reviewed in pull requests, diffed in history, readable by any assistant and any human. No service to buy, secure or keep running, and nothing to approve inside a client’s enterprise.
Present on every Mac and Linux machine and CI runner. Node-only hooks would fail on native Claude Code installs; Python-only hooks are not guaranteed on CI images. That tradeoff is ADR-004.
Why it matters
A correction made once becomes a lesson everyone’s session starts with. Expected benefit: fewer repeated review comments. To be measured in a pilot.
What the AI was told is in the repository and in the pull request history, so reviewers and auditors can see the rules instead of guessing at prompts.
Copy the files, keep the brain. Consultants inside locked-down enterprises lose only the hooks; CLAUDE.md, AGENTS.md and the CI check all still apply.
Install Team Brain in a pilot repository, or have Repogenic set up the intent, constraints and review loop with your engineers, so every AI session starts from what your team already agreed.
Talk to RepogenicOpen source under MIT at github.com/kendallmark3/team-brain. Verified with automated tests, CI and a clean install. Not yet measured on a live team; adoption results will be published when there are some.