plan-loop

Plan Loop

計画ループです。プロンプトを、下位モデルに引き継げるだけ詳細で正確な計画に変換します。成果物は計画で、レイアウトを記した plan.md と、ファイル、テスト、依存関係、原子的なサブタスクを含む PR サイズのタスクをまとめた tasks.json です。フィードバックは、このリポジトリのほかの評価ループと同じく、2つの要素で構成されます。客観的ゲート（tools/validate_plan.py。スキーマの形式、非循環の依存関係グラフ、有効なトポロジカル順序、全コンポーネントの網羅性を検証）と、定性的ゲート（別のプリンシパルエンジニアエージェントが、要件との整合性、分割方法、テスト可能性、およびジュニアエンジニアが推測なしで各タスクを実行できるかを批評）です。第一原理から計画を作成し、検証して批評を受け、批評をクリアするまで修正します。これは、より大きなプロンプト → 計画 → 実行 → デバッグのパイプラインにおける 計画 段階であり、計画を委任できる状態にした時点で終了します。

使用するタイミング

機能・バグ・リファクタリングのプロンプトを、実際のリポジトリに根ざした実行可能な計画に変換する場合に使用します。目的は、後続の実行者（または小規模なモデル）がタスクごとに実装できる引き継ぎ用の成果物を作成することです。文字どおりに解釈する実装者にとって、計画の品質は最も弱いタスクによって決まるため、このループでは文章の巧みさよりも 実行可能性 を重視します。

デフォルトでは、与えられた <repo> に基づいて計画を作成し、プリンシパルエンジニアの批評を修正の指針にします。別の方法として、プロンプトやリポジトリから重要な判断を下せない場合は、推測するのではなく、人間向けの open_question として記録します。コードを書く用途（後続の実行ループ）や、調査・実験の提案には使用しないでください（research-proposal を使用してください）。

セットアップ

バインディングを対話形式で確定します。loop.run.yaml が存在する場合は読み込み、値を1行で確認してからループに進みます。それ以外の場合は、Claude Code（AskUserQuestion ツールを利用可能）の場合、各バインディングの推定値を提示し、推奨値を示します。それ以外の環境では、引用符付きのプロンプトで各項目を確認します。その後、loop.run.yaml（形式：examples/run.example.yaml）を書き込み、ほかのファイルを作成する前に確認します。

binding	意味	デフォルト	推定方法
<prompt>	計画対象のタスク。ファイルパスまたはインラインテキスト	—	ユーザーのリクエスト
<repo>	計画の対象となるプロジェクト。実際の環境と規約を確認するために読み込みます（編集はしません）	.	作業対象のリポジトリ
<plan_file>	人間が読みやすい計画レイアウト（Markdown）	<sandbox_root>/plan.md	—
<tasks_file>	schemas/plan.schema.json に照らして検証する構造化タスク	<sandbox_root>/tasks.json	—
<pr_loc>	タスクごとの目標コード行数（PR サイズ。超過しても構いません）	100-400	—
<sandbox_root>	計画、タスク、台帳を格納する場所	./sandbox	—
<budget>	最大の修正サイクル数	5	—

<skill_dir> はこのスキルがインストールされているフォルダーです。loop.run.yaml を書き込む際は、実際のパスに置き換えてください。 客観的ゲートは各サイクルで実行されます。

python3 <skill_dir>/tools/validate_plan.py --tasks <tasks_file>

{ok, errors, warnings, stats} というJSONオブジェクトを1つ出力します。計画を完成とみなすには、ok が true（エラーなし）である必要があります。

ループ

このチェックリストをコピーし、項目にチェックを付けます。

計画を立てる（イテレーション 0 — 第一原理）：

• 基礎を確認。 <prompt> を読み、<repo> を調べて事実を把握します。言語、パッケージマネージャー、 ランタイム／OS、テストコマンド、再利用できる既存のモジュールや慣習を確認します。確認できるものは調べ、 読めるものを推測で済ませないでください。
• 分解。 第一原理からコンポーネントを洗い出します — 目的、最終状態／完了の定義、 対象外、環境、構成要素、ブロック間のインターフェース／契約、 ツール、パッケージ、データ／アセット、再利用（既存コード＋インストール済み スキル）、未解決の質問。ひとまとまりでは検討が難しいコンポーネントは、再帰的に分割します。
• タスク（PR サイズ）。 作業をタスクに分割します。各タスクはおよそ <pr_loc> で、 1 つの PR に相当します。それぞれについて、対応するコンポーネント（serves）、説明、 構成要素／ツール／パッケージ、作成・変更する正確な files、効果を証明する tests、 acceptance_criteria、estimated_loc を記録します。
• 順序付け。 各タスクの depends_on を埋め、その後、トポロジカルな order を計算します （すべてのタスクを依存先の後に配置します）。
• サブタスク。 各タスクを、追加の判断なしにジュニアエンジニアが実行できる最小単位のサブタスクに 分割します — 「ファイル X を作成する」、「関数 f(args) -> T を定義する」、「f を Y に接続する」。
• 作成＋検証。 <plan_file> と <tasks_file> を作成し、tools/validate_plan.py を実行します。 最初のレビューの前に、すべてのエラーを修正し、すべての警告を検討します。ベースラインの台帳行を記録します。

改善（計画が合格するか <budget> に達するまで繰り返す）：

