Detailed content
🧪 The Context Test
There is a simple, brutal test to see whether your Context works: open a completely fresh Claude session and ask "what does this business do, and who works here?". If Claude answers without navigating any external files, you have Context. If it doesn’t answer, you don’t — regardless of how many docs exist elsewhere.
Open a fresh session
No history. No files opened manually. Claude Code automatically reads only what’s in the project via CLAUDE.md and context/.
Ask without hints
Exact test phrase:
Evaluate the response
An answer with real names, services, and roles = Functional context. A vague answer ("it’s a technology company...") = Insufficient or missing context.
💡 Why a “fresh session” matters
In an existing session, Claude already has context accumulated in the window. The test only counts in a new session because it replicates the real state of an automation, an agent, or a new collaborator entering your AIOS for the first time. It’s the honest litmus test.
📁 The Folder context/
The folder context/ is the heart of your AIOS. It contains the three files that define who you are, what you sell, and where you're focused. It isn't a document dump — they're interpreted facts, written in the voice of someone who knows the business.
✓ Interpreted facts
- ✓"We sell product consulting to B2B SaaS scale-ups"
- ✓"My top_pain is a long sales cycle (45-day average)"
- ✓"Q3 2026: close 3 new enterprise clients"
- ✓Written as a brief for someone who doesn’t know you
✗ Document dump
- ✗Paste the complete pitch deck (50 slides)
- ✗Client contracts or NDAs as “context”
- ✗Complete sales email history
- ✗Notes/misc/inbox as “context files”
⚡ Golden rule
If you can’t write the file about-business.md in less than 30 minutes, the problem isn't a lack of information — it's a lack of clarity about your own business. The writing process is the diagnosis.
📋 CLAUDE.md — Operating Manual
O CLAUDE.md lives in the project root and is canonical — it's the only file Claude Code reads automatically in every session. It works as an operations manual: who you are, how you think (3 Ms), where things live, and how to work with you. It's filled in by the /onboard.
📊 Why only one CLAUDE.md
- Canonicity — no version conflicts between folders
- Guaranteed workload — Claude Code reads it automatically
- Simple maintenance — one place to update
- Quarterly review — a natural, predictable cadence
🚫 What NOT to include
- Credentials or API keys
- Sensitive client content
- CLAUDE.md nested in subfolders
- Duplicated information from context/
💡 Practical tip
Run /onboard to generate the first CLAUDE.md — the skill guides you through 7 questions and puts everything together automatically. For future updates, edit it directly or run it again (idempotent). Recommended review: quarterly or when your strategic focus changes.
🎙️ references/voice.md — The Voice Rule
O references/voice.md stores real samples of your writing, pasted verbatim — never typed during a conversation. It’s the file that keeps Claude from inventing a “generic professional tone” when generating content in your name.
⚠️ The one rule that doesn’t bend
Voice samples need to be pasted verbatim from something you actually wrote — a real email, a published post, a Slack message. Never typed into the chat during a conversation with Claude.
✓ Good voice samples
- ✓Sales follow-up email sent
- ✓Post published on LinkedIn without heavy editing
- ✓Slack message for the team (informal tone)
- ✓Excerpt from a business proposal you wrote
✗ Samples that don't count
- ✗Text generated by AI and reviewed by you
- ✗Description of how you write (“I’m direct...”)
- ✗Text written during the conversation with Claude
- ✗Post extensively edited by an external writer
📌 Standard instruction in voice.md
Whenever you generate external content, include this at the end of the file:
This protects your reputation when Claude generates autonomous drafts via Cadence.
📝 decisions/log.md — Decision Log
O decisions/log.md is the append-only record of decisions and their reasons. It isn't a to-do list or a diary — it's the institutional memory of the reasoning behind every significant choice in your AIOS and your business.
🔑 The AIS-OS litmus test
"While you’re away from your desk, your AIS-OS observes a real event and produces an output faster and more accurately than you would."
The decisions/log.md is what ensures the AIOS reproduces your reasoning, not just your tasks. Without the why recorded, every new session starts from scratch.
Append-only—never delete
The log’s value grows over time. Old decisions explain why the system is configured a certain way. Deleting them means losing historical context you’ll need when something breaks.
Also generated by /level-up
The /level-up skill creates an entry in decisions/log.md every time you scope a new automation—date, decision, why, alternatives, and owner. You don’t have to write it manually each time.
⚡ When to record a decision
Every decision that isn’t obvious or that you’ll want to explain to someone (including yourself 3 months from now). Rule of thumb: if you hesitated between two options for more than 30 seconds, record it. If you changed your approach midway, record why you changed it.
📚 references/ — Interpreted Knowledge
The folder references/ stores knowledge Claude needs to work with you — frameworks you use, API guides for connected tools, SOPs for your process. It’s the operational wiki, not a pile of raw documents.
✓ What goes in references/
- ✓API guide you researched once (researched-once-saved-forever)
- ✓SOP for a recurring process others can replicate
- ✓External framework you apply (e.g., ICE scoring)
- ✓Glossary of internal terms for your business
✗ What does NOT go in references/
- ✗Dump of emails or Slack threads
- ✗Clients’ legal or contractual documents
- ✗Unprocessed personal notes (misc, inbox)
- ✗Folders within folders for no reason (folder-within-folder-within-folder)
🔁 Principle: Researched-once, saved-forever
When connecting a new tool, spend 30 minutes creating references/{tool}-api.md with endpoints, auth, and 3 sample queries. /audit rewards this; future skills won't research what you've already discovered again.
references/notion-api.md
references/hubspot-api.md
🧭 Context is non-skippable — by design
In the dependency graph of the 4 Cs: Context comes first, always. Connections + Capabilities can be developed in parallel, but Cadence (recurring automations) only makes sense once Context is solid.
If Context is empty, AIOS is flying blind. A Cadence automation without Context produces generic outputs—sometimes worse than nothing.
✅ Module Summary
Next Module: 2.2 — Connections
With Context in place, AIOS knows who you are. Now it’s time to teach it what you have and where it is — connecting the tools that are part of your day.