Your Workspace

An AIOS workspace is a git repo you create once and work in every day. One per person. It gives you and your agents the same map: a numbered folder spine, a tier tag on every file that decides who can see it, and validators that refuse to let the two drift apart.

It works on its own

A workspace is fully useful offline, with no Team Brain connection. The spine, tiers, validators, guard hook, and offline-capable skills all work standalone. Skills that sync, report provider spend, or talk to Linear naturally need those services. Connecting a brain is a separate, later, optional decision — see Team Brain when you want it.

Three properties do most of the work:

• Context-first — frontmatter on every file declares what it is and who may see it.
• Default-deny — nothing syncs unless you tagged it and it sits on a whitelisted path. A file with no tier is blocked, not guessed at.
• Agent-native — the repo ships the rules, skills, and hooks your agent reads, so a new agent session starts oriented instead of exploring.

---

The numbered spine

Every workspace uses the same numbered folders, in every context. The numbers are the pipeline: raw capture in 1-inbox, refined work in 2-work, deliberately promoted output in 4-shared. Nothing moves between them on its own.

Folder	What lives there	Tier	What can sync
0-context/	Charter and scope, or role and OKRs	team	All of it
1-inbox/	Raw inputs, meeting transcripts, brain pulls	admin	Only 1-inbox/transcripts/
2-work/	Deliverables and working documents	team	All of it
3-log/	Decision log, tasks, hours, spend	admin	Only the decision log, team tasks, AI spend
4-shared/	Client-facing or company-facing output	external	All of it
5-personal/	Private scratch	admin	Nothing — explicitly excluded

Two other paths matter. .claude/memory/ — what your agent has learned about you and this workspace — is whitelisted, so durable context follows you across machines. And the business-owner context adds a seventh root, 6-business/, which is deliberately left outside the whitelist: bookkeeping, entities, and insurance never sync.

Whitelisted is not the same as synced

A file leaves your machine only if both gates open: its path is in sync_include and its own access: tier is one you allowed in sync_tiers. An untagged file in a whitelisted folder does not sync — it is refused, not inferred. That is why 1-inbox/transcripts/ being whitelisted is safe: a transcript still sits there privately until someone tags it.

---

Access tiers

Every file carries an access tag in its YAML frontmatter:

---
title: Sprint 1 retrospective
access: team
---

Friendly names map onto three canonical tiers:

Friendly	Canonical	Who sees it
private, personal	admin	You only — never leaves your machine
team	team	Everyone on your team, via the brain
client, company	external	External stakeholders

Caution

The Team Brain rejects admin-tier content with a 422 at the API boundary. It never enters the database. This is a hard invariant enforced in code, not a convention.

---

Seeing it happen

You don’t build the spine by hand. scripts/scaffold-project.sh creates it — and if you’d rather not run a script yourself, a coding agent can do the whole thing from one prompt. Here is what that looks like. The six rungs it draws are the folders above, coloured by the tier each one defaults to: grey is private by default, teal is team, amber goes outward.

claude code ✓ done

$ claude  

> Set up AIOS on this machine as a careful onboarding guide. +29 lines

◆ read inspect, explain, choose, validate, then stop

⌕ inspecting aios onboard --inspect --json · read-only

· found no workspace and no toolkit on this machine

· explained first run · starting from a clean machine

▸ your turn Personal / Join / Create?

Personal · keep it standalone

Join · connect an existing brain

Create · deploy Team Brain on Railway

> Join  

⌁ cloned aios-workspace · dependency-free scaffolder, no packages installed

◇ previewed 6 folders to create · nothing written yet

▸ your turn scaffold exactly this?

waiting · nothing is written without approval

> approve  

✓ scaffolded my-workspace · 6 folders, 3 access tiers

· ▁ ▂ ▃ ▄ ▅ ▆ 0-context 1-inbox 2-work 3-log 4-shared 5-personal

▚ private 3 of 6 folders never leave this machine

⌁ normalized https://brain.example.com/t/acme to https://brain.example.com

▸ your turn trust and save this exact Brain origin?

waiting · the URL is not trusted yet

> approve exact origin  

✓ validated GET /api/v1/me · team acme, member tier

✦ ready workspace connected in under 15 minutes

▚ held no push performed · sharing remains a later choice

▸ next aios status · review what is local, blocked, or eligible

A recording of the same six folders and three access tiers described above being created. The coloured rungs are the tiers: grey stays on your machine, teal syncs to the team brain, amber goes outward.

1. $ claude
2. > Set up AIOS on this machine as a careful onboarding guide. +29 lines
3. read — inspect, explain, choose, validate, then stop
4. inspecting — aios onboard --inspect --json · read-only
5. found — no workspace and no toolkit on this machine
6. explained — first run · starting from a clean machine
7. your turn — Personal / Join / Create?
8. Personal · keep it standalone
9. Join · connect an existing brain
10. Create · deploy Team Brain on Railway
11. > Join
12. cloned — aios-workspace · dependency-free scaffolder, no packages installed
13. previewed — 6 folders to create · nothing written yet
14. your turn — scaffold exactly this?
15. waiting · nothing is written without approval
16. > approve
17. scaffolded — my-workspace · 6 folders, 3 access tiers
18. the six folders: 0-context (team), 1-inbox (private), 2-work (team), 3-log (private), 4-shared (external), 5-personal (private)
19. private — 3 of 6 folders never leave this machine
20. normalized — https://brain.example.com/t/acme to https://brain.example.com
21. your turn — trust and save this exact Brain origin?
22. waiting · the URL is not trusted yet
23. > approve exact origin
24. validated — GET /api/v1/me · team acme, member tier
25. ready — workspace connected in under 15 minutes
26. held — no push performed · sharing remains a later choice
27. next — aios status · review what is local, blocked, or eligible

