既存のチームを進化させる

create-team で最初に作成されたチームを改善、再構成、または専門特化バリアントを作成します。このプロシージャはチームライフサイクルのメンテナンス面をカバーします：テンプレートとコーディネーションパターンのギャップ評価、構成とワークフローへの的を絞った改善の適用、バージョン更新、レジストリとクロスリファレンスの同期維持。

使用タイミング

• エージェントの追加、削除、または進化の後にチームのメンバー構成が古くなった場合
• ユーザーフィードバックからワークフローのボトルネック、不明確な引き継ぎ、または欠落している視点が明らかになった場合
• コーディネーションパターンがチームの実際のワークフローに合わなくなった場合（例：hub-and-spokeをparallelにすべき）
• 元のチームと並行して専門特化バリアントが必要な場合（例：r-package-review と r-package-review-security-focused）
• チームメンバーの責任が重複しており、境界を明確にする必要がある場合
• CONFIGブロックが散文の説明またはメンバーリストと同期していない場合
• チームを2つの小さなチームに分割する必要がある場合、または2つのチームを統合する必要がある場合

入力

• 必須: 進化させる既存のチームファイルへのパス（例：teams/r-package-review.md）
• 必須: 進化のトリガー（フィードバック、新しいエージェント、コーディネーションの不一致、スコープの重複、パフォーマンスの問題、エージェントの進化）
• 任意: 目標バージョンバンプの大きさ（patch、minor、major）
• 任意: インプレースでの改良の代わりに専門特化バリアントを作成するかどうか（デフォルト：インプレースで改良）

手順

ステップ1: 現在のチームを評価する

既存のチームファイルを読み、各セクションをチームテンプレート（teams/_template.md）と比較して評価します：

セクション	確認事項	よくある問題
フロントマター	必須フィールドすべて（name、description、lead、version、author、coordination、members[]）	tags の欠落、古い version、誤った coordination
Purpose	明確なマルチエージェントの根拠（少なくとも2つの異なる専門性）	単一エージェントで処理可能
Team Composition	テーブルがフロントマターのメンバーと一致し、責任の重複がない	古いテーブル、重複したフォーカスエリア
Coordination Pattern	実際のワークフローと一致し、ASCIIダイアグラムがある	ワークフローに対して誤ったパターン
Task Decomposition	メンバーごとの具体的なタスクを含むフェーズ別の分解	曖昧なタスク、フェーズの欠落
CONFIG Block	マーカー間の有効なYAML、フロントマターと散文に一致	同期のずれ、blocked_by の欠落、無効なYAML
Usage Scenarios	2〜3個の現実的なアクティベーションプロンプト	プレースホルダーテキスト
Limitations	3〜5個の正直な制約	欠落または過度に一般的
See Also	メンバーエージェント、関連チーム、ガイドへの有効なリンク	古いリンク

# チームファイルを読む
cat teams/<team-name>.md

# すべてのメンバーエージェントが依然として存在することを確認
grep "id:" teams/<team-name>.md | while read line; do
  agent=$(echo "$line" | grep -oP '(?<=id: )[\w-]+')
  grep "id: $agent" agents/_registry.yml || echo "MISSING: $agent"
done

