second-brain-kit

A starter kit for an agent-ready Obsidian vault: a "second brain" that you and your AI agents (Claude Code, T3 Code, Codex, Gemini CLI) read and write under the same rules.

It is more than a place to store notes. The vault carries its own instructions for agents, a schema that a validator checks, and a /project skill that lets an agent open any part of your life or work by a short, forgiving name and load exactly the context it needs.

Manual: coming soon at html.me.uk/t/second-brain.

What's inside

Path	What it does
BOOTSTRAP.md	The setup prompt you paste into your agent after cloning.
_AgentContract.md	Always-on rules for every agent: your language, secrets as references, commit and push at the end of a session, and more.
AGENTS.md + CLAUDE.md / GEMINI.md	Vault conventions for agents, plus one-line shims so each harness finds them.
_Conventions.md, _Index.md	How the vault is organized, and its bird-view map.
_Schema/	Frontmatter schema, tag taxonomy, and validators (frontmatter, tags, wikilinks, transliterated terms).
.agents/skills/project/	The /project skill: a stdlib-only Python resolver with tests, plus knowledge, code, and hybrid workflows.
.claude/skills/project/	Thin Claude Code adapter that points at the canonical skill.
Example/	One sample domain in PARA layout (Projects, Areas, Resources, Archive).

Quick start

1. Click Use this template → Create a new repository. Make it Private: it will hold your personal notes.

2. Clone it where you keep documents:

   gh repo clone <your-user>/<your-vault> ~/Documents/<your-vault>

3. In Obsidian: Open folder as vault → pick the cloned folder.

4. Open the same folder in your agent: run claude inside it, or add it as a project in T3 Code.

5. Paste the whole of BOOTSTRAP.md as your first message.

The agent then interviews you (name, language, the areas of your life and work, the tools you use), fills in the placeholders, creates your domains, optionally imports a folder of seed notes, runs the validators, explains each step as it goes, and pushes the first commit.

Requirements

• git, and uv for the validators. uv downloads a suitable Python on demand; no Homebrew needed:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• An agent harness: Claude Code, T3 Code, Codex, or Gemini CLI.

• Optional: the GitHub CLI (gh) to create the private repository from the terminal.

Daily use

/project Health                          # load a domain
/project garden-app fix the export bug   # load a project and do a task

• Start work with /project <selector>. The resolver accepts omitted folders, dates, and typos, and asks when a name is genuinely ambiguous.

• Durable knowledge goes into notes, not into an agent's private memory.

• At the end of a session the agent runs the validators, commits, and pushes. To run the validators yourself:

  sh _Schema/vault-lint.sh

Layout after bootstrap

<your-vault>/
├── _Index.md  _Conventions.md  _AgentContract.md
├── AGENTS.md  CLAUDE.md  GEMINI.md  BOOTSTRAP.md
├── _Schema/                 # contracts + validators
├── .agents/skills/project/  # /project skill
├── _Assets/Attachments/
├── Health/                  # your domains, e.g.
│   ├── _index.md
│   ├── Projects/  Areas/  Resources/  Archive/
└── Work/
    └── ...

Development

python3 .agents/skills/project/tests/test_resolve_project.py
sh _Schema/vault-lint.sh