A team operating system for a 20-person company

A documentation system for a 20-person startup: git-versioned markdown plus Claude Code agents that turn the Notion graveyard into a living, self-maintaining knowledge base.

There is a specific kind of decay that happens inside a 20-person company. The wiki, which was once cared for by one person who left in 2024, now contains three competing versions of the onboarding doc. The Notion graveyard has 4,200 pages and a search bar that mostly returns archived sprint plans from a product that pivoted. The shared Google Drive has folders called _FINAL, _FINAL_v2, and _for_review_2025_03_use_this_one. New hires ask in Slack because the wiki cannot be trusted and the answer scrolls past in eight minutes. Senior engineers maintain private docs in their own filesystems because they have given up on the shared one.

This is documentation hell. Not a tooling problem. Five years of Notion releases, Confluence updates, and Coda redesigns have not solved it for anyone we have worked with. The problem is structural: traditional wikis are read-only artifacts that depend on a single class of maintainer (humans) and a single mode of update (manual). At 20 people that maintenance cost outruns the capacity of any one person to carry it, and the system rots from the middle.

There is now a different way to build this. Not "use AI to write your docs better." Something more architectural: treat your team's documents as a substrate that humans and AI agents both stand on, version it like code, give agents the same read and write access to it that the team has, and let the wiki maintain itself by being the place the work actually happens.

This is what we call a Team OS. We run one. We have helped install one. This article is a practitioner walkthrough of how it works, what breaks, what it costs, who should build it, and who should not. The thesis, which we will defend through the rest of the piece: your team's docs are not a wiki. They are a substrate. Treat them that way and a 20-person company can operate like a 50-person one.

A Team OS is a self-hosted, git-versioned, markdown-based knowledge and operations layer that both humans and AI agents read and write to. It sits on a Linux server the team controls. People work in it through SSH and a terminal multiplexer (tmux or zellij). Agents work in it through Claude Code or an equivalent agentic CLI. The same files, the same permissions model, the same git history.

That definition is short, so let us unpack what is different about it.

A traditional wiki is a destination. You leave your work, go to the wiki, deposit a document, and return to your work. The wiki is a graveyard of past intentions, decorated with templates.

A Team OS is the work. Your sprint plan is a markdown file. Your meeting notes are a markdown file. Your onboarding doc is a markdown file. Your release notes are generated from commits between two git tags by a script in .claude/skills/release-notes/. Your daily intelligence digest is created at 7 AM by a cron job and posted to Slack. There is no separate destination. The team operates inside the substrate, and the substrate is what humans and agents share.

This is not a metaphor. Garden actually runs a system shaped like this. We have helped a Berlin research firm move toward one. The pattern is increasingly documented in the wild: production agentic systems (GBrain, DiffMem, lat.md, Obsidian-plus-MCP setups) all converge on the same architectural insight, which is that git-backed markdown is the cheapest, most durable, most agent-friendly substrate available in 2026 (Source: extency.com/blog/markdown-versioned-folders-agent-brain-2026).

The hard part is not the tooling. The hard part is the shift in how you think about your docs. They are not artifacts that record decisions. They are the workspace in which decisions are made, by humans and by agents simultaneously, with full audit trails.

A Team OS has four layers. Each can be assembled from open source components. None of them is novel on its own. What is novel is the stacking, and the fact that all four layers are versioned together, in one git repository.

1. Access layer. How humans and agents get into the system. SSH plus tmux is the default. Web-based options exist (Coder, code-server) for non-terminal members.
2. Data layer. What the system stores. Git-versioned markdown files, organized by domain (projects, meetings, knowledge, people, ops). Every change is a commit with an author and a timestamp.
3. Agent layer. Who operates on the data. Claude Code as the orchestrator, with role-specific sub-agents (.claude/agents/) handling specific kinds of work. Agents read and write the same files humans do.
4. Skills layer. The repeatable operations the team relies on. Stored in .claude/skills/, versioned, reviewable, share-able. A skill is a directory containing instructions and assets that any agent on the team can invoke. The "weekly sprint digest," the "onboarding for new designer," the "playtest report parser": each is a skill, not a one-off prompt.

This is not Notion with a chat box bolted on. Notion gives you a single layer: the data. The interface is Notion's, the agents are Notion's (and they cannot write outside Notion), and the structure is Notion's. The Team OS gives you all four layers, fully controllable, in a single git repository you own.

It is also not "just a folder of markdown files." A folder of markdown files is a personal note system (Obsidian, Logseq) and a fine one. A Team OS is multi-user, has a permission model, has agents inside it, and has a skills layer that makes team operations explicit and reproducible. The difference is in the operating layer above the files.

