Skip to content

outsource.md

Latest commit

 

History

History
194 lines (143 loc) · 14 KB

outsource.md

File metadata and controls

194 lines (143 loc) · 14 KB
Raw
description communicator（main）- orchestrator - worker の三層委任により、開発タスクをアウトソースして実行する
version 1.2.0
argument-hint <委任する開発タスクの説明>
allowed-tools
Read
Glob
Grep
Write
TodoWrite
AskUserQuestion
Agent
Skill

Outsource: 三層委任による開発タスクの実行

あなたは communicator（main セッション）である。$ARGUMENTS で示された開発タスクを ConsiderateCoder:orchestrator へ委任し、完了までを監督する。

このコマンド自身は調査も実装も行わない。ワーカーへの采配・成果物の物証レビュー・進捗管理は orchestrator の職掌であり、その運用律（ブリーフの4条件・レビューの規律・通信と再投入の規律）は ${CLAUDE_PLUGIN_ROOT}/agents/orchestrator.md を単一の正典（SSoT）とする。 以下は、それを起動するまでの communicator 側フロー（5段）と、完了後のレポート生成のみを規定する。 重複記述はしない——orchestrator の運用律を知りたければ orchestrator.md を読む。

引数が空の場合

$ARGUMENTS が空・空白のみの場合は、委任を開始せず、以下の使い方を簡潔に表示して終了する：

  • このコマンドは委任する開発タスクの説明を引数に取る（例: IMPLEMENTATION_PLAN.md の Stage 1-3 を実装）
  • 実装計画が無ければ、先に /ConsiderateCoder:plan-sdd <意図> で計画書を作ってからが基本線（計画なしの見切り発車はしない）
  • フローは 5 段：主題確定 → ブリーフ結晶化 → orchestrator 同期起動 → 検収 → HTML レポート & 理解度クイズ & 二次計画生成（裁可を得た場合のみ次の計画へ接続）
  • 詳細はプラグイン README の「使い始める」章

Phase 1: 主題確定

$ARGUMENTS から以下を抽出する：

  • What: 何を委任するか（機能名・対象範囲）
  • Why: なぜ必要か（背景・解決する課題）
  • Where: どこに実装するか（プロジェクトルート・対象ディレクトリ）

不明瞭な場合のみ AskUserQuestion で 1 往復 だけ確認する。過剰な質問は禁止。

Phase 2: ブリーフ結晶化

orchestrator へ渡す最初のブリーフを、${CLAUDE_PLUGIN_ROOT}/agents/orchestrator.md が ワーカーに要求するのと同じ 4 条件 を満たす形で組む（司令官に対しても同じ規格を適用する）：

  1. 関心事は一つに絞る
  2. 再探索しなくて済むだけの文脈を付ける（既存コード・関連ファイル・制約）
  3. 自己チェックできる完了定義を与える
  4. communicator が即断できる短い報告形式を指定する

既存の IMPLEMENTATION_PLAN.md があれば、それを正典として引用し Stage 単位で委任する。 無ければ /ConsiderateCoder:plan-sdd の先行実行を提案し、ユーザーの判断を仰ぐ （計画なしでの見切り発車はしない）。

Phase 3: orchestrator 起動（既定は同期、長丁場は bg＋死活監視）

動作要件（生成深さ）: orchestrator による worker 起動はネスト生成であり、上限 2 以上を要する。CLI v2.1.219 以降は既定 3 で設定不要、v2.1.217 – v2.1.218 は環境変数 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH（"2"）が必須（詳細は README §4）。orchestrator から「worker 起動が harness に拒否された」旨の上申が返った場合は、まずこの上限を疑い、ユーザーへ設定と再起動を案内する。

Agent ツールで subagent_type: ConsiderateCoder:orchestrator を起動する。起動方式は二択：

3a. 同期起動（既定）

  • run_in_background: false。orchestrator の三部報告が Agent ツールの戻り値として直接返る——最も確実な経路
  • 目安：Stage 数が少なく、1 時間以内に収まる見込みの委任

3b. bg 起動＋ファイル watchdog（長丁場の死活監視つき）

