Agent Project

agent-project — 自律ループの外部操作

agent-project（backlog/ を優先順位付け→実行→verify ゲート→収束させる制御層）を、人間の運用側 から操作するスキル。ループ本体は agent-project run が担い（<project>/charter.md があれば run が自動で 目標駆動になる＝専用 project コマンドは無い）。本スキルが担うのは、その外部からのアクションである:

ループの自律消化そのものを依頼されたら、それは agent-project 本体の仕事なので「起動/状態」モードで run を起こす（charter があれば run が自動で目標駆動になる）。本スキルは投入・判断・検収・目標確認という人の接点に徹する。

構成（プロジェクト > バックログ）と CLI 解決

• python3（標準ライブラリのみ）。agent-flow / kiro-cli はループ実行時のみ必要（投入・判断・検収だけなら不要。設定 agent_cli: claude なら kiro-cli の代わりに Claude Code CLI を使う）。
• プロジェクトルート（cwd または --root）直下に backlog/・needs/・decisions/・archive/・ charter.md・repos.json・policy.md・DELIVERY.md などが集約される（1 プロジェクト = 1 ディレクトリ = 1 プロセス）。複数プロジェクトはディレクトリを並べてそれぞれのプロセスで回す。
• CLI を解決する（PATH 優先、無ければリポジトリ内のスクリプト）:

KA="$(command -v agent-project || echo 'python3 tools/agent-project/agent-project.py')"
$KA --help

• 作用先は cwd を当てにしない。 操作対象は いま稼働しているプロセスが監視しているプロジェクトでなければ 意味がない。必ず下記「稼働インスタンスへの接続」で実体を発見し、CLI には --root <レコードの root> を付ける。
• タスク書式の正典は tools/agent-project/backlog.md.example、charter は charter.md.example、運用詳細は同 README.md。

稼働インスタンスへの接続（WSL / Windows）

最重要: 投入・needs 記入・検収・目標確認は、稼働中プロセスが実際に見ているプロジェクトに対して行う。 run（特に --watch）中のプロセスは監視対象を ~/.agent-project/instances/ （$AGENT_PROJECT_HOME で変更可）に登録している。

手順

1. 実行環境を判定する（スキル＝あなたが今どこで動いているか）:

   • WSL/Linux: /proc/version に microsoft を含む、または $WSL_DISTRO_NAME あり → WSL。
   • それ以外で wsl.exe が使える → Windows（プロセスは WSL 側の可能性が高い）。

2. 稼働インスタンスを発見する（instances --json で取得）:

   $KA instances --json                                    # 自分も WSL/プロセスと同じ OS の場合
   wsl.exe -d <distro> -- bash -lc 'agent-project instances --json'   # 自分は Windows・プロセスは WSL
   

   出力は配列。各レコードに pid / root（プロジェクトルート。--root に渡す値）/ project（表示名）/ backlog / needs / decisions / archive / policy / delivery / journal（いずれも直接読み書きできる絶対パス）/ runtime（linux/wsl/windows/darwin）/ wsl_distro / WSL なら root_windows / host が入る。複数プロジェクトが回っていれば複数レコードになる。

   別ホストも横断したいときは共有レジストリ（複数ホストから見える1ディレクトリ）を指す:

   $KA instances --json --registry /mnt/shared/agent-registry   # env AGENT_PROJECT_REGISTRY でも可
   

   別ホストのレコードは host が異なり @host(remote) と表示される。別ホストの操作（stop 等）はそのホスト上で行う （リモート PID へシグナルは送れない）。読み書きは共有ファイルシステム越しに可能。

3. 対象を選ぶ: 生存インスタンスが 1 つならそれ。複数（プロジェクト違い）あれば root（と project 名）を提示して 選ばせる。0 件なら「稼働中の agent-project が無い」ことを伝え、起動するか対象プロジェクトを確認する。

CLI の組み立てと読み書きの原則（境界をまたがない）

発見したレコードから、CLI コマンドは必ず --root <レコードの root> で組む。ファイルは レコードの絶対パス（backlog/needs/archive …）を直接読み書きする。プロセスと同じ OS 側で操作するのが最も確実:

# 発見レコードから（プロセスと同じ OS の場合）
ROOT=<レコードの root>
$KA needs --root "$ROOT"
$KA enqueue --root "$ROOT" --title "…" --verify '…'

