🧱 Technique I — the OS foundation
The three foundation layers, the “back of house” of your OS: Identity (the soul file), Substrate & Context (the dumpster fire) and Rules & Hooks (the fences). Without this static foundation, the agents have nothing to rely on.
How to read: the foundation is built from the top down in terms of understanding, but it stacks as a foundation: Identity, Substrate, and Rules form the stable ground (in blue) on which the action layers (in cyan, faded — Track 3) will rest. This track covers only the foundation.
Learning path map
Detailed content
🪪 Identity — the soul file (CLAUDE.md)
The first file the OS reads. Who it is, whom it serves, what it never refuses—concise, under 30 lines, with a practical generation example at the end.
The Identity layer lives in the CLAUDE.md — the first file the harness reads, before any task.
It's the piece that changes behavior the most for the least effort; a good file gets the tone right on the first try.
Core file · read first · Markdown · sets the tone.
You, the business, the market, current events, preferences, and what you should always/never see. RAW data does NOT go in.
Mixing identity with substrate bloats the file; knowing the limit keeps the soul concise.
Stable context · always/never · identity ≠ data.
Keep the file under ~30 lines and cut anything that doesn't change behavior every time.
An bloated identity dilutes the signal and uses up the model’s attention; keeping it short is a design decision.
< 30 lines · cut until it hurts · point > paste.
If the OS serves a team, identity includes roles, responsibilities, and limits for each function.
The same domain generates different identities depending on the audience; define “you or team” early.
Who it's for · roles · limits by role.
A cheat sheet explaining when the OS should give the benefit of the doubt on your legitimate tasks.
Models are becoming more judgmental; anticipating refusals avoids friction in every session.
Cheat sheet · benefit of the doubt · legitimate use only.
A global file with what's common to you; each OS says "always consult X" instead of repeating it.
As you grow from 1 to 5 OSes, centralizing what they share avoids the maintenance nightmare.
Global file · point, don’t copy · 1 edit point.
A stranger reads the CLAUDE.md and describes the OS’s purpose + 1 thing it refuses.
"It’s good" is vague; the stranger test is an objective criterion for being done.
Stranger test · describes purpose · cold chat.
A ready-to-use prompt that interviews you with 3 questions and writes a CLAUDE.md concise, with a refusal cheat sheet.
Reading about identity doesn’t replace writing one; the prompt becomes a real artifact in minutes.
Copy-run · interview > dump · built-in done-check.
🗑️🔥 Substrate & Context — the flaming garbage truck
From the chaos of 500–5,000 files to injectable nuggets: organize before AI, gather tacit knowledge, and distill with a workhorse model.
You start with 500–5,000 chaotic files of various types; the Substrate turns chaos into a reference.
Most people plug AI into the chaos and get frustrated; accepting the chaos and dealing with it methodically is the differentiator.
Substrate vs. context · 500–5,000 files · design.
Mini data engineering: sort by file type first, then by age (recent vs. old).
The OS's quality is limited by the Substrate's; organizing it first multiplies everything that follows.
Mini data engineering · by type · by age.
Gather what’s missing to create the specialist of your dreams — from YouTube, experts, laws, lawyers.
What you already have is rarely enough; harvesting deliberately closes the gap.
Harvesting · dream expert · external sources.
Practical knowledge, rarely written down: shortcuts, exceptions, “what goes wrong”—things a generic model doesn’t know.
It’s the tacit knowledge that makes the OS seem like an expert rather than a chatbot; it’s the non-generic test.
Tacit vs. explicit · exceptions · non-generic.
Aggregate sources in a compendium.md (distilled reference) and playbooks (how to do X).
It’s the format that makes knowledge usable; a good playbook is almost a Skill.
Compendium · playbook · goal question (done-check).
Folder raw/ (raw, kept) vs. synthesized/ (nuggets). Inject only the nuggets.
It’s the pattern that repeats in every domain; injecting raw material blows up the window and drives up costs.
raw/ · synthesized/ · pantry vs. ready-made dish.
A cheap model (e.g., Gemini Flash) running in a loop across all files to distill nuggets.
Distilling by hand doesn't scale, and using a top-of-the-line model is wasteful; the cheap+loop pair makes the volume feasible.
Workhorse · in a loop · human in the loop.
Sweeping prompt raw/ with the workhorse and writes one nugget per file in synthesized/.
It’s the operational heart of Substrato; generalized, it becomes the "knowledge harvester" skill.
raw/ intact · 1 nugget/file · compendium.md.
🚧 Rules & Hooks — the Fences
Rule = strong suggestion; hook = deterministic. Reflex hooks, settings.json with write denied, PII pre-commit, and the worst-error done check.
A strong suggestion to the model — the “do not enter” sign. Nondeterministic: it can slip.
Knowing which rules are “soft” calibrates your confidence and saves the hooks for what must not fail.
Rule · non-deterministic · good for preferences.
The locked door: always does it or never lets it happen, without depending on the model's judgment.
PII, money, and database writes can't depend on the model "remembering".
Hook · always/never · where it hurts.
Move the "always/never" lines from the CLAUDE.md bloated for a folder rules/.
The foundation grows without becoming a mess: lean identity, auditable rules.
Promote · always/never · move > duplicate.
A mechanism that triggers immediately: PII (SIN, credit card) uploaded to GitHub? Action blocked immediately.
The most costly errors are silent; the reflex turns “I hope not” into “it can’t happen.”
Reflex hook · PII · reflex > memory.
Ban Bash write commands (e.g., never write to a table), unless explicitly overridden.
It’s where "never write here" stops being text and becomes a machine rule — high return.
settings.json · permissions.deny · unless overridden.
A checker that runs before each commit and blocks the submission if it finds PII.
A backup without protection is a leak waiting to happen; pre-commit lets you version safely.
Pre-commit · blocks the commit · + .gitignore.
Name the worst mistake in the domain, write it as a clear never-rule, and reinforce it with 1 deterministic reflex.
Actionable criteria in 5 minutes: the right question, at the right dose (text + hook).
Worst mistake · never-rule · double fence.
One settings.json ready to deny write commands and add a PreToolUse hook (exit 2 blocks).
Turns fence theory into real protection in minutes—the "1 reflex" of the done-check.
permissions.deny · PreToolUse · exit 2 · override.