agent-loop

エージェントループ

Inngest を介して、永続性のある PLANNER→IMPLEMENTOR→REVIEWER→JUDGE のコーディングループを実行します。PRD 内の各ストーリーは、それぞれ独立して実装、テスト、判定されます。クラッシュしても処理を継続できます。各ステップは追跡可能な Inngest の実行として記録されます。

厳格なゲート： ループの処理速度より、検証を優先します。Joel が手作業で付き添わなくても、エージェントが作業の正しさを証明できない場合は、まだ自律型ループを開始しないでください。まず、不足している再現可能なチェック、ブラウザー／操作ツール、品質基準、または再利用可能なスキルを追加し、今後のエージェントが自分の出力を検証できるようにします。

出典：lauren / @poteto の X 記事「Loops You Can Trust」（2026-06-24）では、検証が制約要因として位置づけられています。信頼できる検証のないループは質の低い出力を増幅させますが、再利用可能なスキルやツールは、人間の経験をエージェントの力に変えます。

ループの開始後は、 loop-nanny スキルを使って、監視、トリアージ、ループ後のクリーンアップ、介入が必要なタイミングの判断を行います。

検証の事前確認

joelclaw loop start の前に、各ストーリーに以下があることを確認してください。

• 証明手段： エージェントが実行できる正確なコマンド、テスト、ブラウザーフロー、API の読み戻し、スクリーンショット／動画、ログクエリ、またはソースコードの確認方法。
• 品質基準： 「良い」状態の定義、失敗の状態、許容できない近道。
• 変更前後の証拠： エージェントが変更前の壊れた／古い状態を記録し、修正後の新しい状態を証明する方法。
• 分離計画： 並列エージェント間の競合が発生しうる場合の、ワークツリー、ポート、ブラウザー状態、アプリケーションインスタンス、データベース、またはフィクスチャの分離方法。
• 再利用可能な検証手段： 証明方法が現時点で人の頭の中にしかない場合は、まずスキルやツールを作成し、今後のエージェントも利用できるようにします。

この事前確認を通過できない場合、次のタスクは「ループを実行する」ことではありません。次のタスクは「この種の作業を検証する方法をエージェントに教える」ことです。

クイックスタート

# Start a loop
joelclaw loop start --project /path/to/project --prd prd.json --max-retries 2

# Check status
joelclaw loop status [LOOP_ID]

# Cancel
joelclaw loop cancel LOOP_ID

joelclaw CLI が主なインターフェースです。モノレポのルートから bun run packages/cli/src/cli.ts loop start ... を実行します。

PRD の形式

プロジェクトのルートに prd.json を作成します。

