looper

Looper

Looper をループ設計のコーチおよびスキャフォルダーとして使用します。設計中は、質問、批評、検証を行い、ファイルを書き込みます。出力後は、RUN_IN_SESSION.md を使って現在のセッションでループを実行するか尋ねます。run-loop.py は高度な外部ランナーとして扱います。

ワークフロー

1. /looper の引数から、対象パスと任意の --template <name> を解決します。対象が指定されていない場合は、./looper-output を使用します。対象に既存の loop.yaml が含まれている場合は、新規スキャフォールドではなく編集／再開タスクとして扱います。テンプレートが指定されている場合は、手順 3 のゼロから始めるインタビューではなく、以下のテンプレートモードに従います。
2. 該当する段階に入るときにのみ、関連するルーブリックを読み込みます。
   • 目標の段階：references/goal-rubric.md。
   • 検証の段階：references/verification-rubric.md。
   • カウンシルの段階：references/council-rubric.md。
   • 制御の段階：references/control-rubric.md。
   • モデルの検出またはプライバシーの詳細：references/model-detection.md。
3. 目標、検証、ホストモデル、カウンシル、ゲート／制御、確認フローのプレビュー、出力／実行オプションの 7 段階でインタビューを行います。制御の段階では、実行境界、分離、進捗がないことを示すシグナル、状態、実行ログを扱います。
4. 各段階を受け入れる前に批評します。曖昧な警告よりも具体的な代替案を優先します。弱い目標は、成果、範囲、コンテキスト、完了状態が明確になるよう促します。弱い検証は、まずプログラムによるチェック、次に判定ルーブリック、その後に人間の承認を検討するよう促します。
5. レビュアーと判定者の役割を分けます。レビュアーはメモを書き、判定者は構造化された判定を返します。revise_until_clean では、verdict_source として判定者のメンバーまたは human を指定する必要があります。
6. 複数の終了ガードを必須とします。max_iterations、各ゲートの修正上限、進捗がない場合の停止、そして予算上限または明示的な人間による停止ポイントのいずれかです。
7. ベンダーをまたぐカウンシルメンバーを選ぶ前に、ユーザーのマシンから送信されるコンテキスト、その送信先となる CLI、適用される秘匿化グロブ、そして両方の実行経路で初回送信時の同意が必要であることを説明します。
8. 計画したループの ASCII フロープレビューを表示し、最終出力の前に確認を求めます。Claude Code CLI で読みやすくなるよう最適化します。
9. 次のファイルを対象に出力します。
   • loop.yaml
   • loop.resolved.json
   • LOOP.md
   • RUN_IN_SESSION.md
   • run-loop.py
   • loop-workspace/
   • README.md
10. loop.yaml を書き込んだ後、ヘルパー Python を解決し（以下の「ヘルパー Python」を参照）、次を実行します。 "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md 次に、以下を実行します。 "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml 検出結果を伝えます。続行する前に、error[...] があればすべて修正します（仕様どおりに動作しません）。warning[...] の行は、ユーザーが受け入れるか対処できる設計上のガイダンスとして提示します。
11. 今すぐこのセッションでループを実行するか、ユーザーに尋ねます。実行する場合は、現在のタスクとして RUN_IN_SESSION.md に直接従います。実行しない場合は、同じファイルが簡単に再開できる方法であり、run-loop.py は高度な外部実行に利用できることを説明します。

テンプレートモード

パターンライブラリは ${CLAUDE_SKILL_DIR}/templates/loops/ にあります。テンプレートごとにディレクトリがあり、コンパイル可能な loop.yaml（プロジェクト固有の箇所を示す {{PLACEHOLDER}} トークンを含む）、README.md（使用する場面、プレースホルダーの一覧、カスタマイズに関する注意事項）、および必要に応じて補助チェッカーを含む scripts/ が格納されています。カタログのインデックスは templates/loops/README.md です。

テンプレートは回答済みのインタビューであり、設計レビューを省略するものではありません。

