agent-army

Agent Army

2 層の並列実行フレームワークです。Commander は最上位モデルで、デフォルトでは Fable、セッションのモデルが Opus の場合は Opus です。偵察、構成、ブリーフィング、検証といった思考を担います。Commander は、ユーザーがデプロイ時に選ぶ階層の下位モデルの群れをオーケストレーションします（Power Level を参照）。各 Layer 1 エージェントは、それぞれ独立した完全なコンテキストウィンドウを持ちます（分割された一部ではありません）。各エージェントはその配下に Layer 2 のサブエージェントを複数起動します。その結果、多数の独立した頭脳が同時に稼働します。1 つの頭脳を分割するのではありません。

Commander (you — Fable or Opus, the session model)
 |
 |-- Layer 1: Team (3 to 50+, each = own 1M context, L1 tier from power level)
 |    |-- Agent A (1M) -- Sub-agent A1, A2, ...  (L2 tier)
 |    |-- Agent B (1M) -- Sub-agent B1, B2, ...  (L2 tier)
 |    |-- Agent C (1M) -- Sub-agent C1, C2, ...  (L2 tier)
 |    |-- ... (no cap)

群れと軍隊の違い： 群れは 1 つのコンテキストウィンドウをサブエージェント間で分割します。つまり、1 つの頭脳を分割する形です。軍隊では、Layer 1 の各メンバーがそれぞれ独立したウィンドウを持ちます。この違いこそが、このスキルのすべてです。

使用する場面

• 多数のファイルにまたがる大規模なリファクタリング
• 複数ファイルにわたる色／スタイル／命名／API の移行
• コードベースの広範な監査（セキュリティ、アクセシビリティ、パフォーマンス、不要なコード）
• コンテンツの一括生成または変換
• 同時に進められる独立した作業単位が 6 つ以上あるタスク

使用しない場面

• 独立した作業単位が 6 つ未満の場合 — 直接作業してください
• 各ステップで前のステップの出力が必要となる、逐次的な依存関係が強い場合
• 単一ファイルの変更
• すべての出力で一貫した執筆者の語調が必要なタスク（並列エージェント間で語調にずれが生じます）

タスクが明確に該当しない場合は、その旨を伝え、軍隊を編成するのではなく、その場で作業することを提案してください。

## 必須ルール

1. すべての Layer 1 エージェントは、必ず 2 つ以上のサブエージェントを起動しなければなりません。例外はありません。サブエージェントなしで L1 エージェントをデプロイしようとしている場合は、いったん停止して構成を見直してください。
2. 軍隊の規模を黙って縮小してはいけません。ユーザーが選んだ階層に合わせてください。変更が必要な場合は、その旨と理由を明確に伝えてください。 2b. モデルを黙ってダウングレードしてはいけません。ユーザーが選んだパワーレベルを使い、すべての Agent 呼び出しで model: を明示してください。省略するとセッションのモデルが引き継がれ、Max Power の料金が黙って発生します。
3. サブエージェントのデプロイ指示は Layer 1 のブリーフに含めてください。指示がなければ、サブエージェントは作成されません。
4. エージェントが完了したら、次の形式で報告してください：[Agent N/M complete] name: X files modified, Y flags.
5. デプロイ前に軍隊の計画を提示し、Deployment Gate を通過してください（Full Mode）。Quick Mode では計画を内部で構成しますが、同様に Gate を通過してください。
6. 各ウェーブの後に、ビルドと phantom-completion check の両方を実行してください（Verify を参照）。エージェントからの成功報告は主張であり、証拠ではありません。
7. 「続けて」「止めないで」は連続モードを意味します。エージェントが 1 つ完了したら、すぐに新しいエージェントを起動してください。待ったり、再度確認したりしてはいけません。

軍隊の規模

開始前に階層を確認してください。次の表を提示します。

| Tier         | L1 Agents | Total w/ Sub-agents | Est. Tokens  |
|--------------|-----------|---------------------|--------------|
| Conservative | 3         | ~9                  | ~200-500K    |
| Standard     | 5-10      | ~15-30              | ~500K-1.5M   |
| Aggressive   | 10-20     | ~30-60              | ~1.5-4M      |
| Maximum      | 20-50+    | ~60-100+            | ~4M+         |
| Custom       | you pick  | you pick            | varies       |

「そのまま進めて」と言われた場合は、デフォルトで Standard を選びます。偵察（Step 3）の後、調査結果に基づいて具体的な人数を提案してください。たとえば、「6 つの領域に 35 ファイル → Aggressive：L1 エージェント 8 人、各 2～3 個のサブエージェント（合計約 22 エージェント、約 2M トークン）。調整しますか？」のようにします。トークン数の見積もりは概算で、タスクの複雑さに応じて変動します。

