Version: 1.0.0-draft Status: Draft Authors: Hrithik Gavankar
This document defines BRAIN.md — a structured Markdown file format for documenting an individual engineer’s professional identity, expertise, work patterns, and growth trajectory. It is designed to be consumed by AI coding assistants, enabling personalized, context-aware interactions across any tool that supports it.
BRAIN.md is to engineers what README.md is to projects.
The software ecosystem has converged on standard files that describe projects:
| File | Documents | Consumed By |
|---|---|---|
README.md |
What a project does | Humans, GitHub, package registries |
package.json |
Node.js application metadata | npm, bundlers, CI systems |
pyproject.toml |
Python project configuration | pip, build tools, IDEs |
Cargo.toml |
Rust crate metadata | cargo, crates.io |
Dockerfile |
Runtime environment | Docker, Kubernetes, CI |
Each of these files answers the question: “What is this project, and how should tools interact with it?”
There is no equivalent standard that answers: “Who is this engineer, and how should AI tools interact with them?”
Today, every AI coding assistant starts from zero. Engineers re-explain their expertise, their workspace layout, their team conventions, and their goals — session after session, tool after tool.
BRAIN.md fills this gap.
| File | Documents | Consumed By |
|---|---|---|
BRAIN.md |
The engineer | AI coding assistants |
BRAIN.md SHOULD be located in one of:
.cursor/skills/engineer-brain/BRAIN.md).engineer-brain/BRAIN.md)BRAIN.md is a valid Markdown file using ATX headings (#, ##, ###) to define sections. Tables use GitHub Flavored Markdown pipe syntax.
# [Full Name] — Engineering Profile
> Last updated: [ISO 8601 date]
> Auto-generated baseline. Updates itself via `engineer-brain update`.
The header MUST include the engineer’s name and a last-updated timestamp.
## Identity
- **Name:** [Full name]
- **Role:** [Role title, team, company]
- **Total experience:** [Years]
- **Workspace:** [Path to primary workspace]
- **Primary tools:** [IDE, CLI tools, frameworks]
- **Career goal:** [Next career milestone]
Purpose: Establishes who the engineer is. AI assistants use this to calibrate response complexity, domain assumptions, and career-aware suggestions.
## Career History
### [Company] — [Role]
**[Start] – [End or Present]**
[1-2 sentence summary]
- Primary codebase: [repo or package]
- Key technologies: [stack]
- Key achievements: [measurable impacts]
Purpose: Provides longitudinal context. AI can reference past experience when suggesting approaches the engineer has proven skills in but hasn’t applied in their current role.
## Full Skills Inventory
### [Category]
| Skill | Proficiency | Where Proven | Last Used |
|-------|------------|--------------|-----------|
| [skill] | Strong/Growing/Exposure | [context] | [date] |
Categories SHOULD include: Backend, Frontend, Infrastructure & DevOps, and optionally domain-specific categories.
Proficiency levels:
Purpose: Enables AI to match suggestions to the engineer’s actual skill level rather than assuming expertise or ignorance.
## Active Repositories
| Repo | Role | Contribution Level | Last Active | Focus Area |
|------|------|--------------------|-------------|------------|
| [name] | [role] | Heavy/Moderate/Light | [date] | [area] |
Purpose: Tells the AI which codebases are relevant to current work, preventing suggestions that reference inactive or irrelevant repos.
## Expertise Map
### Strong (proven at current and past roles)
- [Area]: [evidence]
### Growing (actively building)
- [Area]: [current activity]
### Proven but dormant (reactivation targets)
- [Area]: [where proven, when last used]
Purpose: Higher-level view than the skills table. Identifies areas where the engineer can be pushed toward growth or reminded of underused capabilities.
## Work Patterns
### Commit Type Distribution
fix: X%
feat: X%
refactor: X%
test: X%
chore: X%
### Velocity Trend
[Month]: X commits
### Work Schedule
- Peak hours: [time range]
- Active days: [days]
### Implementation Style
1. [Pattern description]
2. [Pattern description]
Purpose: Enables AI to detect anomalies (velocity drops, fix-heavy periods) and tailor workflow suggestions to the engineer’s natural rhythm.
## Current Sprint Context
### Active Branches
| Repo | Branch | Status |
|------|--------|--------|
| [repo] | [branch] | In progress / Merged / Stale |
### Recent Achievements
1. [Achievement with reference]
Purpose: Immediate context for daily interactions. AI can reference in-progress work without the engineer needing to re-state it.
## Growth Areas & Feedback Loop
### Strengths to Leverage
- [Strength with evidence]
### Growth Roadmap
#### [Category]
- [ ] [Goal]
- [x] [Completed goal]
### Learning Log
| Date | What Learned | Source |
|------|-------------|--------|
| [date] | [topic] | [source] |
Purpose: Enables coaching-aware AI behavior. The AI can nudge the engineer toward growth goals rather than only optimizing for immediate task completion.
Pre-structured template for performance review generation.
Team-specific standup format and preferences.
AI assistants SHOULD load BRAIN.md at the start of every session or conversation. The file SHOULD be included in the system context (rules, instructions, or equivalent mechanism).
AI assistants SHOULD use BRAIN.md to:
AI assistants SHOULD offer to update BRAIN.md when:
Updates SHOULD be generated from git history and session data, not fabricated.
The AI coding assistant market is fragmenting. Engineers use multiple tools — often switching between them within a single day. Context should not be locked inside any single vendor’s format.
BRAIN.md proposes a universal, vendor-neutral format that:
BRAIN.md is designed to be forward-compatible:
x-) are allowed for experimental features