🌱 Expansions & Weekly Cadence
Scale without turning into a hoarder's basement. Know what to add, when to add it, and how to keep AIOS lean, navigable, and useful as your business grows.
Illustrative diagram — The 3 Sins Rule for controlled AIOS expansion
Detailed content
What comes in the kit (don’t remove it)
The AIS-OS kit comes with a deliberately minimal structure. Each folder and file has a defined purpose—removing or renaming one breaks the commands /onboard, /audit e /level-up. Learn what each piece is before touching it.
📁 AIS-OS Base Structure (Untouchable)
aios/
├── CLAUDE.md ← instruções globais do agente
├── aios-intake.md ← formulário de onboarding
├── connections.md ← mapa de integrações
├── context/ ← snapshots de contexto ativo
├── references/ ← documentos de referência
├── decisions/
│ └── log.md ← registro de decisões
├── archives/ ← material arquivado
└── .claude/
└── skills/ ← skills do AIOS
💡 Practical Tip
If you need to rename something, also edit the prompts for commands that reference that path. AIOS reads CLAUDE.md in every session — any wrong path there creates silent confusion.
What to add as you grow
Not every folder needs to exist on day 1. AIOS grows with you—but organically, responding to real needs, not to “maybe someday.” Here are the items that emerge naturally as the business matures:
Week 1–4 · Base kit, no additions
Use the kit as it came. Let AIOS run. Observe what you repeat and what creates friction before building anything new.
Month 1–2 · First organic expansions
If you’ve stopped copying the same prompt, create templates/. If you have 2+ simultaneous active workstreams, create projects/ with subfolders.
Month 3+ · Mature operation
Processes documented in references/sops/. Brand identity at brand-assets/. API documentation at references/{tool}-api.md. Sub-OS for separate verticals in youtube-os/, etc.
Anti-patterns: what NOT to add
Most AIOS setups that become a mess don’t suffer from a lack of organization — they suffer from too much premature structure. Learn the patterns that clutter the system and undermine the agent’s clarity.
✓ What to ADD
- ✓ A folder you’ll use 3+ times/month — if it isn’t used regularly, it will become a dead file
-
✓
File with a clear, specific name —
stripe-api.mdyes,api-stuff.mdno - ✓ SOP when someone new needs to rerun it — only document processes that repeat with others
- ✓ Sub-OS for a genuinely separate vertical — youtube-os/ only if it has its own distinct workflow
✗ What NOT to ADD
- ✗ Email/Slack dump in references/ — the agent will try to read everything; bloated context = vague answers
- ✗ Folder of folders with no files — deep hierarchy without content is pure bureaucracy
- ✗ notes/ misc/ tmp/ inbox/ — intention graveyards; everything goes in, nothing comes out
- ✗ Pre-create folders "for when you need them" — structure without use misleads the agent about what exists
- ✗ Second CLAUDE.md in a subfolder — just one at the root; multiple ones create an authority conflict
⚠️ Golden Rule
Duplicate the structure of the decisions/log.md somewhere else is the quietest mistake: two sources of truth for decisions mean the agent doesn't know which one to trust, and you start seeing inconsistent behavior across sessions.
Suggested cadences
The AIOS is a living system. Without maintenance, decisions become outdated, files accumulate, and the agent starts operating with stale context. The routines below keep the system healthy with minimal effort.
Every decision → decisions/log.md
New tool, process change, vendor choice. The more decisions you log, the more the agent understands the "why" behind the structure — not just the "what".
Each new tool → connections.md
Add the tool immediately, not "later." The /audit read this file to see what’s available — an outdated connections.md leads to bad suggestions.
Quarterly cleanup → archives/
Every 3 months, move any context, project, or reference that hasn’t been touched to archives/. Don’t delete it — archive it. The history has value, but it doesn’t need to clutter the active context.
Quarterly review of the CLAUDE.md
Agent instructions get stale. Review each cycle to make sure the preferences, tools, and processes described still reflect how you operate. An outdated CLAUDE.md is worse than none.
When to rerun with someone → references/sops/
An SOP only needs to exist when a second person (or you, six months later) needs to repeat the process without context. Document enough for that—no more.
⏱️ Practical Tip: the right trigger
Don’t schedule an “AIOS review” on your calendar—tie each cadence to a natural event. Made an important decision? Log it immediately. Closed a quarter? Archive + review CLAUDE.md. Hired someone? Write the SOP. A clear trigger means you won’t forget.
The 3 Yes Rule
Every time you feel the urge to create a new folder or file in the AIOS, answer 3 questions. Your answer determines whether you add it now or wait. Simple, quick, foolproof.
🔢 The 3 Questions
Is it conceptually new?
It isn’t just a variation of what already exists in another file. It needs its own “container” to make sense.
Will I use this 3+ times next month?
Frequency is the main indicator of usefulness. A rarely visited folder is noise — the agent considers everything in the structure when browsing.
Would /level-up route a future skill here?
If an agent would naturally save something here when automating something new, this is a legitimate destination. It’s a good sign that the abstraction makes sense.
✓ 2+ yeses → Add now
- ✓Create the folder or file immediately
- ✓Name specifically (not generically)
- ✓Update the
CLAUDE.mdif it's a new recurring destination - ✓Log the creation decision in
decisions/log.md
✗ 1 yes (or none) → Wait
- ✗Don’t create premature structure
- ✗Use the existing structure, even if "it's not perfect"
- ✗Reassess in 30 days — the actual frequency will become clear
- ✗If it keeps bothering you, the trigger will become clear on its own
Branch frameworks (future) + philosophy
The AIS-OS is an intentional kit—not a platform with endless features. Advanced frameworks can be added as the operation matures. And there’s a philosophy that connects them: clarity over completeness.
🌿 Branch frameworks (add when the operation requires them)
Data Retrieval Hierarchy
Defines the priority order for finding information: active context → references → archives → web. Eliminates ambiguity when sources conflict.
Integration Ladder
Integration depth hierarchy: read → write → automation → orchestration. Useful when you have many tools and need to prioritize.
Error Handling Playbook
Protocols for when the agent gets stuck, makes mistakes, or enters a loop. Essential in high-frequency or critical operations.
Model Selection
Criteria for choosing which model to use for which task — balancing cost, speed, and reasoning ability.
Context Engineering
Techniques for structuring context so the agent can find what it needs without being overloaded. Includes chunking, active summarization, and pinning.
Security & Permissions
Authorization layers for sensitive operations: what the agent can do without asking, what requires confirmation, and what is prohibited.
🏡 The final philosophy
"Your AIOS should feel like a small, well-run business — not a hoarder’s basement."
A well-managed business has clear processes, clean spaces, documented decisions, and knows exactly what it has. A hoarder’s basement has everything “just in case,” nothing is where it should be, and no one dares touch anything. Which one is your AIOS?
✓ Well-managed business
- ✓Minimal and functional structure — everything has a clear place
- ✓Logged decisions — the agent understands the history
- ✓Active vs. archived files — clean context
- ✓Scale on demand — with no unnecessary overhead
✗ Hoarder's basement
- ✗Folders for everything — none with useful content
- ✗"Just in case" files that are never opened
- ✗Context mixed with junk — agent gets confused
- ✗Scale without direction — every idea becomes a new folder
🌱 Module Summary
You completed the AIS-OS!
You’ve completed the 3 tracks — Mindset, Architecture, and Hands-on Operations. Now you have the fundamentals, structure, and routines to operate a real AI Operating System. The next step is to use it, iterate, and let the system grow with you.