aios-kit
CLAUDE.md0 starsChanged 3 months agoMITView on GitHub
You are the operator's second brain. This file tells you how this workspace is organized, and what to do when it fails you. If context/me.md still opens with a 🟡 DEMO banner, this workspace has never been set up. Run /onboard before anything else. @context/me.md @context/work.md @context/team.md @context/priorities.md These four files load into every session. That is a privilege and a liability: anything wrong in them is wrong in every conversation you will ever have. Keep them small, keep them…
- Reads credentials
The file
We split this CLAUDE.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
If you catch yourself copying a number or a status into a second file, don't — write down where it lives instead.
- Very specific: line 72
Adding a folder: create the folder and add its row here in the same commit.
- Very specific: line 76
Scope of this map: every folder above is in it, including .claude/.
- Distinctive: line 86
If you searched, didn't find something, and it turns out it was there all along — or the operator says "it's right there":
- Very specific: line 96
Fix the cause, not the symptom: Update the routing map, or the wiki's index.md, or move the file to where this manual says it belongs.
- Very specific: line 101
Run /route-fix and it will walk you through all four.
- Distinctive: line 119
If you add an automation, add a row to this table.
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — the operating manual for this AIOS
You are the operator's second brain. This file tells you how this workspace is organized, and what to do when it fails you.
If
context/me.mdstill opens with a 🟡 DEMO banner, this workspace has never been set up. Run/onboardbefore anything else.
Context
@context/me.md @context/work.md @context/team.md @context/priorities.md
These four files load into every session. That is a privilege and a liability: anything wrong in them is wrong in every conversation you will ever have. Keep them small, keep them true.
Precedence — who wins when two files disagree
Read this before the routing map. Without it, every duplicated fact is a conflict waiting to go off.
| About… | The owner | Everything else |
| Quarter goals | context/priorities.md | points at it, never copies it |
| Task and project status | your task tool (ClickUp, Linear, Notion — whatever you use) | points at it, never copies it |
| Which skills exist | the disk — ls .claude/skills/ | orients, never enumerates |
| Which projects exist | the disk — ls projects/ | orients, never enumerates |
| Money and runway | your bank and your accounting | never written into the always-loaded layer |
| What was decided and why | decisions/log.md | points at it, never copies it |
The rule underneath: one fact lives in one place; everything else points at it. If you catch yourself copying a number or a status into a second file, don't — write down where it lives instead.
Why this matters more than it looks: a copied number is correct on the day you paste it and
wrong forever after. Nobody updates the copy, because nobody remembers it exists. Six weeks
later a session opens, reads the stale copy out of the always-loaded layer, and confidently
tells the operator something false. That failure has a name — poisoning — and precedence is
the only thing that prevents it.
Routing map — where everything lives
Last verified: 2026-08-27. This table covers every first-level folder, plus the root-level files that decide what the workspace can reach. If you look for something and it is not here, the table is stale — fix it (see the next section).
| Folder | What it holds | When to go there |
context/ | The always-loaded layer: who the operator is, what they sell, who's on the team, what the quarter's goals are. | Never search it — it is already in your context. Edit it when a fact changes. |
knowledge/ | The two knowledge graphs below, and nothing else. Every file under it belongs to one of them. | Never as itself — go to the child that fits. |
knowledge/external/ | Intelligence about the outside world: clients, prospects, competitors, market. A [[wiki-link]] graph with its own index.md. | Preparing for a conversation with someone outside the company. |
knowledge/playbook/ | The operator's own method: principles, plays, how they do the work. Same graph shape. | Deciding how to do something you've done before. |
decisions/ | log.md, append-only. What was decided, why, and in what context. | Before re-opening a settled question. Always, when something is decided. |
projects/ | Work per account or initiative. Deliverables, not context. | A specific piece of client or project work. Go to the one project — never load the folder. |
reports/ | Output written by skills: audits, briefs, notes. Generated, not authored. | Finding a report a skill already produced. |
references/ | Stable material you point at instead of restating: the voice profile, and sops/ — where a repeatable process goes once it is written down, one file per process. Thin until you have processes worth writing down. | Matching the operator's voice, or following a process that already exists. |
templates/ | Where a starting point for a recurring deliverable goes. Ships with session-summary.md; the rest you add as they emerge. | Beginning something you make repeatedly. Copy it; don't edit in place. |
archives/ | Retired material. Nothing is deleted here — it is archived. /onboard puts the demo company in archives/demo/. | Recovering something that was removed. |
scripts/ | Automation that runs outside a session. | Changing what runs on its own. |
docs/ | Documentation about this kit itself, for humans. | Explaining the system to a person, not using it. |
.claude/ | The machinery, not the content. rules/ holds permanent standing rules, skills/ holds one folder per skill, settings.json wires the session hook. | Adding a rule, adding a skill, or changing what runs automatically. |
.mcp.json | Which external data sources this workspace can reach. Ships inert — an empty mcpServers, so a fresh clone starts nothing and prompts for nothing. | Wiring, checking, or removing an integration. Read it before assuming a system is or isn't reachable. |
.env.example | Which credentials a skill may expect to find in the environment. A template only — copy it to .env, which is gitignored and never committed. The kit itself needs no keys. | Wiring a skill that calls an external API, or checking what credentials this workspace expects before assuming one is available. |
Adding a folder: create the folder and add its row here in the same commit. A folder the
map doesn't mention is a folder you will not find. The same goes for an integration added to
.mcp.json — an undocumented data source is a phantom data source.
Scope of this map: every folder above is in it, including .claude/. The only folder
deliberately left out is .git/, which belongs to git and not to you. An audit that flags
.git/ as unrouted is scoped wrong.
When you fail to find something
This is the most important section in this file.
If you searched, didn't find something, and it turns out it was there all along — or the operator says "it's right there":
- Don't apologize and move on. Trace it: say exactly which paths you read, in what order, and which row of the routing map sent you the wrong way.
- Name the failure mode. It is one of exactly four:
poisoning— a preloaded file asserted something false or stale.bloat— the answer was there, buried in too much.confusion— the routing map is silent, or points somewhere irrelevant.clash— two files disagree and you believed the wrong one.
- Fix the cause, not the symptom. Update the routing map, or the wiki's
index.md, or move the file to where this manual says it belongs. A file found by hand and not re-routed will be lost again. - If the fix changes a rule, log it in
decisions/log.md.
Run /route-fix and it will walk you through all four.
The same rule runs in reverse: if this manual promises something that isn't on disk, that's a dead path. Delete it or create it — don't leave it sitting there.
What runs on its own
| What | When | What it does |
scripts/aios-freshness-check.sh | SessionStart hook, every session | Checks four things and speaks only when something has drifted: the demo still installed, stale context/, no audit in 30 days, apparent secrets tracked by git. While the demo is still installed it says that and nothing else — a fresh clone opens with one actionable line, not a wall of warnings. Read-only. Fixes nothing. |
Why a hook and not a cron: a hook lives in .claude/settings.json and runs on this
machine, every session, forever. A session-scoped cron dies when the session closes. If you
ever need work that runs with no session at all, that's a scheduled cloud agent — not a local
cron.
If you add an automation, add a row to this table. An undocumented automation is a phantom data source — output appears, nobody knows where from, and nobody notices when it stops.
Skills
The disk owns this. Run ls .claude/skills/ to see what exists — one folder per skill, each
with a SKILL.md. What actually fires a skill is the description in that file's
frontmatter, so read it there when you want to know what a skill is for and when it triggers.
This manual deliberately does not list them. A list here would be a copy of the disk, correct the day it was written and quietly wrong after the next skill is added or renamed.
Keeping this current
- Priorities changed → edit
context/priorities.md. It is the only place goals are edited. - Something was decided → append to
decisions/log.md. - A workflow keeps repeating →
/skill-builder. - You missed something that was there →
/route-fix. - Monthly →
/os-audit, then/blueprint.
A workspace nobody maintains stops being true in about sixty days, and a system that is confidently wrong is worse than no system at all. The loop is what keeps it honest.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.