🏛️ The Architecture (4 Cs)

What it is

A fresh Claude session should be able to answer "what does this business do and who works here?" without browsing any files. If it can't answer accurately, Context isn't configured.

Why learn

Context is the starting point for every output. Without it, Claude responds generically — useful for any company, specific to yours.

Key Concepts

A fresh session: new window with no history. Identity test: name, role, main pain point. Baseline: what exists before building.

What it is

Three files: about-me.md (identity, role, top_pain), about-business.md (offer, ICP, revenue model), priorities.md (90-day priorities). Interpreted facts — not a document dump.

Why learn

These three files are loaded in every session. They define Claude’s "persona" for your specific context. Without them, every conversation starts from scratch.

Key Concepts

ICP: Ideal Customer Profile. top_pain: the operator’s most frequent pain point. Interpreted facts: what that data means for the business, not the raw data.

What it is

File in the project root, automatically loaded by Claude Code. Documents who you are, how you think (3 Ms), where things live in the project, and how to work with you. It is filled in by the /onboard.

Why learn

The CLAUDE.md is your assistant’s “permanent briefing.” It reduces context-setting work to zero in every session—Claude already knows where it is and what you expect from it.

Key Concepts

Canonical: a single source of truth. Auto-loading: Claude Code reads CLAUDE.md automatically when you open the project. /onboard: skill that fills in the file on Day 1.

What it is

Samples of your actual voice pasted verbatim into the file—never described or typed in chat. The instruction to Claude: "Match this style; don’t imitate my voice in external content without showing it to me first."

Why learn

Describing your voice in chat is contamination — Claude interprets the description; it doesn’t learn the real pattern. Verbatim samples teach by example. Content outputs become indistinguishable from your style.

Key Concepts

Verbatim: literal copy, with no edits. Contamination: the risk of Claude imitating a description, not the real voice. Few-shot: a learning technique using concrete examples.

What it is

Append-only strategic decision log. Standard format: date · Decision · Why · Alternatives considered · Owner. The "why" is the most important field — without it, the log has no value.

Why learn

Decisions without context lead to re-debating. The log lets Claude understand the earlier reasoning and avoid contradictions. It’s also an audit trail for /audit.

Key Concepts

Append-only: never edits old entries, only adds new ones. Audit trail: verifiable record of decisions. Owner: responsible for the decision.

What it is

Frameworks, SOPs, API guides, voice. The rule: only interpreted facts belong here — what that data means for the business, not the raw data. The wiki is NOT a document repository.

Why learn

Interpreted knowledge speeds up future sessions. Claude doesn’t need to infer what a piece of data means—it’s already documented. API references saved here prevent having to research them again each time.

Key Concepts

SOP: Standard Operating Procedure. Interpreted fact: data + meaning. Researched-once-saved-forever: principle of not researching what has already been discovered again.

What it is

"What’s on my calendar tomorrow, and which tasks are due?" → Claude responds with live data, no manual paste. If you needed to paste, there are no Connections.

Why learn

Live connections eliminate the manual loop of copying and pasting data into chat. AIOS becomes proactive because it can access information without intervention.

Key Concepts

Live data: read directly from the source, not copied. Paste: anti-pattern — indicates a lack of real connection. Read vs write: connection that reads vs. one that also writes.

What it is

The 7 essential domains: (1) Revenue/Finance · (2) Customer interactions · (3) Calendar · (4) Communication · (5) Projects/tasks · (6) Meeting intelligence · (7) Knowledge/files. Every business has equivalents.

Why learn

/audit scores Connections based on coverage of these domains. Knowing them helps you prioritize which connections to build first—starting with the highest-leverage domains.

Key Concepts

Tier-1: domains present in any business, regardless of industry. Coverage: how many of the 7 are connected. Leverage: impact of adding each domain.

What it is

Four mechanisms for connecting systems: mcp (MCP server) · script (Python/Bash calling the API) · export (CSV/JSON dump) · key+ref (.env key + API docs). The kit is API-first; the audit doesn't favor MCP.

Why learn

