optimal-brain vault pack

About this skill

What's included (36 skills)

• optimal-brain-full

  Router for the full optimal-brain pack (35 agent skills for engineering, planning, review, agent loops, and an Obsidian knowledge vault). Starts new users at setup-optimal-brain, then picks the right skill and order for the task. Use when the user first installs optimal-brain, asks which skill to use, wants to plan, build, review or debug with an agent, run an agent loop until done, or keep research and repo knowledge in a vault across sessions.

• agent-loop

  Agentic loop discipline. Use when the user wants to loop until done, iterate until tests pass, keep fixing until green, run until verification passes, or mentions red-green-refactor in an iterative fix context.

• ask-brain

  Router for the optimal-brain pack: recommends the right skill or flow (research, vault, loops, architecture, review, writing) for what you're doing. Use when the user asks which skill to use, where to start, or how the pieces fit together.

• codebase-design

  Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

• decision-mapping

  Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. Use when the user has a fuzzy idea with many unknowns, asks what to figure out first, or wants a research-and-decide plan before committing.

• diagnosing-bugs

  Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

• domain-modeling

  Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

• edit-article

  Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

• git-guardrails-claude-code

  Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

• grill-me

  Interviews you question by question about a plan or design until every branch of the decision tree is resolved. Use when the user says grill me, poke holes in this, or stress-test my plan before building.

• grill-with-docs

  A relentless interview to sharpen a plan or design that also writes docs (ADRs and glossary in CONTEXT.md) as decisions land. Use when the user wants their plan stress-tested and the outcome documented, says grill me with docs, or is pinning down domain terms before building.

• grilling

  Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.

• handoff

  Compact the current conversation into a handoff document for another agent to pick up. Use when the context is getting long, the user is switching agents or sessions, or says write a handoff.

• implement

  Implements a PRD or issue set end to end: plans, writes code test-first, runs the repo's verification commands, and gates on /two-axis-review before committing. Use when the user says implement this PRD, build issue #N, or work through these issues. Do not use for one-line fixes.

• improve-codebase-architecture

  Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. Use when the user wants an architecture review, asks where the code is shallow or tangled, or wants refactoring candidates ranked.

• obsidian-vault

  Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

• project-notes

  Capture personal notes during or after research in the Obsidian vault under the project's Personal Notes folder. Use when the user wants to jot a reflection, save a thought about the research, or keep notes the agent won't overwrite. Reads and writes only this repo and the vault path you configured.

• prototype

  Build a throwaway prototype to flesh out a design: a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to try a design before committing, compare UI variants, or says prototype this.

• research-from-vault

  Research and synthesize using the personal knowledge vault as the primary source. Use when the user says "research X using my vault", "consult the knowledge vault", "look up in my PDFs and notes", "synthesize from vault sources", or when a knowledge gap appears during loops or engineering work. Reads and writes only this repo and the vault path you configured.

• resolving-merge-conflicts

  Use when you need to resolve an in-progress git merge/rebase conflict.

• seed-vault-from-repo

  Populate an existing optimal-brain Obsidian vault from the current state of a repo (code layout, READMEs, docs, ADRs, plans, CI/pipeline configs). Discovers units (monorepo workspaces or sub-projects), confirms the unit list and vault layout, then writes per-unit Findings, Decision Traces, Plans and a Unit Index one unit at a time, plus a Shared layer for cross-unit contracts. Every note cites source paths and the commit; re-sync mode updates only stale notes. Use when the user wants the vault to know an existing codebase or monorepo, after /setup-knowledge-vault, or says seed/re-sync the vault from this repo. Reads and writes only this repo and the vault path you configured.

• setup-agent-loops

  Configure this repo for agent loops (verification commands, stop rules, scope, starter recipes), or design a custom recurring workflow spec. Use when the user is about to run /until-done or autonomous iteration for the first time, wants stop rules, or wants to design a repeatable workflow.

• setup-knowledge-vault

  Configure a personal knowledge vault for research and learning (vault location, learning records, PDFs/sources, context graph, project overlay). Use when the user first sets up optimal-brain's vault layer, before research-from-vault, /teach, or other vault skills, or to change the vault path. Reads and writes only this repo and the vault path you configured.

• setup-optimal-brain

  Configure this repo for the engineering skills: issue tracker, triage label vocabulary, and domain doc layout, written to .agent/context/. Use when the user first installs optimal-brain in a repo, or before the first /to-prd, /to-issues, or /triage.

• setup-pre-commit

  Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

• system-architect

  Orchestrate solution and system architecture across competence roles (discovery, as-is review, target design, or migration) into a session hub, ADRs, and delivery handoff. Use when the user starts an architecture engagement, asks for a target design or migration plan, or wants an as-is system review.

• tdd

  Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

• teach

  Multi-session tutor that keeps a mission, resources and learning records in the workspace and, if configured, bridges them into your Obsidian vault. Use when the user wants to learn a topic over several sessions, says teach me X, or wants a study plan with progress tracking.

• to-issues

  Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when the user says split this into issues, create tickets from the PRD, or wants work broken down for parallel agents.

• to-prd

  Turn the current conversation into a PRD and publish it to the project issue tracker, with no interview, just synthesis of what you've already discussed. Use when the user says write a PRD, turn this into a spec, or file this as a PRD.

• triage

  Move issues and external PRs through a state machine of triage roles: categorise, verify, grill if needed, and write agent-ready briefs. Use when the user says triage the backlog, look at new issues, or wants incoming issues or PRs made agent-ready.

• two-axis-review

  Review a set of code changes against two separate axes, Standards (does it follow this repo's documented rules?) and Spec (does it do what the issue/PRD asked?), plus correctness, security, and test checks. Produces severity-ranked findings in conventional-comments style and a PASS/FAIL verdict usable as an agent-loop verification gate. Use when the user wants to review a branch, PR, diff, or work-in-progress, asks "review since X", "is this ready to merge", "check my changes against the issue", or when /implement, agent-loop, or /until-done needs a review gate before stopping.

• until-done

  Run a goal-based agent loop until verification passes or a stop rule fires (Cursor's equivalent of handing off the stop condition). Use when the user says keep going until it works, loop until tests pass, or hands over a goal with a clear done condition.

• vault-context-canvas

  Create or refresh an Obsidian JSON Canvas context graph in the vault from Context Index and project-context notes (not the Cursor IDE canvas). Use when the user wants to see how vault notes connect, asks for a context graph or map, or after big research sessions. Reads and writes only this repo and the vault path you configured.

• write-from-vault

  Turn vault research notes into a sourced article, one stage at a time (mine fragments, shape a pyramid, write beat by beat), with every claim traced to a note, saved back into the vault, and exported to publish-ready Markdown. Use when the user wants a blog post, article, memo, or newsletter from their research, or says write this up from my notes. Reads and writes only this repo and the vault path you configured.

• writing-great-skills

  Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. Use when the user is writing a new SKILL.md, editing a skill's description or instructions, or asks why a skill isn't triggering.