Two things worth noticing. It stops and waits before it writes anything — that pause is a human gate, not politeness. And it explains how to connect a Team Brain without connecting one: sharing stays a separate decision you make later.

---

Governance that actually runs

Two mechanisms keep the structure honest. Neither is advice — both fail loudly.

Validators

validation/validate-all.sh runs fifteen checks (OGR01–OGR15) against any workspace:

Group	Checks
Structure and content	OGR01 numbered spine and required files · OGR02 frontmatter present and complete
Secrets	OGR03 API keys, tokens, private keys, .env — critical, hard fail
Configuration	OGR04 aios.yaml schema and runtime validity
Agent layer	OGR05 rubrics and memory · OGR09 skill library integrity · OGR15 delivery skill suite · OGR10 agent-readiness score (advisory)
Portability	OGR06 skill-export round trip · OGR07 runtime adapters · OGR12 OpenCode scaffold parity
Scaffold integrity	OGR08 scaffold guard · OGR11 scaffold git workflow
Codebase hygiene	OGR13 modularity ratchet (advisory) · OGR14 anti-sprawl ratchet

validation/validate-all.sh /path/to/your-workspace   # all fifteen
validation/validate-all.sh . --critical              # secrets only
validation/validate-all.sh . --quick                 # structure only

The validators that scan workspace files enumerate tracked content through git ls-files, so gitignored build trees are structurally invisible to those scans. Other validators inspect fixed configuration and scaffold paths directly. They run in CI: a push that fails the secret scan is blocked, and the scaffold is validated in all three contexts on every build.

The guard hook

hooks/team-ops-guard.sh is a Claude Code PreToolUse hook registered on every Write and Edit in a scaffolded workspace. It blocks:

1. Files containing secrets — API keys, tokens, .env content
2. Admin-tier content written into team-tier directories
3. Markdown deliverables missing frontmatter

Validators catch mistakes before a push. The hook catches them before the file exists.

---

What ships in the scaffold

A new workspace comes with eighteen agent skills in .claude/skills/. Some are multi-agent harnesses; the rest are everyday tools.

Skill	What it does
decision-audit	Governance audit of the decision log — one verifier per rule, then an adversarial pass
scope-creep	Classifies deliverables against the scope baseline, with a refuter that downgrades false positives
weekly-synthesis	Weekly digest with a rubric-gated self-correction loop
okf-traverse	Answers a question by traversing the local link graph — offline, no brain needed
transcript-decisions	Turns meeting transcripts into grounded decisions and task commitments
aios-sync	Review what’s staged, decide what to promote, then push
workspace-setup	Interviews you and writes your profile into the workspace
agentic-maturity	Places you on the Agentic Maturity model and prescribes a next step
maturity-report	Builds a transformation maturity report across individual, codebase, and team
cost-monitor	Collects AI provider spend and pushes it to the brain
ai-code-review	Verifies the checkable claims in an agent’s wrap-up
aios-deck	Builds brand-themeable slide decks and verifies their rendered visual quality
review-plan	Critiques an implementation plan and emits feedback for another model
codebase-memory	Structural code queries over a codebase knowledge graph
framework-currency	Known framework gotchas, checked before writing framework code
find-skills	Discovers and installs additional skills
aios-linear	Reads and updates the Linear board
workstream-update	Proposes non-overlapping parallel agent workstreams

transcript-decisions runs through the CLI

Transcript review is driven by aios transcripts draft → list → approve, which stages results for one human approval before either log changes. The skill guides that flow; it does not write your logs behind your back.

The four harnesses — decision-audit, scope-creep, weekly-synthesis, and okf-traverse — are the interesting ones. Each spawns focused sub-agents and adds an independent verification step, because the finding behind their design was that adversarial verification, not parallelism, is what makes a harness trustworthy. See Harnesses for what each one does and how to run it.

---

The OKF

The workspace keeps a structured link graph — the Open Knowledge Framework. Any file can carry links: in its frontmatter pointing at related decisions, tasks, or documents. aios pull-bundle fetches the graph from the brain, and okf-traverse answers questions by following those links rather than searching full text. Once pulled, it works offline.

---

Three contexts

The scaffold asks once how you work, and skins 0-context/ and 4-shared/ accordingly. The numbered spine itself is identical in all three.

• consultant — 0-context/ holds the engagement charter and client scope; 4-shared/ is the client-facing surface.
• employee — 0-context/ holds your role definition and OKRs; 4-shared/ is the company-facing surface.
• business-owner — the consultant skin, plus a seventh root 6-business/ for bookkeeping, entities, engagements, insurance, and administration. It is deliberately outside the sync whitelist and never leaves your machine.

---

Where to go next

• Quickstart — scaffold your workspace and run your first harness
• Harnesses — the multi-agent workflows in detail
• The Cockpit — drive all of this from a GUI instead of the terminal
• Integrations — connect Slack, Linear, Granola, GitHub and more
• CLI reference — every aios command
• Team Brain — when you’re ready to share with a team