plannotator

plannotator

作業内容が1つのレビュー対象を分類し、最も簡潔で誠実なビジュアルレビュー経路を開き、広範な計画策定／PR ポリシー／UI 批評の作業を入口の対象外にすることである場合は、このスキルを使用します。

plannotator はプランナーではありません。 以下の間に位置する人間による承認ゲートです。

• 計画／仕様の作成（task-planning、ralph）
• オーケストレーション／ランタイムの管理（jeo、task-planning、bmad）
• より広範な PR／コードの判断（code-review）
• レンダリング済み UI のバグへのマークアップ（agentation）
• クリーンなブラウザー検証（browser-harness）

まず、以下のサポートドキュメントを読んでください。

• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md

このスキルを使用する場合

• コーディングエージェントが実装計画を作成済みで、コーディング開始前に人間が承認するか、変更を求める必要がある場合。
• 具体的な git 差分、コミット範囲、または PR が存在し、レビュー担当者がブラウザー上で行単位を指定したフィードバックを求めている場合。
• 仕様、PRD、アーキテクチャに関するメモ、生成された計画パッケージなどの Markdown 成果物をビジュアルレビューし、修正に関するフィードバックを行う必要がある場合。
• ユーザーが plannotator を Claude Code、Gemini CLI、Codex CLI、または OpenCode に接続する必要があり、主な作業がレビューのワークフローをセットアップすることである場合。
• レビューフローはすでに存在するものの、リモートモード、安定した URL／ポート、またはプラットフォーム固有の動作が不安定で、対象を絞ったトラブルシューティングが必要な場合。

このスキルを使用しない場合

• 主な作業が計画／仕様そのものの作成や改善である場合 → task-planning、ralph、または survey
• 主な作業が広範な PR ポリシー、マージ基準、リスク判断、またはコードオーナーの承認である場合 → code-review
• 主な作業がフロントエンドの修正につながる、正確なレンダリング済み UI の批評である場合 → agentation
• 主な作業が使い捨て可能なクリーンなブラウザー自動化、または決定論的なウェブサイト検証である場合 → browser-harness
• 主な作業がタスクのオーケストレーション、ボードの状態、または複数エージェントへの振り分けである場合 → jeo、task-planning、bmad
• 主な作業がメモの分類、Wiki の整理、または長期的なメモシステムの管理である場合 → obsidian、llm-wiki

手順

ステップ 1：まずレビュー対象を分類する

コマンドについて話し合う前に、依頼を1つの主要な対象に整理します。

plannotator_intake:
  primary_packet: plan-review | diff-review | markdown-review | platform-setup | troubleshooting
  artifact_ready: yes | no
  artifact_type: plan | git-diff | pr | markdown-spec | generated-response | unknown
  platform: claude | gemini | codex | opencode | mixed | unknown
  trigger_mode: native-hook | manual-review | unknown
  feedback_goal: approve | request-changes | annotate | archive | unknown
  repo_context: git-repo | markdown-only | remote-container | unknown
  confidence: high | medium | low

まず、最も明確で範囲の狭い解釈を選びます。

• 既存の実装計画 → plan-review
• 既存のコード変更／PR／コミット範囲 → diff-review
• 既存の仕様または Markdown 成果物 → markdown-review
• インストール／統合に関する質問 → platform-setup
• 不安定なリモート／ブラウザー／ステータスの問題 → troubleshooting

ステップ 2：具体的な成果物が存在することを確認する

plannotator が役立つのは、レビュー可能な具体的なものがある場合だけです。

チェックリスト：

1. 計画、差分、PR、Markdown ファイル、または生成された応答がすでに存在する。
2. ユーザーが求めているのはレビューであり、計画の生成ではない。
3. 差分レビューの場合、git リポジトリ、PR URL、または明示されたコミット範囲が存在する。
4. Markdown／仕様のレビューの場合、ファイルまたは生成された成果物を特定できる。
5. メモのエクスポートの場合、保存／統合が設定済みである。これを主要な対象ではなく、二次的なものとして扱う。

成果物がない場合は、レビュー用ツールを無理に使わず、適切な別の経路に振り分けます。

ステップ 3：レビュー対象を1つだけ選ぶ

references/intake-packets-and-route-outs.md のルーターを使用して、主要な対象を1つ選びます。

• plan-review
• diff-review
• markdown-review
• platform-setup
• troubleshooting

それ以外の項目は共同の担当対象ではなく、後続の作業として列挙します。

Step 4: 選択したパケットを実行する

• プランレビュー → ランタイムからプランを plannotator に渡せることを確認し、実際に利用できる場合はネイティブ／フック経由の方法を使います。各ステップにつき問題点を1つ注釈し、最後に 承認、変更をリクエスト、または アーカイブ／保存 を選びます。
• 差分レビュー → 具体的な対象を指定し、最小限の差分パケットを起動します。

  bash scripts/review.sh
  bash scripts/review.sh HEAD~1
  bash scripts/review.sh main...HEAD
  