There’s no single way to connect. MCP is convenient but not required—a Python script that calls an API is just as valid. What matters is that the data is accessible.

Key Concepts

MCP: Model Context Protocol. API-first: prefer direct API calls over fragile automations. .env: environment variables file for API keys.

What it is

Table with columns: # · Domain · Tool · Mechanism · Auth · Last checked. One row per connected system. This is your AIOS Connections inventory.

Why learn

Without a record, you don’t know what’s connected. /audit reads connections.md to calculate the Connections score. A complete record ensures no domain is forgotten.

Key Concepts

Inventory: auditable list of systems. Auth: authentication method (API key, OAuth). Freshness: when it was last verified.

What it is

When connecting an API, save references/{tool}-api.md with endpoints, auth, and the main queries. /audit rewards this; future skills won't research it again.

Why learn

API research takes time. By saving what you discover, every future use of that system starts where you left off — no need to research the docs, endpoints, or authentication formats again.

Key Concepts

API ref doc: endpoint reference document. Endpoints: API URLs with parameters. Compounding: each documented connection speeds up the next ones.

What it is

At least one connection needs to WRITE — send email, post, create a task. If everything is read-only, AIOS is a viewer, not an OS.

Why learn

Reading without writing is passive monitoring. An OS takes action. The ability to write (send, create, update) is what sets an operator apart from a dashboard.

Key Concepts

Read-only: only reads data; does not modify it. Write permission: authorization to create/update/delete. OS vs. dashboard: distinguishes an operating system from a simple dashboard.

What it is

Integration reliability hierarchy: direct API (most reliable) > CLI > Browser Automation > Scraping (most fragile). Always prefer the most reliable option available.

Why learn

Scraping breaks when the layout changes. Browser automation breaks when the UI changes. APIs are stable contracts—when available, they’re always preferable. Knowing the hierarchy helps you avoid integrating at the wrong level.

Key Concepts

Integration Ladder: mechanism decision model. Reliability: probability it will work tomorrow. API contract: stable, versioned interface.

What it is

A short phrase triggers a multi-step workflow that produces a concrete artifact. If it takes five messages explaining what you want before you get something useful, no Capability is configured.

Why learn

Capabilities are your AIOS automation index. Each skill is a packaged action that any team member can trigger with a natural-language phrase.

Key Concepts

Artifact: concrete output (doc, email, analysis). Workflow: sequence of steps with a defined outcome. Natural trigger: plain-language phrase that triggers the skill.

What it is

Skill = SKILL.md with frontmatter (trigger + step-by-step instructions). Agent = multi-step sub-assistant with its own context and a cheaper model. Skills first—agents are for when skills aren't enough.

Why learn

Agents are more complex and costly to maintain. Skills are simple, predictable, and easy to debug. The rule is to start with the simplest thing that solves the problem.

Key Concepts

Frontmatter: YAML metadata at the top of SKILL.md. Sub-assistant: Claude running in a separate context. Its own context: isolation from the main session.

What it is

Three included skills: /onboard (Day 1 setup), /audit (Four-Cs diagnosis), /level-up (ship 1 automation per week). Intentionally lean — you build on top of them.

Why learn

These three skills cover the basic AIOS lifecycle: configure, measure, and evolve. Understanding what each one does helps you decide where to add your own capabilities first.

Key Concepts

/onboard: filling in the CLAUDE.md. /audit: diagnosis and score 0-100. /level-up: weekly automation shipping cycle.

What it is

Frontmatter with name e description (when to trigger) + body with step-by-step execution. Location: .claude/skills/<nome>/SKILL.md.

Why learn

Knowing the anatomy lets you create new skills from scratch without relying on skill-creator. Claude Code uses the frontmatter to decide when to invoke the skill automatically.

Key Concepts

name: skill identifier. description: semantic trigger — when Claude should use it. body: step-by-step execution instructions.

What it is

Boring-is-Beautiful preference order: saved prompt → deterministic skill (script, no AI) → AI-assisted skill (1 call) → sub-agent (last resort). Always use the simplest level that works.

Why learn

