How I built a Team OS

Most teams I've been on share the same recurring tax. The same questions get re-asked every week. Context lives in heads, in Slack threads, in scattered docs. A PM, an engineer, and a CS lead walk into the same meeting with three different pictures of the same situation.

I got tired of that. So I built a Team OS — a shared context layer that the team reads, that AI agents can read, and that the systems we already use feed into automatically. This is how I did it, what changed when I actually started running real material through it, and why I think most teams would benefit from one.

A note before we start: I tried this on myself first. My personal knowledge vault has been running on this pattern for months. If a librarian-curated Markdown system works for one person juggling a dozen projects, it works for a team.

---

1. Why I built this in the first place

Context drift looks like this. A teammate asks, "how does this account actually use our product?" Someone half-remembers. Someone else has a Slack thread from three months ago. Someone pulls up a deck that's two versions stale. By the time the meeting starts, everyone is operating from a slightly different version of the truth.

Now multiply that by every account, every metric, every commitment, every integration. Multiply it by every new person who joins and has to rebuild that picture from scratch. The cost isn't dramatic. It's the slow tax that eats your team's hours every week.

I wanted one place a teammate could go and see the same picture as everyone else. Not a SharePoint dump. Not a wiki that no one updates. A curated context layer that an AI agent can read directly, that the team can read in a clean UI, and that updates itself from the systems we already use.

---

2. The shape — four moving parts

A Team OS, in my initial version, is four pieces working together. The shape matters more than any of the parts.

A vault. Markdown files in a private git repo. This is the source of truth. Humans don't have to touch git; only the librarian does. Everyone else reads a rendered view.

Ingest. Scheduled scripts that pull from the systems the team already uses — meeting transcripts, ticketing systems, watched spreadsheets, internal APIs — and write the raw output into the vault's raw/ folder. The librarian's job is curation, not transcription.

Compile skills. Small, reusable workflows (I use Claude Code skills) that turn raw drops into curated articles. One per source type, plus a few cross-cutting ones for audits and one-pager briefs.

A UI. A static site that reads the vault and renders it as a polished, searchable, link-rich app. The team's only surface. They never see Markdown, never touch git.

The split that makes this work: the vault is the data, the UI is just a renderer. Agents and humans both read the same Markdown. Nothing has to be re-modeled to be readable in two surfaces.

Under the hood — what the folders actually look like

If you want to see the bones, here's the tree as it stands today:

team-os/
├── CLAUDE.md                    # librarian rules + conventions
├── README.md                    # 5-min onboarding for new librarians
├── memory/
│   ├── constitution.md          # non-negotiables: definitions, lineage, sensitivity
│   ├── data-model.md
│   └── information-architecture.md
├── schemas/                     # JSON schemas for frontmatter + entity data
├── wiki/                        # curated content (UI reads this)
│   ├── _master-index.md
│   ├── catalog/                 # cross-cutting reference layer
│   │   ├── metrics/
│   │   ├── data-sources/
│   │   ├── integrations/
│   │   ├── stakeholders/
│   │   └── workflows/
│   └── accounts/{slug}/
│       ├── _index.md
│       ├── discovery/
│       ├── evidence/
│       ├── issues/
│       ├── operational/
│       └── people/
├── raw/                         # inbox (ingest scripts write here)
├── output/                      # generated briefs, exports, snapshots
├── skills/                      # compile-account, scrape-gong-briefs, slack-digest, etc.
├── evals/                       # tiny fixtures per skill
└── ui/                          # static site (Next.js)

Every file has YAML frontmatter — owner, last-reviewed, status, sensitivity, source links. That's how the audit skills find stale content. It's also how the UI builds tag filters and timelines without any extra code.

---

3. The decisions that actually matter for V1

Markdown, not a wiki tool or shared Drive. Agents can read Markdown directly, no scraper, no API rate limit. Diffs are readable. Multiple pipelines can write to it without fighting.

Git, not a shared Drive folder. Version history. Librarian-only access. The UI can pull the repo as static input. "Anyone can edit" is a maybe-for-later point, not initially.

