loop-factory

Loop Factory

Loop Factory は、「エージェントに何かを作るよう頼む」ことを、目に見える組立ラインに変えます。各タスクは Markdown の 仕様書 です。仕様書が置かれているフォルダーが、そのまま状態を表します。エージェントは実装と検証を行いますが、何を作るかは決めません。

   📥 inbox/          🔧 active/           📦 archive/
   tasks not      ──► task an agent    ──► finished work,
   started yet        is building now      reviewed + accepted

すべてを統制する唯一のルールは、製品に関する決定ではなく、実装と検証を自動化することです。仕様書に決定事項が欠けている場合は、未解決の質問として記録してください。製品の方向性を勝手に決めてはいけません。

必要に応じて /loop-factory と入力してこのスキルを呼び出す（手動で1回実行する）か、cron による無人実行に任せることができます。［自律モード］（#autonomous-mode-cron）を参照してください。

このスキルを使う場面

• リポジトリに Loop Factory をセットアップする（CLI をインストールし、init を実行する）。
• インボックスから仕様書を選び、Claude Code または Codex にディスパッチする。
• 受け入れ基準に沿って仕様書を実装する。
• 完了した作業をレビューし、承認された仕様書をアーカイブする。
• 実装で得た学びを、更新を続ける仕様書やドキュメントに反映する。

セットアップ（リポジトリでの初回のみ）

状態管理エンジンは loop-factory CLI です。一度インストールすれば、任意の git リポジトリをスキャフォールドできます。

# get the CLI (clone the source repo, install editable)
git clone https://github.com/JuliusBrussee/Loop-Factory.git
python3 -m pip install -e ./Loop-Factory

# scaffold the factory/ folders in your target project
cd your-project
loop-factory init
loop-factory doctor      # confirm git + agent CLIs are wired up

Python 3.10 以外のランタイム依存関係はありません。すでに Loop-Factory リポジトリ内にいる場合は、インストールを省略して python3 bin/loop-factory <command> を直接実行できます。インストール手順の全文、エージェント CLI のセットアップ方法、ネイティブエージェントアダプターのコピー方法については、references/install.md を参照してください。

ループ

1. キューを確認します。 loop-factory scan を実行して、インボックスとアクティブな仕様書を確認します。
2. 新しい仕様書は、まず詳細を確認します。 新しい仕様書をディスパッチする前に、一度に1つずつ質問して内容を掘り下げてください（この決定の責任者は誰か、対象範囲外は何か、最もリスクの高い前提は何か、許容できる最小バージョンは何か）。回答は # Grill Gate セクションに記録します。曖昧な仕様書からは、曖昧なコードが生まれます。
3. ディスパッチします。 実装プロンプトを生成し、仕様書を active/ に移動します。

   loop-factory dispatch --agent claude --limit 1 --stage
   

   これにより、プロンプトが factory/prompts/ に、実行記録が factory/runs/ に書き込まれます。--execute を追加しない限り、AI は実行されません。
4. 実装します。 受け入れ基準だけを実装します。既存のコードスタイルに合わせ、対象範囲を守ってください。
5. 検証します。 仕様書の verification: フロントマターに記載されたすべてのコマンドを実行します。出力を証拠として保存します。
6. レビューします。 レビュープロンプトを生成し、基準に照らして差分を確認します。

   loop-factory review <spec-id> --agent claude
   

   合格 → アーカイブします。不合格 → 次の作業に備えて、仕様書を active/ に残します。
7. 承認された作業をアーカイブします。

   loop-factory archive <spec-id> --accepted
   

   --accepted が必須なのは意図的です。合格が確認されるまで、何も active/ から移動しません。
8. バックプロパゲーションします。 機能の構築によってシステムの実際の動作が変わった場合は、製品の意図を変えずに、その内容を仕様書やドキュメントに反映します。

   loop-factory backprop --agent claude
   

自律モード

人がいない状態で受信箱を空にする、自己完結型の処理を一度実行します。「autonomous」／「drain the inbox」で呼び出されたとき、スケジュールされた cron による実行時、または /loop で繰り返し実行するとき（例：/loop 30m /loop-factory）に起動します。

1回の処理では、次のことだけを行います。

