Architecture

Architecture

Four layers. Each one is useless without the one below it, and that is the whole design: a rule that no command executes is a wish, and a command with nowhere to write is a session that ends when the terminal closes.

  you type  /ask "what did I decide about X?"
                │
   ┌────────────▼────────────┐
   │ 1. RULES                │  CLAUDE-EXTERNAL.md → your ~/.claude/CLAUDE.md
   │    always loaded        │  how the assistant behaves before any command runs
   └────────────┬────────────┘
   ┌────────────▼────────────┐
   │ 2. SKILLS   101 files   │  ~/.claude/skills/<name>/SKILL.md
   │    one /command each    │  prose: when to fire, what to do, what to report
   └────────────┬────────────┘
   ┌────────────▼────────────┐
   │ 3. ENGINES  246 files   │  deterministic Python: search, import, score, render
   │    the cheap half       │  no model tokens spent on counting and filtering
   └────────────┬────────────┘
   ┌────────────▼────────────┐
   │ 4. MEMORY               │  an Obsidian vault + a markdown CRM
   │    where output lands   │  notes, decisions, people, leads — plain files
   └─────────────────────────┘

Layer 1 — rules

CLAUDE-EXTERNAL.md is the behaviour set: receipts instead of "understood", a before/after preview before changing anything, a pause on money, deletion and outbound, plain-language explanations. BOOTSTRAP-CLAUDE.md tells the assistant how to fold those into the user's own ~/.claude/CLAUDE.md — which is the file that is loaded into every session and therefore the only place where a rule surfaces by itself.

The practical consequence: a rule that lives only in a skill fires only when that skill fires. If you want behaviour to be unconditional, it has to end up in the always-loaded file.

Layer 2 — skills

A skill is a directory with a SKILL.md: a description that says when to trigger, and instructions that say what to do. Prose, not code — the model reads it. The full catalogue is skills/INDEX.md, grouped by area (fleet, vault, content, leads, health, sessions).

Skills are where a repeated action gets a name. The rule the original system runs on: a routine repeated twice becomes a /command.

Layer 3 — engines

246 Python files under engines/, split into two homes that must not be merged:

Folder	Lives at	Holds
engines/scripts/ (49)	~/.claude/scripts/	plumbing — buses, approvals, guards, brokers
engines/imports/ (197)	the vault's _imports/	knowledge work — importers, retrieval, dashboards, content tools

The split is not cosmetic. Plumbing has to keep working when the vault is unavailable (moved, syncing, on another disk); knowledge work has to sit next to the data it reads. A flat pile of 246 files also leaves you guessing which is which — that guess is the bug.

Why so much determinism under a model: counting, filtering, joining, deduplicating and parsing are exact operations. Handing them to an LLM costs tokens and buys errors. The engines do the exact half; the model does judgement, synthesis and language. See engines/README.md.

Layer 4 — memory

Two stores, deliberately separate:

• The vault — an Obsidian folder of plain markdown (01-Concepts, 02-Decisions, 03-Insights, 04-Projects, 07-People, 08-Templates, _imports, _originals). Templates for the recurring note shapes are in templates/ (13 of them: concept, decision, literature note, weekly/monthly review, several writing styles).
• The CRM — crm-template/: one markdown card per person, plus four reference scripts (temperature.py scores how warm a relationship is, budget.py caps outbound, safe_send.py is the gate in front of sending, demo.py runs it on the bundled sample leads). schema.sql is there for when the markdown outgrows grep.

Everything is a file. That is the property that makes the whole thing repairable by someone who is not a programmer: you can open it, read it, and fix it with a text editor.

The trust boundary

Three things never cross into this box, and the rule is worth keeping when you adopt it:

1. Secrets stay outside the vault and outside anything the model always loads.
2. Money, deletion, and anything outbound to a third party stop for an explicit human yes.
3. Personal data is substituted, not stripped, before publication — a fake of the same shape keeps code readable, <REDACTED> teaches nothing.

What is deliberately absent

No multi-machine bus, no consensus engine, no fleet skills, no third-party connectors. On day one you do not need them, and each one is a way to lose data before you have any. When you outgrow one machine, that half is a separate repository: claude-consensus.