Architecture overview

English | 日本語

AI Teams is a Codex Plugin that supplies a product-development operating model, focused Skills, bounded MCP tools, and optional integration components. It is a coordination layer over existing systems, not a replacement for source control, planning, CI, review, deployment, or provider authentication.

This document describes the current accepted system in the present tense. The rationale and agreement history for this documentation architecture is Decision Issue #670.

The diagram policy and the choice to use C4 with complementary behavioral views are recorded in Decision Issue #682.

Current C4 Context view

This view answers one question: where does AI Teams sit relative to its human, execution host, systems of record, optional control plane, and effect providers?

flowchart LR
    human["Human operator<br/>owns intent and privileged authority"]
    codex["Codex<br/>execution host and workspace tools"]
    ai["AI Teams<br/>product-development coordination system"]
    github["GitHub<br/>Issues, Git, PRs, CI, Releases"]
    control["External Control<br/>trusted wake-up and runtime orchestration"]
    providers["External providers<br/>authorized review, communication, deployment primitives"]

    human -->|"requests work and supplies authority"| codex
    codex -->|"loads and executes"| ai
    control -->|"starts isolated work and exchanges bounded state"| ai
    ai -->|"records decisions and delivery evidence"| github
    ai -->|"selects one authorized primitive"| providers

Arrows name the relationship, not unrestricted authority. GitHub and each provider retain their own authentication and effect permissions.

Major components

Component Responsibility Canonical implementation contract
AI Teams core Skill Goal refinement, Bet selection, team shape, evidence interpretation, and replanning Core Skill
Focused Skills Plugin diagnosis, product design, and release management plugins/ai-teams/skills/*
Architecture capabilities Provider resolution and bounded operation gates plugins/ai-teams/capabilities/architecture
Quality MCP Read-only repository inspection and fixed quality-profile execution plugins/ai-teams/mcp
Bounded Control MCP client Planning/status/action transport to external Qoo257/ai-teams-control, which owns queued execution and runtime orchestration plugins/ai-teams/mcp
Repository delivery system Git branches/worktrees, GitHub Issues/PRs, and isolated self-hosted validation Delivery architecture
Human documentation Product intent, accepted architecture, policy, user guidance, and generated reference docs/en and official docs/ja translations

Responsibility model

Documentation  → intent, policy, accepted architecture
GitHub Issues  → decisions, rationale, agreement history, mutable project state
Tests/gates    → mechanically enforceable invariants
Code/config    → actual behavior and reconstructable facts
Plugin docs    → machine-facing execution contracts and task routing

Human architecture links to machine contracts for operational detail rather than copying them. Machine instruction files route agents to the narrowest canonical contract and do not reproduce the human overview.

System invariants

  • One coordinator remains accountable for the Goal, Bet, acceptance, authority, and learning even when specialists are activated.
  • External systems retain their own authentication and effect authority.
  • Missing evidence is unknown, not success.
  • Mutable work state remains in the established tracker and Git/GitHub objects.
  • Repository changes use an Issue-linked isolated worktree and pull request.
  • A merge candidate is accepted only with successful exact-head hosted validation; every absent or unsuccessful result blocks acceptance.
  • Delivery proves implementation, not product outcome.
  • External Qoo257/ai-teams-control owns scheduler, queue, persistence, recovery, worker lifecycle, GUI, and provider-integration runtimes; the Plugin supplies no runtime fallback for those surfaces.

See execution, delivery, and trust boundaries for the major sequences and boundaries.