1. factory/specs/inbox/ をスキャンします。
2. 準備ができている仕様だけに絞り込みます。 仕様のグリルゲートが完了している場合、つまりフロントマターに grill: completed があるか、# Grill Gate セクションに記入があれば、準備完了です。それ以外はスキップし、「グリルが必要」と記録します。自律的にグリルを行ってはいけません。グリルゲートには人間の回答が必要であり、それをでっち上げることはプロダクトの方向性を決めることになるためです。
3. 準備ができている仕様ごとに、ステージング → 受け入れ基準に沿った実装 → 検証の実行を行います。
4. レビューゲートで停止します。 実装済みの仕様は active/ に残します。アーカイブしてはいけません。受け入れの判断は人間が行います。
5. 検証に失敗した場合は、仕様を active/ に残し、factory/runs/ にメモを記録します。ループで再試行したり、合格させるために基準を緩めたりしてはいけません。
6. 報告する内容は、実装済み、スキップ（グリルが必要）、検証失敗の各件数です。その後、停止します。

これにより境界が保たれます。ループは疲れを知らないビルダーであり、ひそかに判断を下す決定者ではありません。

定期的に実行する方法は2つあります。

• /loop（ローカル、アクティブな作業に推奨） — /loop 30m /loop-factory は、ローカルの作業ツリーを対象に、任意の間隔でこのスキルを再実行します。実装済みの仕様は active/ に置かれます。git push や PR は必要ありません。Claude Code のセッションが開いている間だけ実行されます。
• Cron（クラウド、無人実行） — オンラインかどうかにかかわらず実行されるスケジュール済みのルーチンです（最短間隔は1時間）。作業結果はプルリクエストとして返されます。

どちらの方法も、安全設定とあわせて references/autonomous.md に記載されています。

基本コマンド

loop-factory scan                              # list inbox + active specs
loop-factory dispatch --agent <claude|codex> --stage   # prompt + move to active
loop-factory review <spec-id> --agent <claude|codex>   # generate review prompt
loop-factory archive <spec-id> --accepted      # archive a passed spec
loop-factory backprop --agent <claude|codex>   # sync docs/specs with code
loop-factory doctor                            # health-check setup

どこでも --agent claude を --agent codex に置き換えられます。ループの動作は同じです。デフォルトではプロンプトファイルが書き出されます。--execute を追加するのは、ローカルに codex／claude CLI がインストールされており、ユーザーが実行を求めている場合だけにしてください。すべてのフラグについては references/commands.md を参照してください。

仕様の作成

仕様は、フロントマター（id、title、agent、risk、verification）と、Context、Acceptance Criteria、Constraints、Review Notes を含む本文で構成される Markdown です。受け入れ基準は契約です。エージェントが実装の目標とし、レビュアーが照合する対象なので、具体的でテスト可能な内容にしてください。形式、例、グリルゲートの質問については references/spec-authoring.md を参照してください。

境界

• 仕様を inbox から active に移動できるのは、人間または明示的な CLI コマンドだけです。
• 仕様を active から archive に移動できるのは、レビューで承認された場合だけです。
• レビューに失敗した仕様は active に残ります。削除されたり、ひそかに再ディスパッチされたりすることはありません。
• Backprop は仕様やドキュメントを更新できますが、それ自体でプロダクトの意図を変更してはいけません。
• factory/prompts/、factory/runs/、factory/reviews/ 内の生成ファイルは成果物であり、監査証跡です。内容を読むことはできますが、信頼できる唯一の情報源として扱ってはいけません。信頼できる唯一の情報源は仕様です。

サブエージェントとの連携

分離が有効な場合は、すべてを1つのコンテキストで行うのではなく、各ステージを専用のサブエージェントに任せます。

• 1つのアクティブな仕様のコードを書く spec-implementer。
• 差分を評価する、コンテキストを分離した spec-reviewer。
• 学びを仕様やドキュメントに反映する spec-backpropagator。

作業が順次進む場合、同じファイルに触れる場合、またはリスクが高い場合は、エージェントを1つ使います。仕様が互いに独立している場合や、レビューのコンテキストを分離すべき場合に限り、複数のエージェントに分担させます。