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, bounded operation gates, and optional non-authoritative repository understanding	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
Bounded specialist tasks	Opt-in Control Lite task ownership and receipts; Codex executes and stops one read-only task; provider Decisions determine impact	Specialist runtime
Repository delivery system	Git branches/worktrees, GitHub Issues/PRs, and isolated self-hosted validation	Delivery architecture
Linear planning adapter	Organization/team-bound Initiative, Project and Issue operations with external-identity receipts; Linear owns authentication and records	Linear contract
Jira and Confluence adapters	Tenant/Project-bound Jira field/workflow operations with exact readback and receipts; separate page reads retain native Confluence attribution without planning persistence	Jira contract
Human documentation	Product intent, accepted architecture, policy, user guidance, and generated reference	docs/en and official docs/ja translations
Evaluation evidence	Family-scoped fixtures, selected baselines and immutable history with explicit consumers; separate from production routing and the source hash inventory	Evaluation artifact governance

Responsibility model¶

This is a navigation summary, not a second definition of documentation authority. Specification governance owns the detailed allocation and promotion rules.

Specification → current accepted behavior and durable invariants
GitHub Issues → active changes, decisions, rationale, and mutable project state
Tests/gates   → enforceable evidence
Code/config   → implementation 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.
• Optional Graft repository graphs remain disposable retrieval state; exact source and policy contracts remain authoritative.
• Missing evidence is unknown, not success.
• Mutable work state remains in the established tracker and Git/GitHub objects.
• Code, configuration, packaging, security, CI, and test changes use an Issue-linked isolated worktree and pull request. Repository policy may allow a narrow docs-only L1 branch and PR without a new Issue.
• 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 its service, scheduler, worker lifecycle, GUI and integrations. Explicit Control Lite commands own their registered local coordination only; they start no background service and never silently replace an unavailable external Control operation.

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

Live GitHub portfolio assembly belongs to work-item-search-projection: the existing GitHub delta adapter and disposable cache feed the Issue graph, with a fresh open inventory and exact closed-dependency reads. Unknown evidence is explicit; neither ranking nor the cache owns execution authority. There is no new scheduler or authoritative backlog.

Linear/Jira portfolios reuse that same graph and result renderer through their accepted planning adapters. Explicit workflow-state partitions and native description metadata preserve provider identity; resumable native pages stage separately and atomically promote normalized records plus the shared index after a complete scan. Goal/team/component partitions use the existing bounded selector. Native descriptions are cached, credentials are not; a failed external read never selects GitHub.