AI is powerful, but it isn’t the simplest solution for everything. A script that runs the same way every time is more reliable than an LLM call. Boring = predictable = operational.

Key Concepts

Deterministic: same input → same output every time. AI-assisted: uses an LLM for reasoning. Boring-is-beautiful: principle of preferring simple, reliable solutions.

What it is

Each /level-up run produces 1 artifact (skill or automation). Use skill-creator (Anthropic) or write the SKILL.md by hand. Every artifact starts with bike-method-phase: 1.

Why learn

/level-up is AIOS’s growth engine. One automation per week = 52 automations per year. Starting in phase 1 keeps the scope small and ensures delivery.

Key Concepts

bike-method: incremental delivery methodology. phase 1: minimum viable scope. skill-creator: Anthropic tool for generating SKILL.md.

What it is

When the work requires reasoning + repeatable use of tools. Sub-agents run in their own context to keep the main session lean. Located in .claude/agents/.

Why learn

Agents isolate complex work from the main context. This keeps a long analysis from consuming the operator’s session tokens. They offer the highest level of autonomy—use them judiciously.

Key Concepts

Its own context: isolated Claude session. Cheapest model: agents can use smaller models. Haiku for agents: lower cost for repetitive tasks.

What it is

Laptop closed. A brief lands in the inbox. A colleague asks a question and gets a real answer. If this happens without you manually starting it, you have Cadence. If you had to open and run it, you don't.

Why learn

Cadence is the level where AIOS stops being a tool and starts becoming a true operating system—autonomous in its rhythm, not just in its responses.

Key Concepts

Proactive: acts without being asked. Reactive: responds when called. Cadence: a regular, autonomous operating rhythm.

What it is

Hooks on .claude/settings.json, or skills named with a frequency prefix: daily-* / weekly-* / monthly-* / morning-* / standup.

Why learn

Triggers are the infrastructure for Cadence. Without them, every automation is manual — you have to remember to run it. With triggers, the system knows when to act.

Key Concepts

Hook: event that triggers execution. settings.json: Claude Code hooks configuration file. Frequency prefix: naming convention for recurring skills.

What it is

The kit’s anchor isn’t cron—it’s the ritual: weekly /audit (Day 7) + /level-up every Friday. Behavior builds the habit; infrastructure is secondary.

Why learn

Cron systems without habits get abandoned. Rituals create the feedback loop that keeps the AIOS evolving. Running /audit every week is what makes the score go up.

Key Concepts

Ritual: repeated action with intention and regularity. Cron: automatic scheduler. Feedback loop: measure → adjust → repeat.

What it is

Complete dependency graph: Context (foundation) → Connections + Capabilities (parallel) → Cadence (top). Don’t automate workflows that don’t work manually. Automation amplifies — it doesn’t fix.

Why learn

Automating a bad process creates more problems, faster. Validating it manually first ensures that what you automate already works — so automation only speeds it up.

Key Concepts

Dependency graph: required build order. Amplification: automation scales what exists, for better or worse. Manual-first: validate before automating.

What it is

Three signs that AIOS has changed the way you work: (1) Team-reaches-out — colleagues come to you as an AI resource. (2) Context-switching reduction — less mental context switching. (3) Knowledge-leaves-your-head — knowledge moves from your head into the system.

Why learn

KPIs are easy to manipulate. Experiences are hard to fake. These three signals show that AIOS created real behavior change, not just automations on paper.

Key Concepts

Team-reaches-out: external recognition of competence. Context-switching: cognitive cost of switching tasks. Knowledge externalization: turn tacit knowledge into explicit knowledge.

What it is

When the indicators appear for one person, the same data architecture scales to dashboards, automations, and team rollout. A company where every operator runs a personal AIOS is truly AI-ready.

Why learn

An individual AIOS isn’t an isolated personal project—it’s a prototype of what the company can become. Mastering the 4 Cs individually is the foundation for organizational scale.

Key Concepts

AI-ready: structure ready to adopt and scale AI. Rollout: expansion of the model to the whole team. Replicable architecture: a pattern that multiple people can apply.