Brain Kit is a recipe: a single instruction file, recipe.md, that you hand to any AI coding agent. The agent builds a project brain in your repo - a small tree of plain markdown files where agents keep everything they need to run your project well: what it is, how to work on it, what the current plan is and what has already been done. From then on, agents use the brain and keep it tidy on their own.
AI agents: asked to adopt this workflow, or to update an existing brain? Follow
recipe.md- it is the complete instruction set.
The brain is what a fresh session reads to pick up exactly where the previous one stopped. And it bakes in good habits:
- start small while planning for growth;
- grow automated testing with the product, instead of burying a day-old project under industry-grade test suites;
- split work so several agents build in parallel without stepping on each other's toes;
- measure progress in milestones, not dates;
- build on proven dev tools instead of inventing their own;
- clean up after themselves, and report to you briefly, in plain human language.
architecture/
├── 00-index.md # tiny table of contents, used for routing
├── owner/ # you ↔ AI: your todo list, step-by-step guides written for you
├── docs/ # the product in plain language: every flow, policy and mechanic
├── guides/ # (for agents) how to work here: conventions, rules, methods
│ └── skills/ # (for agents) expert know-how, grouped by domain
├── plans/ # dated plans: milestones, task ledgers, compact session memory
└── sources/ # research and reference material
AGENTS.md # the front door that points agents into the brain
CLAUDE.md # compatibility pointer to AGENTS.md
Recommended: first write a short .md file (any name, e.g. idea.md) saying what you want to build - or, for an existing project, what it is and does. It gives the agent context and helps it pick the right skills.
Paste into your AI coding agent, at the project root:
Read @idea.md for context, then adapt this AI workflow: https://github.com/reves/brain-kit/
The agent studies an existing project first, then asks you one batch of questions - answer once and it builds the rest. Existing docs are safety-copied to ./backup/ during adoption, and version history keeps everything else - nothing is ever lost. A new project gets a few starter questions instead.
The recipe is versioned, and your brain records the version it follows in AGENTS.md. To bring it up to date, paste at the project root:
Update the project brain to the latest recipe version: https://github.com/reves/brain-kit/
If the brain is already current, the agent says so and stops. If it is behind, the agent audits it against the new recipe and applies the whole migration in one batch, with your approval.