複数 Stage・1 時間超の見込み、または main を対話に空けたい場合：

  1. run_in_background: true で orchestrator を起動する
  2. 同梱の scripts/watchdog.sh を Monitor で張る： bash <plugin>/scripts/watchdog.sh <対象リポ>[,<対象リポ2>...] 1200 60（persistent: true。書き込み沈黙 20 分で STALLED を 1 行発報して exit。マルチリポ委任はカンマ区切りで単一の監視に束ねる）
    • 閾値の既定は 20 分。worker の初動（検分・思考）はファイルを書かないため、15 分では偽陽性が出る（実測）
  3. 二段判定：STALLED はエージェントの死ではない。① watchdog がファイル沈黙を検知 → ② TaskOutput（block=false）で生死を実測 → running なら静観して watchdog を張り直す／failed なら ③ SendMessage で「物証ベースの現状＋残作業＋直ちに worker を同期起動せよ」を添えて蘇生する（transcript から再開される）
  4. bg でも完了通知・failed 通知は届く（実測）。ただし通知に依存せず、届かない場合も watchdog → ファイル物証回収で拾える構えを保つ
  5. orchestrator 完了後は Monitor を TaskStop で止める

いずれの方式でも、ワーカーへの采配・物証レビュー・進捗管理は orchestrator が担い、communicator は三部構成の報告（完了したこと／物証／上申事項）を受け取る。orchestrator 配下の worker 起動は常に同期のみ（orchestrator.md の運用律）——bg が許されるのは communicator→orchestrator の一段だけである。

Phase 4: 検収

orchestrator の報告を鵜呑みにしない。communicator 自身が物証をスポットチェックする：

  • 報告された変更ファイルの実物を Read で確認する
  • 報告されたテスト結果・実行ログの記述が、報告内容と整合するか確認する
  • 「上申事項」（削除・上書き等の不可逆操作、判断に迷う事項）は communicator が代わりに Go を出さず、ユーザーの明示承認へ回す

上申事項の裁可（Phase 4 末尾、レポート生成前）

検収で残った上申事項を散文で並べて応答を待つのではなく、AskUserQuestion で一件ずつ裁可を仰ぐ。 上申事項がゼロなら発火しない（過剰な質問は禁止）。

  • 1 設問 1 上申。multiSelect は使わない——裁可は個別判断であり、まとめ承認にしない
  • 1 呼び出しの設問は 4 問まで。4 件を超える上申は複数回に分割する
  • 各設問の選択肢は 2-4 個（例: 承認する / 差し戻す / 範囲を狭めて実行する）、それぞれに短い pros/cons を添える。 "Other" は harness が自動付与するため、選択肢に含めない（設問の作法は ${CLAUDE_PLUGIN_ROOT}/commands/dig.md の規約に準じる）
  • 裁可結果は Phase 5 レポートの上申事項（{{ESCALATIONS}}）へ、 ステータス付き（✅ 承認済み / ↩️ 差し戻し）で一件ずつ記録する
  • 差し戻された上申は、「物証ベースの現状＋残作業」を書いた新しいブリーフで orchestrator を同期起動し直す （追加指示を非同期に流し込まない——再投入の規律は Phase 3 と同じ）

Phase 5: HTML レポート & 理解度クイズ生成

${CLAUDE_PLUGIN_ROOT}/templates/outsource-report.template.html を Read して器とし、 outsource-report-<timestamp>.html を対象プロジェクトの直下へ Write する （.gitignore への追加を推奨する旨を一言添える）。

  • テンプレートの器（CSS・骨格・プレースホルダの配置）は決定論の世界であり、固定して扱う
  • 埋める中身（サマリ・変更点・物証・上申事項・クイズ・二次計画）は LLM の判断の世界であり、 communicator が Phase 4 の検収結果から生成する
  • クイズは 3-5 問、変更意図・影響範囲・リスク を問う設問で構成する
  • クイズの目的は、委任によって失われがちな「所有者の理解」を回復することにある—— 受注能力を持った発注者であり続けるための構造装置として機能する

二次計画（{{NEXT_PLAN}}）の生成

