計画参照とタスク分解

引数で与えられた計画ソースを読み、子エージェントに依頼可能な粒度のタスクに分解する。

引数

• 数値(例: 42)または #42 形式 → GitHub Issue とみなし gh issue view <ID> --comments で取得
• それ以外 → 計画ドキュメントのパスとみなし Read で読む

引数がない場合はユーザーに計画ソースを質問する。

手順

0. 開始時判定(新規 or 追加)

この skill に入ったら、新規・追加のどちらのモードに関わらず、まず
agent-branch-guard skill の手順でブランチを確かめる(branch-check を実行し、
main 上やマージ済みブランチなら利用者の承認を得て develop/<作業名>-plan 等の
専用ブランチを切ってから進む)。

既存の .agents/workflow/state.json の有無と状態で分岐する:

• state.json が無い → 通常モード(§1〜§5)で新規作成する
• state.json があり、全タスクが done → まず、確認なしで
  scripts/workflow-archive(PowerShell: .agents/workflow/scripts/workflow-archive.ps1
  / POSIX: workflow-archive.sh)にスラッグを渡して実行する。スクリプトが作業ブランチの
  PR の状態を確かめ、マージ済みのときだけアーカイブする

  .agents/workflow/scripts/workflow-archive.ps1 <スラッグ>

  .agents/workflow/scripts/workflow-archive.sh <スラッグ>

  スラッグは計画ソースやIssue番号から簡潔に生成する(例: issue-42)。
  exit code ごとの次の行動:
  • exit 0 → アーカイブされた。通常モードで新規作成する
  • exit 2(Next: escalate reason=pr-open。PR が未マージ)→ 何も移動されていない。
    全タスクが done でも、PR がマージされるまでサイクルは終わっていない。
    • 計画ソースがその PR のレビューで見つかった残課題なら、追加モードで今のサイクルに追記する。
      state.json の group が空でなければ、追記するタスクに - **グループ**: <group> を付けて
      今の PR のグループに入れる
    • 別件なら、PR のマージを待つか、--force(PowerShell: -Force)でアーカイブして
      新規作成するかを利用者に確認する
  • exit 3(pr-closed)・exit 5(pr-not-created)・exit 4(gh-unavailable)→
    利用者に状況を伝え、追加モードにするか、--force でアーカイブして新規作成するかを確認する
• state.json があり、未完了タスクが残っている → 「進行中のワークフローがあるが
  破棄してよいか」をユーザーに確認する。破棄する場合も削除ではなく
  workflow-archive でアーカイブする(履歴が残るため安全に「破棄」できる)。
  利用者が破棄を承認しているので、--force を付けて PR の状態の判定を飛ばす

  .agents/workflow/scripts/workflow-archive.ps1 <スラッグ> -Force

  .agents/workflow/scripts/workflow-archive.sh <スラッグ> --force

  破棄しない場合は §「追加モード」に進む(ユーザーが途中追加を意図している場合)か、
  作業を中断する。

1. 計画の読解

計画ソースを読み、目的・スコープ・制約を把握する。関連する既存コードを Grep/Glob で
調査し、変更対象の見当をつける。

続けて、計画ソースから要件の抽出と解釈の確認を行う:

1. 要望を番号付き(R1, R2, ...)で抜き出す。1要件 = 利用者が確かめられる1つの要望
2. あいまいな点・解釈が複数ありうる点・置いた前提・対象外(意図的に外すもの)を列挙する
3. あいまいな点は、タスク分解(§2)の前に利用者に質問する。質問には、選択肢ごとの違いが
   分かる前提の説明を添える。あいまいな点が無ければ質問は省略する
4. 結果を tasks.md の ## 要件(- R1: ...)・## 前提・解釈・## 対象外 の節に書く
   (書式は README の tasks.md 節。§3 で tasks.md を生成するときに書く)

2. タスク分解

以下の基準でタスクに分解する:

• 1タスク = 子エージェントへの1回の依頼で完結する粒度(目安: 変更ファイル数個、1コミット相当)
• 子に設計判断を委ねない: 実装方法が複数ありうる箇所(プロセス境界の値の受け渡し、引用符の入れ子、
  ハッシュの計算方法、正規表現 等)は計画時に決めておく。必要なら、コードの骨格(関数シグネチャ・
  データ構造・アルゴリズムの流れ)を目的欄に書く。子が判断に迷って推論を続け、出力トークン上限に
  達して止まることがあるため
