---
name: wi-standards
description: >
  AWI又はUWIの起草、読解、採否、状態判断及び投入時に起動し、
  人間向けキュー項目の共通契約を提供する。
---

# AWIとUWIの共通規範

AWIとUWIは、ユーザーとエージェントが非同期に作業要求と確認事項を共有する人間向け文書である。
AWIは未完了の作業要求を、UWIは人間の入力がなければ元の作業を再開又は確定できない確認事項を表す。
回答不要の通知、完了報告、別項目の完了待ち及び時間経過待ちをUWIにしない。

本文は`agent-toolkit:writing-standards`に従い、技術的な実装へ寄り過ぎず、単独で対象と期待結果を特定できる粒度で書く。

## 型と計画

- `normal`はレビュー済み計画が関連していないAWI、`plan`はレビュー済み計画が関連するAWIである。
- 変更量にかかわらず、全ての実装要求は実装前に計画と計画レビューを完了する。`normal`を計画なしで実装しない。
- `agent-toolkit:plan-and-add-awi`は、自然言語要件から新しい`inbox(plan)`を作成する経路と、既存の`inbox(normal)`を`hold(normal)`へ移して同じ項目を`inbox(plan)`へ変換する経路を持つ。
- 計画ファイルと同じstemの付属ファイルは、実行レビューが収束するまで計画作業root`~/.claude/plans`の直下で更新する。private-notes配下の計画ファイルを編集せず、保存先への移動は`atk plans commit`だけが行う。
- `plan_file`へは、計画の作成時点で保存先を指す可搬値`$(atk config get private_notes)/plans/yyyy/MM/<メイン計画ファイル名>`を書く。計画ファイルの実体が計画作業rootと保存先のどちらにあっても同じ値が同じ計画を指すため、保存先への移動後も値を書き換えない。

## 通常AWIの本文

通常AWIは次の順序で記載する。H1は提案又は依頼の要約とし、各項目は本文だけで判断できる具体性を持たせる。

```markdown
# <提案又は依頼の要約>

- 反映内容: <何をどう変えるか>
- 反映先: <対象リポジトリ、文書、機能など>
- 理由: <観測事象、要件又は根拠>
- 適用範囲: <エージェント由来では必須。誤りの機構が依存する条件と、観測事象と表面構造が異なる該当例1件以上>
- メリット: <採用時に得られる効果>
- デメリット: <費用、副作用又は「なし」>
- 完成条件: <変更後に消費主体が達成できる状態と、消費主体へ要求する操作又は要求しない操作>
```

`source`を持つエージェント由来の通常AWIは`適用範囲`を必須とし、`理由`の次へ置く。
誤りの機構が依存する条件と、観測事象と表面構造が異なる該当例を1件以上書く。
観測事象のファイル名、工程名又は識別子が条件へ現れる場合は、機構が当該属性へ依存する根拠を併記する。
人間由来の本文には`適用範囲`を要求しない。

`完成条件`には、実装方式ではなく外部可視の終了状態を一意に書く。
複数の実装方式を許容する場合も、達成する状態と消費主体へ要求する操作の要否は一意にする。
完成条件を確定できない本文は登録しない。

`反映先`が配置規約を持つ対象である場合は、当該配置規約の正本を起草前にSkill機能で起動し、その判定を適用して反映先を確定する。
配置規約を持つ対象とは、置き場所の選択によって読み込み契機又は適用範囲が変わる文書群及びコード群を指す。
規範文書では常時読み込まれる層と場面ごとに起動する層の別を`agent-toolkit:writing-standards`が定め、コマンドラインツールでは配置先ディレクトリの別を対象リポジトリの配置規約が定める。
判定基準を本節へ複製せず、当該正本の判定をそのまま用いる。

既存の実装、設計又は規範を過去の形へ戻す提案と、過去の契約を撤去する提案では、当該箇所を現在の形にした変更の導入目的を調べ、提案する案がその目的を満たすかを確定する。満たさない場合は両方を満たす案へ改める。調べた変更の識別子と判定結果を`理由`へ記録する。判定の手順は`agent-toolkit:plan-mode`の`references/plan-file-standards.md`「復元・巻き戻し型の変更」を正本とし、本節へ複製しない。

詳細な証拠、代替案又は再現手順は、固定部分だけでは完成条件と採否を判定できない場合に限り、この固定部分の後へ記載する。

本文の記載量は、次に当該項目を処理する主体が、当該項目を誤って不採用と判定せず、意図と異なる実装へ進まないために必要十分な情報を残すことを基準に決める。基準を満たす限りにおいて、同じ事実の再掲、経緯の説明及び他項目との関係の説明のうち、採否と実装の判断を変えないものは書かない。文字数の上限は定めず、項目ごとに必要な情報量を判定する。