Here is the file tree of a real Team OS for a 20-person company:

team-os/
├── CLAUDE.md                    # team-wide rules and conventions for agents
├── .claude/
│   ├── agents/                  # sub-agents (sprint-tracker, gdd-editor, etc.)
│   ├── skills/                  # reusable team operations
│   └── settings.json            # permissions, allow- and deny-lists
├── people/                      # team profiles, ownership maps
├── projects/
│   ├── product-a/
│   │   ├── design/
│   │   ├── production/          # sprint plans, current work
│   │   ├── postmortems/
│   │   └── decisions/           # ADRs
│   └── product-b/
├── ops/                         # infra, releases, deploys, runbooks
├── meetings/                    # standups, retros, syncs (raw + summaries)
├── knowledge/                   # internal wiki, glossary, references
└── intel/                       # daily/weekly external intelligence feeds

Every leaf in that tree is markdown. Every change is a git commit. Every agent that touches anything writes to a feature branch and opens a pull request, just like every human does. The whole thing is mirrored to a private git host (Gitea, GitLab, GitHub). The whole thing is searchable by ripgrep in milliseconds and by an MCP-backed semantic index when you want concept-level retrieval (Source: github.com/willynikes2/knowledge-base-server).

For a small technical team, the access layer is almost embarrassingly simple. A Linux VPS (Hetzner, IONOS, Scaleway, or a self-managed box) with SSH. Each team member gets a Unix account. Each account gets tmux as the default shell environment. That is the whole thing.

Why SSH plus tmux and not a slick web IDE?

Persistence. A tmux session survives your laptop closing, your network changing, your flight landing. You reattach and your Claude Code session is still running, your sprint-tracker agent is still where you left it, your half-written meeting note is still open in the same pane. For a team doing knowledge work across timezones, this matters more than it sounds. The friction of resuming work after an interruption is one of the silent drains on a 20-person company. tmux removes it (Source: blle.co/blog/claude-code-tmux-beautiful-terminal).

Parallel agents. A senior engineer working on three things in three panes is a normal tmux workflow. Three agents working on three things in three panes is the same workflow. You can have a Claude Code session refactoring code in pane 1, another summarising yesterday's meetings in pane 2, and a third writing a release-note draft in pane 3. All visible, all interruptible, all logged (Source: ksingh7.medium.com/watch-claude-code-agents-work-side-by-side).

No vendor. SSH is older than most of the engineers using it. It will be here in 2040. The same cannot be said for any specific web IDE, AI-coding-assistant cloud, or "AI workspace" startup.

The honest cost: this access layer assumes terminal comfort. If your team's median member cannot ssh into a server without help, this layer needs an alternative. Coder (self-hosted) is the cleanest one we have used: an open-source web IDE that gives every user a containerized dev environment, accessed through a browser, with the same underlying file system as the SSH users (Source: coder.com/vs/gitpod-self-hosted-alternative). It adds operational complexity, and it adds about €40 to €120 per month in compute, but it removes the terminal barrier for designers, PMs, and non-engineers.

Hardening the access layer is non-negotiable and not complicated. Disable root login. Disable password authentication. Require SSH keys. Add a fail2ban or equivalent rate-limiter. Optionally add MFA via pam_google_authenticator or a Yubikey. For a regulated context, put a bastion host in front. None of this is exotic. It is the same checklist any competent sysadmin runs on any production server, applied to your team's knowledge layer instead of your database (Source: itguyeric.com/mastering-user-and-group-management-on-linux).

This is the layer that matters most, and the layer most teams get wrong when they try to copy the pattern. Three principles do the heavy lifting.

Markdown, not HTML, not rich-text, not blocks. Markdown reads cleanly in a terminal, renders cleanly in any browser, opens in Obsidian and VS Code, and is parseable by every LLM and tooling chain. It has no proprietary structure to lose. When you export from Notion you lose half the structure because Notion's block model is richer than markdown and the export is lossy. With markdown, there is no export. There is just git clone.

Git, not a database. Git gives you author and timestamp on every change, automatic conflict resolution, free branching, free rollback, and a free audit trail. A database gives you faster queries on structured fields. For 20 people producing documents, you want git. For querying who is in which project as of last quarter, the answer is git log --since='3 months ago' -- people/. Slower than a Notion view, infinitely more durable.

Folders, not databases. Notion's killer feature was the database view: take 200 sprint items and slice them by owner, status, due date. The Team OS pattern is to keep that structure in YAML frontmatter at the top of each markdown file and let a script (or an agent) generate the views on demand. The view is a query over the substrate, not a separate source of truth. When the structure changes you change the script, not the data.

A real example. Here is what one of our weekly digests looks like under the hood:

