Team knowledge

A team includes the AI agents working alongside its people, and the knowledge they all draw on. Both live as optional sections in the same teamapi.yml document as everything else:

Section	What it is
`agents[]`	AI assistants treated as first-class team participants — provider, model, role, capabilities, permissions.
`memory[]`	Persistent organizational memory: architecture decisions, conventions, lessons learned, recurring issues.
`specifications[]`	Specification-driven-development artifacts — requirements/design/tasks/acceptance criteria, with a lifecycle, reviewers, approvals, and linked PRs/issues.
`steeringDocuments[]`	Coding standards, API conventions, security guidelines, architecture principles — inherited organization → team → project by walking the existing `platform` team-reference chain.
`prompts[]`	A version-controlled, renderable prompt library (`{{variable}}` templating, with history).
`playbooks[]`	Ordered operational procedures — incident response, release, onboarding — with required roles and automation hooks.
`policies[]`	Machine-readable governance (PR requirements, required approvals, security/dependency policy) for external automation to enforce.
`knowledgeBase[]`	ADRs, FAQs, meeting notes, runbooks, design docs.
`workflows[]`	Process state machines (e.g. testing → approval → deployment → announcement), independent of any particular CI/CD system.
`sessions[]`	A record of AI collaboration sessions: objective, prompts used, artifacts produced, decisions made.

Backward compatible by design. Every section is optional, so existing documents keep validating without migration. Like the rest of the toolchain, these sections are edited in git and exposed read-only—never POSTed.

A worked example#

Agents follow the same team boundaries as services. In examples/acme-org, platform-payments runs a five-agent fleet (architecture-reviewer, test-generator, security-scanner, docs-writer, compliance-auditor). Each agent has a narrow enough scope that three can review the same OAuth pull request in parallel without contradicting each other; memory/conways-law-for-agents records why that split replaced a single do-everything agent. stream-onboarding, the only team touching raw KYC data, carries a policies/no-agents-on-applicant-pii entry and no agents[] at all. Its GET /teams/stream-onboarding/agents response is therefore a documented [].

Context bundles#

POST /context (or the get_context_bundle MCP tool) takes a goal such as { "goal": "Implement OAuth" }, optionally scoped to one teamId. It returns the matching entries from those sections along with the scoped team's related teams, members, and services. Ranking uses keyword overlap, and each hit includes the matchedTerms behind its score. One call gives an assistant the task-specific part of the graph.

flowchart LR
  goal["Goal + optional team"] --> bundle["Context bundle"]
  bundle --> knowledge["Relevant knowledge"]
  bundle --> ownership["People and services"]
  bundle --> seams["Cross-team seams"]

Cross-team seams#

It also returns seams[], listing every pair of teams spanned by the matched entries. Each item includes the declared interaction mode, or undeclared: true when neither team declares an edge to the other. Without that list, a scoped bundle can make a cross-team goal look as though it belongs to one team. An undeclared seam warns that the work is crossing a line nobody wrote down.

Knowledge graph#

GET /knowledge-graph, GET /knowledge-graph/:nodeId/traverse, and the matching MCP tools link every team, person, agent, and document by ownership, role, team topology, and resolved cross-team $ref edges for visualization or traversal tooling to consume.

One interface for every resource#

Each section gets the same read-only REST shape — GET /<plural>, GET /teams/:id/<plural>, GET /teams/:id/<plural>/:resourceId, e.g. /teams/platform-payments/prompts/code-review — plus a matching list_*/get_* MCP tool pair, and all of them are covered by GET /search?q=. POST /teams/:id/prompts/:promptId/render (or render_prompt) fills a prompt's {{variable}} placeholders. Field-by-field reference: docs/spec/teamapi-extended-v1.md.