はじめに¶

English | 日本語

要件¶

• Plugin 対応の Codex
• Git
• CPython 3.11、3.12、3.13、または3.14
• 対象に含める repository と external system への access
• 推奨 GitHub Plugin、または対応 operation 用に認証済みの gh fallback

Plugin installation は Python module を同梱し、CPython standard library のみを使います。 初回実行時に Python package を install しません。python3 と git は必須です。 認証済み gh は、選択した GitHub operation が CLI fallback を必要とするときだけ確認します。 Control と GitHub Plugin は optional integration であり、project の build/test dependency は project-owned readiness として分離されます。credential-safe な dependency readback には python3 <plugin-root>/skills/plugin-diagnostics/scripts/runtime_audit.py を実行してください。 この診断は install も authentication も行いません。

実行時の保証レベル¶

AI Teams の既定値は、Codex の workspace-write と approval never です。 Codex を意図的に danger-full-access または unrestricted で使う場合は、OS account ごとに一度だけ ~/.codex/ai-teams/execution-policy.json で opt-in します。

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

この file と親の .codex、ai-teams directory は同じ account が所有し、 symlink や group/world writable であってはいけません。trusted full access でも Issue、branch、repository 外の登録済み worktree、runtime cwd、PR、検証は 維持しますが、filesystem isolation は未検証として記録します。file を削除すれば すぐに strict mode へ戻ります。repository は strict mode を要求できますが、 repository 内の内容だけでユーザーの trusted full access を有効化できません。

実行環境¶

AI Teams は delivery 方針と Git・test・GitHub operation を実行する runtime を分離します。 repository、Issue、branch、revision、選択した runtime に対して workspace readiness が status: ready を返した後だけ source work を開始します。worktree の作成だけでは readiness evidence になりません。

Codex には専用 OS account または disposable な machine/container を使います。primary checkout は read-only の coordination surface とし、登録済み Issue worktree だけを編集します。runtime に 渡す credential は認可済み operation に必要な最小限にし、無関係な host file と ambient credential は境界外に保ちます。

対応 flow は repository-owned worktree/readiness contract を解決し、明示的に選択した local または container provider を検証して、exact Issue execution context を claim します。focused check と local pre-push verification はそこで実行します。push、PR、hosted validate、merge、remote branch 削除 evidence は引き続き GitHub が所有します。ready はこれらの effect や release、deployment、 settings、secret、destructive authority を付与しません。

責任	Owner
Goal、Issue、delivery、acceptance semantics	AI Teams
worktree と runtime process effect	選択した local host または container runtime
runtime と worktree state	OS account と Git repository
credential	user と選択した provider
GitHub read/write	GitHub Plugin または認証済み gh fallback
既存 authority	Issue、worktree、verification、PR、release contract
新しい runner / installer lifecycle	別途登録された component。core Skill は所有しない

現在の readiness support は完全な runner より意図的に狭くしています。

Path	現在の対応	Boundary
Local provider	Linux-native user-state filesystem	supplied Python executable を1つ使い、install はしない
Container provider	local に存在する immutable image ID	readiness 中は pull、network、credential、implicit fallback なし
AI Teams development image	再現可能な linux/amd64 local build	readiness image 専用。durable runner / hosted-CI image ではない
Managed consumer	current な repository-owned managed-project manifest	5つの readiness command は consumer が所有する
Native package installer	Fedora 42/RHEL 9 noarch RPM source と manual transaction	package repository と暗黙の privileged install は未提供
Reference delivery runner	optional immutable-image launcher	provider operation と hosted acceptance は独立したまま

repository の locked setup を完了してから、fresh host-capability evidence と worktree policy を packaged preparation command に渡します。

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>

明示的な container path では、最初に approved image を provision します。source repository は 次の bounded local build を提供します。

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

返された immutable image_id を --provider container、absolute container runtime、image 内の Python path とともに指定します。repository contract が選択した場合だけ --preflight ci を使い、 exact-head hosted validate の代替にはしません。

blocked は actionable handoff であり、provider の切替や dependency の暗黙 install を許可しません。 宣言した runtime、manifest、identity、freshness を修正して新しい readiness を取得します。5分経過後や revision 変更後の evidence は再利用しません。image 不在時は pull/build をせず、probe failure は candidate edit を開始せず、不確かな GitHub effect は blind retry せず exact readback します。