パワーレベル

規模でエージェント数を、パワーで使用するモデルを決めます。1 回の質問で両方を尋ねてください（AskUserQuestion を使うと便利です。1 回の呼び出しで規模とパワーの 2 つの質問をします）。ユーザーがすでにパワーレベルまたは具体的なモデルを指定している場合は、質問を省略してください。

| Power Level         | Commander          | Layer 1 | Layer 2 | Best For                                        |
|---------------------|--------------------|---------|---------|-------------------------------------------------|
| Max Power           | Fable/Opus (session)| Opus   | Opus    | gnarly refactors, correctness-critical migrations|
| Heavy (recommended) | Fable/Opus (session)| Opus   | Sonnet  | most large tasks — smart orchestration, fast exec|
| Balanced            | Fable/Opus (session)| Sonnet | Sonnet  | mechanical migrations with clear patterns        |
| Economy             | Fable/Opus (session)| Sonnet | Haiku   | high-volume, dead-simple find/replace            |

ルール：

• Commander は常にセッションのモデル（Fable または Opus、ユーザーが選択）とし、委任してはいけません。セッションで Sonnet または Haiku が実行されている場合は、デプロイ前に切り替えるようユーザーに伝えてください（/model または claude --model fable）。Commander の品質が軍隊全体の品質の上限になります。
• すべての Agent 呼び出しでモデルを明示してください。チームメンバーには model: "<L1 tier>" を指定し、L1 のブリーフでサブエージェントに model: "<L2 tier>" を指定するよう指示します。
• どのパワーレベルでもエージェントごとのモデル引き上げが可能です。大規模または複雑なファイル（1000 行以上、複雑なロジック）を担当するサブエージェントは、1 段階上の階層に引き上げられます。引き上げは軍隊の計画に記載してください。
• 監査ウェーブは、パワーレベルにかかわらず Opus で実行します。実行担当者の作業を、より強力なモデルで新たに確認します。通知ウェーブは Haiku に引き下げられます。

プロトコル

モード： スコープがすでに具体的な場合（ファイルパス、正確な変更内容、ティア）は、ステップ 3（クイックモード）に進みます。それ以外の場合は、ステップ 1（フルモード）から始めます。

ステップ 1：受付（フルモード）

ユーザーがすでにコンテキストを提示している場合は、1 行で確認します：「目標：[X]。スコープ：[Y]。ティア：[Z]。パワー：[P]。開始します。」そうでない場合は、目標（1 文）、スコープ（ファイル／ディレクトリ／「すべて」）、制約（X には触れない、Y に合わせる）、ティア、パワーレベルを尋ねます。

ステップ 2：Git チェックポイント

1. git status — 未コミットの変更があれば警告し、先に stash または commit するか尋ねます。
2. git checkout -b agent-army/checkpoint-{timestamp} を実行してから、元のブランチに戻ります。これがロールバックポイントです。
3. Git リポジトリがない場合は、安全策がないことを警告し、明示的な確認を得ます。

ステップ 3：調査

1. Grep / Glob / Read で影響を受けるファイルをすべて見つけます。
2. 作業単位の数を数えます。
3. 各ファイルに対して wc -l を実行します。500 行以上のファイルには 重い と印を付け、単独で割り当てます。
4. ドメインに分類します（ディレクトリ、インポートグラフ、ファイル種別、命名パターンに基づく）。
5. 共有依存関係を特定します — ドメインをまたいでインポートされる 基盤ファイル。これらは先に処理します（ステップ 5）。
6. ビルドコマンドを特定します（package.json、Makefile など）。

出力：Files: N | Heavy: [list] | Domains: [list] | Shared deps: [list] | Build cmd: [cmd]

ステップ 4：編成

1. 共有依存関係には 基盤エージェント を割り当てます — 依存先との競合を避けるため、並列作業の前に実行します。
2. レイヤー 1： ドメインごとにエージェントを 1 つ割り当てます。大きなドメインは複数のエージェントに分割します。
3. レイヤー 2： 各 L1 エージェントに 2 つ以上のサブエージェントを割り当てます。ファイル数ではなく、重み付けしたファイル負荷に基づいて割り当てます。
   • 小（200 行未満）：サブエージェントごとに 2～3 ファイル
   • 中（200～500 行）：サブエージェントごとに 1～2 ファイル
   • 重い（500 行以上）：サブエージェントごとに 1 ファイル、単独で担当
4. すべてのエージェントに名前を付けます。各ファイルを必ず 1 つのサブエージェントだけに割り当てます — 重複も漏れも認めません。

編成計画を出力します。フルモードでは「進めますか？」と確認して一時停止します。クイックモードでは 1 行で要約してから、展開します。