# チームがいずれかのガイドで参照されているか確認
grep -r "<team-name>" guides/*.md

期待結果： セクションごとに整理された、特定のギャップ、弱点、または改善の機会のリスト。

失敗時： チームファイルが存在しないかフロントマターがない場合、このスキルは適用されません—代わりに create-team を使用してゼロから作成してください。

ステップ2: 進化の要件を収集する

進化を引き起こしたものを特定し、分類します：

トリガー	例	典型的なスコープ
ユーザーフィードバック	「レビューに時間がかかりすぎる、エージェントが作業を重複している」	責任の明確化またはパターンの変更
新しいエージェントが利用可能	api-security-analyst エージェントが作成された	メンバーの追加
エージェントが進化した	code-reviewer が新しいスキルを習得した	メンバーの責任の更新
エージェントが削除された	deprecated-agent が廃止された	メンバーの削除、タスクの再割り当て
コーディネーションの不一致	sequentialチームに独立したサブタスクがある	parallelへの変更
スコープの拡大	チームがレビューだけでなくデプロイもカバーする必要がある	メンバーの追加またはバリアントの作成
チームが大きすぎる	6人以上のメンバーによるコーディネーションのオーバーヘッド	2つのチームへの分割
チームが小さすぎる	単一メンバーが大半の作業を行う	別のチームとの統合またはメンバーの追加

編集前に必要な具体的な変更を文書化します：

- フロントマター: 新しいメンバー `api-security-analyst` をロール "API Security Reviewer" で追加
- Team Composition: コンポジションテーブルに行を追加
- Task Decomposition: 実行フェーズにAPIセキュリティレビュータスクを追加
- CONFIGブロック: メンバーとタスクエントリを追加
- See Also: 新しいエージェントファイルへのリンクを追加

期待結果： 各変更がチームファイルの特定のセクションにマッピングされた、具体的な変更のリスト。

失敗時： 変更が不明確な場合は、進める前にユーザーに明確化を求めます。曖昧な進化の目標は曖昧な改善を生み出します。

ステップ3: 進化のスコープを選択する

このデシジョンマトリックスを使用して、インプレースでの改良かバリアントの作成かを決定します：

基準	改良（インプレース）	専門特化バリアント（新しいチーム）
Team ID	変更なし	新しいID: <team>-<specialty>
ファイルパス	同じ .md ファイル	teams/ の新しいファイル
バージョンバンプ	パッチまたはマイナー	1.0.0 から開始
コーディネーション	変更可能	元と異なる場合あり
レジストリ	既存エントリを更新	新しいエントリを追加
元のチーム	直接変更	そのまま維持、See Alsoクロスリファレンスを追加

改良: メンバーの調整、責任の明確化、CONFIGブロックの修正、またはコーディネーションパターンの変更時に選択します。チームはそのアイデンティティを保持します。

バリアント: 進化したバージョンが実質的に異なるユースケースに対応する、異なるコーディネーションパターンを必要とする、または異なる対象者をターゲットにする場合に選択します。元のチームは既存のユースケースのためにそのまま残ります。

追加のスコープ決定：

状況	アクション
チームに6人以上のメンバーがいて遅い	2つのフォーカスしたチームへの分割
隣接ドメインをカバーする2つの2人チーム	3〜4人の1つのチームへの統合
チームのコーディネーションパターンが誤っている	改良 — パターンをインプレースで変更
チームに完全に異なるリードが必要	リードが存在する場合は改良、存在しない場合は先にエージェントを作成

期待結果： 根拠を伴う明確な決定 — 改良、バリアント、分割、または統合。

失敗時： 不確実な場合は、改良をデフォルトとします。チームの分割や統合は影響範囲が広いため、ユーザーに確認する必要があります。

ステップ4: チームファイルに変更を適用する

改良の場合

既存のチームファイルを直接編集します。チーム構成を参照するすべてのセクション間の一貫性を維持します：

1. フロントマター members[]: メンバーエントリを追加、削除、または更新します（各エントリに id、role、responsibilities）
2. Team Compositionテーブル: フロントマターのメンバーと正確に一致する必要があります
3. Coordination Pattern: パターンが変更される場合は散文とASCIIダイアグラムを更新します
4. Task Decomposition: 新しい構成を反映するためにフェーズとメンバーごとのタスクを修正します
5. CONFIGブロック: 一致するように members と tasks リストを更新します（ステップ5参照）
6. Usage Scenarios: チームのアクティベーショントリガーが変更された場合は修正します
7. Limitations: 新しい制約を反映するように更新するか、解決されたものを削除します
8. See Also: エージェントリンクを更新し、新しい関連チームやガイドへの参照を追加します

以下の編集ルールに従います：

• 既存のセクションをすべて保持する — コンテンツを追加し、セクションを削除しない
• メンバーを追加する際は、フロントマター、コンポジションテーブル、タスク分解、CONFIGブロックのすべてに追加する
• メンバーを削除する際は、それらすべての場所から削除し、タスクを再割り当てする
• 各メンバーエージェントが存在することを確認: grep "id: agent-name" agents/_registry.yml
• メンバーリストにリードを維持する — リードは常にメンバーです

バリアントの場合

# 出発点として元をコピー
cp teams/<team-name>.md teams/<team-name>-<specialty>.md

# バリアントを編集:
# - `name` を `<team-name>-<specialty>` に変更
# - `description` を専門化されたスコープを反映するように更新
# - 必要に応じて `coordination` パターンを調整
# - `version` を "1.0.0" にリセット
# - 専門化されたユースケース向けにメンバー、タスク、CONFIGブロックを変更
# - 汎用的な代替としてSee Alsoで元を参照

期待結果： チームファイル（改良版または新しいバリアント）がステップ1の評価チェックリストをパスし、すべてのセクションが内部的に一貫している。

失敗時： 編集によって内部の一貫性が崩れた場合（例：CONFIGブロックにフロントマターにないメンバーがリストされている）、フロントマターの members[] をTeam Compositionテーブル、Task Decomposition、CONFIGブロックと比較して不一致を見つけます。

ステップ4.5: 翻訳済みバリアントを同期する

翻訳が存在する場合に必須。 このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 古い source_commit 値は、npm run validate:translations がすべてのロケールにわたって誤った古さ警告を報告する原因となる。

進化したチームの翻訳が存在するかどうかを確認し、新しいソース状態を反映するように更新する:

# 既存の翻訳を確認する
ls i18n/*/teams/<team-name>.md 2>/dev/null