Optional reference runner と native package¶

既存の isolated Codex host がない場合は、 packaging/reference-runner/Dockerfile から optional image を build し、immutable image ID を inspect して、同じ accepted source commit から launcher を install します。

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>

最初の native-package target は Fedora 42 と RHEL 9 です。 packaging/reference-runner/ai-teams-reference-runner.spec から noarch RPM を build し、同じ accepted commit の RPM と checksum/SBOM の組だけを install します。この project は package repository を設定しません。

専用 Docker network を別途 provision し、Issue worktree を ready にしてから、immutable image を1回だけ起動します。optional な private/user-owned credential directory は引数順に /run/ai-teams/credentials/ 以下へ read-only mount されます。

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>'

launcher が開始する container は最大1個です。image の作成/pull、network 作成、credential 取得、failed command の retry、hosted acceptance の主張は行いません。writable なのは exact worktree と Git common directory だけで、Docker socket、host home、他の repository はありません。

upgrade は新しく accepted された source から install を再実行し、その後 verify します。 transaction 失敗時は以前の exact file を復元します。uninstall は変更済み artifact を拒否し、 digest が一致する3個の file だけを削除します。

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

repository、credential、image、network、無関係な prefix file は残ります。非対応 transition は operator handoff であり、recursive delete の authority ではありません。

Install¶

現在推奨する review 済み prerelease は v0.30.0-rc.1 で、 公開元の exact commit は a6a2eca2a6819ed29d1105ac7f23cb0faa27d5e4 です。 リンク先の Release と commit を確認してから、この immutable な40文字 commit を install します。

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

exact commit を main などの moving ref に置き換えないでください。新しい Release を 使う場合は、その immutable tag と40文字 commit を個別に review してから install します。

選んだプロジェクトだけで AI Teams を有効にする¶

Plugin の有効・無効は Codex の標準設定で制御します。インストール後、 ~/.codex/config.toml の既存の表を編集し、既定を無効にします。

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

利用するプロジェクトを明示的に選び、そのルートの .codex/config.toml に追加します。

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

ほかの設定は残し、同じ表を重複させないでください。Codex がそのプロジェクトを信頼済みと 判断した後にだけ、この上書きが読み込まれます。利用しないプロジェクトには有効化設定を 置かず、複数プロジェクトの共通の親ディレクトリにも置きません。Git 管理された設定は 同じリポジトリの worktree に引き継がれますが、各作業場所の信頼確認は別です。 インストール、有効化、管理・準備状態、機能別の opt-in、外部操作の許可は独立しています。

設定変更前に実行中の作業を完了または中止し、新しい Codex セッションを開始してください。 無効にするときはプロジェクト側を false にして再開します。ファイルの削除だけで無効に なるのは、実効的な既定値も false の場合です。古い会話の指示やキャッシュ内のスクリプトを 使って無効化を迂回しません。対象 cwd の実効設定と Skill・MCP・Hook の一覧を確認します。 インストール一覧の enabled 表示だけでは、プロジェクトでの有効状態を証明できません。 インストールや更新でホスト側の設定が変わる場合があるため、その後にも再確認します。

設定・移行と導入済みホストの検証手順は 標準設定による有効化の契約 が所有します。.ai-teams/managed-project.json や settings.json に別の有効化フラグを設けません。

プロジェクト設定を確認する¶

有効にしたプロジェクトで新しいセッションを開き、$ai-teams setup で 最小限の Project profile、変更ファイルの差分、readiness command 候補、不足する能力を 確認できます。既存の Issue template は保持し、機能・不具合・設計判断の雛形を任意で検討できます。 提案時にはファイルを書き換えず、repository command も実行しません。各段階の変更を 確認してから既存の adoption / delivery-readiness の apply 手順へ進み、適用後に再計画します。

Plugin の導入状態と Project の準備状態は別に表示します。workflow や設定の存在だけで CI 成功、provider 認証、deployment、成果の観測を判断しません。任意の integration onboarding では、認証と install の承認を引き続き provider の手順で行います。

installed CLI から同じ読み取り専用の提案を得るには、次を実行します。

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

