I Turned Obsidian Into an Operating System for My AI Agents

I'm a solo developer. Like everyone else, I started using Claude Code as a very smart autocomplete. A few weeks in, I realized the bottleneck wasn't the model — it was that every session started from zero. It didn't know who I am, what I'm building, how I like to work, or what we decided yesterday.

So I gave it a memory: my Obsidian vault. Now I type one word — cortex — in any Claude Code session, and the whole system boots: my profile, my projects, my workflow rules, my kanban boards, and a five-agent team that takes a feature from "let's talk about it" to a reviewed pull request. The only thing AI never does is publish. That's mine.

This post is the full setup: the folder structure, the config files, the agent team, and the rules that keep it from running away with itself.

The idea: one word boots everything

The core insight is boring but important: Claude Code reads a CLAUDE.md from the directory it runs in. Put one at the root of your Obsidian vault and every session inside the vault knows your rules.

But I don't work inside my vault — I work inside my app repos. A vault CLAUDE.md is invisible from there. The trick that makes the whole thing portable is a user-level skill (~/.claude/skills/cortex/SKILL.md). Skills are loaded in every session, from any directory. Mine is a tiny router: when I type cortex, it reads the vault's CLAUDE.md, then my core notes, then follows whatever I asked for.

So: the vault is the brain, the skill is the boot loader.

The vault structure

vault/
├── CLAUDE.md              ← the routing brain (instructions for Claude)
├── Cortex/                ← the "master mind"
│   ├── Master Mind Index.md
│   ├── Who I Am.md        ← profile, stack, hard rules
│   ├── Skills.md          ← which Claude Code skills I use, and when
│   ├── AI Dev Pipeline.md ← how work flows through the agent team
│   ├── Pipeline Retros.md ← the pipeline's memory (more on this below)
│   └── Ideas.md           ← idea inbox
├── Projects/
│   └── <app>/             ← one folder per app, same layout every time:
│       ├── <App> Info.md  ←   repo path + facts agents need
│       ├── <App> Plan.md  ←   kanban board (obsidian-kanban plugin)
│       ├── stories/       ←   Story + Design notes
│       ├── changelog/     ←   Changelog.md + archived feature docs
│       └── ideas/         ←   app-specific ideas
├── Ideas/                 ← big general ideas

Two rules make this survivable:

1. Rule zero: files move. I reorganize my vault whenever I feel like it. So agents are forbidden from trusting memorized paths — they locate notes by title search (find by name), every time. My agents survived three reorganizations in one week without breaking.
2. Wikilinks by title only. Obsidian resolves [[Story - Dark Mode Toggle]] no matter which folder it's in. Links survive the reorganizations too.

The routing brain: vault-root CLAUDE.md

The vault CLAUDE.md holds the rules of engagement. A trimmed skeleton you can adapt:

# Master Mind — instructions for Claude

Boot sequence (also triggered by the `cortex` alias):
1. Read Who I Am   2. Read Skills   3. Read AI Dev Pipeline

## Rule zero: files move
Never trust a memorized path — locate notes by title search.

## Routing rules

### Feature request
0. KICKOFF DISCUSSION first — challenge my choice, offer alternatives,
   ask scope questions, settle the risk tier WITH me.
   No stories, no code, before my explicit approval.
1. Tier by risk (Low / Elevated / Full — see table)
2. Run the tiered pipeline
3. Changelog entry + retro, card to Done, notify me.
I publish. AI never pushes/merges/releases without my explicit OK.

### "It's an idea"
Talk it through with me first → file it with the discussion captured
→ ask before promoting it to stories.

### Working on an existing project
Board columns have meanings:
- InProgress → continue it
- TODO      → approved and groomed; take the top card
- BackLog   → MY PARKING LOT. Never start these on your own. Ask.

That BackLog rule exists because of a real incident: early on, I typed the project alias and the system happily groomed my someday-maybe pile into user stories. I stopped it and we wrote the rule. The parking lot is sacred now.

The boot alias

The skill file is short. The interesting part is the modes:

---
name: cortex
description: Boot alias. Trigger on "cortex", "cortex idea <...>",
  or "cortex <project name>".
---
1. Read the vault CLAUDE.md and the three core notes (by title search).
2. Route:
   - `cortex`            → boot + status (what's InProgress, top of TODO)
   - `cortex idea ...`   → discuss the idea with me, then file it
   - `cortex <project>`  → open that project's board and resume work

cortex <project> reads the board, finds the top approved card, and runs the pipeline. cortex idea a backoffice for user stats starts a discussion — not code.

The agent team

Five agents live in ~/.claude/agents/, each a markdown file with frontmatter. Different models for different jobs:

A trimmed agent file, to show the shape:

---
name: developer
description: Use when a story or kanban card needs implementing.
model: opus
---
1. Load the story + acceptance criteria (note file or card).
2. Read the repo's AGENTS.md — conventions are law.
3. TDD: failing test → implementation → green.
4. All gates must pass: typecheck · lint · format · tests · build.
5. Commit locally. NEVER push, never open the PR, without an
   explicit OK in the current session.

Every agent file repeats the hard rules — never push, never merge, never write my .env, no AI attribution in commits — because subagents boot from their own definition, not from the conversation.

Ceremony proportional to risk

My first full pipeline run was great — and heavy. Six agent invocations and five vault notes for one small story, with the review loop costing about five times what the developer did. So the pipeline tiers by risk, not size (a one-line auth change is riskier than a five-file UI refactor):

The tier is settled with me during the kickoff discussion. Agents can escalate mid-run ("this wants architecture, stop and re-tier") and de-escalate ("a design already exists, skip the designer"). After tiering, run costs dropped to roughly a third for mid-size stories and a fifth for small fixes — with review quality intact, as far as I can measure it.

The system improves itself (with me as the gate)

After every run, the session appends an entry to Pipeline Retros.md: what broke, what wasted effort, and — this matters — a verdict on the previous change (did it actually help?). A process change is only proposed when a pattern shows up in two or more retros, or one severe failure demands it. I approve every mutation of the flow. Capture is automatic; evolution is human-gated.

This is the part I'd defend hardest. "Self-improving" without an evidence threshold just churns; without a human gate it drifts somewhere you didn't choose.

What I'd tell you to build first

1. Vault CLAUDE.md with your boot sequence and the discussion-gate rule. This alone changes the texture of working with Claude — it argues with you before building.
2. The alias skill in ~/.claude/skills/, so any session anywhere can boot the vault.
3. One project folder with the Info note (repo path!), a kanban board (obsidian-kanban plugin: columns as ## BackLog / TODO / InProgress / Done, cards as - [ ] items), and the three subfolders.
4. Two agents — developer and code-reviewer. PM, designer, and QA can come later; the developer/reviewer pair is where the leverage is.
5. The retro note from day one. The system gets better because the lessons have somewhere to live.

And keep the one rule I'd never trade away: the AI proposes, loops, verifies, and stops. Publishing is yours.