Getting started¶

English | 日本語

Requirements¶

• Codex with Plugin support
• Git
• CPython 3.11, 3.12, 3.13, or 3.14
• access to each repository and external system placed in scope
• the recommended GitHub Plugin, or an authenticated gh fallback for supported operations

Plugin installation bundles its Python modules and uses only the CPython standard library; it does not install Python packages on first use. python3 and git are required. Authenticated gh is checked only when a selected GitHub operation needs the CLI fallback. Control and the GitHub Plugin are optional integrations, while a project's build and test dependencies remain project-owned readiness concerns. Run python3 <plugin-root>/skills/plugin-diagnostics/scripts/runtime_audit.py for a credential-safe dependency readback; it never installs or authenticates anything.

Runtime assurance¶

AI Teams defaults to Codex workspace-write with never approvals. If you intentionally run Codex with danger-full-access or unrestricted, opt in once for your OS account at ~/.codex/ai-teams/execution-policy.json:

{
  "schema": "ai-teams-user-execution-policy/v1",
  "mode": "trusted-full-access",
  "provider": "codex",
  "responsible_owner": "local-user",
  "external_containment": "dedicated OS account"
}

The account must own that file and its .codex and ai-teams parent directories; none may be a symlink or group/world writable. Trusted full access keeps Issue, branch, registered external worktree, runtime cwd, pull request, and validation checks, but reports filesystem isolation as unverified. Remove the file to restore strict mode immediately. A repository may require strict mode, but repository content cannot enable trusted full access for a user.

Execution environment¶

AI Teams separates delivery policy from the runtime that performs Git, tests, and GitHub operations. Source work starts only after workspace readiness returns status: ready for the exact repository, Issue, branch, revision, and selected runtime. Creating a worktree alone is not readiness evidence.

Use a dedicated OS account or disposable machine/container for Codex. Keep the primary checkout as a read-only coordination surface and edit only the registered Issue worktree. Give the runtime the minimum credentials needed for an authorized operation; keep unrelated host files and ambient credentials outside it.

The supported flow resolves the repository-owned worktree and readiness contracts, verifies one explicitly selected local or container provider, and claims the exact Issue execution context. Focused checks and local pre-push verification run there. GitHub still owns push, pull request, hosted validate, merge, and remote-branch deletion evidence. A ready result grants none of those effects and grants no release, deployment, settings, secret, or destructive authority.

Responsibility	Owner
Goal, Issue, delivery, and acceptance semantics	AI Teams
Worktree and runtime process effects	Selected local host or container runtime
Runtime and worktree state	OS account and Git repositories
Credentials	User and selected provider
GitHub reads and writes	GitHub Plugin or authenticated gh fallback
Existing authority	Issue, worktree, verification, PR, and release contracts
New runner or installer lifecycle	A separately registered component; not the core Skill

Current readiness support is deliberately narrower than a complete runner:

Path	Current support	Boundary
Local provider	Linux-native user-state filesystem	Uses one supplied Python executable; installs nothing
Container provider	Already-present immutable image ID	No pull, network, credentials, or implicit fallback during readiness
AI Teams development image	Reproducible linux/amd64 local build	Readiness image only; not a durable runner or hosted-CI image
Managed consumer	Current repository-owned managed-project manifest	Consumer owns all five readiness commands
Native package installer	Fedora 42/RHEL 9 noarch RPM source plus manual transaction	No package repository or implicit privileged install
Reference delivery runner	Optional immutable-image launcher	Provider operations and hosted acceptance remain independent

After completing the repository's locked setup, run the packaged preparation command with fresh host-capability evidence and its worktree policy:

python3 <ai-teams-skill-dir>/scripts/prepare_workspace.py \
  --root <repository-root> --repo <owner/repository> --issue <number> \
  --policy <repository-worktree-policy.json> \
  --host-capability-evidence <fresh-host-evidence.json> \
  --python <absolute-python-executable>

For the explicit container path, provision an approved image first. The source repository supplies a bounded local build:

python3 scripts/build_workspace_readiness_image.py \
  --root <absolute-repository-root> --runtime <absolute-container-runtime>

Pass the returned immutable image_id with --provider container, the absolute container runtime, and the Python path inside the image. Use --preflight ci only when the repository contract selects it; it never replaces exact-head hosted validate.

