chidi-optimal-brain

Optimal Brain for Agentic Engineering & Research

flowchart LR
  subgraph External[External Research Layer]
    D["davidondrej research-and-web\n(browser, YT, APIs, web)"]
  end
  subgraph Memory[Personal Memory / Vault]
    V["Obsidian Vault\n(PDFs, notes, sources)"]
    LRV["Vault Learning Records\n(wikilinked)"]
    KV["docs/agents/knowledge-vault.md"]
  end
  subgraph Synthesis["Synthesis & Capture"]
    RV["research-from-vault (model)"]
    T["/teach (user)"]
  end
  subgraph Execution["Engineering Execution + Loops"]
    AL["agent-loop + /until-done"]
    ENG["grill-with-docs, domain-modeling,\ntdd, implement, ..."]
    ASK["/ask-matt (router)"]
  end
  D -->|"pull fresh\nmaterial"| V
  V --> RV
  RV --> LRV
  T --> LRV
  AL -->|"knowledge gap"| RV
  ENG -->|"ground terms/decisions"| RV
  ASK --> T
  ASK --> RV
  ASK -->|"install + use davidondrej\nthen synthesize"| D

Layered architecture of the optimal brain (see docs/OPTIMAL-BRAIN.md for details).

This is a composite "optimal brain" for agentic engineering and research. It layers the strong engineering fundamentals from mattpocock/skills with disciplined autonomous iteration via loop engineering and durable personal memory via a knowledge vault. External research capabilities (from davidondrej/skills) feed the vault, and synthesis tools turn fresh and stored knowledge into lasting learning records. See docs/OPTIMAL-BRAIN.md for the full architecture and comparison.

These skills are designed to be small, easy to adapt, and composable. They work with any model. They're based on decades of engineering experience. Hack around with them. Make them your own. Enjoy.

Quickstart (30-second setup)

1. Install the core collection:

   npx skills@latest add chidi/optimal-brain
   

   For external research reach (browser, web, YouTube, APIs — feeds the vault):

   npx skills@latest add davidondrej/skills
   

2. Pick the skills you want, and which coding agents you want to install them on. Make sure you select at minimum /setup-matt-pocock-skills, /setup-agent-loops, and /setup-knowledge-vault.

3. Run the setup skills in your agent (in a repo/workspace):

   • /setup-matt-pocock-skills — configure issue tracker, triage labels, and domain doc layout.
   • /setup-agent-loops — configure verification commands, stop rules, and scope for agent loops.
   • /setup-knowledge-vault — configure your Obsidian vault location, learning record bridging, PDF handling, and vault integration.

4. (Optional but powerful for research) From davidondrej/skills, select the research-and-web category to pull fresh material that can be synthesized into the vault.

5. Restart Cursor (or start a fresh Agent chat) and use /ask-matt to discover flows. Bam — you're ready to go.

Why These Skills Exist

The skills in this collection (founded on mattpocock/skills) were built to fix common failure modes seen with Claude Code, Codex, and other coding agents.

#1: The Agent Didn't Do What I Want

"No-one knows exactly what they want"

David Thomas & Andrew Hunt, The Pragmatic Programmer

The Problem. The most common failure mode in software development is misalignment. You think the dev knows what you want. Then you see what they've built - and you realize it didn't understand you at all.

This is just the same in the AI age. There is a communication gap between you and the agent. The fix for this is a grilling session - getting the agent to ask you detailed questions about what you're building.

The Fix is to use:

• /grill-me - for non-code uses
• /grill-with-docs - same as /grill-me, but adds more goodies (see below)

The grilling skills are among the most popular in the collection. They help you align with the agent before you get started, and think deeply about the change you're making. Use them every time you want to make a change.

#2: The Agent Is Way Too Verbose

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.

Eric Evans, Domain-Driven-Design

The Problem: At the start of a project, devs and the people they're building the software for (the domain experts) are usually speaking different languages.

The same tension appears with agents: they are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do.

The Fix for this is a shared language. It's a document that helps agents decode the jargon used in the project.