• Markdownレビュー → 仕様書／PRD／アーキテクチャファイルが存在することを確認し、注釈／レビューモードを直接使います。ランタイムがより強力な承認フローではなく注釈のみをサポートする場合は、その点を明示します。
• プラットフォームのセットアップ → まず次を実行します。

  bash scripts/install.sh
  bash scripts/check-status.sh
  

  次に references/platform-setup.md を使います。
• トラブルシューティング → まず次を実行します。

  bash scripts/check-status.sh
  bash scripts/configure-remote.sh
  

  次に references/notes-and-troubleshooting.md を使います。

Step 5: 手動とフック経由の実態を明確にする

• Claude と Gemini は、ネイティブ／フック駆動のプランレビューに最も適しています。
• Codex には公開フックがありますが、上流の plannotator では、実用的な方法として手動の差分／Markdownレビュー、または部分的なセットアップが引き続き案内されています。
• OpenCode のユーザーからは、自動呼び出しの頻度が高すぎる場合に、手動でより細かく制御したいという要望が明確に寄せられています。

「すべてのプラットフォームで同じように動作する」と一括りにしないでください。

Step 6: 関連作業は積極的に振り分ける

• 計画／仕様の作成または改善 → task-planning、ralph、survey
• オーケストレーションの状態管理またはマルチエージェントのルーティング → jeo、task-planning、bmad
• 広範なPRポリシー、マージのゲート管理、リスク判断 → code-review
• レンダリングされたUIのバグへの注釈 → agentation
• 使い捨てのクリーンな環境でのブラウザー検証 → browser-harness
• レビュー済み成果物の保存を超えるノート／Vault／Wikiの管理 → obsidian、llm-wiki

Step 7: 短い出力形式を使う

推奨する出力：

# plannotator Review Packet
- Primary packet:
- Artifact:
- Platform + trigger mode:
- Next action:
- Outcome or limitation:
- Route-outs:

セットアップが中心の依頼では、次の項目を含む簡潔なセットアップ概要を使います。

• プラットフォーム
• ネイティブフックか手動レビューかの状況
• インストールコマンド
• 検証手順
• 注意事項

例

例 1: 具体的なプランを承認する

入力

エージェントがすでに6ステップの実装プランを提案しています。コード作成を始める前に、視覚的に確認して承認するか、修正を送り返したいです。

望ましい出力の方針

• plan-review を選ぶ
• プランがすでに存在することを確認する
• ランタイムの実際のレビューモードを使う
• 各ステップにつき問題点を1つ注釈する
• 承認するか変更をリクエストして終了する
• プランがまだ未成熟であれば、プラン作成を別の場所に振り分ける

例 2: 差分をレビューする

入力

エージェントがすでに3つのファイルを変更しています。main...HEAD のビジュアル差分レビューを開いて、対象を絞ったフィードバックを残せるようにしてください。

望ましい出力の方針

• diff-review を選ぶ
• Gitのコンテキスト／差分範囲を確認する
• bash scripts/review.sh main...HEAD を使う
• より広範なPRポリシーのレビューは code-review に振り分ける

例 3: PRD／仕様書の成果物をレビューする

入力

このアーキテクチャに関するメモに注釈を付けて、そのまま受け入れるか、作業を続ける前に修正のフィードバックを送りたいです。

望ましい出力の方針

• markdown-review を選ぶ
• Markdownの成果物が存在することを確認する
• 現在のプラットフォームがネイティブ承認をサポートするのか、手動の注釈のみなのかを説明する
• ノートのエクスポートは副次的なものとし、Wiki／Vaultの管理は別の場所に振り分ける

例 4: Codexのセットアップの実態確認

入力

コードの実行前にプランをレビューできるよう、Codex用にplannotatorをセットアップしてください。

望ましい出力の方針

• platform-setup を選ぶ
• インストールとステータス確認から始める
• 上流ドキュメントに示されていない同等の機能を約束せず、Codexの現在の手動／部分的な対応状況を正直に説明する
• 必要であれば、広範なフック／プラットフォームのポリシーに関する作業を別の場所に振り分ける

ベストプラクティス

1. plannotator は計画エンジンではなく、視覚的な承認ゲートとして扱います。
2. 一度に確認する具体的な成果物は1つにします。
3. 手動レビューとネイティブフックの違いを明確にします。
4. 可能な限り、問題ごとに注釈を1つ付けます。
5. 明確な結果で終えます：承認、変更依頼、注釈のみ、またはアーカイブ。
6. ノートのエクスポートはレビューパケットより優先度を下げます。
7. plannotator の役割を無理に広げず、PR ポリシー、オーケストレーション、レンダリング済み UI の批評は関連するスキルに振り分けます。

参考資料

• GitHub：backnotprop/plannotator
• 公式サイト：plannotator.ai
• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md
• references/review-modes-and-boundaries.md