$ cat /architecture
Under the hood of
the operating system
Git as the company knowledge database. YAML frontmatter as machine-readable metadata. MCP as the protocol for AI agents. Pull Requests as an approval workflow.
Repository architecture
# Directory structure
company-os/
context/ # Company context
company/ # Profile, values, team, KPIs
products/ # Product catalog
clients/ # ICP (Ideal Client Profile)
market/ # Competitors
strategy/ # Vision, roadmap, goals
decisions/ # ADR records
processes/ # Workflows and processes
sales/ # Discovery, proposals
delivery/ # Onboarding, projects
finance/ # Invoicing, payroll
agents/ # AI agents
personas/ # Agent identity
prompts/ # System prompts
tools/ # Tool inventory
templates/ # Document templates
blueprints/ # Technical plans
reference/ # Glossary, tech stack
docs/ # Conventions, SOUL.md
CLAUDE.md # Routing table
Why this structure?
Every folder maps to one company "domain." The AI agent receives context only for its task; it does not need to load the entire repo. This is progressive context disclosure.
CLAUDE.md = sitemap for AI
100+ entries in the format | I need... | Go to... |. The agent never searches the entire repo. Instead, it checks the routing table and finds the right file.
Conventions drive quality
docs/conventions.md defines rules for all files: language, format, naming, frontmatter schema. AI and humans follow the same rules.
YAML frontmatter: metadata for AI
Every file in the repository has a mandatory YAML header. These are machine-readable metadata that tell the AI agent: what type of document this is, who owns it, what state it is in, and how to interpret it.
Schema
| Field | Type | Description |
|---|---|---|
| title | string | Document name |
| type | enum | persona, process, workflow, strategy... |
| status | enum | ai-generated, draft, review, approved |
| version | string | Epoch.Revision (0.1, 1.0, 1.3) |
| owner | string | Responsible person |
| tags | array | Classification labels |
| domain | enum | sales, finance, products... |
| summary | string | Brief content description |
# Example: payroll workflow
---
title: "Payroll Workflow"
type: workflow
status: approved # ai-generated -> draft -> review -> approved
version: "1.3" # Epoch.Revision
created: 2026-01-15
updated: 2026-03-01
owner: "Jan Tobolik"
tags: [payroll, finance, workflow]
domain: finance
summary: "6-step payroll processing workflow"
---
# What the AI sees:
"This is an approved workflow, version 1.3,
in the finance domain, owned by Jan Tobolik.
I can trust it as an authoritative source."
Trust model
The AI agent follows document status. It knows what to trust.
ai-generated
Untrusted
AI version without human review. Always warns the user.
draft
Low trust
Work in progress. Agent proceeds with caveats.
review
High trust
Likely correct. Agent flags uncertainty.
approved
Ground truth
Human-verified. Full confidence.
archived
Invalid
Historical record. Do not use.
# Status workflow
ai-generated → draft → review → approved → archived
# Key rule:
# Only a human can set the "approved" status
# AI proposes, humans decide
AI integration: three levels
From passive reading to active system maintenance.
AI reads documentation
User:
"How does our onboarding work?"
Agent:
→ Finds processes/delivery/onboarding.md
→ Reads it, answers in company context
Passive. The agent serves as a knowledge assistant.
AI executes processes
User:
"Prepare payroll data for February"
Agent:
→ Follows 6-step workflow
→ Connects to Google Sheets (MCP)
→ Sends email via Gmail (MCP)
Active. The agent executes work following repo processes.
AI maintains the system
User:
"Update the roadmap"
Agent:
→ Reads ADR, goals
→ Proposes changes
→ Creates a Pull Request
Autonomous. The agent proposes changes, humans approve.
MCP: Model Context Protocol
A standardized protocol for AI to access external services.
# Architecture
Claude (AI) <--> MCP server <--> Gmail / Drive / Sheets
# .mcp.json configuration
{
"mcpServers": {
"google-workspace": {
"command": "uvx",
"args": ["mcp-google-workspace"],
"env": {
"CLIENT_ID": "${...}",
"CLIENT_SECRET": "${...}"
}
}
}
}
One OAuth token
A single login = access to Gmail, Google Drive and Google Sheets. No repeated authorization.
Credentials outside the repo
OAuth tokens live in .env (in .gitignore). A SessionStart hook verifies they exist.
Practical use
AI reads an email with payslips, downloads attachments, saves them to Drive, writes data to Sheets, all through MCP.
Zone model for Drive
GREEN free write YELLOW on request RED read only
Git workflow and tier system
Who can do what. Pull Requests as the approval process.
| Tier | Who | Can | Cannot |
|---|---|---|---|
| Admin | Owner | Everything | – |
| T1 | Team | Push, PR, edit | Merge to main |
| T2 | Readers | Read, comment | Push |
| T3 | AI agents | agent/* branches, PR | Merge, push main |
# Branch naming
Human: feature/pricing-update-2026
Fix: fix/broken-links
Docs: docs/conventions-update
AI: agent/sales-proposal-template
Key rule
The AI agent never merges its own PR. It always creates a branch, commits changes, opens a PR with a description, then waits for human review.
SOUL.md: AI agent identity
Every AI agent has a "soul," a set of behavioral rules.
Transparency
Always discloses it is AI. Never impersonates a human.
No hallucinations
If it does not know the answer, it says "I don't know." Unknown data is flagged with TODO.
Convention compliance
Follows docs/conventions.md: frontmatter, language, format.
Humans decide
AI proposes changes. Only a human can approve (set status to approved).
Three paths to AI
Start where it makes sense. Each level delivers real value.
Level 1
Explorer
"Right tools, right approach. Results appear immediately."
- AI tools set up for your team
- Personal AI plan for every participant
- No setup, no coding required
- Results from day one
Level 2
Builder
"No code to write, but plenty to think through. Your entire company, its procedures, is essentially code."
- Company memory: AI retains processes, customers, history
- Automation of repetitive tasks (CRM, reporting, documents)
- A system that learns and improves every week
- Your data stays yours. No vendor lock-in.
Level 3
Architect
"A 5-hour contract takes 2.5 hours. That is 50% more margin."
- 50-80% efficiency gain in routine operations
- Full automation of entire business processes
- A smarter company, not just a faster one. Knowledge multiplies.
- Strategic competitive advantage for years ahead
Why Git + Markdown?
Compared with common knowledge management tools.
| Criterion | Git + Markdown | Notion / Confluence |
|---|---|---|
| Version control | Full (every commit) | Limited (30 days / none) |
| Data ownership | 100% yours | On vendor servers |
| AI-ready | YAML + MD = ideal for LLMs | Proprietary API, complex parsing |
| Cost | Free (GitHub) | $8-15/user/month |
| Review workflow | Pull Requests | Manual (comments, email) |
| Offline access | Yes | No (cloud only) |
Want to see it in action?
In our workshop we demo the full architecture live, including the payroll workflow and AI agents.