展開ゲート

展開前に、このチェックリストを回答に出力します。頭の中で確認するだけにせず、必ず書き出してください。

DEPLOYMENT GATE:
[ ] Every L1 brief contains "You MUST spawn N sub-agents"
[ ] Every sub-agent is named with specific files assigned
[ ] Every file is owned by exactly one sub-agent (no overlap, no gap)
[ ] L1 briefs include full sub-agent deployment instructions
[ ] Tier matches the user's selection
[ ] Power level set: model: "<L1 tier>" on every L1 call; L2 tier + escalations in every brief

すべて PASS である必要があります。FAIL が 1 つでもあれば、展開前に計画を修正します。

ステップ 5：展開

1. 基盤エージェントがある場合は、L1 ティアで最初に実行します。完了を待ちます。
2. すべてのレイヤー 1 エージェントを並列で起動します — 1 回のメッセージですべての呼び出しに run_in_background: true と model: "<L1 tier>" を指定します。
3. 各 L1 エージェントは、指示に従って L2 サブエージェントを並列で起動します。
4. 完了ごとに報告します：[Agent N/M complete] name: results。

ステップ 6：検証

1. 再スキャン — ステップ 3 の検索を再実行し、違反が残っていないか確認します。
2. 完了の偽装チェック — git diff --stat を実行し、エージェントの報告と照合します。「COMPLETE、N files modified」と報告したエージェントに対応する差分がない場合、虚偽の報告または未実行です。そのエージェントに再度割り当てます。報告ではなく差分を信頼してください。
3. ビルド — ビルドコマンドを実行します。PASS／FAIL を記録します。
4. レポートにあるチーム間の指摘に対処します。
5. 編成レポートを出力します。

Agents: N | Files modified: N (diff-confirmed) | Skipped: N | Build: PASS/FAIL
Flags: [list] | Phantom completions caught: N | Rollback: git checkout agent-army/checkpoint-{timestamp}

ウェーブ

各ウェーブは、前回より小規模で、専門分野の異なる新たなチームです。各ウェーブの前にユーザーの承認を得てください。最大4ウェーブです。

ウェーブ	名前	トリガー	目的
1	実行	常時	変更を加える
2	監査	ビルド失敗、違反の残存、ファイル数が20以上、またはフラグが1つ以上	新たなエージェントがWave 1をレビューし、正確性やエッジケースを確認する
3	反映	変更がAPI／型／インターフェースに及ぶ場合、またはテストやドキュメントで旧パターンを参照している場合	テスト、ドキュメント、設定、下流の呼び出し元を更新する
4	通知	ユーザーが希望した場合	PRの説明、変更履歴、Slackの概要を下書きする

各ウェーブのレポートを次のウェーブの偵察情報として使用します。各ウェーブの後にVerifyを再実行します。再スキャンで問題がなく、ビルドも成功したら終了します。そうでなければ、4ウェーブに達した時点で終了します。

再開／スクラッチパッド

複数ウェーブにわたる実行や中断可能な実行では、Wave 1の後に.army-state.mdを作成し、変更したファイル（diffで確認済み）、未解決のフラグ、未解決の問題、決定事項を記録します。実行が強制終了された場合、次の呼び出しではこのファイルを読み込み、最初からやり直すのではなく、最後に問題がなかったウェーブから再開します。単一ウェーブのタスクでは省略してください。

レイヤー1のプロンプトテンプレート

実際にエージェントが受け取る内容です。このスキルで最も重要なセクションです。

You are [AGENT_NAME], specialist on [DOMAIN].

Objective: [one sentence]
Approved patterns: [exact values — hex codes, class names, API shapes]
Forbidden patterns: [what to remove/avoid]
Your files: [absolute paths with line counts]
Rules: [constraints]. Skip files already using approved patterns (idempotency).
Flag issues outside your files in "Flags for Commander" — do NOT fix them.

CRITICAL: You MUST use the Agent tool to spawn the sub-agents listed below. Do
NOT do the work yourself. Do NOT skip spawning. Deploy ALL sub-agents in a single
message with multiple Agent tool calls, passing model: "[L2_TIER]" on every call
[note escalations: except "NAME" which gets model: "[higher tier]"].

Sub-agents:
- "[NAME]": [files with line counts]
- "[NAME]": [files with line counts]

Pass each sub-agent: objective, their files, approved/forbidden patterns, rules,
report format. After all complete, aggregate their reports and verify (by re-reading
or grepping) that no forbidden patterns remain in your domain before reporting back.

レイヤー2のプロンプトテンプレート

You are [SUB_AGENT_NAME], working under [TEAM_MEMBER_NAME].