projects/product-a/production/sprint-2026-W22.md
---
sprint: 2026-W22
start: 2026-05-25
end: 2026-05-31
goal: Ship v3.2 to staging by Friday
owner: bob
status: in-progress
---

## Committed
- [x] Auth rewrite (alice, #421)
- [ ] Webhook reliability (bob, #432)
- [ ] Dashboard v2 hotfix (carol, #438)

## Notes
The webhook work is blocked on the new queue selection...

The agent that generates the Monday morning sprint summary reads every file in projects/*/production/sprint-2026-W22.md, parses the frontmatter, summarises the notes, cross-references the linked GitHub issues, and writes a single digest to meetings/2026-05-25-monday-sync.md. A human reviews the digest before the standup. The work the agent did is committed by its own user account with a clear commit message; if it makes a mistake, you git revert and move on.

This is what we mean by "the wiki is a substrate." There is no separate place to update. The sprint plan, the sprint digest, the meeting note, and the audit trail are all the same files in the same repository, written by the same combination of humans and agents.

A note on search. ripgrep will index 20,000 markdown files in milliseconds. For 95% of internal queries that is sufficient. For semantic search ("find everything we have ever decided about onboarding new contractors"), you mount a small MCP-backed knowledge index over the same files. It is one process, takes about an hour to set up, and gives you concept-level retrieval without changing where the documents live (Source: github.com/willynikes2/knowledge-base-server).

This is the layer that takes a markdown repository from "fine note system" to "living team knowledge base." It is also where most documentation about agentic AI is vague, so we are going to be specific.

Claude Code is a CLI-based agentic tool from Anthropic. It runs in your terminal, reads and writes files, executes shell commands (within configurable permissions), makes git commits, and can be configured with sub-agents (specialized agents that handle specific kinds of work). There are alternatives (Aider, Cursor in agent mode, Continue) but Claude Code is the one we have run in production and the one this article describes. The same pattern works with the others; details change (Source: code.claude.com/docs/en/sub-agents).

A Team OS agent layer typically has three pieces.

The team-wide CLAUDE.md. This is a markdown file at the root of the repository that every agent reads before it does anything. It contains the team's conventions, the project structure, the rules of engagement. "Write commits in present tense." "Never modify files in projects/*/postmortems/ without a human reviewer." "When summarising meetings, preserve quotes verbatim." This is the contract between the team and the agents. It is the single most under-invested-in artifact in agentic teams; we have seen 20-person teams whose CLAUDE.md is 12 lines long and another whose is 600 lines long, and the difference in agent behaviour is enormous (Source: github.com/FlorianBruniaux/claude-code-ultimate-guide).

Sub-agents in .claude/agents/. Each sub-agent is a markdown file that describes a role. The file contains the agent's mandate, its allowed tools, the files it is allowed to touch, and the prompt skeleton it uses. Some examples from real Team OS setups:

• sprint-tracker.md: reads projects/*/production/*.md, summarises status, generates weekly digest.
• meeting-summariser.md: takes a raw transcript in meetings/raw/, outputs a structured note in meetings/.
• release-notes.md: diffs git tags, generates release notes for ops/releases/.
• intel-curator.md: runs daily, reads RSS and search APIs, writes intel/YYYY-MM-DD.md.
• onboarding-buddy.md: answers questions for new hires by querying the repo and citing specific files.

Each agent is invoked either by a human ("run the sprint-tracker for product-a") or by a cron schedule ("intel-curator runs at 07:00 UTC daily"). Each invocation creates a git commit under the agent's user account. The agent has its own SSH key, its own Claude API key, and its own audit trail.

Skills in .claude/skills/. Skills are the next level of abstraction up from agents. An agent is a role with a persistent identity. A skill is a unit of work: a procedure that any agent can invoke. We cover skills in the next section because they deserve their own.

A critical design choice in the agent layer: agents never push to main directly. They create branches, commit, open pull requests, and wait for a human to merge. This is non-negotiable for a multi-user system. It gives the team a review surface for agent work, prevents an agent from silently corrupting the substrate, and makes the audit trail explicit. The cost is small: a few extra seconds per agent action. The benefit is enormous: you can trust the substrate (Source: medium.com/@Micheal-Lanham/20-lesser-known-ways-to-use-claude-code).

Permissions for agents are configured in .claude/settings.json and committed to the repository. Here is a minimal but realistic version:

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(rg:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Read",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:* | sh)",
      "Edit(.env*)",
      "Edit(.claude/settings.json)"
    ]
  }
}

The deny list is more important than the allow list. It is the explicit statement of what an agent cannot do, no matter how confidently it argues otherwise. Versioning this file in git means the team can review changes to agent permissions the same way it reviews code changes (Source: claudedirectory.org/blog/claude-code-permissions-guide).

A multi-user installation of Claude Code has a known sharp edge: by default, it is configured for a single user and fails with EACCES errors when multiple Unix users try to share it. The fix is straightforward but requires DevOps awareness: a shared claudeusers group, setgid bits on the config directories, and symlink redirection from each user's ~/.claude to the shared location. This is documented and not painful, but it is the kind of thing that is invisible until you trip on it (Source: dev.to/jeremy_longshore/fixing-claude-code-eacces-multi-user-linux-permission-architecture).

This is the layer we think is most underappreciated in current writing about agentic systems, and it is the one that makes a Team OS scalable beyond a few power users.

A skill is a directory in .claude/skills/ containing a SKILL.md file (instructions for the agent), optional supporting files (templates, prompts, scripts), and a clear interface (inputs, outputs, side effects). Any agent in the system can invoke any skill. Skills are versioned, reviewable, and share-able. They are the team's institutional knowledge encoded into a form that an agent can execute reliably (Source: agensi.io/learn/how-to-share-claude-code-skills-with-team).

Why this matters: prompts do not scale, skills do.

When a team starts using agents, the first six months are characterised by everyone tinkering with their own prompts. The senior PM has a great prompt for meeting summaries that lives in their browser bookmarks. The lead engineer has a great prompt for ADRs that lives in a private gist. The head of design has a great prompt for stakeholder summaries that lives in a Notion page nobody else knows exists. The system gets better in a hundred individually-tuned ways and worse organisationally, because none of that knowledge is shared.

A skill is what those prompts become when they grow up. A skill says: "here is how this team writes release notes; here is the input format; here are the conventions we follow; here are the edge cases we have learned to handle." Anyone (human or agent) can invoke it. When the team learns something new, the skill is updated in a pull request, reviewed, and merged. The next agent invocation benefits from the new knowledge. Institutional memory becomes a versioned artifact.

Concrete examples from real Team OS setups:

.claude/skills/
├── release-notes/
│   ├── SKILL.md
│   ├── templates/
│   │   ├── major-release.md
│   │   └── patch-release.md
│   └── examples/
├── meeting-summary/
│   ├── SKILL.md
│   └── format.md
├── adr/                       # architecture decision records
│   ├── SKILL.md
│   └── template.md
├── postmortem/
│   ├── SKILL.md
│   └── prompts.md
├── onboarding/
│   ├── SKILL.md
│   └── by-role/
│       ├── engineer.md
│       ├── designer.md
│       └── pm.md
└── intel-digest/
    ├── SKILL.md
    └── sources.md

A SKILL.md is typically 100–300 lines and reads like a working document for a smart new hire. It explains what the skill does, when to invoke it, what inputs it expects, what the team's conventions are, and what counts as a good output. Here is a sketch of one:

# Release Notes Skill

## When to use
Invoked by the release-notes agent after a git tag is pushed.
Can also be invoked manually with `claude run release-notes --from <tag1> --to <tag2>`.

## Input
- `from` and `to` git tags
- The git log between them
- The merged PRs between them (via GitHub MCP)

## Output
A markdown file at `ops/releases/<tag>.md` with:
- A one-paragraph executive summary
- "What's new" section (user-facing changes)
- "Internal" section (refactors, infra)
- "Breaking" section (if any)
- Contributors list

## Conventions
- We write in past tense ("added", not "adds")
- Each bullet links to the PR
- Breaking changes get their own H2 with migration notes
- Never include internal infra changes in "What's new"
- Always cite specific PR numbers, never hallucinate

The skill is short. It is also enough. An agent that reads this file before generating release notes will produce something the team accepts about 90% of the time, with the remaining 10% being edge cases that get added to the conventions list as the team learns (Source: agensi.io/learn/how-to-share-claude-code-skills-with-team).

The deepest property of skills is that they make team knowledge legible. Most teams have implicit conventions about how to write a postmortem, what an ADR should contain, how thorough a meeting summary should be. These conventions live in the heads of two or three senior people. When those people leave, the conventions degrade. A skill is the same convention written down once and used a hundred times. It is the closest thing a knowledge-work team has to a software function, and it accrues the same compound benefits.

A Team OS is best understood by looking at the work it does, not the architecture diagram. Here are five workflows that come up in almost every Team OS we have built or studied.

07.017.1 Sprint Tracker

The sprint-tracker agent runs on Monday morning at 09:00 local time. It reads every file in projects/*/production/sprint-<current-week>.md, parses the YAML frontmatter for status fields, cross-references the linked GitHub or Linear issues (via MCP), and produces three artifacts.

First, a single digest at meetings/<date>-monday-sync.md summarising progress across all active sprints. The PM uses this to run the Monday standup; they edit it during the meeting to add commitments, and the edited version becomes the canonical record of the week's plan.

Second, a Slack message in #general with the digest summary and a link to the full file. People who could not make standup catch up by reading the file, not by asking on Slack.

Third, a list of "needs attention" items: sprints where the goal has shifted three times, sprints with no updates in five days, sprints where the stated status does not match the linked GitHub activity. This list goes to the relevant leads.

The agent costs about $0.30 in API calls per run. It saves the PM about 90 minutes a week. The team finds out about stuck work earlier. Nobody has to chase status.

07.027.2 Meeting Summariser

After each meeting, the host drops the raw transcript (from Otter, Granola, or any tool that exports markdown) into meetings/raw/<date>-<topic>.md. The meeting-summariser agent watches that directory and produces a structured summary in meetings/<date>-<topic>.md with five sections: context, key decisions, action items (with owners and dates), open questions, and notable quotes.

The agent has a deliberately conservative bias. If it is not sure something is a decision, it puts it in "open questions" instead. If it cannot identify the owner of an action item, it leaves it blank with a flag for the host to fill in. This is the kind of judgment that lives in the skill file at .claude/skills/meeting-summary/SKILL.md, and it is what makes the agent's output trustworthy.

The first month, the host edits about 30% of the summary. By month three, the edit rate drops to about 5%, because the skill has accumulated team-specific conventions: "Bob's joke about Q4 is never a real action item," "Alice always says 'maybe we should' when she means 'we are doing this,'" "anything said in the last five minutes is usually noise."

07.037.3 Daily Intelligence Digest

This is the workflow that surprises non-technical members the most when they see it work. The intel-curator agent runs at 07:00 UTC every morning. It queries a small set of search APIs (Exa for semantic, Tavily for news, Perplexity for current events) on a list of topics the team cares about, deduplicates the results, summarises each item in 2–3 sentences, and writes a digest to intel/<date>.md. A Slack bot posts the digest to a #intel channel.

The topics are stored in a markdown file the team can edit: .claude/skills/intel-digest/sources.md. When a team member realises they want to start tracking a new area, they edit the file in a PR. The next morning, the digest includes the new area.

This pattern has another property worth naming. The intel digest is also a teaching artifact: junior members read it daily and build a mental map of what the team considers important and how the senior members evaluate sources. It is institutional knowledge transfer that happens passively, every morning, at the cost of a few dollars in API calls a day.

We run a version of this in production at Garden: a daily AI-and-science digest piped into Telegram at 07:00 UTC. The cost is about $0.40 per day in API calls and roughly 0.05 FTE in maintenance. The reading habit it creates is worth significantly more than that.

07.047.4 Release Note Generator

When a git tag is pushed, a CI hook triggers the release-notes agent. The agent reads the git log between the previous tag and the current one, fetches the PRs merged in that range via the GitHub MCP, and produces a draft release note at ops/releases/<tag>.md. The skill file specifies the team's conventions for what goes in each section (see Section 6 above).

The draft is opened as a PR. The release manager reviews it, edits the executive summary, and merges. The release note is now in the repository, versioned with the release. When marketing wants the changelog for the website, they grep ops/releases/. When a customer asks what changed in v3.2, the answer is ops/releases/v3.2.md. There is no separate "release notes" tool, and there is no manual rewriting in three different formats.

07.057.5 Onboarding

This is the workflow where the Team OS pays back its biggest dividend. On a new hire's first day, they get an SSH account, a Claude API key, and a one-line instruction: "Run claude run onboarding-buddy --role <your-role>."

The onboarding skill reads the role-specific instructions in .claude/skills/onboarding/by-role/<role>.md, points the new hire at the relevant sections of the repository, and offers to answer questions. When the new hire asks "what's our deployment process?", the agent reads ops/runbooks/deployment.md and answers, citing the specific file and line. When they ask "what does the founder care about?", the agent reads people/founders.md and the recent intel/ digests and answers with context.

A week in, the new hire is contributing to the substrate themselves: editing the role-specific skill file with things they wish had been clearer, fixing outdated paths in the deployment runbook, adding a postmortem entry for a process they tripped over. The wiki improves because it is being used, not despite being used.

We are not anti-Notion. Notion solves real problems for real teams, especially teams without technical comfort. But we want to be precise about the trade-offs.

The Notion case is real and we are not trying to bury it. If your team is non-technical, mobile-first, and small enough that documentation hell has not arrived yet, Notion is the right answer. Buy the Business plan, hire someone at 20–30% of their time to keep it organised, and revisit in 18 months (Source: notion.com/pricing).

The Team OS case is real for a different shape of team: 10–20 people, ≥60% terminal-comfortable, with documentation pressure (regulated work, IP-heavy work, or rapid scaling), and a willingness to invest in setup in exchange for a dramatically lower maintenance tax in years 2–3.

There is also the Notion-plus-AI-agents hybrid: keep Notion as the front-end, run agents behind it via MCP. We have looked hard at this. It is the worst of both worlds for a team of 20: you pay for two systems and you maintain two systems. It makes sense only if you have already invested 1–2 years in Notion and cannot stomach the migration cost (Source: dust.tt/blog/notion-ai-alternatives-ai-workspace-automation).

The honest gating criteria.

This is right for you if:

• Your team is 10–20 people. Below 10, you do not have a documentation problem yet; you have a "we have not written things down" problem, which a Team OS will not solve. Above 25, you start needing role-based access controls and HR-grade compliance that the SSH-plus-git model handles but feels increasingly thin against.
• At least 60% of your team is comfortable in a terminal. Engineers, technical PMs, technical designers, data folks, ops folks. If only your three engineers can SSH and your other 17 cannot, you are going to end up with the same documentation hell you started with, just with worse UX.
• You are willing to be opinionated about tooling. A Team OS is opinionated, not a buffet. You are choosing markdown over rich text, git over a database, terminal over web app, agents-write-back over agents-suggest-and-humans-paste. If your team's culture is "everyone picks their favourite tool and we integrate them," this is not the system for you.
• You have someone, even at 10% time, who can own the DevOps layer. Updates, backups, monitoring, the occasional permissions debugging. This person does not need to be full-time, but they need to exist.
• You have documentation pressure. You are scaling fast, you are in a regulated space, you have IP that needs to stay inside your perimeter, or you have been bitten by a Notion graveyard before and are determined not to repeat it.

This is wrong for you if:

• Your team is non-technical. A 15-person agency with three designers, a copywriter, two account managers, and a founder who never opens a terminal is not the target. Stick with Notion or Coda and invest in a documentation owner.
• You are in a regulated industry that requires ISO-certified document management (financial services with specific SEC requirements, healthcare with HIPAA-grade audit trails for documents themselves, certain government contracts). A Team OS can be made compliant, but you will spend more on compliance than on the system itself. Buy a commercial DMS.
• You need mobile-first access. Field teams, sales teams in the wild, anyone whose primary device is a phone. The Team OS is a desktop-and-laptop system. There are workarounds (Working Copy, Obsidian Mobile, Pretext on iOS) but the experience is not first-class.
• You are not willing to commit to a 90-day implementation period. The setup work is real. The team retraining is real. If your CEO wants "the AI thing" working in two weeks, do not start here.
• You expect the wiki to be self-maintaining without anyone using it. No system is. The Team OS makes the maintenance cheap when the system is used. If nobody uses it, it rots faster than a Notion graveyard does, because the entry barrier is higher.

We have been on the wrong side of these criteria for clients before. The pattern we see most often: a 25-person company with three engineers and 22 non-technical people convinces itself it wants a Team OS because the engineers want one. Six months in, the three engineers use it daily, the other 22 still ask in Slack, and the company is paying for two systems. Do not do this.

If you have read this far and decided a Team OS is the right shape for your team, here is what 90 days looks like. We have run this rollout three times now, in slightly different shapes. The phases below are the version that has worked best.

10.01Days 1–14: Discovery and Substrate

The first two weeks are about understanding the team's actual processes and standing up the substrate.

Discovery work:

• 4–6 conversations with team members across roles. What is your daily documentation pain? What do you write that nobody reads? What do you read that is always out of date? What would you automate if you trusted the automation?
• Audit of current tools. What do you actually use vs. what is open in tabs? What is the load-bearing document vs. the abandoned one?
• Map of current information flows. Where do meeting notes go? Where do sprint plans live? Where do decisions get recorded? You will discover surprises here.

Substrate work, in parallel:

• Provision a VPS (Hetzner, IONOS, or similar) with reasonable specs (4–8 vCPU, 16 GB RAM, 100 GB SSD is plenty for 20 people).
• Linux hardening: SSH keys only, fail2ban, no root login, no password auth.
• Create the team's Linux user accounts, group structure (team, engineers, designers, producers, leads).
• Set up the team-os git repository on your preferred host (private GitLab, Gitea, GitHub Enterprise).
• Bootstrap the folder structure shown in Section 2.
• Install Claude Code in multi-user configuration (the claudeusers group, setgid bits, symlinks).
• Write the first CLAUDE.md. Short, honest, evolves over time.

End of phase 1: the substrate exists, three to five team members have SSH'd in and made commits, the repository has its first 20 files.

10.02Days 15–45: Content and First Agents

This is where the substrate starts to hold real work.

Content migration:

• Identify the 20–30 documents that the team actually uses (not the 2,000 in Notion). Migrate them. Pandoc plus a small custom script handles Notion-to-markdown conversion at about 80% fidelity; the remaining 20% is manual cleanup (Source: pandoc.org).
• Establish the structure that will hold new work: meetings, projects, ops, knowledge, intel.
• Migrate one project's full documentation as a stress test. If it works for one product, it works for all of them.

First agents:

• Start with the cheapest, most-visible win. For most teams, that is the meeting-summariser or the sprint-tracker. Pick one, ship it, let the team see the value.
• Add the second agent only when the first is reliable. Resist the urge to ship four agents in two weeks.
• For each agent, write the corresponding skill file in .claude/skills/. The skill is the contract; the agent is the executor.
• Set up cron schedules for agents that run on a clock (intel-curator, sprint-tracker).

End of phase 2: the team is using the system daily for at least one workflow. Two or three agents are running. The first PRs from agents have been merged.

10.03Days 46–75: Integrations and Skills

Now the system gets wired into the rest of the company's tooling.

MCP integrations:

• Set up MCP servers for the team's existing tools: Slack, GitHub or GitLab, Linear or Jira, Google Drive (read-only), the team's calendaring tool. Each integration takes a few hours; the value compounds quickly (Source: code.claude.com/docs/en/mcp).
• Wire CI hooks: when a tag is pushed, the release-notes agent runs. When a webhook fires from your build system, an incident agent creates a note.
• Add semantic search if grep-only is insufficient (most teams reach this point around day 60).

Skills expansion:

• By now the team has opinions about how it works. Encode those opinions as skills.
• Run a "skills writing day": pull two senior people for half a day, walk through every recurring operation, write a skill file for each.
• Establish the review process for skill changes. A new skill is a PR; a skill update is a PR. The team learns to read skill diffs.

End of phase 3: the substrate has integrated with the company's existing tools. There are 8–15 skills. There are 4–6 agents. The system is doing visible work daily.

10.04Days 76–90: Handoff and Hardening

The last two weeks are about removing the implementation team's dependency and making the system the team's own.

Handoff work:

• Designate the internal DevOps owner. This person becomes the first responder for the next 6 months.
• Walk the DevOps owner through the full system: server access, backup procedure, restore procedure, common failures, escalation path.
• Write a "DevOps runbook" inside the team-os repository at ops/runbooks/team-os.md. The system documents its own operation.
• Role-specific training sessions: 1 hour for the full team (basic workflow), 2 hours for power users (writing skills, debugging agents), 4 hours for the DevOps owner (operations).

Hardening:

• Backup verification. Restore a backup to a staging server. Confirm the restore works. Do this before you need it.
• Secrets audit. Confirm no secrets are in the repo. Set up the secrets management approach (sops + age for most teams, Vault for larger).
• Permission review. Audit the deny list. Confirm agents cannot do things they should not.

End of phase 4: the implementation team is no longer essential. The internal DevOps owner can run the system. The team is producing real work in the substrate. The wiki is no longer hell.

A note on this timeline: it is a guideline. Two of the three rollouts we have done took 75 days; one took 105 days because the company added a new product mid-rollout and the substrate had to grow with it. The phases are not magic but the sequence is. Substrate before content, content before agents, agents before integrations, integrations before handoff. Skip a step and you pay for it later.

A real budget for a 20-person team. We are going to be specific because most vendor pricing is misleading by omission.

Infrastructure, year 1. A reasonable VPS at Hetzner or IONOS runs €40–€120/month depending on specs. Add €20–€60/month for backups (Hetzner Storage Box, Backblaze B2, or similar). Optional: €40–€120/month for Coder if you need web-IDE access. Total: €1,200–€3,600/year.

Claude Code seats, year 1. Anthropic's pricing for Claude Code Team Premium runs roughly $100/user/month. For 20 people, that is $24,000/year (~€22,400/year). You can also do this via individual subscriptions or pay-as-you-go API usage; for a 20-person team, the seat model is usually cheaper and easier to budget against (Source: claude.com/pricing).

Additional API usage. Even with seats, agents that run on a schedule (intel-curator, sprint-tracker, etc.) accrue separate API costs through the Anthropic API. Realistic for a 20-person team: €1,500–€4,000/year.

Setup, one-time. This is the cost vendors hide. A real Team OS rollout, done correctly, takes 90 days and roughly 60–80 hours of senior engineering plus 40 hours of training and writing. At market rates this is €40,000–€60,000 for the full rollout. You can DIY this if you have the right people, but most 20-person companies do not, and the in-house cost shows up as 0.5–1 FTE for a quarter, which is usually more expensive in lost product velocity than hiring an outside engagement.

DevOps support, ongoing. After handoff, you need someone to own the system. For a 20-person team, this is 0.1–0.2 FTE of a senior engineer's time. At market rates: €6,000–€16,000/year. If you do not have this person internally, an outside retainer is €1,500–€3,000/month.

Total year 1: €71,000–€106,000, with €40,000–€60,000 of that being one-time setup. Total year 2 and beyond: €30,000–€46,000/year recurring.

Compare to a fully-loaded Notion Business plus AI plus maintenance for 20 people at year 2: roughly €25,000–€33,000/year recurring, plus the documentation tax that does not show up on any invoice (estimated 6–10 hours per week of team time spent on maintenance, drift, and re-finding lost documents; at €40/hour blended, that is €12,000–€20,000/year of hidden cost).

The Team OS is not radically cheaper. It is more capable for a comparable cost, and the capability gap widens over time as the substrate accumulates skills and the team's leverage on its own documentation compounds. For some teams that is worth it. For others it is not. The honest framing is: this is not "AI saves you money," this is "AI changes what your 20 people can do."

Is this just Obsidian for teams? No, though Obsidian users will find the substrate familiar. Obsidian is an editor. A Team OS is an editor and a multi-user permission model and an agent layer and a skills layer. Obsidian is a great human interface to the substrate (some team members will use it daily); it is not the substrate itself.

What happens if Anthropic goes down or changes its pricing? The substrate keeps working. It is markdown in git. Agents are an additional layer; if Claude Code becomes unavailable, you lose the automation but you do not lose your knowledge base. You can also point the system at other agentic CLIs (Aider, Cursor in agent mode, open-source alternatives) without rebuilding the substrate. The lock-in is near zero. That is one of the strongest arguments for this architecture compared to Notion.

How do you handle non-technical team members? Three options, in order of how often we use them. First, train them on the basics: tmux, basic editor (Helix or VS Code over SSH), basic git. About 60% of non-technical people can get to fluent in a few days if they are motivated. Second, put Coder on top: a web IDE that gives them VS Code in a browser, file editing without the terminal. Third, for the genuinely uncomfortable, have them keep working in their preferred tool and let an agent sync their notes into the substrate (Google Docs → MCP → markdown, for instance). The third option is friction; we use it as a transitional measure, not a permanent one.

What about regulated industries? A Team OS can be made compliant for many regulated contexts (the GDPR posture is significantly stronger than Notion's, in our reading). For specific compliance regimes (ISO 27001 document control, FDA Part 11 for pharma, certain government classifications) you need either a heavily configured Team OS with explicit compliance work, or a commercial DMS that has been certified for your context. We do not recommend Team OS for primary document control in heavily regulated environments. We do recommend it as a knowledge layer alongside the compliant system.

Can a 50-person team use this? Up to about 35, yes, with the same architecture. Beyond that, the SSH-and-Unix-groups permission model becomes thin and you need to layer something heavier on top (identity provider integration, RBAC at the git host, more formal access reviews). The substrate principle still works at 100+ people; the access layer needs more infrastructure.

What if our team is distributed across timezones? Better than most alternatives. The substrate is async by design. Agents run on a schedule, not on a meeting. The intel-curator runs at 07:00 UTC and the entire team reads it at their morning. The sprint-tracker runs Monday 09:00 local for the lead's timezone, and other timezones see a freshly-summarised state when they wake up. Git's branching model is essentially designed for distributed async work.

How do you handle confidential or sensitive subsets? Two patterns. First, separate repositories for sensitive domains (finance, HR, legal), with their own access control at the git host. They can be referenced from the main repository without being part of it. Second, encrypted files inside the main repository using sops and age: the file is in git, but only people with the right keys can read it. Both work. We use both, for different categories of sensitivity.

If you read this far and recognise your team in the description, the conversation we have in a Garden audit is exactly the one this article is trying to start. We map your actual knowledge flow, identify where the substrate model would help and where it would be a square peg, and either propose a rollout or tell you honestly that a Team OS is not the right answer for you. Most of our audits end somewhere in the middle: parts of a Team OS, integrated with the tools you already have, with a clear plan for what to migrate and what to leave.

Email a@gardenresearch.eu if you want to start that conversation. We respond within a few days and we do not send a deck. We send a question.

This article is part of Garden Research's investigation into how small technical teams can use AI without the hype, the chaos, or the 95% pilot failure rate. We are EU-sovereign by default, we self-host where it matters, and we ship systems rather than slide decks.