Governance layers¶

English | 日本語

AI Teams applies the same governance split to itself that its distributed Skill uses for other projects:

Portable AI Teams Skill
        ↓
AI Teams canonical managed-project contract
        ↓
Project-specific rules / Issue or decision record

The portable rule is: AI Teams carries cross-project invariants; each project owns its durable interpretation; a decision remains local until future work must inherit it. The installed Skill's repository stewardship contract is self-contained and does not depend on this site.

Classification audit¶

Governance surface	Classification	Why
Distributed core SKILL.md	PORTABLE	Routes Issue owners through source-of-truth preservation, authority, delivery, verification, and durable-policy promotion without naming a required tracker, language, or layout.
Distributed references/repository-stewardship.md	PORTABLE	Defines the three layers, placement and promotion decisions, explicit overrides, and testing economics for downstream repositories.
Distributed operating, delivery, project-conventions, quality, and testing references	PORTABLE	State cross-project coordination and verification invariants; a target project supplies concrete systems, commands, and exceptions.
AI Teams routing block in AGENTS.md	ROUTING	Loads the canonical AI Teams Skill before repository work. The repository owns the surrounding file, including other Skill/Plugin routes and safety rules.
.ai-teams/project-rules.md	PROJECT-LOCAL	Holds verified repository parameters, scoped extensions, and stricter constraints; it may not weaken or contradict the Skill.
Documentation governance and docs/en / docs/ja	PROJECT-LOCAL	English is canonical, Japanese is an official maintained translation, and MkDocs/Cloudflare Pages are this repository's validated documentation projection.
Architecture documentation and Decision Issues	PROJECT-LOCAL	AI Teams keeps current accepted architecture in this site and rationale/history in GitHub Decision Issues. Other repositories may use a different owner.
Tests, verification_policy.py, quality profiles, CI, and self-hosted validation	PROJECT-LOCAL	They define AI Teams' concrete test commands, gates, workflow identity, and acceptance evidence while inheriting portable artifact-led verification principles.
Plugin release metadata, release-management contracts, and release artifacts	PROJECT-LOCAL	They define this Plugin's versioning, tag, GitHub Release, and publication verification procedure.
Repository layout, capability locations, generated capability reference, and module-size advisory	PROJECT-LOCAL	These are AI Teams placement and maintenance conventions, not a downstream directory or numeric requirement.
Implementation selections, temporary workarounds, migration sequencing, and one-off external conditions	ISSUE/DECISION-LOCAL	They remain in their Issue or Decision record unless a future-work inheritance need promotes them.

This table is an audit, not a second policy database. The named sources remain authoritative for their own rules.

Applying local policy deliberately¶

For managed projects, AI Teams-specific durable guidance belongs in the project-rules owner; the root AGENTS.md retains one bounded AI Teams routing block alongside other repository-owned instructions. Reader-facing documentation governance belongs in this policy, executable verification in scripts and CI, architecture in the architecture site, release procedure in release contracts, and rationale in a Decision Issue. Do not create another layer merely to restate them.

The documented local rules do not change portable semantics. For example, AI Teams' English/Japanese surface, use of GitHub Issues, and advisory module size signal are local implementations of portable language, system-of-record, and cohesion principles. They create no downstream migration requirement.

When AI Teams changes a portable Skill invariant, the release's semantic change manifest records its policy identifiers and downstream compatibility action. An AI Teams-only policy change is not a downstream Skill requirement. A project that overrides a portable default should name the relevant policy identifier, scope, reason, and authority so it can assess a future manifest without receiving additional authority from that record.

Persisted settings¶

AI Teams may read one account-owned ~/.codex/ai-teams/settings.json and one repository-owned .ai-teams/project-policy.json. The user file contains only reviewed defaults; the project file contains portable repository conventions and the existing release overlay. Current explicit instructions outrank project policy, project policy outranks user defaults, and product defaults are last. Neither file stores credentials, provider availability, absolute project paths, work state, or effect authority. Missing files preserve current defaults; malformed, unsafe, unknown-version, or authority-broadening documents are rejected. Removing the new file restores the prior defaults and never changes the security-only meaning of an execution-policy file.

Delivery readiness after adoption¶

A valid managed-project manifest and a completed semantic adoption audit do not by themselves prove that Issue delivery can finish. The project-lifecycle route assesses repository-owned focused, required, pre-push CI, exact-head hosted validate, pull-request acceptance, language policy, repository protection, and packaging/install surfaces separately. Existing reviewed mechanisms remain primary and can be mapped without replacement.

When a supported GitHub repository has complete readiness commands but lacks a workflow or pull-request template, the tool can preview at most those two absent paths. Applying requires the exact preview digest and reads every write back. Unknown stacks, collisions, missing commands, and malformed mappings stay delivery_not_ready with zero provider or settings effects; they require a repository-owner decision instead of receiving AI Teams source-repository tooling.