Librarian-only writes, team-read-only UI. This is a design choice knowing most team members will need to read and get value first, before contributing.

Pre-fetch and cache data, don't call it at runtime. The UI reads the cached file. Static stays static. Agents can reason over the cached data alongside everything else. I gave up freshness; I got resilience, speed, and a UI that doesn't need a backend.

Manual dump first, automate later. Don't build pipelines for content you haven't curated yet. Compile the first few accounts by hand. Watch where the pain is. Then automate the painful sources, not the easy ones.

That last one matters more than it sounds. I'll come back to it in the next section, because I ended up violating it in a useful way.

---

4. How it actually got built — anchored in the jobs that kept hurting

Customer context. To automate customer research, I built a company-research skill — give it an account name, get back a structured brief: business context, structure, recent news, named stakeholders. That alone gives the foundational company context for any customer.

Getting at what we'd already heard from the customer. Meeting recordings sit in Gong. Gong's Account AI had already synthesized every email and call into topic-level briefs — but you have to hover-click-expand through accordion sections one by one to read the evidence. So I built a headless-browser scraper that drives Gong on my behalf — hovers each section, expands the sources, walks every "Show N more" button, captures source text verbatim (dates, names, direct quotes) into the vault. Unattended, two minutes per account. Lesson: when a tool is already doing the synthesis, harvest it. Don't rebuild it.

The question bank came out of doing that work. While extracting briefs I noticed the same questions kept showing up across every account — variations of why did they buy, what's their measurement scorecard, what does their workflow look like. Sales asks them. CS asks them. PM asks them in renewal prep. So I built a question pack: the pack runs against Gong's Ask-Anything feature and dumps a structured Q&A per account. Lesson: the question is the unit of reuse. Capture questions, not just answers.

Slack was a different shape of pain — all the signal was buried in all the noise. A few channels — the account-specific ones, the eng-support channel — held the actual issues, decisions, and commits. So I built a tiered Slack digest. Each account gets a small _slack-sources.md file listing channels in Tier 1–3 (always scanned) and Tier 4–5 (only when something specific is in play). The skill pulls messages and classifies each thread as a decision, blocker, commit, sentiment, risk, resolution, or noise. Noise drops on the floor. Signal gets filed automatically into the account's evidence/, issues/, or commits.md. Lesson: when the source is noisy, build a classifier, not a search.

Then I wrapped everything in one command. compile-account {name} fans out — company research, Gong scraper, Slack digest, plus a Customer 360 layer that pulls CRM-side context — runs them concurrently, gates on schema validation, and folds the results into a single account folder. One prompt turns an account name into a complete brief. The same brief structure works for a Sales kickoff, a CS check-in, or a PM prep for the next review. Lesson: orchestrators come last, not first. They earn their place only after the underlying skills are solid enough to compose.

Once accounts had structured data, the dashboards built themselves. Product teams live on a calendar — weekly business reviews, monthly business reviews, quarterly business reviews. Every cycle, someone burns a week scrambling for metrics: adoption, ticket themes, customer health, time-to-key-milestone, escalations. I built a dashboard layer inside the UI that pulls these directly from the structured account data — already cut by account, by week, by month, by quarter. A PM walking into a WBR has the picture already drawn. Lesson: dashboards are downstream of clean structured data. Don't build them until the upstream is real.

What I'd do differently. I overbuilt the per-account template before the first real compile — eight flat files. The first compile broke it. The material wanted nested folders (discovery/, evidence/, issues/, operational/, people/). I should have started with one account, no template, and let the structure emerge. Lesson: templates are downstream of one real compile, not upstream.

---

A closing line, and a warning

Context drift is the binding constraint on team velocity. A Team OS is how you stop paying that tax.

But it'll be smaller, scrappier, and more iterative than the plan you write before you start. The shape that ships isn't the shape you sketched. That's not a bug — it's the point. The work teaches you what the shape needs to be.

---

Tools I leaned on