Treat blocked as an actionable handoff, not permission to switch providers or install dependencies implicitly. Correct the declared runtime, manifest, identity, or freshness problem and obtain new readiness. Do not reuse evidence after five minutes or a revision change. Missing images cause no pull/build, failed probes start no candidate edit, and uncertain GitHub effects receive exact readback without blind retry.

Optional reference runner and native package¶

When an existing isolated Codex host is unavailable, build the optional image from packaging/reference-runner/Dockerfile, inspect its immutable image ID, and install the launcher from the same accepted source commit:

python3 scripts/reference_runner.py install \
  --source-root <accepted-clean-source-root> \
  --prefix <absolute-install-prefix>
python3 <absolute-install-prefix>/bin/ai-teams-reference-runner verify \
  --prefix <absolute-install-prefix>

Fedora 42 and RHEL 9 are the first native-package targets. Build the noarch RPM from packaging/reference-runner/ai-teams-reference-runner.spec; install only the RPM and checksum/SBOM set from the same accepted commit. This project does not configure a package repository.

Provision a dedicated Docker network separately, make the Issue worktree ready, then invoke one immutable image. Optional private, user-owned credential directories are mounted read-only in argument order below /run/ai-teams/credentials/:

ai-teams-reference-runner run \
  --runtime /usr/bin/docker \
  --repository owner/repository --issue 123 \
  --worktree /absolute/registered/123-delivery \
  --image sha256:<64-hex-image-id> \
  --network ai-teams-delivery-123 \
  --credential-dir /private/codex-home \
  --credential-dir /private/gh-config \
  -- env CODEX_HOME=/run/ai-teams/credentials/0 \
       GH_CONFIG_DIR=/run/ai-teams/credentials/1 \
       codex exec '<bounded delivery request>'

The launcher starts at most one container. It never creates or pulls an image, creates a network, obtains credentials, retries a failed command, or claims hosted acceptance. Only the exact worktree and its Git common directory are writable; the Docker socket, host home, and other repositories are absent.

Upgrade by running install from newly accepted source and verify afterward. A failed transaction restores the previous exact files. uninstall refuses changed artifacts and removes only its three digest-matching files:

ai-teams-reference-runner uninstall --prefix <absolute-install-prefix>

Repositories, credentials, images, networks, and unrelated prefix files remain. Unsupported transitions are an operator handoff, not recursive-delete authority.

Install¶

The recommended reviewed prerelease is v0.30.0-rc.1, published from exact commit a6a2eca2a6819ed29d1105ac7f23cb0faa27d5e4. Review the linked Release and commit, then install that immutable 40-character commit:

AI_TEAMS_COMMIT=a6a2eca2a6819ed29d1105ac7f23cb0faa27d5e4
codex plugin marketplace add Qoo257/ai-teams --ref "$AI_TEAMS_COMMIT"
codex plugin add ai-teams@ai-teams

Do not replace the exact commit with main or another moving ref. A later release should be installed only after reviewing its own immutable tag and 40-character commit.

Enable AI Teams only for selected projects¶

Codex owns the Plugin switch. After installation, edit its existing table in ~/.codex/config.toml so the default is disabled:

[plugins."ai-teams@ai-teams"]
enabled = false

Add the following to .codex/config.toml at the root of each project you explicitly choose to enable:

[plugins."ai-teams@ai-teams"]
enabled = true

Preserve other settings and avoid duplicate tables. Codex must also trust the project before it reads that override. Leave unselected projects without an enabling override; keep this setting out of a shared parent workspace. A tracked override follows that repository's worktrees, subject to their host trust checks. Installation, project enablement, management/readiness, feature opt-ins and permission for external effects remain separate.

Finish or cancel active work and start a fresh Codex session after changing these values. To disable a project, set its override to false and restart; removal alone works only when the effective default remains false. Do not resume old AI Teams instructions or invoke cached scripts as a workaround. Verify the effective cwd configuration and Skill/MCP/Hook inventories; a global installed/enabled listing does not prove a project's effective state. Recheck after installation or update because host-managed activation can change.

The canonical native activation contract owns setup, migration and the bounded installed-host smoke. The Plugin introduces no duplicate activation flag in .ai-teams/managed-project.json or settings.json.

Review project setup¶

Start a fresh session in the enabled project. Use $ai-teams setup to review a minimal Project profile, proposed file diffs, readiness command candidates and missing capabilities. It preserves existing Issue templates and offers an optional feature, bug and decision starter review. The proposal changes no files and runs no repository commands. Review each stage before using its existing adoption or delivery-readiness apply owner; re-plan after each applied stage.