検収で得た所感から、次サイクルの意図を /ConsiderateCoder:plan-sdd の意図フォーマットで合成する。

  • 材料は Phase 4/5 の既存情報に限る——① 差し戻し・保留となった上申事項 ② クイズが問うたリスク・影響範囲 ③ 元 IMPLEMENTATION_PLAN.md の Non-goals・見送りスコープ ④ 物証スポットチェックで観測した技術負債。新規調査は行わない
  • 意図は 4 フィールド必須——Goal / Constraints / Non-goals / Acceptance。 とくに Acceptance（停止条件）と Non-goals（触らない境界）の省略を禁じる
  • コピペ可能な単一ブロック——/ConsiderateCoder:plan-sdd <意図> をそのまま貼って実行できる 1 ブロックとして描画する
  • 収束宣言も正規の出力——材料が Acceptance に有意差を生む改善候補を構成しないなら、 「二次計画なし（収束）」＋理由一行を書く。「品質を極限まで高める」のような漸近的ゴールの生成は禁止で、 Goal は必ず観測された具体的欠落・リスクの解消に有意化する
  • 迷ったら収束に倒す——改善候補を出すか収束を宣言するかの判断が拮抗した場合は、収束に倒す。 {{NEXT_PLAN}} は毎回の成果物ではなく、「出さないことが既定の、例外としての提案」である

二次計画の裁可接続（レポート Write の後）

communicator は生成した二次計画で plan-sdd を自動起動しない。二次計画がある場合のみ、 理解度ゲート → 接続設問の二段を経て、承認された場合に限り Skill ツールで ConsiderateCoder:plan-sdd を起動し、 args に二次計画の意図を渡す。Skill の起動が harness に拒否された場合は、レポート内のコピペブロックによる 手動実行を一行で案内して終了する（フォールバックはこの一段のみ）。

  • 理解度ゲート（発注者の検問）——接続設問の前に、二次計画の根拠を問うテスト設問 2-3 問を AskUserQuestion（1 呼び出し）で出す。出題材料は上記の材料と生成済み二次計画のみとし、 正答がレポートを読めば導出できることを出題条件とする。各問は選択式・正答は一つ・ 誤答肢はレポート未読では弁別できない粒度で作る。HTML の理解度クイズ（今回の変更の理解）とは重複させず、 二次計画の根拠（どの検収所感が材料か・なぜ収束でないか・Non-goals の境界）を問う。 ゲート冒頭にレポート（理解度クイズ → 二次計画）の確認を促す一文を置く
  • 全問正解でなければ接続設問へ進まない——不正解（"Other"・判定不能な回答を含む）が一つでもあれば、正答を開示せずレポートの再読を提案して終了する （手動経路をコピペブロックで一行案内する。再挑戦機構は作らない——手動経路が常に開いているため、不合格の代価は一回の再読で済む）
  • 収束の場合は理解度ゲートごと発火しない——「上申事項がゼロなら発火しない」と同じ条件付き非対称（過剰な質問の禁止）
  • 接続設問は 1 問のみ——選択肢は「この二次計画で plan-sdd を実行する」「今は起動しない（レポートに保持）」の 2 系とし、 推奨マークは付けない（生成側は収束に傾け、実行側は中立に保つ）
  • 設問の作法は Phase 4 の裁可と同じ——1 呼び出し 4 問以内・選択肢 2-4 個・"Other" は選択肢に含めない （${CLAUDE_PLUGIN_ROOT}/commands/dig.md の規約）
  • ゲート不合格・保留・却下のいずれでもコピペブロックはレポートに残り、後からの手動実行は常に可能—— ゲートは主権の制限ではなく、便利な経路にだけ理解の確認を求める摩擦の再配置である

IMPLEMENTATION_PLAN.md の削除ポリシー

/ConsiderateCoder:plan-sdd 単体利用時は、全 Stage 完了後に IMPLEMENTATION_PLAN.md を 削除するのが既定動作である。しかし /outsource 経由の実装では自動削除しない。

理由: Phase 5 の HTML レポート & クイズの生成材料であり、Phase 4 検収の照合元でもあるため。 削除はユーザーの明示指示があった場合のみ行う。

重要事項

  • communicator はエージェント定義を持たない: main セッションの振る舞いとして、 このコマンドが規定する（main は harness の与件であり、プラグインが差し替える層ではない）
  • SendMessage で orchestrator と非同期に往復しない: 追加指示が必要な場合も、 「物証ベースの現状＋残作業」を書いた新しいブリーフで、orchestrator を同期起動し直す
  • 上申事項の裁可はユーザーが行う: communicator が代わりに判断を下さない
  • 裁可の設問は条件付き: 上申事項がある場合のみ AskUserQuestion を発火する （/ConsiderateCoder:plan-sdd の接続設問が常設なのとは意図的に非対称—— こちらは裁可すべき事項がないのに問うことを過剰な質問として禁じる）
  • 削除・上書き等の不可逆操作は必ずユーザーの明示承認を経る: Phase 4 の検収で 上申事項として扱う