翻訳が存在する場合

1. 現在のソースコミットハッシュを取得する:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. 各翻訳ファイルのフロントマターで source_commit を更新する:

for locale_file in i18n/*/teams/<team-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. 影響を受けるロケールをコミットメッセージに含めて、再翻訳のためにファイルにフラグを立てる:

evolve-team(<team-name>): <変更の説明>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <変更されたセクションをリストする>

4. 翻訳ステータスファイルを再生成する:

npm run translation:status

翻訳が存在しない場合

アクション不要。ステップ5に進む。

バリアントの場合

新しいバリアントの翻訳は、バリアントが安定するまで（1〜2バージョン）延期する。v1.2までに大幅に変わる可能性のあるv1.0バリアントを翻訳するのは労力の無駄だ。バリアントが少なくとも1回は改良された後で翻訳を追加する。

期待結果： すべての翻訳ファイルで source_commit が現在のコミットに更新されている。コミットメッセージには、どのロケールで再翻訳が必要か、どのセクションが変更されたかが記載されている。npm run translation:status は0で終了する。

失敗時： sed がフロントマターフィールドにマッチしない場合、翻訳ファイルが非標準のフォーマットになっている可能性がある。手動で開き、YAMLフロントマターに source_commit があることを確認する。フィールドが欠落している場合、ファイルは正しく足場作りされていない — npm run translate:scaffold -- teams で再度足場作りする。

ステップ5: CONFIGブロックを更新する

<!-- CONFIG:START --> と <!-- CONFIG:END --> の間のCONFIGブロックは、散文セクションと同期している必要があります。メンバーまたはタスクの変更後：

1. CONFIG members のすべての agent がフロントマターのメンバーと一致することを確認
2. CONFIG tasks のすべての assignee がメンバーエージェントのidと一致することを確認
3. タスクの順序が変更された場合は blocked_by の依存関係を更新
4. 合成/最終タスクがすべての前提タスクを参照していることを確認

team:
  name: <team-name>
  lead: <lead-agent>
  coordination: <pattern>
  members:
    - agent: <agent-id>
      role: <role-title>
      subagent_type: <agent-id>
  tasks:
    - name: <task-name>
      assignee: <agent-id>
      description: <one-line>
    - name: synthesize-results
      assignee: <lead-agent>
      description: Collect and synthesize all member outputs
      blocked_by: [<prior-task-names>]

期待結果： CONFIG YAMLが有効で、すべてのエージェントとタスクがファイルの残りの部分と一貫しており、blocked_by が有効なDAGを形成している。

失敗時： CONFIGブロックのYAMLを別途パースして構文エラーを見つけます。すべての assignee を members リストと相互チェックします。

ステップ6: バージョンとメタデータを更新する

セマンティックバージョニングに従ってフロントマターの version フィールドをバンプします：

変更の種類	バージョンバンプ	例
文言の修正、See Alsoの更新	パッチ: 1.0.0 → 1.0.1	古いエージェントリンクを修正
新しいメンバーの追加、タスクの修正	マイナー: 1.0.0 → 1.1.0	security-analystメンバーを追加
コーディネーションパターンの変更、チームの再構成	メジャー: 1.0.0 → 2.0.0	hub-and-spokeからparallelへの変更

また以下も更新します：

• updated 日付を現在の日付に
• チームのドメインカバレッジが変更された場合は tags を
• チームの目的が実質的に異なる場合は description を
• パターンが変更された場合は coordination を

期待結果： フロントマターの version と updated が変更の大きさと日付を反映している。新しいバリアントは "1.0.0" から始まる。

失敗時： バージョンのバンプを忘れた場合、次の進化で現在の状態と以前の状態を区別する方法がなくなります。コミット前に必ずバンプしてください。

ステップ7: レジストリとクロスリファレンスを更新する

改良の場合

teams/_registry.yml の既存エントリを修正されたフロントマターと一致するように更新します：

# チームのレジストリエントリを見つける
grep -A 10 "id: <team-name>" teams/_registry.yml

description、lead、members、coordination フィールドをチームファイルと一致するように更新します。カウントの変更は必要ありません。

バリアントの場合

新しいチームを teams/_registry.yml に追加します：

- id: <team-name>-<specialty>
  path: <team-name>-<specialty>.md
  lead: <lead-agent>
  members: [agent-1, agent-2, agent-3]
  coordination: <pattern>
  description: 専門化されたバリアントの一行説明

次に：

1. レジストリの上部で total_teams をインクリメント
2. バリアントを指す元のチームにSee Alsoクロスリファレンスを追加
3. 元を指すバリアントにSee Alsoクロスリファレンスを追加

READMEの自動化を実行します：

npm run update-readmes

期待結果： レジストリエントリがチームファイルのフロントマターと一致している。npm run update-readmes がゼロで終了する。バリアントの場合、total_teams が実際のチームエントリ数と等しい。

失敗時： レジストリのカウントが誤っている場合は、grep -c "^ - id:" teams/_registry.yml でエントリを数え、カウントを修正します。READMEの自動化が失敗した場合は、package.json が存在し js-yaml がインストールされていることを確認します。

ステップ8: 進化したチームを検証する

完全な検証チェックリストを実行します：

• チームファイルが期待されるパスに存在する
• YAMLフロントマターがエラーなしにパースされる
• version がバンプされた（改良）または "1.0.0" に設定された（バリアント）
• updated 日付が今日を反映している
• 必要なセクションがすべて存在する: Purpose、Team Composition、Coordination Pattern、Task Decomposition、Configuration、Usage Scenarios、Limitations、See Also
• フロントマター members[] がTeam Compositionテーブルと一致する
• CONFIGブロックのメンバーがフロントマターのメンバーと一致する
• CONFIGブロックのタスクに有効なassigneeと blocked_by 参照がある
• すべてのメンバーエージェントIDが agents/_registry.yml に存在する
• リードエージェントがメンバーリストに含まれている
• 2つのメンバーが同じ主要な責任を共有していない
• レジストリエントリが存在しフロントマターと一致する
• バリアントの場合: total_teams カウントがディスク上の実際のカウントと一致する
• クロスリファレンスが双方向である（元 ↔ バリアント）
• git diff に元のコンテンツからの意図しない削除がない

# フロントマターを確認
head -25 teams/<team-name>.md

# すべてのメンバーエージェントが存在することを確認
for agent in agent-a agent-b agent-c; do
  grep "id: $agent" agents/_registry.yml
done

# ディスク上のチーム数 vs レジストリ
ls teams/*.md | grep -v template | wc -l
grep total_teams teams/_registry.yml

# すべての変更を確認
git diff

期待結果： すべてのチェックリスト項目がパスする。進化したチームはコミット可能な状態にある。

失敗時： 失敗した各項目を個別に対処します。進化後の最も一般的な問題は、CONFIGブロックのドリフト（メンバーまたはタスクが散文と一致しない）と忘れられた updated 日付です。

バリデーション

• チームファイルが存在し、有効なYAMLフロントマターを持っている
• version フィールドが行われた変更を反映している
• updated 日付が最新である
• すべてのセクションが存在し、内部的に一貫している
• フロントマター members[]、Team Compositionテーブル、CONFIGブロックが同期している
• すべてのメンバーエージェントIDが agents/_registry.yml に存在する
• リードエージェントがメンバーリストにいる
• CONFIGブロックのYAMLが有効でパース可能である
• レジストリエントリがチームファイルと一致する
• バリアントの場合: 正しいパスで teams/_registry.yml に新しいエントリがある
• バリアントの場合: total_teams カウントが更新されている
• クロスリファレンスが有効である（See Alsoに壊れたリンクがない）
• git diff が意図しないコンテンツの削除を確認している

よくある落とし穴

• CONFIGブロックのドリフト: CONFIGブロック、フロントマター、および散文セクションはメンバーとタスクに関してすべて一致している必要があります。一方を他方なしに更新することは最も一般的なチーム進化のエラーです。変更のたびに3つすべてを相互チェックしてください。
• バージョンのバンプを忘れる: バージョンバンプなしには、何が変わったか、いつ変わったかを追跡する方法がありません。コミット前に必ず version と updated を更新してください。
• 孤立したメンバー参照: メンバーを削除する際、Task DecompositionとCONFIGブロックのタスクを再割り当てまたは削除する必要があります。孤立したassigneeを残すとアクティベーションの失敗を引き起こします。
• 進化後の誤ったコーディネーションパターン: parallelが可能なメンバーをsequentialチームに追加する、またはエージェントが互いの出力を必要とするhub-and-spokeチームを作る。構造的な変更後は create-team ステップ4からパターンの決定を再評価してください。
• メンバー追加後のチームが大きすぎる: 5人以上のメンバーを持つチームはコーディネーションが難しくなります。進化によってチームが5人を超える場合は、代わりに2つのフォーカスしたチームへの分割を検討してください。
• バリアント作成後の古いSee Also: バリアントを作成する際、元とバリアントの両方がお互いを参照する必要があります。一方向の参照はグラフを不完全なままにします。

関連スキル

• create-team — 新しいチームを作成するための基盤。evolve-teamはこれが元々従っていたことを前提とします
• evolve-skill — SKILL.mdファイルを進化させるための並行プロシージャ
• evolve-agent — エージェント定義を進化させるための並行プロシージャ
• commit-changes — 説明的なメッセージで進化したチームをコミット