Agent Loop

Agent Loop

Run durable PLANNER→IMPLEMENTOR→REVIEWER→JUDGE coding loops via Inngest. Each story in a PRD gets independently implemented, tested, and judged. Survives crashes. Every step is a traceable Inngest run.

Hard gate: verification comes before loop throughput. If agents cannot prove the work is correct without Joel manually babysitting, do not start an autonomous loop yet. First add the missing reproducible check, browser/control tool, quality rubric, or reusable skill that lets future agents verify their own output.

Source receipt: lauren / @poteto's X article "Loops You Can Trust" (2026-06-24) frames verification as the limiting step: loops without trusted verification compound slop, while reusable skills/tools turn human experience into agent leverage.

After starting a loop, use the loop-nanny skill for monitoring, triage, post-loop cleanup, and knowing when to intervene.

Verification Preflight

Before joelclaw loop start, confirm every story has:

• Proof path: exact command, test, browser flow, API readback, screenshot/video, log query, or source inspection the agent can run.
• Quality bar: what "good" means, what failures look like, and which shortcuts are unacceptable.
• Before/after evidence: how the agent captures the broken/old state and proves the fixed/new state.
• Isolation plan: worktree, ports, browser state, app instance, database, or fixture isolation when parallel agents could collide.
• Reusable verifier: if the proof currently lives in a human's head, author a skill/tool first so future agents inherit it.

If this preflight fails, the next task is not "run the loop". The next task is "teach agents to verify this class of work".

Quick Start

# 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

The joelclaw CLI is the primary interface. Run with bun run packages/cli/src/cli.ts loop start ... from the monorepo root.

PRD Format

Create a prd.json in the project root:

{
  "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
    }
  ]
}

Story writing tips:

• Acceptance criteria must be machine-verifiable (tests, typecheck, lint)
• Include the verification method or artifact in the criterion, not just the desired behavior
• If a criterion needs manual taste, first turn that taste into a reusable review checklist, skill, fixture, or tool
• Lower priority number = runs first
• Keep stories small and atomic — one concern per story
• Include file paths in descriptions when possible
• passes flips to true when JUDGE approves; skipped: true added on max retry exhaustion
• Runtime preflight normalizes legacy aliases (acceptance, acceptanceCriteria) to acceptance_criteria, but malformed stories still fail fast with explicit schema errors — keep PRDs canonical.

Pipeline Flow

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

Create a progress.txt in the project root with a ## Codebase Patterns section at the top. This is read by the implementor for project context and appended by the judge after each story. Defends against context loss across fresh agent instances.

## Codebase Patterns

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

## Progress

(stories will be appended here)

Infrastructure

• Canonical source: ~/Code/joelhooks/joelclaw/packages/system-bus/ (monorepo)
• Inngest functions: agent-loop-plan, agent-loop-implement, agent-loop-review, agent-loop-judge, agent-loop-complete, agent-loop-retro
• Inngest server: k8s StatefulSet at localhost:8288
• Loop --project target: Use the absolute target project named by the request. The system-bus package owns loop runtime code; it is not every workload’s target.
• Apply worker changes: ~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh
• Verify functions: joelclaw functions
• View runs: joelclaw runs -c
• Inspect a run: joelclaw run RUN_ID

Single-source deployment flow

The monorepo is the source of truth for loop function code. After loop-related function changes merge, deploy the worker from the monorepo:

1. Run ~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh
2. Wait for rollout: kubectl -n joelclaw rollout status deployment/system-bus-worker --timeout=180s
3. Refresh registration: joelclaw refresh

Event Schema

All events carry loopId for tracing. Key events:

Tool Assignment

Default: codex for implementation, claude for review. Override per-story via toolAssignments in the start event:

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

Known Gotchas

• Concurrency keys use CEL expressions (event.data.project), not {{ }} templates
• loop is reserved in CEL — don't use in concurrency key strings
• Read codex exec --help for current invocation flags. Use the configured sandbox and approval policy; do not weaken them as part of task dispatch.
• Worker changes require a k8s deploy (k8s/publish-system-bus-worker.sh)
• Docker must be running for Inngest server (open -a OrbStack)
• Large tool output uses claim-check pattern (written to /tmp/agent-loop/{loopId}/)

Telemetry and receipts

Story attempts must be visible through loop status, Inngest runs/events, and canonical OTel. Query with:

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

The former slog write path is retired. Capture only durable loop decisions or behavior changes in Brain .svx; do not recreate an append-only journal.

Source Files