Objective: [one sentence]
Files you own: [absolute paths with line counts — touch only these]
Approved / Forbidden patterns: [exact values to use and remove]
Rules: [constraints]. Skip files already correct. Flag issues outside your files —
do NOT fix them.

Process: read each file fully → check idempotency → apply approved, remove forbidden
→ re-read to confirm no forbidden patterns remain.

Report: Files Modified (file: N replacements), Files Skipped (already correct),
Flags for Commander, Issues, Status (COMPLETE/PARTIAL/FAILED).

レポート形式

各エージェントは次の内容を返します。

## Report: [Name]
Files Modified:   [file: N replacements]
Files Skipped:    [file: reason]
Flags for Commander: [issue or "None"]
Issues:           [issue or "None"]
Status:           COMPLETE / PARTIAL / FAILED

反パターン

このスキルは、以下の失敗パターンを防ぐためのものです。いずれかに気づいたら、いったん止めて修正してください。

• 見せかけの並列展開 — L1エージェントがサブエージェントを起動せず、自分で作業してしまいます。並列化による速度向上が失われます。必須ルール1とゲートで防止します。
• 見せかけの完了 — エージェントが何も編集せずにCOMPLETEと報告します。報告を鵜呑みにせず、git diff --statとの照合で検出します。
• 無断の縮小 — ユーザーがAggressiveを選んだのに、黙ってエージェントを3つだけ実行します。逸脱は必ず明らかにしてください。
• モデルのずれ — Agentの呼び出しでmodel:を省略したため、すべてのサブエージェントが指揮役のモデルを暗黙に継承します。ユーザーはEconomyを選んだのに、Max Powerの料金が請求されます。必須ルール2bとゲートで防止します。
• 担当範囲の重複 — 2つのサブエージェントが同じファイルを編集し、競合や変更の消失を招きます。ゲートで担当者を必ず1人に限定して防止します。
• 基盤の更新を後回しにする — 共有ファイルを更新する前に依存先を変更し、インポートエラーが連鎖的に発生します。最初にFoundation Agentを実行します。
• 小さな作業に大人数のチームを使う — 4ファイルの変更に9つのエージェントを使うと、オーケストレーションのオーバーヘッドで遅くなり、トークンも消費します。「使用しない場合」を参照してください。

エラー処理

• サブエージェントが失敗した場合 → L1エージェントが担当ファイルを再試行するか、代わりのエージェントを起動します。
• L1エージェントが失敗した場合 → Commanderが同じ指示内容で代わりのエージェントを起動します。
• ビルドが失敗した場合 → チェックポイントブランチとの差分を確認して問題を切り分け、修正ウェーブを実行します。
• 見せかけの完了があった場合 → 該当エージェントの担当ファイルを、新しいエージェントに再割り当てします。
• 再実行時の冪等性 → エージェントは適用済みのパターンを最初に確認するため、チームを2回実行しても変更が二重に適用されることはありません。

実例

ユーザー：「サイト全体で、ネオンカラーの Tailwind の色をすべてサンドパレットに置き換えてください。」

調査： 45 個のファイル、5 つのドメイン、2 つの共有依存関係（テーマ設定と共有 <Button>）。ビルドコマンド：npm run build。積極的な構成を推奨：基盤エージェント 1 つ + L1 エージェント 5 つ、各エージェントにサブエージェント 2～4 つ（合計約 22）。ユーザーはヘビーを選択：Fable の指揮役、Opus の L1、Sonnet の L2。

第 1 波（実行）： 基盤エージェントが最初に 2 つの共有ファイルを更新します。その後、5 つの L1 エージェントが並行して作業を開始し、それぞれサブエージェントに展開します。報告：43 個を変更、2 個をスキップ（すでに正しい）、3 件のフラグ。

検証： git diff --stat で変更されたファイルが 42 個と表示されます。あるエージェントが、実際には変更していないファイルを報告していました（ファントム）。再割り当て後、43 個を確認できました。ビルドは成功。3 件のフラグと 2 件のエッジケース違反が残っているため、監査ウェーブを推奨します。

第 2 波（監査）： 新たなエージェント 3 つが、フラグの付いたファイルと違反を対象にします。修正済み。ビルドも再スキャンも問題なし。変更された <Button> をインポートしているテストファイルが 4 つあるため、伝播を推奨します。

第 3 波（伝播）： エージェント 3 つが、4 つのテストファイルと 1 つのドキュメントを更新します。ビルドは引き続き成功。

最終結果： 3 波、エージェント合計約 28、48 個のファイルに変更（差分で確認済み）、ファントムを 1 件検出、違反はゼロ、ビルドは成功。ロールバック用ブランチも利用可能です。