UWIを起草する場合は[references/uwi-format.md](references/uwi-format.md)を全文読み、現行の質問・回答欄契約を適用する。

## 由来と承認

`source`は本文全体の既定由来を示す。`source`の欠落だけを既定で人間由来とし、値を持つ項目は全て既定でエージェント由来とする。保存済みの値は改変せず、過去の項目も移行しない。

エージェントが投入する項目は`source`を必須とする。スキルを起動して投入する場合は、当該スキル名からプラグイン名の修飾を除いた値（`add-awi`、`plan-and-add-awi`、`process-wi`、`session-review`など）を用いる。対応するスキルを持たない起票は`agent`を用いる。ユーザーの指示に基づいてエージェントが投入する項目にも同じ規則で値を付け、人間由来として扱う範囲は次の明示由来で示す。

要求単位に記録された次の明示由来は、本文全体の既定由来より優先する。

- 末尾の厳密なH2 `## ユーザーコメント`配下の要求
- UWIの`## 回答`に記録された要求
- 関連計画の実施内容に記録された由来
- 出所と引用範囲を保持した対話回答

明示由来の有無は種類ごとに本文を確認して判定し、`## ユーザーコメント`の見出しの有無だけで判定しない。同見出しは末尾の厳密なH2として定義されたユーザー専用の記入欄であり、出所と引用範囲を保持した対話回答はこれとは別の明示由来として、別の見出しの下に置かれることがある。
由来を分離できない要求は人間由来として扱う。人間由来の要求を全部又は一部不採用にする場合は、原文との差異、技術的理由及び代替案を示してユーザーへ確認する。回答を得られない場合はUWIを保存し、当該項目に採用済みの範囲があるかで終端を確定する。
採用済みの範囲が無い項目は、暫定判断で`rejected`へ終端してよい。
採用済みの範囲がある項目は`rejected`へ終端せず、当該範囲を`adopt`で終端し、確認を得られない不採用の範囲だけを内容とする新しい項目を登録して当該UWIを`depends_on`へ加える。
`rejected`は全要求の不採用を確定した終端であり、採用済みの範囲を持つ項目へ用いると当該範囲の完了が終端の意味と一致しないためである。
UWIの回答が採用を示した場合は、`return-to-inbox`で`rejected`から`inbox`へ戻して再処理する。エージェント由来だけの独立した要求は、技術的根拠により自律的に不採用と判断できる。

人間由来のWI本文、ユーザーコメント、UWI回答、対話回答のいずれかに、外部操作、対象及び範囲が明記されていれば、その範囲の承認として扱う。`source`値だけの場合、空のコメント欄、エージェントの推奨、一般的な「進めて」は承認にしない。読み書きする主体はユーザーとエージェントだけとする。署名、認証、監査用の仕組みは追加しない。

UWIの`## 回答`節とAWIの`## ユーザーコメント`節はユーザーだけが書き込む欄とし、エージェント環境から起動した`atk`はこれらの節を含む本文の投入と編集を拒否する。
`atk wi edit`が本文をMESSAGEで受け取る場合は、`## ユーザーコメント`節を編集の対象から外し、保存済みの内容をそのまま残す。
エージェントがユーザーの発言を引用する場合は、これらの見出しを作成せず、本文中へ出所と引用範囲を示して引用する。引用する本文は`agent-toolkit:writing-standards`の「ユーザー入力素材の取扱い」が定める逐語引用の記法で囲み、原文を改変しない。引用はエージェントが書いた記述であり、ユーザー自身の記入欄と同じ扱いにしない。

## 状態と依存

型、保存状態、導出判定及び一覧集合を区別する。

| 分類 | 値 | 意味 |
| --- | --- | --- |
| 保存状態 | `inbox` | 次の処理主体による取得待ち。依存未解決なら`blocked` |
| 保存状態 | `processing` | `agent-toolkit:process-wi`が取得して処理中 |
| 保存状態 | `hold` | ユーザー又はエージェントが編集中であり、自動処理の対象外 |
| 保存状態 | `adopted` | 採用内容が完了した終端 |
| 保存状態 | `rejected` | 全要求の不採用を確定した終端 |
| 導出判定 | `ready` | 全依存が終端し、UWI回答、metadata及び計画が有効 |
| 導出判定 | `blocked` | 依存、未回答UWI、cooldown又はmetadata不備により着手不能 |
| 一覧集合 | `active` | `inbox`、`processing`及び`hold`。ユーザーが未終端の項目を確認する範囲 |
| 一覧集合 | `processable` | `inbox`及び`processing`。`ready`かは別途判定する |

