evolve-team

# 既存のチームを進化させる `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 | メンバーエージェント、関連チーム、ガイドへの有効なリンク | 古いリンク | ```bash # Read the team file cat teams/<team-name>.md # Verify all member agents still exist 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 # Check if the team is referenced by any guide grep -r "<team-name>" guides/*.md ``` **期待結果：** セクションごとに整理された、特定のギャップ、弱点、または改善の機会のリスト。 **失敗時：** チームファイルが存在しないかフロントマターがない場合、このスキルは適用されません—代わりに `create-team` を使用してゼロから作成してください。 ### ステップ2: 進化の要件を収集する 進化を引き起こしたものを特定し、分類します： | トリガー | 例 | 典型的なスコープ | |---|---|---| | ユーザーフィードバック | 「レビューに時間がかかりすぎる、エージェントが作業を重複している」 | 責任の明確化またはパターンの変更 | | 新しいエージェントが利用可能 | `api-security-analyst` エージェントが作成された | メンバーの追加 | | エージェントが進化した | `code-reviewer` が新しいスキルを習得した | メンバーの責任の更新 | | エージェントが削除された | `deprecated-agent` が廃止された | メンバーの削除、タスクの再割り当て | | コーディネーションの不一致 | sequentialチームに独立したサブタスクがある | parallelへの変更 | | スコープの拡大 | チームがレビューだけでなくデプロイもカバーする必要がある | メンバーの追加またはバリアントの作成 | | チームが大きすぎる | 6人以上のメンバーによるコーディネーションのオーバーヘッド | 2つのチームへの分割 | | チームが小さすぎる | 単一メンバーが大半の作業を行う | 別のチームとの統合またはメンバーの追加 | 編集前に必要な具体的な変更を文書化します： ```text - フロントマター: 新しいメンバー `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` - メンバーリストにリードを維持する — リードは常にメンバーです #### バリアントの場合 ```bash # Copy the original as a starting point cp teams/<team-name>.md teams/<team-name>-<specialty>.md # Edit the variant: # - Change `name` to `<team-name>-<specialty>` # - Update `description` to reflect the specialized scope # - Adjust `coordination` pattern if needed # - Reset `version` to "1.0.0" # - Modify members, tasks, and CONFIG block for the specialized use case # - Reference the original in See Also as a general-purpose alternative ``` **期待結果：** チームファイル（改良版または新しいバリアント）がステップ1の評価チェックリストをパスし、すべてのセクションが内部的に一貫している。 **失敗時：** 編集によって内部の一貫性が崩れた場合（例：CONFIGブロックにフロントマターにないメンバーがリストされている）、フロントマターの `members[]` をTeam Compositionテーブル、Task Decomposition、CONFIGブロックと比較して不一致を見つけます。 ### ステップ4.5: 翻訳済みバリアントを同期する > **翻訳が存在する場合に必須。** このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 古い `source_commit` 値は、`npm run validate:translations` がすべてのロケールにわたって誤った古さ警告を報告する原因となる。 進化したチームの翻訳が存在するかどうかを確認し、新しいソース状態を反映するように更新する: ```bash # Check for existing translations ls i18n/*/teams/<team-name>.md 2>/dev/null ``` #### 翻訳が存在する場合 1. 現在のソースコミットハッシュを取得する: ```bash npm run validate:translations ``` 2. 各翻訳ファイルのフロントマターで `source_commit` を更新する: ```bash npm run check:fence-propagation -- --id <team-name> node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths> ``` 3. 影響を受けるロケールをコミットメッセージに含めて、再翻訳のためにファイルにフラグを立てる: ```text evolve-team(<team-name>): <変更の説明> Translations flagged for re-sync: de, zh-CN, ja, es Changed sections: <変更されたセクションをリストする> ``` 4. 翻訳ステータスファイルを再生成する: ```bash 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. 合成/最終タスクがすべての前提タスクを参照していることを確認 ```yaml 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` の既存エントリを修正されたフロントマターと一致するように更新します： ```bash # Find the team's registry entry grep -A 10 "id: <team-name>" teams/_registry.yml ``` `description`、`lead`、`members`、`coordination` フィールドをチームファイルと一致するように更新します。カウントの変更は必要ありません。 #### バリアントの場合 新しいチームを `teams/_registry.yml` に追加します： ```yaml - id: <team-name>-<specialty> path: <team-name>-<specialty>.md lead: <lead-agent> members: [agent-1, agent-2, agent-3] coordination: <pattern> description: One-line description of the specialized variant ``` 次に： 1. レジストリの上部で `total_teams` をインクリメント 2. バリアントを指す元のチームにSee Alsoクロスリファレンスを追加 3. 元を指すバリアントにSee Alsoクロスリファレンスを追加 READMEの自動化を実行します： ```bash 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` に元のコンテンツからの意図しない削除がない ```bash # Verify frontmatter head -25 teams/<team-name>.md # Verify all member agents exist for agent in agent-a agent-b agent-c; do grep "id: $agent" agents/_registry.yml done # Count teams on disk vs registry ls teams/*.md | grep -v template | wc -l grep total_teams teams/_registry.yml # Review all changes 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` — 説明的なメッセージで進化したチームをコミット