agentsclimarketplace

Ai dev plan

Skill s977043/PlanGate/.agents/skills/ai-dev-plan

PBI INPUT PACKAGE から PlanGate の plan.md / todo.md / test-cases.md を B-1→B-2→B-3 フローで作成する。Use when: docs/working/TASK-XXXX/pbi-input.md を元に実行計画を作りたい時。From its SKILL.md

Install
npx -y skills add s977043/PlanGate --skill ai-dev-plan

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

14.6 KB, as published. Nobody here has run it

AI-Driven Plan (PlanGate / Codex 共用)

PlanGate ワークフローの plan フェーズ(WF-02〜WF-03) を Codex / Claude Code 両方で実行する skill。実行ロジックは上流リポジトリの scripts/ai-dev-workflow / bin/plangate CLI 側に集約し、skill は読む順序と入出力規約のみを担う。

Read First

参照解決順(導入先で必ずこの順に探す)

本 skill の参照は上流リポジトリ基準の相対パスで書かれている。導入先ではそのままでは 解決できないものがあるため、次の順で探索する:

  1. 導入先リポジトリの相対パス(例: .claude/rules/mode-classification.md)
  2. 無ければ plugin root 配下(例: ${CLAUDE_PLUGIN_ROOT}/rules/mode-classification.md)
    • 解決は Bash で ls "${CLAUDE_PLUGIN_ROOT}/rules/" を実行して確認する。 Read ツールは絶対パスを要求し環境変数を展開しないため、${CLAUDE_PLUGIN_ROOT}/... という文字列をそのまま Read しても必ず失敗する
    • 変数が空・未設定なら glob(~/.claude/plugins/cache/** 等)で推測せず 3 へ進む。 キャッシュには複数バージョンが並存しうるため、当て推量は版の取り違えを招く
  3. どちらにも無い場合は 「解決できなかった」と明示し、推測で内容を補わない

plugin root 配下の探索は docs/** には適用しない(手順 2 は rules/*.md 等の 配布対象にのみ適用する): plugin が配布するのは agents / commands / skills / rules 等の 定義ディレクトリのみで docs/ を配布対象として認識せず、plugin root 配下に相当する配布物が 存在しないため必ず空振りする。docs/** は手順 1 で解決できなければ手順 2 を飛ばして手順 3 へ進む。

導入経路は 3 つあり、配置されるものが違う(「同じ 4 ディレクトリが配られる」わけではない):

  • install.sh --claude 経由: コピー対象は agents / skills / commands / rules の 4 ディレクトリのみ(一次ソース: install.sh の for dir in agents skills commands rules)
  • plugin(Claude marketplace)経由: バンドルは agents / assets / commands / hooks / rules / scripts / skills + README.md / .claude-plugin/。ただし scripts/ の中身は install-plangate-skills.sh のみで、ai-dev-workflow も bin/plangate も含まれない
  • Codex(install.sh --codex / marketplace)経由: 配置されるのは skills だけ。 install_codex() は install-plangate-skills.sh を呼ぶのみで、同スクリプトは rules を一切扱わない(.claude/rules/ は作られない)。${CLAUDE_PLUGIN_ROOT} も Claude Code の変数であり Codex には無い
参照install.sh --claude 経由plugin(Claude marketplace)経由Codex 経由
rules/*.md.claude/rules/ に着地(解決可)${CLAUDE_PLUGIN_ROOT}/rules/ で解決未配置(解決不可 → 手順 3 へ)
docs/**コピー対象外(解決不可)バンドル対象外(解決不可)未配置(解決不可)
bin/**コピー対象外(解決不可)バンドル対象外(解決不可)未配置(解決不可)
scripts/**コピー対象外(解決不可)${CLAUDE_PLUGIN_ROOT}/scripts/ は存在するが install-plangate-skills.sh のみ(目的の CLI は解決不可)未配置(解決不可)

Codex 経路では解決順 1・2 とも成立しないため、rules 参照は手順 3(解決できなかったと 明示)に落ちる。docs/** が解決できない環境と同様、正本の内容は 本 skill の記述で代替 し、plan.md の Questions / Unknowns に「正本 <path> を参照できなかった」旨を記録する。

読む順序

下記 3〜5 の fallback にある <plugin_root> は、上の「参照解決順」手順 2 のとおり Bash で ${CLAUDE_PLUGIN_ROOT} を展開して得た絶対パスを指す(変数を含む文字列を そのまま Read しない)。

  1. CLAUDE.md
  2. AGENTS.md
  3. .claude/rules/working-context.md → fallback <plugin_root>/rules/working-context.md (B フェーズ 3 ファイル同時生成・段階別出力・ゲート条件の正本)
  4. .claude/rules/mode-classification.md → fallback <plugin_root>/rules/mode-classification.md (5 段階 mode + lite_eligible 派生属性の正本)
  5. .claude/rules/hybrid-architecture.md → fallback <plugin_root>/rules/hybrid-architecture.md (Rule 1〜5 / handoff 必須化)
  6. docs/ai-driven-development.md(配布対象外。上流リポジトリで作業する場合のみ解決する)
    • 最低限: ## ワークフロー全体像、### タスク規模によるモード分岐(5 モード)、## ゲート条件、### Prompt 1: Plan + ToDo + Test Cases生成
    • 解決できない場合は 3〜5 の rules を優先正本とし、本 skill の「Rules」節で代替する
  7. docs/working/TASK-XXXX/pbi-input.md(導入先で作成する入力。無ければ plan を開始しない)

Output

  • docs/working/TASK-XXXX/plan.md
  • docs/working/TASK-XXXX/todo.md
  • docs/working/TASK-XXXX/test-cases.md
  • docs/working/TASK-XXXX/INDEX.md(任意・無ければ生成)
  • docs/working/TASK-XXXX/decision-log.jsonl(初期化)

Rules

フロー(詳細は正本参照)

  • B-1 / B-2 / B-3 フローおよび plan.md 必須セクション(確認事項 / アプローチ比較 / Mode判定 / lite_eligible 等)は docs/ai-driven-development.md の ### Prompt 1: Plan + ToDo + Test Cases生成 と .claude/rules/mode-classification.md を 正本 とする。skill は順序のみを示す。
  • B-1(最大 3 問の確認質問)→ 事前メトリクス検証 (mandatory gate) → B-2(2〜3 案の trade-off 比較)→ B-3(3 ファイル同時生成)

事前メトリクス検証 (B-1 → B-2 mandatory gate / #351 TASK-0117)

正本: docs/ai/plan-metrics-verification.md (docs/** は配布対象外。解決できない環境では以下の要約に従い、正本未参照である旨を plan に記録する)

「全部 / 全件 / 残り N 件」系の対象は 実数を取得 してから B-2 へ進む。

検証コマンド例 (.git / node_modules 等を除外):

grep -rln --exclude-dir={.git,node_modules,dist,docs/working} <symbol> --include='*.md' -- . | wc -l
find . -name <pattern> -not -path './.git/*' -not -path './node_modules/*' | wc -l
# 推奨: rg --files <path> | wc -l

判定基準 (実数 / AI 見積もり):

  • ≥ 3 倍 → スコープ縮小 or 別タスクへ切替
  • 1〜3 倍 → 採用、plan の Risks に記録
  • < 1 倍 → 採用、Mode を 1 段下げる候補

plan.md template に ## Metrics Evidence 欄を必須化 (実数 / 見積もり / ratio / 判定 を残す出力契約 / AC-8)。

未取得時の分岐 (安全側 / R-001/R-004): 実数取得不能 / Plan Health 未算出 / 「全件」系の対象が曖昧な場合は 必ず Mode 引き上げ側に倒す (mode-classification.md AC-8 安全側不変条件と一貫)。

todo.md 規約

  • タスク粒度 2-5 分、Owner: agent / human 必須、depends_on / files 必須
  • L-0〜V-4・PR 作成は workflow-conductor が自動制御するため含めない
  • 各タスクに rollback: を記載(戻し手順)。必須=high-risk / critical の実装タスク。standard 以下は任意、検証/読取のみは rollback:不要 と明記可
  • rollback 手順が長い場合はタスク直下に補助ブロックで記述してよい

test-cases.md 規約

  • 各 AC → テストケースのマッピング必須、Edge case を含める

監査

  • decision-log.jsonl に B-1/B-2/B-3 の主要判断を append-only で記録
  • mode が critical で lite_eligible=true の場合は人間の C-3 明示承認記録が前提(mode-classification.md AC-11)

計画の構造化観点(river-review rr-upstream-create-plan-001 由来 / #517 受け入れ)

plan.md 生成時、以下の観点を Work Breakdown / Risks に反映する:

  1. 仮説と確定事項の分離 — 判断に必要な事実が欠けていれば Questions / Unknowns に 質問として先出しし、仮説(未確認の前提)と確定事項を混ぜない。情報不足のまま 推測で進めない
  2. リスクの 3 点セット — Risks には 内容 / 検証手段 / Fallback を揃える。 不確実性(互換性・性能・移行・セキュリティ)ごとに検証方法が無いリスクを残さない
  3. 人間ゲートの明示 — 設計確認・仕様確認など人間レビューが必要なブレーキ ポイントを Work Breakdown の 🚩 チェックポイントとして明示する(自己設置 Gate は 勝手に解除しない — responsibility-classes.md 準拠)
  4. 速く学べる順 — ステップは検証が早く回る順に並べ、クリティカルパスを明示。 並列可能な作業はまとめて示す

出典: river-review rr-upstream-create-plan-001(skill インベントリ監査で 「plan を作る側 = PlanGate の責務」と整理され移管。s977043/river-review#1105)

CLI 呼び出し

呼び出し表記は実行環境で変わる。相対パス形式(./scripts/... / bin/...)が成立するのは 上流リポジトリ(s977043/plangate)を clone した cwd に居るときだけで、導入先には bin/ も scripts/ も配置されない(次節参照)。導入先で PATH を通した場合のコマンド名は plangate(bin/plangate ではない)。変わるのはコマンド表記だけでなく TASK-XXXX の解決先でもある(表の下の注意)。どちらの環境かを確定してから使う。

実行環境plan 生成plan_hash 機械検証
上流リポジトリの cwd./scripts/ai-dev-workflow TASK-XXXX planbin/plangate validate TASK-XXXX
導入先 + PATH に plangate ありplangate plan TASK-XXXX は実在するが出力先が CLI 側(下記注意)→ 導入先の TASK には使えず手動生成plangate validate --dir <導入先の TASK ディレクトリ>
導入先 + PATH に無い(既定)手動生成次節のフォールバック(sha256 突合)

注意: TASK-XXXX 位置引数は cwd ではなく CLI 本体の位置を基準に解決される。 bin/plangate は自身のパスから plangate_root(= bin/ の親)を求め、 scripts/ai-dev-workflow も同じ規則で repo root を求めたうえで、 どちらも <CLI の repo root>/docs/working/TASK-XXXX を読み書きする。 bin/ は導入先に配置されない(次節)ため、PATH 上の plangate は必ず 別の場所にある上流 clone の実体を指す。つまり導入先のプロジェクトで plangate plan TASK-XXXX / plangate validate TASK-XXXX を実行しても、 対象は導入先の docs/working/ ではなく その clone 側の docs/working/ になる。 導入先の TASK を検査したいときは、cwd 非依存でパスを明示できる validate --dir <パス> を使う(plan 側に相当オプションは無いため手動生成)。

CLI 不在時のフォールバック(導入先では既定)

scripts/ai-dev-workflow と bin/plangate は 3 経路のいずれでも導入先に 配置されない。根拠は経路ごとに異なる:

  • install.sh --claude 経由: コピー対象が agents / skills / commands / rules の 4 ディレクトリに限られ、bin/ も scripts/ も対象外
  • plugin(Claude marketplace)経由: ${CLAUDE_PLUGIN_ROOT}/scripts/ は存在するが中身は install-plangate-skills.sh のみ。bin/ はバンドルに無い
  • Codex 経由: 配置されるのは skills のみ

上表の「導入先 + PATH に無い(既定)」に該当する場合は次に従う:

  1. 手動生成に切り替える — 「Output」の 5 ファイルを skill の手順どおり手で作る。 B-1 →(事前メトリクス検証)→ B-2 → B-3 の順序と出力契約は CLI の有無に関わらず不変

  2. plan_hash 整合検証は標準コマンドで代替する(スキップしない) — plangate validate の plan_hash 検査は plan.md の素の sha256(正規化・前処理なし)と c3.json の plan_hash から sha256: prefix を除いた値の単純比較なので、CLI 無しで再現できる:

    # 算出(sha256sum が無い環境では shasum -a 256 を使う)
    sha256sum docs/working/TASK-XXXX/plan.md | awk '{print $1}'
    # 突合先: docs/working/TASK-XXXX/approvals/c3.json の "plan_hash": "sha256:<この値>"
    

    不一致なら C-3 承認後に plan が改変されている → exec に進まず、再承認 (c3.json の plan_hash 更新)または plan の revert を行う。 sha256sum / shasum の両方とも無い場合に限りスキップし、その事実を decision-log.jsonl と plan.md に記録して 「機械検証済み」と書かない (未検証を検証済みと誤記しない)

  3. ゲートは人手で維持する — plan_hash を照合する hook も導入先には配線されないため、 item 2 の突合は exec 開始前に自分で実行する。C-3 は人間の明示承認記録 (docs/working/TASK-XXXX/approvals/c3.json 相当)で成立させ、CLI が無いことを理由に C-3 を省略しない

  4. CLI による機械検証が必要なら、上流リポジトリ(s977043/plangate)を clone して bin/plangate validate --dir <導入先の TASK ディレクトリの絶対パス> を実行する。 位置引数形式(validate TASK-XXXX)は使わない — 上表の注意のとおり clone 側の docs/working/TASK-XXXX を見に行ってしまい、導入先の TASK は検査されない

次フェーズへ

plan 完了後は plan-review-gate skill で C-1 → C-2 → C-3(c3.json APPROVED)。exec は ai-dev-exec skill。

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.