0. 対象ディレクトリにすでに loop.yaml がある場合は、ステップ 1 の編集／再開ルールが優先されます。テンプレートで上書きしないでください。ディレクトリにループがすでにあることを伝え、続行する前に空の対象を選ぶか、置き換えることを確認するようユーザーに依頼してください。
1. --template に名前が指定されていない場合、名前が不明な場合、または利用可能なテンプレートをユーザーが尋ねた場合は、カタログの表（テンプレートと使用する場面）を表示して選んでもらいます。
2. テンプレートの loop.yaml と README.md を読みます。空の仕様の代わりにテンプレートをベースとして使用します。
3. 白紙から始める場合の 7 段階の代わりに、簡略化したインタビューを実施します。テンプレートの README に記載された各 {{PLACEHOLDER}} の箇所について尋ね、検出された CLI に対してホストモデルの段階を実行し（detect-models）、実際にインストールされ認証済みのものに合わせて host／council の呼び出しを置き換えた後、対象パスとワークスペースパスを確認します。
4. インタビュー後の手順はすべて、変更せずに適用されます。各事前入力済みの段階をその評価基準（ステップ 4）に照らして批評し、構造上のルール（ステップ 5～8。ベンダーをまたぐエグレスに関する記述を含む）を確認し、ASCII のフロープレビュー、確認、出力、コンパイルを行います。
5. loop.yaml に {{ トークンが残っている間は、絶対に出力しないでください。この場合、コンパイラーは looper: warning: unresolved template placeholders remain ... と警告します。この警告は助言ではなく、処理を止める条件として扱ってください。
6. 出力時に、テンプレートの scripts/ ディレクトリがある場合は、標準の出力ファイルとともに <target>/scripts/ にコピーしてからコンパイルを実行します。

ファイルのルール

• すべてのモデル呼び出しとチェック呼び出しには、シェルコマンド文字列ではなく argv 配列を記述してください。
• API キー、アクセストークン、パスワード、CLI の認証情報を loop.yaml、loop.resolved.json、モデルレジストリに記述しないでください。
• デフォルトの秘匿対象グロブは .env、.env.*、secrets/**、**/*.key です。
• loop.yaml は人が読みやすい状態に保ち、役立つ箇所にはコメントを付けてください。出力されたランナーが読み込むのは loop.resolved.json のみです。
• RUN_IN_SESSION.md は、デフォルトで簡単に実行を引き継ぐためのファイルとして維持してください。現在の LLM セッション、または後で貼り付けるプロンプトで使うことを想定しています。
• ユーザーから外部ランナーの契約を変更するよう明示的に依頼されない限り、templates/run-loop.py をそのままコピーしてください。

補助 Python

インストーラーはスキルディレクトリ内に非公開の venv を作成します。その Python は、macOS/Linux では .venv/bin/python、Windows では .venv/Scripts/python.exe にあります。コマンド間でシェルの状態は引き継がれないため、以下の補助コマンドの呼び出しにはすべて、この解決処理を前置してください（POSIX シェルおよび Windows 上の Git Bash で動作します）。

LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/bin/python"; [ -x "$LOOPER_PYTHON" ] || LOOPER_PYTHON="${CLAUDE_SKILL_DIR}/.venv/Scripts/python.exe"; [ -x "$LOOPER_PYTHON" ] || { LOOPER_PYTHON=python3; "$LOOPER_PYTHON" -c "" >/dev/null 2>&1 || LOOPER_PYTHON=python; }

最後のフォールバックは、候補の場所を特定するだけでなく、候補を実際に実行します。Windows では、PATH 上の python3 が Microsoft Store のエイリアススタブであることが多く、存在はしていてもスクリプトを実行できないためです。-c "" を実行できる候補がない場合は、Looper インストーラーを再実行するようユーザーに伝えてください（インストーラーが venv を作成します）。

ヘルパースクリプト

以下の各コマンドでは、同じシェル呼び出し内でヘルパーの Python 解決パスを先頭に指定します。

• モデル CLI を検出します： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py detect-models --write
• カスタム CLI を登録します（フラグを含む場合は、呼び出し全体を引用符で囲みます）： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py register-model <id> --invoke "<cmd> [args...]"
• コンパイルしてレンダリングします： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py compile <target>/loop.yaml --out <target>/loop.resolved.json --render <target>/LOOP.md --session-prompt <target>/RUN_IN_SESSION.md
• design-rubric のアンチパターンに照らしてリントします（警告がある場合に失敗させるには --strict を、ツールで扱うには --json を追加します）： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py lint <target>/loop.yaml
• セッション内の引き継ぎプロンプトのみをレンダリングします： "$LOOPER_PYTHON" ${CLAUDE_SKILL_DIR}/scripts/looper.py session-prompt <target>/loop.resolved.json --out <target>/RUN_IN_SESSION.md

確認フローのプレビュー

以下の形式を使用し、ラベルをカスタマイズします。

+--------------------------------+
| 1. Goal + context              |
| read sources                   |
+--------------------------------+
               |
               v
+--------------------------------+
| 2. Draft plan.md               |
| state -> state.json            |
+--------------------------------+
               |
               v
+--------------------------------+
| 3. Plan gate                   |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 2
               | pass
               v
+--------------------------------+
| 4. Write delivery-N.md         |
| log -> run-log.md              |
+--------------------------------+
               |
               v
+--------------------------------+
| 5. Delivery gate               |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 4
               | pass
               v
+--------------------------------+
| 6. Final output                |
| all gates clean                |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens

出力チェックリスト

• 目標に、明確な成果、スコープの境界、コンテキストのソース、完了状態が設定されています。
• 検証基準の種類は programmatic、judge、human のいずれかです。
• ユーザーがそのリスクを明示的に受け入れている場合を除き、少なくとも1つの基準は雰囲気だけに基づくものではありません。
• 各 revise_until_clean ゲートに有効な verdict_source が設定されています。
• すべての外部呼び出しが、タイムアウトを指定した argv 配列になっています。
• ベンダー間の外部送信範囲が限定され、データが秘匿化され、同意が必須になっています。
• loop_control に、イテレーション、修正、進捗なし、経過時間または予算の上限が設定されています。
• 現在のワークスペースを選択する場合も含め、実行境界と分離方法が明示されています。
• 可観測性に、run-log.md と state.json のパスが指定されています。
• 引き継ぎ前に、loop.resolved.json、LOOP.md、RUN_IN_SESSION.md のコンパイルが成功しています。