counselors

Counselors — マルチエージェントレビューのスキル

プロンプトを複数の AI コーディングエージェントに並列で送信し、回答を統合します。

引数：$ARGUMENTS

引数が指定されていない場合は、レビューする内容をユーザーに尋ねます。

---

フェーズ 1：コンテキストの収集

$ARGUMENTS を解析し、ユーザーが何をレビューしたいのかを把握します。その後、関連するコンテキストを自動で収集します。

1. プロンプト内で言及されたファイル：Glob/Grep を使って、名前、クラス、関数、キーワードで参照されているファイルを検索します
2. 最近の変更：git diff HEAD と git diff --staged を実行し、最近の作業内容を取得します
3. 関連コード：プロンプト内の主要な語句を検索し、最も関連性の高いファイルを読み込みます（最大 5 ファイル、合計約 50KB まで）

取捨選択してください。コードベース全体を出力してはいけません。最も関連性の高いコード箇所を選んでください。

---

フェーズ 1b：Context7 による古さのスキャン

プロジェクトの主要なテクノロジーを、package.json、CLAUDE.md、tsconfig.json、または設定ファイルから特定します（フェーズ 1 のコンテキストから明らかな場合を除く）。主要なライブラリ／フレームワークを最大 5 つまで選び、次の手順を行います。

1. mcp__plugin_compound-engineering_context7__resolve-library-id — Context7 のライブラリ ID を取得します
2. mcp__plugin_compound-engineering_context7__query-docs — API、設定、破壊的変更に焦点を当てた関連スニペットを 2～3 件取得します

制限：

• 参照ドキュメントの合計は約 8,000 トークンまでにします。上限を超える場合は、関連性の低いスニペットを削ります。
• Context7 でライブラリが見つからない場合は、REFERENCE DOCUMENTATION ブロックに [library name] (docs not verified) のような行を追加して続行します。
• コンテキストから特定のライブラリを識別できない場合は、このフェーズ全体をスキップします。

エントリーごとにライブラリ名とバージョンを記載した REFERENCE DOCUMENTATION ブロックを作成します。このブロックはフェーズ 3 のプロンプトに含まれ、レビュー担当者が古いパターンを指摘するために使用されます。

---

フェーズ 2：エージェントの選択

デフォルトのエージェント： or-claude-opus、or-gemini-3.1-pro、or-codex-5.4

1. ユーザーが変更を指定しない限り、デフォルトを使用します。 $ARGUMENTS にエージェント選択の指示（例：「すべてのエージェントを使用」「codex を追加」「gemini のみ」）が含まれていない場合は、デフォルトのまま確認手順に進みます。

2. ユーザーが別のエージェントを指定した場合（$ARGUMENTS または追加のやり取りで）、Bash 経由で実行して利用可能なエージェントを確認します。

   counselors ls
   

   出力全体を表示してから、AskUserQuestion を使ってユーザーに選択してもらいます。

   エージェントが 4 つ以下の場合：multiSelect: true を指定した AskUserQuestion を使い、エージェントごとに 1 つの選択肢を用意します。

   エージェントが 4 つを超える場合：AskUserQuestion で指定できる選択肢は 4 つまでです。次の固定選択肢を使用します。

   • 選択肢 1：「すべての [N] エージェント」— 設定済みのすべてのエージェントに送信します
   • 選択肢 2～4：ID 順で最初の 3 つの個別エージェント
   • ユーザーはいつでも「その他」を選び、上記の表示済みリストからエージェント ID をカンマ区切りで入力できます

   エージェントをプリセットのグループ（例：「claude + codex + gemini」）にまとめてはいけません。各選択肢は、単一のエージェントまたは「すべて」でなければなりません。

3. 必須：続行前に選択内容を確認します。 ディスパッチする正確なリストをそのまま伝えます。

   ディスパッチ先：or-claude-opus、or-gemini-3.1-pro、or-codex-5.4

   その後、先に進む前にユーザーに確認を求めます（例：「この内容でよろしいですか？」）。これにより、ツールの指定漏れを防げます。ユーザーがリストを修正した場合は、それに応じて選択を更新します。

---

フェーズ 3：プロンプトの組み立て

1. トピックからスラッグを生成します（小文字、ハイフン区切り、最大 40 文字）。

   • 「認証フローをレビューする」→ auth-flow-review
   • 「この移行は安全か」→ migration-safety-review

2. Bash 経由で出力ディレクトリを作成します。実行結果を辞書順で並べ替えられ、重複しないよう、ディレクトリ名には必ず秒精度の UNIX タイムスタンプを先頭に付けます。

   ./agents/counselors/TIMESTAMP-[slug]
   

   例：./agents/counselors/1770676882-auth-flow-review

   Mac のヒント： date +%s（エポックからの秒数）で生成します。GNU coreutils を使わない macOS の date ではミリ秒精度を利用できません。移植性のある秒精度のタイムスタンプには date +%s を使用してください。

3. Write ツールを使用して、プロンプトファイルを ./agents/counselors/TIMESTAMP-[slug]/prompt.md に書き込みます。

# Review Request