{
  "title": "Feature Name",
  "description": "What we're building",
  "stories": [
    {
      "id": "S1",
      "title": "Short title",
      "description": "What to implement. Be specific about files, patterns, behavior.",
      "acceptance_criteria": [
        "Criterion 1 — must be verifiable by automated test",
        "Criterion 2 — must be checkable by typecheck/lint"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

ストーリー作成のヒント：

• 受け入れ条件は機械的に検証できるものにします（テスト、型チェック、リンター）。
• 望ましい動作だけでなく、受け入れ条件に検証方法や成果物も含めます。
• 条件に人の感覚による判断が必要な場合は、まずその判断を再利用可能なレビューチェックリスト、スキル、フィクスチャ、またはツールに変えます。
• 優先度の数値が小さいほど、先に実行されます。
• ストーリーは小さく、独立した単位にします。1つのストーリーにつき1つの懸念事項にします。
• 可能な場合は、説明にファイルパスを含めます。
• JUDGE が承認すると passes が true に切り替わります。最大再試行回数に達すると skipped: true が追加されます。
• 実行時の事前チェックでは、レガシーの別名（acceptance、acceptanceCriteria）が acceptance_criteria に正規化されます。ただし、不正なストーリーは明示的なスキーマエラーですぐに失敗します。PRD は正規の形式にしてください。

パイプラインの流れ

joelclaw loop start → agent/loop.start event
  → PLANNER reads prd.json, finds next unpassed story
    → IMPLEMENTOR spawns codex/claude/pi, commits changes
      → REVIEWER writes tests from acceptance criteria (independently — does NOT read implementation)
        → JUDGE: all green? → mark passed, next story
                 failing?   → retry with feedback (up to maxRetries)
                 exhausted? → skip, flag for human review, next story
  → All done → agent/loop.complete

progress.txt

プロジェクトのルートに progress.txt を作成し、先頭に ## Codebase Patterns セクションを置きます。これは実装担当エージェントがプロジェクトのコンテキストを把握するために読み込み、各ストーリーの後に JUDGE が追記します。新しいエージェントインスタンスでコンテキストが失われるのを防ぎます。

## Codebase Patterns

- Runtime: Bun, not Node
- Tests: bun test
- Key files: src/index.ts, src/lib/...

## Progress

(stories will be appended here)

インフラストラクチャ

• 正規のソース： ~/Code/joelhooks/joelclaw/packages/system-bus/（モノレポ）
• Inngest 関数： agent-loop-plan、agent-loop-implement、agent-loop-review、agent-loop-judge、agent-loop-complete、agent-loop-retro
• Inngest サーバー： localhost:8288 の k8s StatefulSet
• Loop の --project 対象： リクエストで指定された絶対パスの対象プロジェクトを使用します。ループの実行コードを所有するのは system-bus パッケージですが、すべてのワークロードの対象がこのパッケージというわけではありません。
• ワーカーの変更を適用： ~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh
• 関数を確認： joelclaw functions
• 実行を表示： joelclaw runs -c
• 実行を調査： joelclaw run RUN_ID

単一ソースのデプロイフロー

モノレポをループ関数コードの信頼できる唯一の情報源とします。ループ関連の関数変更がマージされたら、モノレポからワーカーをデプロイします。

1. ~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh を実行します
2. ロールアウトを待ちます：kubectl -n joelclaw rollout status deployment/system-bus-worker --timeout=180s
3. 登録を更新します：joelclaw refresh

イベントスキーマ

すべてのイベントには、トレース用に loopId が含まれます。主なイベントは次のとおりです。

イベント	目的
agent/loop.start	ループを開始します（loopId、project、prdPath、maxRetries、maxIterations）
agent/loop.plan	プランナーを再実行します（次のストーリーを探します）
agent/loop.implement	実装者にディスパッチします（storyId、tool、attempt、feedback?）
agent/loop.review	レビュアーにディスパッチします（storyId、commitSha、attempt）
agent/loop.judge	判定者にディスパッチします（testResults、feedback、attempt）
agent/loop.complete	ループが完了しました（summary、counts）
agent/loop.cancel	ループを停止します
agent/loop.story.pass	ストーリーが合格しました
agent/loop.story.fail	最大リトライ回数に達したため、ストーリーをスキップしました

ツールの割り当て

デフォルトでは、実装には codex、レビューには claude を使用します。開始イベントの toolAssignments で、ストーリーごとに上書きできます。

{
  "toolAssignments": {
    "S1": { "implementor": "claude", "reviewer": "claude" },
    "S2": { "implementor": "codex", "reviewer": "pi" }
  }
}

既知の注意点

• 同時実行キーには CEL 式（event.data.project）を使用します。{{ }} テンプレートは使用しません
• loop は CEL の予約語です。同時実行キー文字列では使用しないでください
• 現在の起動フラグを確認するには codex exec --help を参照してください。設定済みのサンドボックスと承認ポリシーを使用し、タスクのディスパッチ時にこれらを緩和しないでください
• ワーカーの変更には k8s デプロイが必要です（k8s/publish-system-bus-worker.sh）
• Inngest サーバーを起動するには Docker が必要です（open -a OrbStack）
• 大きなツール出力にはクレームチェックパターンを使用します（/tmp/agent-loop/{loopId}/ に書き込みます）

テレメトリーと実行記録

ストーリーの試行は、ループステータス、Inngest の実行／イベント、正規の OTel で確認できる必要があります。次のコマンドで照会します。

joelclaw loop status <loop-id> -v
joelclaw otel search "story-pass|story-retry|story-skip|build-complete" --hours 24

以前の slog 書き込み経路は廃止されています。Brain の .svx には、永続化すべきループの判断または動作の変更のみを記録してください。追記専用のジャーナルを再作成しないでください。

ソースファイル

ファイル	目的
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/client.ts	イベント型の定義
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/utils.ts	PRD の解析、git、キャンセル、クレームチェック
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/plan.ts	プランナー
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/implement.ts	実装者
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/review.ts	レビュアー
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/judge.ts	判定者
~/Code/joelhooks/joelclaw/packages/system-bus/src/serve.ts	ワーカー登録
~/Code/joelhooks/joelclaw/packages/cli/src/cli.ts	joelclaw CLI（ループのサブコマンド）