tjrtm/the-team-loop

チームループ

このスキルは、協力する2つのチームまたはエージェントが1つのリポジトリで作業するときに使用します。Team A と Team B は設定済みの名前に置き換えてください。オーナーは人間であり、優先順位、マージ、デプロイ、フリーズ、およびポリシーに関する決定の権限を持ちます。

オンボーディング：5分でセットアップ

1. このスキルをターゲットリポジトリにコピーし、使用するエージェントツール用のアダプターをインストールします。
2. templates/team-loop.yml を .team-loop.yml にコピーし、チーム名と gate_command を設定します。
3. scripts/setup-labels.sh --repo OWNER/REPO を実行します。
4. オーナーがピン留めされた調整用Issueと、ready ラベルが付いた1つのIssueを作成します。
5. 各チームはこのファイルを読み、最大1つのアイテムをクレームし、設定済みのステータスヘッダーを使用します。

役割

• オーナー: 準備のできた作業を作成またはプロモートします。Owner: の決定を自分の言葉で直接投稿します。スコープとUTC終了時間が明記された書面による委任がない限り、マージとデプロイを承認します。
• チームA / チームB: ビルド、テスト、レビュー、クレーム、ハンドオフ、および報告を行います。可能な場合は別々のGitHub IDを使用します。
• レビューア（オプション）: 新しいコンテキストでレビューを実行します。設定されたリスクパスまたはカテゴリに対して必須とします。

ループの状態

backlog -> ready -> in-progress -> blocked または needs-owner -> 実装PR -> ready-for-owner -> merged -> deployed。

• backlog はクレーム不可です。週1回、重要度の低いバックログ作業をまとめてオーナーによるプロモーションを依頼します。
• ready は実装、テスト、およびPRのオープンを許可します。マージやデプロイは許可しません。
• Issueをクローズするときは、in-progress、ready、blocked、needs-owner などの古い状態ラベルを削除します。

クレームプロトコル

1. 行動する直前にラベルを再読み込みします。in-progress、blocked、または ready 以外の作業はクレームしないでください。
2. scripts/claim.sh --repo OWNER/REPO --issue N --team "Team A" --plan "short plan" を実行します。
3. スクリプトは in-progress とチームラベルを追加し、クレームを投稿してから状態を再確認します。競合に負けた場合はバックオフします。
4. 進行中の作業はチームごとに wip_limit 以下に保ちます。別のアイテムをクレームする前に、現在のアイテムを完了するか、ハンドオフするか、明示的にブロックします。
5. team:any の場合、最も早い有効なクレームコメントが優先され、もう一方のチームはバックオフします。重複実装によって同点を解決しないでください。

コメントとコミュニケーション

すべてのチームコメントは、最初の行を次の形式で開始します。

Status: <state> | Team: <configured team> | <short context>

クレームと計画、レビュー結果、ゲート結果、ハンドオフ、質問、オーナーへのエスカレーション、合意、またはリリースレポートのみを投稿します。開始、キューイング、待機中、再アーム、その他の儀式的なコメントは投稿しないでください。通常のコメントは5行以内に収め、証拠はPR説明または折りたたみ詳細に配置します。

オーナーのみが Owner: の決定を記述します。チームは直接のオーナーコメントにリンクするか、依頼する必要があり、権限として中継してはなりません。

ラベルとルーティング

reference/labels.md のラベルを使用します。アサインされていない ready Issueは、設定で別の指定がない限りデフォルトでチームAに割り当てられます。team:any により、どちらのチームもクレームできます。アイドル中は、次の優先順位で相手チームを支援します：依頼されたレビュー、トレインの準備またはリベース、週次のバックログバッチ。オーナーからのリクエストなしに、無制限のバグスイープを行わないでください。

レビュー、トレイン、ゲート、証明書

1. 各PRは軽量で焦点を絞ったチェックを実行し、そのリスクに応じて必要なレビューレベルを受けます。

2. レビューアは完了したPRに ready-for-owner ラベルを付けます。

3. トレインランナーは、その時点で利用可能なレビュー済みPRを収集します。次のコマンドを実行します。

   scripts/train.sh --repo OWNER/REPO --name train-YYYYMMDD-N PR_NUMBER...
   

4. train.sh は含まれるすべてのPRに train-running ラベルを追加し、ベースとヘッドを記録し、衝突スクリーンを実行し、一時的なマージ結果を構築し、gate.sh を1回呼び出します。

5. gate.sh は証明書を git rev-parse HEAD^{tree} にキー付けします。一致する既存の証明書は、--force が使用されていない限り、成功の証拠となります。

6. ベースまたはPRヘッドが変更された場合、またはスクリーン/ゲートに失敗した場合は、トレインは無効です。問題のあるPRを削除または分割してから、トレインを再構築します。train-running がトレインを保持している間は、無関係な作業をマージしないでください。

7. オーナーの直接承認または有効な委任の後、train.sh を --merge --owner-authorization "Owner: ..." フラグを付けて再度実行し、記録されたPRヘッドを順にマージします。ベースまたはヘッドが変更された場合は拒否し、各マージ後に保護ブランチのツリーを検証します。

デプロイ、フリーズ、ホールド、ポーズ

• 設定された保護ブランチのみを、一致するツリー証明書がある場合にのみデプロイします。ただし、オーナーが記録された例外を提供する場合はこの限りではありません。
• リリースにつき1つのデプロイメントレポートを作成します。出荷済みのPRとIssueに deployed ラベルを付け、それらを複製せずに1つのレポートにリンクします。
• freeze は新しいマージとデプロイを停止します。ラベルの読み取りに失敗した場合は、不可逆的なアクションに対して凍結されたものとして扱います。
• トレインホールドは、そのトレインが終了するまで、そのトレイン外のマージをブロックします。
• ポーズ中は、クレーム、トレイン、マージ、デプロイを停止します。オーナーは再開を許可するアイテムを指定した再開リストを投稿します。再開前にラベル、PRヘッド、ベース、証明書を再確認します。

エスカレーションと委任

製品、セキュリティ、法務、リリース、または所有権があいまいな決定によって作業がブロックされた場合は、needs-owner を使用します。観察された動作、オプション、推奨事項、および期限があればそれを記載します。独立した作業は継続します。

委任は、その正確なスコープとUTC有効期限を明記する必要があります。例：

Owner: Team A may merge and deploy reviewed documentation PRs 41 and 42 until 2026-05-01T18:00:00Z.

そのスコープ外または期限切れのものは、新たな直接の決定が必要です。

レトロスペクティブ

少なくとも週1回、scripts/scorecard.sh を実行し、reference/metrics.md で定義を議論します。測定可能なボトルネックを一度に1つずつ改善します。マージされたPRあたりのゲート実行回数、クレームレイテンシ、サイクルタイム、キューの正味変化、平均バッチサイズ、認証済みシェア、変更失敗率をレビューします。

規範的な番号付きルールについては reference/rules.md を、ステータス投稿前には reference/comment-templates.md を参照してください。