## Question
[User's original prompt/question from $ARGUMENTS]

## Context

### Files Referenced
[Contents of the most relevant files found in Phase 1]

### Recent Changes
[git diff output, if any]

### Related Code
[Related files discovered via search]

## Reference Documentation
[Phase 1b content — current library docs from Context7. If Phase 1b was skipped, omit this section.]

## Instructions
You are providing an independent review. Be critical and thorough.
- Analyze the question in the context provided
- Identify risks, tradeoffs, and blind spots
- Suggest alternatives if you see better approaches
- Be direct and opinionated — don't hedge
- Structure your response with clear headings
- Flag any code patterns that appear outdated vs. the Reference Documentation above

---

フェーズ 4：ディスパッチ

ディスパッチする前に、ユーザーに次のように伝えます。

「[N] 個のエージェントにディスパッチしています：[list]。通常、完了まで 2～5 分かかります……」

作成したプロンプトディレクトリのパス（例：./agents/counselors/1772865337-auth-flow-review/）を記録します。counselors CLI は、秒単位のタイムスタンプのサフィックスが付いた兄弟出力ディレクトリを作成します。

プロンプトファイルを指定し、ユーザーが選択したエージェントを渡して、Bash 経由で counselors を実行します。

set -a; for f in ~/.env .env ~/.vibe-tools/.env; do [ -f "$f" ] && source "$f"; done; set +a; counselors run -f ./agents/counselors/[slug]/prompt.md --tools [comma-separated-selections] --json

環境変数を読み込む理由： Claude Code の Bash ツールは、ユーザーの対話型シェルから API キー（例：OPENAI_API_KEY）を継承しない場合があります。set -a と source を組み合わせる方法では、標準的な dotenv ファイルから移植性のある形でキーを読み込めます（bash、zsh、sh で動作します）。存在しないファイルはエラーを出さずにスキップされます。

例：--tools claude,codex,gemini

Bash の timeout: 480000（8 分）を使用します。ツールは並列で実行されます（順次実行ではありません）。counselors の設定にあるツールごとのタイムアウトによって、各ツールの実行時間が制御されます。

重要： -f（ファイルモード）を使用して、プロンプトをラップせずそのまま送信します。構造化された出力を解析できるように、--json を使用します。

---

フェーズ 5：結果の読み込み（ファイルシステムベース — stdout に依存しません）

重要： JSON の stdout だけに頼らないでください。CLI は、すべてのツールが完了した後にのみ run.json を書き込み、JSON を出力します。ツールがハングした場合やプロセスが強制終了された場合、stdout は空になります。必ずファイルシステムをスキャンして確認してください。

ステップ 1：出力ディレクトリを探します。

ls -dt ./agents/counselors/[slug]-*/ 2>/dev/null | head -1

ディレクトリが見つからない場合、CLI はディスパッチ前に失敗しています。ユーザーに伝え、counselors doctor の実行を提案してください。停止します。

ステップ 2：run.json を確認します（正常終了の場合）。 run.json が存在する場合は、解析します。

• status: "success" かつ wordCount > 0 — 正常に成功
• status: "timeout" — ツールがタイムアウトに達した
• status: "error" — ツールがクラッシュした
• status: "success" かつ wordCount: 0 — サイレント失敗（.stderr を読み込みます）

ステップ 3：run.json がない場合は、個別のファイルをスキャンします。 想定される各ツールについて、{tool-id}.md が存在し、サイズが 0 より大きいか確認します。エラーの詳細は {tool-id}.stderr で確認します。

ステップ 4：ユーザーに報告します。

• すべてのツールが出力を生成した： フェーズ 6 に進みます。
• 一部のツールが出力を生成した： 失敗したツールとその理由をユーザーに伝え、次のように尋ねます。「[M] 件中 [N] 件の回答で続行しますか、それとも再試行しますか？」
• 出力を生成したツールが 0 個： エラーを報告します。counselors doctor の実行を提案します。停止します。

---

フェーズ 6：統合して提示

すべてのエージェントの回答を統合します。

## Counselors Review

**Agents consulted:** [list of agents that responded]

**Consensus:** [What most agents agree on — key takeaways]

**Disagreements:** [Where they differ, and reasoning behind each position]

**Key Risks:** [Risks or concerns flagged by any agent]

**Blind Spots:** [Things none of the agents addressed that seem important]

**Recommendation:** [Your synthesized recommendation based on all inputs]

---
Reports saved to: [output directory from manifest]

この統合結果をユーザーに提示します。個別のレポートは詳しい確認用に保存されているため、簡潔にまとめてください。

---

フェーズ 7：対応（任意）

統合結果を提示した後、ユーザーに何に取り組みたいか尋ねます。統合結果から、実行可能な項目を上位 2～3 件、選択肢として提示してください。ユーザーが調査結果に基づいて対応したい場合は、変更を加える前に実装を計画します。

---

エラー処理

• counselors がインストールされていない：ユーザーにインストールするよう伝えます（npm install -g counselors）。
• ツールが設定されていない：counselors init または counselors add を実行するよう伝えます。
• 出力ディレクトリが作成されていない：ディスパッチ前に CLI が失敗しています（設定の誤り、バイナリの欠落など）。Bash 呼び出しの stderr を確認します。
• 出力ディレクトリは存在するが run.json がない：すべてのツールが完了する前に CLI が強制終了されています。個別の .md ファイルを検索します。完了したツールの出力は書き込まれています。部分的な失敗で最もよくあるパターンです。
• サイレントな失敗（status: "success" だが wordCount: 0、または .md ファイルが 0 バイト）：.stderr ファイルを読み取ります。よくある原因は、API キーの期限切れ、402 の支払い要求、レート制限です。
• 単一のエージェントが失敗：その旨を記録し、残りの回答を続行するか再試行するか、ユーザーに確認します。
• すべてのエージェントが失敗：.stderr ファイルに記載された各エラーを報告します。counselors doctor の実行を提案します。統合には進みません。
• 無期限に待機しない：8 分の Bash タイムアウトが上限です。sleep／再試行ループを追加しないでください。