• レビュー。 プロンプト、リポジトリ、plan.md、tasks.json、最新の validate_plan.py の出力、 このホストにインストールされているスキルの一覧を添えて、主任エンジニア （spawn-or-degrade、roles/principal-engineer.md）を起動します。構造化されたレビュー結果 （schemas/critique.schema.json）として、判定、スコア、問題（ブロッキング／重大／軽微、それぞれに修正案）、 カバレッジの不足、推奨スキルが返されます。
• 改訂。****すべてのブロッキングおよび重大な問題の修正を適用します — 再分解、サイズ変更、順序変更、 テスト追加、パッケージのバージョン固定、ジュニアエンジニアが迷わないよう、具体的なシグネチャ／パス／データ形状を追加します。 tools/validate_plan.py を再実行します。台帳行を追加します。
• 停止。 レビューが pass（ブロッキングまたは重大な問題なし）を返し、かつバリデーターがクリーンなら 停止します — 計画は委任できる状態です。それ以外の場合は <budget> までループします。スコアが頭打ちで 軽微な問題だけが残る場合は停止し、それらを未解決の注記として記録します。

停止時の成果物は <plan_file> ＋ <tasks_file>（および人間向けの open_questions）です。下流の実行ループまたは 下位モデルが、order に従ってタスクごとに実行できるように作成します。

計画の成果物

<tasks_file>（tasks.json） — 機械実行可能な計画。契約全体は schemas/plan.schema.json を参照してください。 簡潔な形式：

{
  "objective": "...", "end_state": "...", "non_goals": ["..."],
  "environment": {"language": "python", "package_manager": "uv", "test_command": "pytest -q"},
  "components": [{"id": "c1", "name": "config", "description": "load + validate config"}],
  "open_questions": ["which auth provider?"],
  "tasks": [
    {"id": "T1", "title": "config loader", "serves": ["c1"], "description": "...",
     "building_blocks": ["dataclass Config"], "tools": ["pytest"], "packages": ["pyyaml"],
     "files": [{"path": "src/config.py", "action": "create", "what": "Config + load()"}],
     "subtasks": [{"id": "T1.1", "description": "define load(path) -> Config"}],
     "tests": [{"description": "load() parses a valid file", "kind": "unit"}],
     "acceptance_criteria": ["invalid config raises ConfigError"],
     "depends_on": [], "estimated_loc": 180, "suggested_skills": []}
  ],
  "order": ["T1"]
}

<plan_file>（plan.md） — 人間向けの構成です。目的、最終状態、対象外、環境、コンポーネント、 order に沿ったタスク表（id · title · serves · depends_on · est. LOC）、リスク／未解決の質問、 tasks.json の参照先を示す「実行方法」の一行を記載します。tasks.json と内容を一致させます。実行側が使用する 信頼できる唯一の情報源は tasks.json です。

台帳

<sandbox_root>/ledger.tsv はタブ区切りで、自由記述にカンマは使用しません。ヘッダーは iter phase verdict score blocking major change：

iter	phase	verdict	score	blocking	major	change
0	build	-	-	-	-	first-principles decomposition: 6 components, 8 tasks, validator ok
1	critique	revise	72	1	2	PE: T3 bundles 2 PRs; T5 has no real test; nothing covers config loading
2	revise	-	-	-	-	split T3 -> T3a/T3b; added retry test to T5; added T9 config loader; reordered
3	critique	pass	90	0	0	PE: solid; one minor naming nit recorded as an open note

レビューが合格したサイクルの最終計画（または <budget> 時点で到達した最高スコアの計画）を報告します。

制約

• 計画のみ — 実装しないでください。 <repo> に本番コード、ひな形、ファイルを書き込まないでください。出力は plan.md + tasks.json です。実行とデバッグは後続のループで行います。
• すべての主張を実際のリポジトリ／環境に基づかせてください。 パッケージ、ファイル、API、コマンドを捏造せず、<repo> で確認してください。本当に不明な点は推測せず、人間への open_question としてください。誤った内容を自信たっぷりに記載する計画は、問題点を明示する計画よりも悪いものです。
• タスクは PR サイズに収め、単独で完結させてください。 各タスクは 1 つ以上のコンポーネントに関連付け、テストと受け入れ基準を含めてください。各サブタスクはアトミックにしてください。不足を補わない実装者でも進められるように最適化してください。
• 批評者の独立性を保ってください。 プリンシパルエンジニアは、自身が作成していない計画をレビューします（Claude Code では spawn-or-degrade により実際の分離が実現します）。作成者自身に計画を承認させないでください。
• 編集は <sandbox_root> 内（計画、タスク、台帳）に限定してください。 <repo> は読み取り専用のコンテキストです。続行するかどうかを尋ねるために中断せず、批評で合格するまで、または <budget> に達するまでループを実行してください。

役割

roles/principal-engineer.md — 敵対的な視点で計画を批評する役割です。spawn-or-degrade：Claude Code では、実際に分離されたサブエージェント（Agent／Task ツール）を使用し、それ以外の場合はインラインでその役割を担います。読み取り専用で、固定の評価基準に照らして判断し、schemas/critique.schema.json に対して検証済みの JSON を返します。再利用可能なスキルを提案できるよう、ホストにインストールされたスキルの一覧を渡してください。その一覧を利用できない場合は、suggested_skills を省略します。