• 1タスクの受け入れ基準は5件まで、変更するファイルは3件までにする(参照ファイル欄で
  変更対象のファイルに (変更対象 という理由注記を付ける)。dispatch-prompt-gen がこれを
  超えると WARN: を出す(超過は警告のみで生成は続くが、タスクを分割できないか検討する)
• 1タスクで追加するテストケースは数件までにする。tests/test-*.sh と tests/test-*.ps1 の
  ような sh/ps1 の対については、変更が小さければ同じタスクに入れてよい。大きい場合は別タスクに
  分け、tests/case-parity-allow.txt 等にケース名を書いて一時的な sh/ps1 の差を許可する
  (sh/ps1 の対の仕組みが無い利用先では、前者だけでよい)
• スクリプトの変更とドキュメントの変更は別タスクにする。ドキュメントの変更も大きい場合は、
  ファイルごと(さらに大きいファイルは節ごと)にタスクを分ける
• 各タスクに検証可能な受け入れ基準を必ず書く(「〜が動く」ではなく「〜を実行すると〜になる」)
• タスク間の依存関係を明示し、依存順に並べる
• テスト方法が自明でないタスクには、受け入れ基準にテストコマンド・確認手順を含める
• 各タスクに参照ファイル欄を書く: 子が最初に読むべきファイルを数件(5件以内)まで、
  ルート相対のパスをバッククォートで囲んだ箇条書きで挙げる。範囲を絞れる場合は
  `path:10-40` のように行範囲を付け、括弧で読む理由(真似る既存実装・使う関数 等)を添える。
  読ませるものが無ければ - **参照ファイル**: なし と書く。dispatch-prompt-gen が、存在しない
  パスをエラー(exit 1)、欄が無い・6件以上を警告にする。子は参照ファイル以外を必要になってから
  読むよう指示されるため、README 全体のような大きいファイルは挙げず、該当の節に範囲を絞る
• 外部コマンドの挙動は事実で書く: 受け入れ基準や目的に外部コマンド(gh・git 等)の出力・
  exit code を書くときは、「〜相当」「〜のはず」のような推測を誘う表現を使わず、計画時に実際に
  実行して確かめた結果を書く(例: 「gh pr list --head <branch> --state merged --json url は
  PR が無いとき [] を出力して exit 0」)。子は書かれていない挙動を確かめようとして
  プロジェクト外で試し、権限拒否で止まることがある
• タスク数が多い場合は、意味的なまとまり(機能グループ)ごとにタスクを並べ、グループ境界を
  厳密フォーマットの区切り行で示す:
  <!-- グループ <名前>: <説明> -->(: <説明> は省略可。<名前> は空白と : を
  含まない文字列。大文字小文字を区別する)。区切りが無い領域のタスクは既定グループ
  (空の名前)に属する。依存関係の記述だけで十分に整理できている場合は無理にグループ化
  しなくてよい。このグループ境界は agent-workflow skill の「グループ単位の PR と
  ブランチ切替」で PR 作成・ブランチ切替の機械的な単位として使われる
• グループ間依存の制約: タスクが依存できるのは同じグループまたは前のグループの
  タスクのみ(後のグループのタスクへの依存は、そのタスクが永久に実行できないため、
  state-sync / next-task がエラー(exit 1)にする)

依存欄の指針:

• 機械パース可能な厳密フォーマットを厳守する: - **依存**: なし | T1, T2
  (依存が無い場合は なし、ある場合はカンマ区切りのタスクID列。この行を
  state-sync / next-task / dispatch-prompt-gen が機械的にパースするため、フォーマットを崩さない)
• 依存欄に注記を書かない: T30(Prometheus 基盤。完了済み) のような括弧書き・状態の説明は
  書かない。前提タスクについての補足(何を使うか等)は目的欄に書く。タスクの完了状態は
  state.json で機械的に判定されるため、依存欄にも目的欄にも書かない
• 依存行はすべてのタスクに必須(依存が無い場合も - **依存**: なし と書く)
• 形式違反・tasks.md に存在しないタスクID・自分自身への依存・循環依存は、state-sync が
  state.json を作る前にエラー(exit 1)にする。エラーになったら stderr の内容に従って
  tasks.md を直し、再実行する
• 依存は真の前提となるタスクのみ記載する。単に記述の並び順を揃えたいだけの理由で
  依存を張らない
• 依存欄 = 引き継ぎが発生する欄であることを踏まえる: 依存に挙げたタスクの完了報告
  (runs/<依存ID>-<試行番号>/report.md)が dispatch 時に自動結合される。不要な依存を
  書くと不要な引き継ぎ文がプロンプトに混入し、依存漏れがあると引き継ぎガードで
  dispatch が止まる(依存タスクが done かつ報告が存在することが条件)。グループ区切りを
  使う場合は、依存先は同じグループまたは前のグループのタスクに限る(「グループ間依存の
  制約」を参照)

要件欄の指針(## 要件 節を書いた場合):

• 各タスクに - **要件**: R1, R3(カンマ区切りの要件ID)または - **要件**: なし を書く。
  なし は、要件に直接対応しないタスク(例: 他タスクの前提となる基盤整備、後始末)に使う
• どのタスクにも対応しない要件があると、state-sync がエラー(exit 1)にする。タスクを足すか、
  意図的に外す要件なら ## 要件 節から消して ## 対象外 に移す
• 要件欄の欠落、## 要件 節に無いIDもエラーになる(詳細は README の「要件の節と要件欄」)

3. ファイル生成

.agents/workflow/README.md に記載のフォーマットに従って生成する(.agents/workflow/README.md が存在しない場合は .agents/skills/_templates/workflow/README.md（配布元リポジトリではルートの _templates/workflow/README.md）を参照する。本来は /agents-md-setup の再実行で .agents/workflow/README.md が配置されるため、利用先で欠落している場合はセットアップ手順を見直すこと):

• .agents/workflow/tasks.md — タスク定義の正本(子エージェントも参照する)。LLMが
  生成するのはこのファイルのみ

• .agents/workflow/state.json — LLMは生成しない。tasks.md を書き終えたら
  scripts/state-sync(PowerShell: .agents/workflow/scripts/state-sync.ps1 / POSIX:
  state-sync.sh)を --init オプションで実行し、機械生成する。--source には
  計画ソース(Issue URL やドキュメントパス)を渡す。branch は git から自動取得される

  .agents/workflow/scripts/state-sync.ps1 -Init -Source "<計画ソース>"

  .agents/workflow/scripts/state-sync.sh --init --source "<計画ソース>"

  実行後、全タスクが "status": "pending", "retries": 0, "commit": null で
  初期化された state.json が生成される。state.json が既に存在する場合はエラー
  終了する(§0 の分岐で新規作成が確定している状態でのみ実行すること)。

4. 進捗表示への登録(任意)

親エージェントに進捗表示用のタスク機能がある場合だけ(例: Claude Code の TaskCreate)、各タスクを登録する。無い場合はこの手順を
飛ばす(正本はファイル側)。

5. ユーザー承認

提示前のセルフチェック: 分解結果を提示する前に、各タスクが §2 の目安を満たすかを
一覧に照らして確かめる。

• 照らす目安: 設計判断を子に委ねていないか(実装方法が複数ありうる箇所を計画時に
  決めているか)、受け入れ基準が5件までか、(変更対象 の理由注記を付けた変更対象
  ファイルが3件までか、追加するテストケースが数件までか、スクリプトの変更と
  ドキュメントの変更が分かれているか
• dispatch-prompt-gen <ID> を実行して WARN: を出す方法は、state.json を作った後
  (§3 の後)でないと使えない上に、runs/<ID>-1/prompt.md を書き出してしまうため
  このチェックでは使わない。§2 の目安を一覧にして各タスクを照らすこと
• 満たさないタスクは、提示の前に分割・修正しておく
• 提示する一覧には、各タスクの受け入れ基準の件数と変更対象ファイルの件数を添える

提示の中心は「要件 → タスク」の対応表にする。## 要件 節がある場合、表は state-sync の
stdout の Requirement 行(Requirement R1: T1, T3 / Requirement なし: T5)から作る
(要件の本文は tasks.md の ## 要件 節から取る)。表に続けて、## 前提・解釈 と ## 対象外 の
内容を示し、その後に各タスクの受け入れ基準の件数と変更対象ファイルの件数を添える。
利用者は、要件の取りこぼしや解釈の違いを対応表で確かめて承認する。

対応表と分解結果(タスク一覧と受け入れ基準)を提示し、承認を得る。修正を求められた場合は
tasks.md を直し、state-sync(--init なし)で state.json を同期してから再提示する。
タスクの見出し(タイトル)を修正した場合も同期対象で、tasks.md に合わせて state.json の
title が更新される(変更があったタスクごとに Updated title: <ID> が出力される)。

6. 計画のコミット

承認後、次フェーズ(/agent-dispatch または /agent-workflow のループ)に進む前に、
tasks.md と state.json をコミットする。agent-dispatch の事前チェックは作業ツリーが
クリーンであることを求めるため、コミットしないと最初の dispatch で止まる。

git add .agents/workflow/tasks.md .agents/workflow/state.json
git commit -m "chore: <計画ソース> のタスク計画を作成"

• 一巡後のアーカイブ(§0)で旧 tasks.md / state.json を退避した場合も、同じコミットに含まれる
  (同じパスのファイルが新しい内容に置き換わるため)
• .agents/ を追跡していないリポジトリ(本ワークフローの配布元など)ではコミット対象が無いので、
  この手順は不要

追加モード(タスクの途中追加)

サイクル途中でレビューにより派生タスクが見つかった場合や、ユーザーが要件を
追加した場合に使う。LLM は既存タスクを一切書き換えず、追記のみで完結させる
(既存タスクの間に挿入する場合も、既存タスクの依存欄の書き換えはスクリプトが行う)。

追加モードの作業自体もファイル変更・コミットを伴うため、まず
agent-branch-guard skill の手順でブランチを確かめる
(main 上やマージ済みブランチなら専用ブランチを作ってから進む)。
専用ブランチを作った場合は、state-sync --set-branch で state.json の branch を
更新してから追記を始める。

1. 新IDの採番: .agents/workflow/state.json から既存の最大タスクID
   (例: 既存最大が T7 なら次は T8)を取得する。tasks.md 全文は読み直さない
   (state.json だけで採番が完結する)

2. 追記専用: .agents/workflow/tasks.md の末尾に、新IDのセクションのみを
   §2 と同じ基準(検証可能な受け入れ基準・依存欄の厳密フォーマット・グループ間依存の
   制約・要件欄)で追記する。既存セクションには一切触れない
   (例外: 新しい要件が出た場合は、## 要件 節の末尾に次の番号(既存の最大が R4 なら R5)で
   - R5: ... を追記してよい。既存の要件行は書き換えない。追記するタスクにも要件欄を書く。
   また、要件の充足確認で合意した対象外は、## 対象外 節の末尾に追記してよい。既存行は書き換えない)
   追記タスクの所属グループは記述位置で決まる(tasks.md 上の最後の区切りのグループ)。
   現在の作業グループ(state.json の group)など別のグループに属させたい場合は、
   タスク欄に - **グループ**: <名前>(区切り行で宣言済みのグループ名)を書く
   (この欄が位置より優先される)。既定グループは名前が空文字列のためこの欄では
   参照できない(空欄は state-sync がエラーにする)。未宣言の名前もエラーになる。
   挿入モードで tasks.md 末尾に追記したセクションも同じ扱いである

3. 依存: 既存タスク(done 済みタスクも含む)を依存先にしてよい。done
   タスクへの依存は、引き継ぎガードが report.md の存在を保証しているため
   問題なく解決できる

4. state.json への反映: state-sync を --init なしで実行し、追加分のみを
   pending として追記する(既存タスクの status / retries / commit は
   一切変更されない)

   .agents/workflow/scripts/state-sync.ps1

   .agents/workflow/scripts/state-sync.sh

   既存タスクの間に挿入する場合(例: T3 → T4 の間に T8 を挟み、T4 を T8 の完了後に
   実行したい場合)は、--insert <新ID> --before <後続ID> を付けて実行する。
   スクリプトが後続タスクの依存欄に新IDを追加する(例: T4 の T3 → T3, T8)。
   新タスク自身の依存欄(例: T3)は手順2で LLM が書く。--before にはカンマ区切りで
   複数の後続タスクを指定できる

   .agents/workflow/scripts/state-sync.ps1 -Insert T8 -Before T4

   .agents/workflow/scripts/state-sync.sh --insert T8 --before T4

   • 書き換えてよいのは pending の後続タスクだけ。done / in_progress /
     in_review / failed のタスクを --before に指定すると拒否される(exit 1)
   • 循環依存になる挿入(例: T8 が T4 に依存しているのに T4 の前に挿入する)も拒否される。
     拒否された場合、tasks.md と state.json は変更されない
   • タスクの実行順は tasks.md の記述順や ID 順ではなく依存関係で決まる。挿入した T8 は
     state.json の末尾に追加されるが、next-task が依存関係に従って T4 より先に選ぶ

5. 進捗表示への登録(§4。任意)も追加分のみ行う(既存タスクの再登録はしない)

6. ユーザー承認も追加分のみ提示する(既存タスク一覧の再提示はしない)。§5 と同様に、
   追加分の「要件 → タスク」の対応表(追加した要件と追加したタスクの行だけ)を中心に示す

7. コミット: 承認後、§6 と同様に tasks.md と state.json をコミットする
   (chore: <追加したタスクID> を追加。挿入した場合は chore: <新ID> を <後続ID> の前に挿入)。
   dispatch 前に作業ツリーをクリーンにするため

このモードでの親のLLM出力は「追加するタスクのセクション」だけに限る。既存部分の
再読・再出力・state.json の手書き編集は行わない。