エージェントが実行できる状態遷移を次に示す。ユーザーはブラウザーUIから任意の状態へ遷移させられる。

| 遷移 | 操作 | 実行する主体と契機 |
| --- | --- | --- |
| `inbox`→`hold` | `atk wi hold` | 項目を編集する主体が、編集の開始時に自動処理から除外する |
| `hold`→`inbox` | `atk wi unhold` | 編集した主体が、編集の完了時に自動処理へ戻す |
| `inbox`→`processing` | `atk wi start-processing` | `agent-toolkit:process-wi`のpickerが、処理対象を確定した直後に遷移させる |
| `inbox`→`adopted` | `atk wi adopt` | `agent-toolkit:process-wi`のpickerが、回答を保存済みで未終端のUWIをAWIの処理開始前に終端する |
| `processing`→`adopted` | `atk wi adopt` | `agent-toolkit:process-wi`のpickerが回答済みUWIをAWIの処理開始前に終端するか、レーンがベースブランチへのマージ完了時又は実装変更を伴わない充足の確定後にAWIを終端する |
| `processing`→`rejected` | `atk wi reject` | `agent-toolkit:process-wi`のレーンが、計画工程で確定した全要求の不採用についてメインが確認を終えた後に遷移させる |
| `rejected`→`inbox` | `atk wi return-to-inbox --state=rejected` | UWIの回答が採用を示した項目を再処理へ戻す |
| `processing`→`inbox` | `atk wi return-to-inbox` | 処理中に未回答UWIへの依存が生じた項目を`inbox`かつ`blocked`へ戻す |

`inbox`と`hold`の項目は`atk wi rm`で削除できる。本文の編集は`inbox`、`processing`、`hold`の各状態で行える。
投入済み項目の本文を修正する主体は、`atk wi hold`で保留し、本文を編集し、`atk wi unhold`で保留を解除する順序で行う。常駐する`atk wi process-loop`が編集途中の本文を取得することを防ぐためである。
`agent-toolkit:process-wi`は`processable`の項目だけを処理の対象とし、`hold`の項目を候補、優先度、依存判断及び固有指示の入力から除外する。

`depends_on`は、当該項目より先に終端すべきキュー項目のファイル名を保持する。用途は、未回答UWIによる外部待ちと、先に終端すべきAWIへの先行成果依存の2つとする。依存先は`target_repo`が異なるキュー項目でもよく、着手可否はリポジトリを横断して判定する。値は保存済みのメタデータを正本とし、本文の記述から依存を再構築しない。

`depends_on`は型によらず登録でき、`atk wi set-dependencies <filename> --depends-on <filename>`が`inbox`と`processing`の項目の依存だけを更新する。計画型への変換を伴う`atk wi edit --plan-file`と`atk wi convert-to-plan`を依存の登録手段として使わない。本文へ依存を記述してメタデータの代わりにしない。本文の記述は`ready`と`blocked`の導出判定へ反映されない。

着手不能の要因は、解除される契機で分類する。時間経過だけで解除される要因は`cooldown_until`で表し、レート制限のバックオフ、再試行間隔及び期日到来待ちがこれに当たる。実在する先行キュー項目の終端で解除される要因は、当該項目のファイル名を`depends_on`へ直接加えて表す。他リポジトリの成果待ちも、待つ対象がキュー項目として実在する場合はこの直接依存で表す。人間の回答がなければ解除できない要因は、解除条件と再開工程を本文へ持つUWIを`depends_on`へ加えて表す。UWIへ分類する前に、回答者へ提示する問いを1文で記述できることを確認する。問いを記述できない要因をUWIにしない。外部環境の制約と別環境での実施は要因の発生場所を示すに過ぎず、それだけではUWIの根拠にならない。対処方針の選択若しくは実施可否の判断をユーザーへ求める場合だけUWIとし、必要な認可を既に得ている実施は`agent-toolkit:process-wi`の外部操作の経路で扱う。`cooldown_until`を設定する主体は、当該要因が時間経過で解消することを実測又は公式一次資料で確認してから設定する。確認できない要因を`cooldown_until`で表さない（厳守規定。時間経過で解消しない要因を`cooldown_until`で表すと、選定側が期日まで当該項目を除外し続け、解除の契機が発生しない）。

UWI待ちは物理的な`hold`へ移さず、元項目の既存依存を保持してUWIを`depends_on`へ加え、`inbox`かつ`blocked`にする。`inbox`へ戻した後に着手可否が`blocked`であることを確認する。回答を保存したUWIを先に終端し、依存解除を確認した後に元項目を次の処理対象へ戻す。回答を保存した別セッションが終端まで到達しなかった場合は、次に当該キューを処理する`agent-toolkit:process-wi`のpickerが、AWIを`processing`へ移す前に当該UWIを終端する。メインは`${CLAUDE_PLUGIN_ROOT}/share/pick-wi.parent.md`の「出力の受領」に従って`adopted`への存在を検収し、「①の完了」へ進む。