# Windows 側のスキルから WSL 側を操作する（推奨パターン）
DISTRO=<wsl_distro>
wsl.exe -d "$DISTRO" -- bash -lc "agent-project needs --root '$ROOT'"
wsl.exe -d "$DISTRO" -- bash -lc "cat > '<レコードの backlog>/T42.md'" < /tmp/T42.md   # ファイル直接投入

どうしても Windows 側のツールで直接 読み書きするときだけパスを変換する: レコードの root_windows、または WSL 内で wslpath -w <wslパス>（→Windows）/ wslpath -u '<winパス>'（→WSL）。/mnt/c/... ↔ C:\... は wslpath が変換する。

あなたが WSL・プロセスも同一ディストロなら変換は不要。root をそのまま渡し、ファイルも直接編集する。

以降のモードの前提: まず接続で root / 各パスを発見しておく。以下の例の <ROOT>＝root に 読み替え、CLI には --root <ROOT> を付ける。 プロセスが WSL で自分が Windows なら各コマンドを wsl.exe -d <distro> -- bash -lc '…' で包む。

モード1: バックログ投入（enqueue）

最短は enqueue コマンド（検証済みで backlog/<id>.md を生成。id 自動）。完了条件は --verify が最良だが、 **verify を書けないときは --accept（自然言語→実行時に合成）か --verify-template（決定的展開）**で代替できる:

$KA enqueue --root <ROOT> --title "利用規約に最終更新日を表示" \
  --verify 'grep -q 最終更新 web/terms.html' --priority 1
# verify を書けないとき:
$KA enqueue --root <ROOT> --title "概要を追加" --accept "README に ## 概要 の見出しがある"
$KA enqueue --root <ROOT> --title "規約に最終更新" \
  --verify-template 'file-contains :: web/terms.html :: 最終更新'
echo '{"title":"X","verify":"make test","after":"T1"}' | $KA enqueue --root <ROOT> --json
cp task.md <レコードの backlog の親>/inbox/   # inbox ドロップ口に置くだけでも run/watch が取り込む

外部ソース（GitHub issue 抽出・メール 等）からの取り込みは --json 形式に整形して enqueue --json へパイプする。 ファイルを直接書く場合はレコードの backlog パスへ <id>.md（1ファイル＝1タスク。id はファイル名の stem。正典は backlog.md.example）を書く:

cat > <レコードの backlog>/T42.md <<'MD'
## T42: 利用規約ページに最終更新日を表示する
- status: ready
- source: human
- priority: 1
- verify: `grep -q "最終更新" web/terms.html`
- retries: 0
MD

フィールド: status（ready/inbox/draft/blocked）・priority（整数・大ほど高）・verify（done の唯一の根拠）・ after（依存 DAG）・review: human（検収ゲート）・level/track（タスク単位の自律度）・expect: changes（偽 done 対策）・ followup（done 時に派生生成）。

鉄則（投入時に必ず守る）

1. 完了条件を必ず持たせる。 --verify（最良）か --accept/--verify-template。いずれも無いと triage で人へ戻る （accept/verify_template があれば最終的に concrete な verify に変換され、done は verify のみが根拠の鉄則は不変）。
2. 曖昧で人間判断が要るタスクは積まず、先にユーザーに確認する。 ループは「機械検証できる作業」の箱。シェルで 検証できないものは --review human で人承認（検収ゲート）に回す。
3. 書きかけは status: draft にして消化・誤発火を防ぐ（書き終えたら ready に上げる）。

投入後の確認（消化しない）: $KA triage --root <ROOT>。

モード2: 人の判断（decide）

タスクが判断待ちになると needs/<id>.md（通知＋フィードバック記入欄）が生成される。プロジェクト毎に閉じる （別プロジェクトの判断は混ざらない）。

$KA needs --root <ROOT>     # blocked / 検収待ち / acceptance 未定義 を一覧

needs/<id>.md を読んで文脈（失敗内容・必要な判断）を把握し、ユーザーに要約して指示を仰ぐ（判断を勝手に決めない）。

(a) フィードバック往復: needs/<id>.md の「## Decision Outcome」欄（MADR 互換。旧「## フィードバック」も可）に方針を書き、確定チェックを - [x] にして保存。 次パス（--watch なら次 poll）で拾われ次の実行に反映される。[x] の時だけ確定（書きかけ保存では発火しない）。

(b) サブコマンドで明示操作（決定は decisions/<id>.md に記録）:

$KA approve <id> --root <ROOT> --reason "テスト側の期待値を修正して再実行"  # 承認して積み直し
$KA reject  <id> --root <ROOT> --reason "方針転換で不要"   # 却下（廃止・依存先を再審査へ・再計画要求）
$KA impact  <id> --root <ROOT>                             # 依存関係（前提/依存先・推移）の影響一覧
$KA hold    <id> --root <ROOT> --reason "本番反映は手動"                    # 保留（policy deny 追加）
$KA reprioritize <id> --pin   --root <ROOT> --reason "今日中に必要"          # 最優先
$KA reprioritize <id> --defer --root <ROOT> --reason "後回し"

モード2.5: 能動の軌道修正（revise）

needs はループが人へ回した時の受動の口。対して revise は、人が気づいた時点でタスクの内容・ 依存・優先度を修正し、指示（feedback）を次の実行へ必ず届ける能動の口。典型は「実行中の作業の方向が 違う」と気づいた時（例: ローカルサーバで e2e を始めた →「実サーバに配備して実施」へ即修正）。

# 実行中でも軌道修正: 現在の試行は確定されず（done にならず）、修正内容で積み直される
$KA revise <id> --root <ROOT> \
  --feedback "e2e はローカルサーバでなく実サーバに配備して実施すること" --reason "軌道修正"

# フィールドの置換（'' / none で削除。after の循環は拒否される）
$KA revise <id> --after "T1,T2" --priority 5 --root <ROOT> --reason "依存と優先度を整理"
$KA revise <id> --verify "curl -fsS https://staging.example.com/health" --root <ROOT> \
  --reason "検証を実サーバ基準に変更"

• 置換できるフィールド: --title --priority --verify --accept --after --note --level --track。
• 効き方: ready 等は即時反映 ／ blocked/review は反映して ready に積み直し（needs は消える）／ doing（実行中）は反映を予約し現在の試行の結果を確定しない（verify も done もせず積み直し）。
• CLI を実行できない環境では commands/<name>.json のドロップでも同じ （{"command": "revise", "id": "<id>", "feedback": "...", "after": "...", ...}）。
• 決定は DR（action: revise）に残り、feedback は - learn: として類似案件の学習材料にもなる。
• ユーザーの意図が「このタスクを二度とやらせない」なら revise でなく hold、「順序だけ」なら reprioritize。内容ややり方を変えるのが revise。

検収待ち（review）の承認 — verify=PASS でも人の承認が要る案件

needs に「## 検収待ち（verify=PASS・承認で done 確定）」が並ぶことがある。- review: human か policy の gate: で 承認ゲート対象になった案件で、verify は通っているが done 未確定。この approve は**done 確定（納品書＋archive）**になる （積み直しではない）。成果参照を確認しユーザーに可否を仰いでから approve <id> … --reason "本番OK"。差し戻すなら needs に方針を書いて [x]。高リスク・不可逆・質的レビュー案件は投入時に - review: human か policy gate: を提案する。

モード3: 成果物の検収（deliver）

done タスクは archive/<id>.md へ退避され検収用納品書が付く。一覧は DELIVERY.md（いずれもレコードの絶対パス）:

sed -n '1,40p' <レコードの delivery>            # 受領書一覧（id・タイトル・検収・成果参照・完了）
sed -n '1,60p' <レコードの archive>/T42.md      # 個票の「## 納品書」（verify=PASS・成果参照）

成果参照（PR/MR URL → commit SHA → git log -1）を辿って実際の変更を確認し、「何が・どこで・どう検証されて 完了したか」を要約する。自己申告で「完了」と報告しない——納品書の verify=PASS と成果参照を根拠に提示する。

モード4: プロジェクト目標（charter）

人が書く目標（charter）からバックログを起こし、達成を評価して改善し続ける上位ループ。専用コマンドは無く、 <project>/charter.md があれば run が自動でこの三相（plan→execute→evaluate）に入る（プロセスは run に一本化）。

sed -n '1,80p' <レコードの root>/charter.md     # 目標/制約/前提/成果物/acceptance(受入 verify)/links を確認
$KA run --root <ROOT> --executor agent          # charter あり→plan→execute→evaluate（収束で人へ）
$KA run --root <ROOT> --watch                  # 目標を満たすまで回り続ける常駐（charter 更新も待つ）

