// a genius-builder brain for your AI
Your AI writes code.
MasterMind helps it write good code.
MasterMind is a genius-builder brain for your AI — a small set of markdown files that give your coding tools sharp defaults, real judgment, and the discipline to check their own work. It works with Claude Code, Codex, Cursor, and more. Just text — no app to run.
$ tree ~/.mastermind
core/ mindset · principles · rigor · agent-loop
fields/ frontend, backend, … (swappable)
skills/ build · debug · tdd · learn · spec · …
agents/ architect · code-reviewer · refactorer
$ claude # every project, sharper by default
▸ reduce complexity · verify before done · learn the stack// 01 · the problem
By default, AI writes average code.
The models are powerful, but the results are average. They reach for the most common answer — and they forget your rules every time a new chat starts.
01
Looks right, but isn't
Confident code that quietly breaks on the cases no one mentioned.
02
You keep repeating yourself
You paste the same rules and preferences into every new chat.
03
Average by default
It picks the safe, common pattern instead of the best one for your problem.
// 02 · the difference
Same prompt. Better output.
The gap isn't syntax — it's judgment. Plain AI wires up the first thing that runs. MasterMind models the data right, so whole classes of bugs simply can't exist.
function useUser(id) {
const [user, setUser] = useState(null)
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
useEffect(() => {
setLoading(true)
fetch('/api/users/' + id)
.then((r) => r.json()).then(setUser)
.catch(setError).finally(() => setLoading(false))
}, [id])
return { user, loading, error }
}- 3 booleans → illegal states (loading && error)
- server data in useState — no cache or dedupe
- effect-driven fetch → waterfalls & races
// server state ≠ client state — model it once, source it right
function useUser(id: string) {
return useQuery({
queryKey: ['user', id],
queryFn: () => api.getUser(id), // typed, validated at the edge
})
}
// → data + status: 'pending' | 'error' | 'success'
// cached · deduped · retried — illegal states can't exist- server state in its place — cached, deduped, retried
- status is one union — impossible states can't exist
- typed & validated at the boundary; one source of truth
// 03 · what it is
It adds judgment, not more facts.
Your AI already knows the syntax. MasterMind adds what it's missing: good defaults, a clear way to make decisions, the habit of checking its work, and taste. Then it picks the right approach for your task.
- → teaches judgment, not facts
- → small on purpose — only what matters
- → adapts to whatever you're building
- → works with any tool, any model
# The best code is the code you never wrote.
Good taste makes the special case disappear.
Get the data model right and the code shrinks.
# Never on the chopping block:
correctness · security · a11y
# Judgment over inventory —
choose & compose, don't hoard.
// 04 · why use it
Four ways it makes your AI better.
Makes better choices
Picks the right tool and pattern for the job — not just the most common one. It reuses proven solutions, but never copies them blindly.
Checks its own work
It tests before it says "done," and never trades correctness, security, or accessibility for speed.
Fits your stack
It finds your tools and versions, reads the current docs when it needs to, and follows today's best practices — not old memory.
Gets better over time
It learns from real work and trusted sources, and saves the useful lessons for next time.
// 05 · how it works
A small core. The rest loads when needed.
Almost nothing loads up front. The always-on part stays small; the rest loads only when your task needs it — so your AI adapts to your stack, checks its own work, and stays light on tokens.
// 06 · the library
Skills & agents — grows with you.
Add a skill for any task you repeat — each one does a single job well. Bigger expert roles, like design or code review, run as separate agents.
skills/
- /builddesign → implement → verify → review → learn, end to end
- /tddred → green → refactor; test-first design pressure
- /verifyconfirm it works by exercising it — QA without a test suite
- /debugstructured six-phase debugging — evidence over guessing
- /prototypefast throwaway spike to answer one risky unknown
- /promptsharpen a vague ask into a clear, token-efficient, AI-ready prompt
- /learnjust-in-time stack/field learning before building
- /specturn a fuzzy request into a crisp, buildable spec
- /domain-modelcanonical glossary — one name per concept
- /grillinterrogate your understanding against the real docs
- /handoffa handoff that survives a context reset
- /levelupcapture lessons · refresh standards · bootstrap a field
agents/
- architectblueprint before code — boundaries, data model, state
- code-revieweradversarial diff review against the rigor gate
- refactorerbehavior-preserving redesign toward deeper modules
- tech-scoutbuild-vs-buy decisions, reuse-with-judgment
// 07 · works everywhere
One brain. Every editor.
It's just markdown, so any tool can read it. Built in for Claude Code, and it works as steps in Codex, Cursor, Copilot, or any tool that reads an AGENTS.md file.
// 08 · get started
Install once. Sharp in every project.
Clone the repo and run the installer. It sets up the brain in ~/.mastermind and connects your tools. To update later, just run git pull.
$ git clone https://github.com/mehrad-dm/mastermind ~/mastermind
$ cd ~/mastermind && ./install.shOr add just the skills & agents as a Claude Code plugin:
/plugin marketplace add mehrad-dm/mastermind
/plugin install mastermind@mastermindRun the installer above too — the skills & agents read the brain from ~/.mastermind.