Plugin installation and Project readiness are reported separately. A workflow file or configuration is not proof of successful CI, an authenticated provider, deployment or measured outcome. Optional integration onboarding retains the provider-owned authentication and installation approval flows.

For the same read-only proposal from the installed CLI:

python3 <ai-teams-skill-dir>/scripts/project_setup.py \
  --root <repository-root> --repo <owner/repository>

Use a clean committed repository. --expect-revision can reject a stale commit; --readiness-contract and --equivalents reuse existing owner schemas. Supply tracked relative --evidence-source or --deployment-request documents to check their configuration without connecting or dispatching. Missing runtime checks or integrations remain degraded/unknown, with the next owner action shown in the proposal.

Optional Issue forms¶

For a repository without suitable forms, the starter includes portable metadata, outcome, evidence, scope, stable acceptance IDs and verification prompts. Choose the optional step after reviewing local instructions, existing templates, tracker, language and labels. Declining changes no files. The issue_starters part of the setup result contains a complete review_input; save and complete that object as a temporary review file. It is not another project configuration.

python3 <ai-teams-skill-dir>/scripts/issue_starters.py plan \
  --root <repository-root> --repo <owner/repository> --review <review.json>

Review the exact diffs, then use apply with the same arguments and --accept-digest <digest> in the adoption Issue worktree. Re-plan after other adoption stages change the repository. At most three forms and one missing chooser configuration are created. Existing or modified files are preserved; unknown policy or overlapping forms stop the write. Identical repeats change nothing. A partial failure reports the created paths and retains them for exact repository-owned reconciliation, without automatic deletion or retry.

The repository owns the accepted files in .github/ISSUE_TEMPLATE. Customize the reviewed form text and existing labels, including required local fields; configured companion summaries are included once for browser and CLI creation. Later Plugin versions do not overwrite local changes. Remove or revert the forms through normal repository review. The baseline records the GitHub schema sources and its review date; setup never downloads mutable standards. See the starter contract for the supported form subset, evidence inputs and recovery boundary.

Update an exact-ref installation¶

Codex's generic marketplace refresh does not advance a marketplace pinned to an immutable commit. Keep the pin: detect an available release with the packaged plugin-diagnostics/scripts/update_check.py, review that Release and its exact 40-character commit, and then run the packaged updater from a stable directory outside the marketplace checkout:

python3.11 <plugin-diagnostics-skill-dir>/scripts/update_check.py

python3.11 <plugin-diagnostics-skill-dir>/scripts/marketplace_update.py \
  --target-revision <40-character-reviewed-commit> \
  --target-version <manifest-version> \
  --target-release <vMAJOR.MINOR.PATCH-or-RC> \
  --preflight-only

The preflight validates current and target version, release, ref, and provenance without changing the marketplace or Plugin. After granting separate authority for that exact update, rerun the same command without --preflight-only. The bounded updater replaces the pinned marketplace, reinstalls ai-teams@ai-teams, reads the result back, and reports updated, rolled-back, rejected, or unresolved. Do not retry an unresolved result.

Confirm status: updated and that active_revision, active_version, and active_release match the reviewed target. Then start a new Codex session and use the installed plugin-diagnostics Skill to run the explicit update diagnostic and a representative repository inspection. Codex's supported Plugin surfaces and new-session behavior are described in the official Plugin documentation; AI Teams' exact-ref safety and updater behavior are defined by the packaged update contract.

To roll back, review the previous immutable Release and run the same updater with its exact commit, manifest version, and Release tag. Verify the restored identity and start another new session. Never move or reuse a published tag, switch the marketplace to main, hand-edit Codex configuration, or edit the installed cache.

Use¶

Ask Codex to use AI Teams for product direction, discovery, planning, Issue delivery, repository adoption, status, semantic review, or recovery. The Plugin chooses the smallest applicable workflow and keeps material state in the project system of record.

Plugin installation alone does not start a service, deploy anything, alter a marketplace, or grant access to external systems.

Local GitHub CLI help can use the exact command gh pr merge --help or the existing gh help pr merge form. The AI Teams Hook still checks the current Issue execution context; refresh workspace readiness if that context is missing or expired. Extra arguments or shell combinations receive no new help exemption. Older installed versions may reject the first form; use gh help pr merge until a corrected Plugin is explicitly installed. Source PR acceptance alone does not activate a new installed Hook.