• done の唯一の根拠は acceptance（=受入 verify）全 PASS。charter は charter.md.example を正典に人が書く（スキルは 下書きを提案してよいが、目標・受入条件はユーザーに確認する）。検証コマンドを書けない受入条件は自然文でも可 （- accept: <自然言語> か散文の箇条書き）。run 時にエージェントが決定的 verify へ合成し、合成できなければ人へ回る。
• 収束候補（milestone）は needs/<project>.md に出る。ユーザーに概況（acceptance の PASS 数・改善状況）を要約し、 次のいずれかを仰ぐ:
  • 完了として受領 → $KA approve <project> --root <ROOT> --reason "受領"（最終納品書）。
  • 次フェーズへ続行 → charter.md の goal/acceptance を更新して再実行。
  • 方向修正 → needs に方針 ＋ policy.md 編集。
• 横展開: 別プロジェクトの定義・判断を活かしたいときは charter の ## links に他プロジェクト名を足すよう提案する。

補助モード

起動 / 常駐 / 状態

$KA --root <ROOT>                             # = run --watch（常駐。backlog 投入を待つ）
$KA run --root <ROOT> --executor agent                     # 単発消化（charter あれば目標駆動）
$KA run --planner none --flow-planner stub --executor stub                # エージェント CLI 無しで挙動確認
$KA stats   --root <ROOT>                                # 計測（スループット・自動化率・人対応待ち）
sed -n '1,30p' <レコードの journal>                                       # 機械のサイクルログ

常駐の起動/停止/再起動は lifecycle コマンドで（プロセスを直接 kill しない）。対象は --root で選ぶ:

$KA start   --root <ROOT>    # detached 常駐起動（重複監視は拒否。設定は --config か .agents/ に寄せる）
$KA stop    --root <ROOT>    # graceful 停止（SIGTERM→居残りは SIGKILL）。--pid / --all も可
$KA restart --root <ROOT>    # 同じプロジェクトを止めてから起動し直す
$KA instances                                 # どの project を誰(pid)が監視中か先に確認

「状態を見せて」には stats の値で答える。「回して」で run/project を起こしたら、停止後は判断待ち（blocked）の 有無と停止理由を報告する（勝手に done 扱いしない）。終了コード: 0=完走で判断待ち無し / 1=判断待ちあり / 2=予算停止。 巻き込み事故を防ぎたい案件では run --regression-cmd "<共通スモーク>" を提案する。

設定ファイルで既定を恒久化できる（CLI > 設定ファイル > 既定）。./.agents/agent-project.yaml（or ~/.agents/…）に 置くと自動検出。サンプルは tools/agent-project/agent-project.yaml.example。executor/planner/poll/予算/level/throttle 等の スカラ＋真偽フラグを書ける（個別パスは CLI 専用）。PyYAML 無しなら同キーの JSON（agent-project.json）。

自律裁定は既定 on: verify 失敗を人へ送る前に エージェント CLI が「積み直して解けるか／人が要るか」を一次裁定する （人の policy/承認は飛ばさない・エージェント CLI 不在は必ず人へ）。人の判断を機械に任せたくないと言われたら --no-auto-adjudicate（または設定 auto_adjudicate: false）で無効化する。

方針（policy.md・per-project）

優先順位・実行先・安全ゲートを人間が上書きする面（人 policy ＞ エージェント提案）。レコードの policy パスへ書く:

deny:    prod       # 自動実行しない（実行前に止める）／ pin: T3（最優先）／ defer: cleanup（後回し）
offload: heavy      # 分散環境へ（--git-bus 設定時）
gate:    release    # verify PASS でも done 前に人の承認（検収ゲート・タスク一致）
protect: auth/**    # act が触ったら done せず承認へ（パス一致の safety denylist。.env/**/secrets/** 等を推奨）

ガードレール（このスキルの一線）

• 操作対象を取り違えない。 発見レコードの root を --root に渡す。複数プロジェクトが 回り得るので、対象が曖昧ならユーザーに確認する。
• 投入時は必ず verify を付ける。 機械検証できないタスクは積まず、ユーザーに確認する。
• 判断を代行しない。 needs・milestone の内容はユーザーに要約し、方針を確認してから approve/hold/feedback に落とす。
• done は verify（プロジェクトは acceptance 全 PASS）でしか確定しない。 検収は自己申告でなく納品書（verify=PASS・成果参照）を根拠にする。
• ループの自律消化・目標評価のロジック自体は agent-project 本体の責務。本スキルはその外周（投入・判断・検収・目標確認）に徹する。