変更のない commit 済み repository を使います。--expect-revision は古い commit を拒否し、 --readiness-contract と --equivalents は既存の所有者の schema を使います。 追跡済みの相対パスを --evidence-source / --deployment-request に渡すと、接続や実行を せずに設定を確認できます。未検証の runtime や不足する integration は degraded / unknown のまま、次に必要な操作とその所有者を表示します。

任意の Issue フォーム¶

適切なフォームがないリポジトリでは、メタデータ、成果、根拠、スコープ、固定 ID 付きの 受け入れ条件、検証方法を含む雛形を利用できます。既存の指示、テンプレート、tracker、 言語、ラベルを確認してから導入を選びます。断った場合は変更しません。setup 結果の issue_starters.review_input が完全な入力雛形です。このオブジェクトを一時的な review ファイルに保存して確認結果を記入します。新しいプロジェクト設定ではありません。

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

差分を確認したら、導入 Issue の worktree で同じ引数に --accept-digest <digest> を加え、 apply を実行します。他の導入段階でリポジトリが変わった場合は再計画します。作成するのは 最大3種類のフォームと、存在しない場合の chooser 設定1件です。既存・変更済みファイルを 保持し、方針が不明な場合や用途が重複する場合は書き込みを止めます。同じ内容での再実行は 無変更です。部分失敗では作成済みパスを明示して保持し、リポジトリの手順で正確に復旧します。 自動削除や自動再試行は行いません。

導入後の .github/ISSUE_TEMPLATE はリポジトリが所有します。文言、既存ラベル、追加の 必須項目を調整でき、副言語の概要欄は設定に従って browser / CLI のどちらでも1回だけ 出力されます。後の Plugin 更新でローカル変更を上書きしません。削除・取り消しは通常の リポジトリレビューで行います。baseline には GitHub 仕様の参照先と確認日を記録し、setup 時に可変の外部仕様を取得しません。対応するフォームの範囲、確認入力、復旧条件は starter 契約 を参照してください。

exact-ref installation を更新する¶

Codex の一般的な marketplace refresh では、immutable commit に固定された marketplace の ref は 進みません。固定は維持します。packaged plugin-diagnostics/scripts/update_check.py で利用可能な Release を検出し、その Release と exact な40文字 commit を review してから、marketplace checkout 外の安定した directory で packaged updater を実行します。

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

preflight は marketplace や Plugin を変更せず、現在と対象の version、Release、ref、provenance を 検証します。その exact update に対する個別の authority を付与した後、--preflight-only を外して 同じ command を再実行します。bounded updater は固定 marketplace を置き換え、 ai-teams@ai-teams を再 install し、結果を read back して updated、rolled-back、 rejected、unresolved のいずれかを返します。unresolved は retry しません。

updater result の status: updated と、active_revision、active_version、 active_release が review 済み target と一致することを確認します。その後、新しい Codex session を開始し、 installed plugin-diagnostics Skill で明示的な update diagnostic と代表的な repository inspection を 実行します。Codex が対応する Plugin surface と新しい session への反映は 公式 Plugin documentation、AI Teams の exact-ref safety と updater behavior は packaged update contract で定義されています。

rollback する場合は、以前の immutable Release を review し、その exact commit、manifest version、 Release tag を同じ updater に指定します。復元された identity を確認し、もう一度新しい session を 開始します。published tag を移動または再利用したり、marketplace を main に切り替えたり、Codex configuration や installed cache を手作業で編集したりしません。

利用¶

Product direction、discovery、planning、Issue delivery、repository adoption、status、semantic review、recovery で AI Teams を使うよう Codex に依頼します。Plugin は最小の適用 workflow を 選び、重要な状態を project system of record に保持します。

Plugin を install しただけでは service 起動、deployment、marketplace 変更、external system への access は発生しません。

GitHub CLI のローカルヘルプには、正確に gh pr merge --help と入力するか、 従来の gh help pr merge を使えます。AI Teams Hook は引き続き現在の Issue 実行コンテキストを確認します。不足・期限切れの場合は workspace readiness を 更新してください。追加引数や複合コマンドには、新しいヘルプ例外を適用しません。 古いインストールでは前者が拒否されるため、修正版を明示的にインストールするまでは gh help pr merge を使ってください。ソース PR の受け入れだけでは、インストール済み Hook は切り替わりません。