Skip to main content

Team OS Overview

Team OS is a local operating system for AI product work in Codex and Claude Code. It installs six role skills, but the larger value is the runtime that preserves context between sessions, keeps handoffs structured, and turns product work into auditable state instead of disposable chat history.

The runtime lives in your repo under .team-os/. It records initiatives, tasks, design artifacts, implementation evidence, FE finish reviews, QA matrices, learnings, PIP ledger entries, and sprint archives. The AI roles use that state to make better decisions; the shell commands keep the state consistent.

Why the runtime matters​

Long product work fails when context disappears. A normal chat can explain a plan, implement a slice, and test it, but the next conversation may not know which assumptions were accepted, which UI artifact FE used, which bug reopened a task, or whether QA tested after the latest code change.

Team OS solves that by making workflow memory programmatic:

  • stable ids for initiatives, tasks, bugs, artifacts, evidence, and learnings
  • deterministic state mutation through team-os commands
  • validation rules that catch missing evidence and stale references
  • sprint workspaces that keep active artifacts close to the current delivery slice
  • archived sprint artifacts that preserve history without loading every old detail into current context
  • PIP scores and ledger entries that let roles improve from repeated mistakes

AI vs runtime responsibilities​

Team OS deliberately splits the work.

The runtime can do deterministic operations:

  • initialize or onboard a repo
  • create, move, reopen, list, and show initiatives and tasks
  • assign stable ids
  • enforce required fields and completion gates
  • sync sprint sequencing
  • route UI, FE, and QA artifacts into sprint workspaces
  • archive completed sprint evidence
  • validate cross-file contracts
  • produce reports and next-handoff recommendations

The AI roles do judgment-heavy work:

  • decide whether an idea is worth building
  • slice a validated initiative into the right tasks
  • design the product experience and system rules
  • choose implementation architecture
  • polish a UI against design intent
  • decide regression depth, write tests, and judge ship confidence

This is the core design principle: scripts preserve structure; AI applies judgment.

What you get​

  • CEO role for opportunity scoring, product framing, and go / partial / defer / kill decisions.
  • Product role for milestone planning, task slicing, bug triage, sequencing, and QA expectations.
  • UI role for design systems, screens, flows, components, current-system audits, and artifact refs.
  • Code role for implementation, architecture decisions, regression watch areas, and technical learnings.
  • FE role for finish-quality audits, responsive polish, accessibility, interaction states, and QA watch points.
  • QA role for reusable test matrices, automation and E2E coverage when warranted, bug filing, reopen decisions, and ship confidence.
  • Team OS handoff helper for read-only next-role selection.
  • team-os low-level commands for deterministic state control, scripting, validation, and recovery.

Normal loop​

team-os init
team-os validate
team-os report
team-os next

Then use the role returned by team-os next.

$ceo evaluate
$product plan
$ui task
$code task
$fe task
$qa task

As work moves through the loop, each role writes evidence back through runtime commands. That evidence becomes the next role's context and the validation system's source of truth.