`rejected`はエージェントが全要求を不採用と判断した時点で使用できる終端とし、後から`return-to-inbox`で`inbox`へ復元できる。技術的失敗、入力不足、外部条件待ち又は計画不備は不採用へ変換せず、必要なUWI依存を付けてactiveのまま保持する。

対象リポジトリの成果物を変更しても満たせず、対象リポジトリが依存する上流リポジトリの改訂を要する要求は、外部条件待ちとして据え置かず、当該上流リポジトリへ同じ要求のAWIを投入する。元項目は`hold`と終端のいずれへも移さず`inbox`へ戻し、1つの項目を要求ごとに異なる保存状態へ分けない。対象リポジトリで実施できる要求を併せ持つ項目は、当該要求の実装を終えてから`inbox`へ戻す。投入したファイル名の依存への追加、状態の確認及び上流項目の終端後の進め方は[references/cross-repository-submission.md](references/cross-repository-submission.md)に従う。

エージェントが自身の誤りで投入した項目は`rejected`へ終端せず、`atk wi rm`で削除するか`atk wi edit`で本文を正しい要求へ書き直して再利用する。`rejected`は要求として成立する項目の不採用だけに使う。
`atk wi rm`による削除はキュー管理リポジトリのGit履歴へ残るため、復旧経路を失わない。
当該削除を確認の対象にしない。

## 条件付き重複判定

エージェントが新しい通常AWIを生成する場合だけ、投入前に同じ対象リポジトリのactive項目を取得し、対象、期待結果、観測事象、根本原因及び必要な処置を照合する。既存項目が全てを覆う場合は新規投入せず既存ファイル名を再利用し、部分的に覆う場合は未被覆部分だけを投入する。表現の類似又は最終結果の一致だけを重複の根拠にしない。

ユーザーが手動起動した`agent-toolkit:add-awi`、`agent-toolkit:plan-and-add-awi`、UWI及び移行・復元では、この重複判定を実行しない。

## 投入と取得

1. 通常AWIは技術主張を実装、実行結果又は公式一次資料で裏付け、ユーザー依存事項をUWIへ分離してから起草する。観測した欠陥を起点とする通常AWIは、本文の起草前に`agent-toolkit:bugfix`の初動と原因分析の要否判定を適用する。UWIは原因分析の対象にしない。
2. 複数リポジトリへ投入する場合は[references/cross-repository-submission.md](references/cross-repository-submission.md)を全文読む。
3. 同じ対象リポジトリの複数項目を一括取得する場合は[references/managed-temp-bulk-show.md](references/managed-temp-bulk-show.md)を全文読む。
4. 本文へ引用符又は改行を含む場合はファイルへ保存し、`atk wi add --body-file <path>`で渡す。位置引数とは併用しない。
5. 登録は本文の内容が確定した時点で行い、複数件をセッション終了時までためて一括登録しない。内容が未確定の事項は登録の対象外とする。
6. 登録するAWIの対象ファイルが現在のセッションの変更対象と重なる場合は、当該セッションが対象ファイルの変更を完了してから登録する（努力目標）。常駐処理が動作する環境では登録が遅れると次の反復まで着手が遅れる一方、変更対象が重なる項目を即時に登録すると別の作業ツリーで同じファイルへ並行着手し得るため、両者を比較して時機を選ぶ。
7. 呼出元が指定した本文、対象リポジトリ、種別、`source`、plan file及び依存を変更せず登録する。エージェント自身の投入では前節で確定した`source`を省略しない。`source`が未指定の人間由来入力へ値を推測して追加しない。
8. 保存本文の照合は`agent-toolkit/rules/02-agent-operations.md`「ツール・コマンド運用」の登録・送信後の規定に従い、`atk wi add`と`atk wi edit`の出力を保存本文として扱う。構造の検収では、ファイル名、`target_repo`、`target_commit`、`plan_file`、`depends_on`、指定・確定済みの`source`及び非予約frontmatterを確認する。いずれかに欠落がある場合は完了扱いにせず同じ経路で修復する。警告又はエラーが出た場合は終了コード0でも`atk wi show <filename> --target-repo=<repo> --skip-pull`で保存本文を再取得する。
9. 保存の完了は、`atk config get private_notes`が返す作業ツリーから前項の確認ができ、対象branchとremoteへ反映済みであることを確認して判定する。未pushのcommitが残る旨の通知を受領した場合は、`atk wi commit`でpushしてから完了とする。別の作業ツリーを作成して保存する経路は使わない。