@jgalego/teamapi

@jgalego/teamapi

Who owns this? Just curl your org.

Write your org as Team API as Code — one teamapi.yml per team declaring services, roles, members, interactions and cognitive load, reviewed in pull requests and versioned in git — and teamapi turns it into organigrams, org-health checks, a REST API with a live dashboard, an MCP server for LLM assistants, a chat persona per team, trend reports over your git history, and config for tools like CrewAI and Backstage.

Install

npm install -g @jgalego/teamapi

Quick start

teamapi init my-org                       # scaffold a whole org repo: config, CI, first teams
teamapi validate examples/acme-org
teamapi render examples/acme-org --scope topology
teamapi serve-api examples/acme-org --port 3000   # REST API + dashboard at /dashboard
teamapi serve-mcp examples/acme-org       # point Claude Desktop/Code at this command
teamapi chat examples/acme-org --team stream-checkout --ask "is payments overloaded?"

<patterns> in every command accepts a file, a glob, or a directory to auto-discover every teamapi.yml/.yaml under it — or comes from teamapi.config.yml so the everyday commands take no arguments at all.

Commands

Author and validate

Command	Purpose
teamapi init [dir]	Scaffold a whole org repository: config, CI workflow, first teams
teamapi scaffold <id> --type <type> --out <file>	Generate one minimal, schema-valid document
teamapi validate <patterns...>	Resolve every $ref transitively; report unresolved refs and conflicts
teamapi fmt <patterns...> [--check]	Rewrite documents into canonical form (comment-preserving)
teamapi migrate <patterns...>	Bring documents up to the latest teamApiVersion
teamapi schema	Print the document JSON Schema for editors and CI

Check the org's shape

teamapi assess <patterns...> combines every check into text, JSON, HTML or SARIF, with optional baseline comparison.

Command	Purpose
teamapi gaps <patterns...>	Report accountability holes between teams — unowned event contracts, vacant seats, unowned agents
teamapi policy <patterns...>	Check declared policies[], and report the ones nothing enforces
teamapi topology <patterns...>	Report Team Topologies design smells — overrunning collaborations, inverted platform flow
teamapi shadow-ai <patterns...> --scan <dir>	Report AI adoption found in repositories against what teams declare in agents[]

The individual checks take --format text|json|sarif. assess also supports a self-contained HTML report and --state <file> for stable new/resolved finding comparison. See the evaluation guide for a bounded adoption workflow.

See and track it

Command	Purpose
teamapi render <patterns...> --scope topology|hierarchy|context-map|org-hierarchy	Render a Mermaid/DOT diagram
teamapi diff <patterns...> --against <ref>	Diff the resolved org graph against a git revision
teamapi history <patterns...> --period week	Trends over git history: cognitive load, agent adoption, supervision, churn
teamapi digest <patterns...> [--webhook <url>]	Gaps/policy/topology findings and what moved since last run, to Slack or email

Serve it

Command	Purpose
teamapi serve-api <patterns...>	REST API + dashboard; opt-in --metrics, --mcp, --embeddings, --propose-to, --watch
teamapi serve-mcp <patterns...>	MCP server over stdio, for Claude Desktop/Code
teamapi chat <patterns...> --team <id> [--ask <q>]	Chat as a team or member — Anthropic or any OpenAI-compatible endpoint

Connect it to everything else

Command	Purpose
teamapi import github-org|backstage|okta|slack|csv <arg> --out <dir>	Bootstrap documents from the systems an org already has
teamapi generate crewai|backstage|paperclip|codeowners|agents-md|port|otel <patterns...> --out <dir>	Generate config for another tool from the org graph
teamapi apply <patterns...> --org <github-org> [--yes]	Reconcile GitHub teams/memberships (plan by default)
teamapi apply-to slack|okta|pagerduty <patterns...> [--yes]	Reconcile membership in Slack usergroups, Okta groups, PagerDuty
teamapi slack-sync <patterns...> [--yes]	Set each declared Slack channel's topic to name the owning team
teamapi okta-drift / pagerduty-drift / paperclip-drift	Read-only drift reports against live systems
teamapi doctor github|slack|pagerduty|okta|paperclip	Check a live integration: auth, the read, field shapes, pagination

See teamapi.dev (or the main README) for the full walkthrough, rendered diagrams, REST/MCP reference, and the extended spec.

The TeamAPI toolchain

One org graph, seven doors into it — install only the ones you need:

Package	What it does
@jgalego/teamapi (this package)	The CLI — validate, diagram, check, import, reconcile, serve and chat with your org
@jgalego/teamapi-core	The engine: $ref resolution, the org graph, scoring, checks, diagrams, generators
@jgalego/teamapi-schema	Zod schemas and TypeScript types for the extended spec
@jgalego/teamapi-rest-api	REST API, live dashboard, Swagger UI, Prometheus metrics
@jgalego/teamapi-mcp-server	The org graph as MCP tools for LLM assistants
@jgalego/teamapi-chat	Chat as a team or member — Anthropic or any OpenAI-compatible endpoint
@jgalego/teamapi-backstage	Live Backstage catalog entity provider

Docs, examples and the extended spec: teamapi.dev · github.com/JGalego/TeamAPI

License

MIT