Loop Engineering: Building Web Apps with an Agent in the Loop

What Is an Agentic Harness?

An AI agent can write code, operate tools, and make decisions. An agentic harness is the system around that agent: it gives the work a shape, observes what actually happened, runs checks, feeds useful failures back, and decides whether to continue or stop.

Spiderloop is one implementation of that idea. Its source is organized around a domain-agnostic core, web workflows, and a service layer. The examples below are more useful than a tour of every internal module:

• /spiderloop:run: build a site, inspect it in a real browser, run quality gates, then iterate.
• /spiderloop:review: similar to Deckmark, hand the browser back to a person, collect annotations, and apply those notes to source.
• /spiderloop:migrate: capture a parity baseline from an existing site and use it as the oracle while moving route by route.

That same pattern can support focused modes for bug fixes and telemetry: define the evidence first, then let the agent work toward it.

Do You Need One?

No, not automatically. If you know exactly what needs to be done, the task is small, and verification is obvious, adding a harness can be more work than the task itself. A careful person with a direct prompt may be faster.

The value appears when the work repeats or the verification is easy to forget. A harness can save time by automating the same checks and prompts, preserve practices that would otherwise live in someone’s memory, and reuse those practices across projects. It is especially useful for teams building sites, fixing recurring classes of bugs, migrating systems, or asking agents to touch work that still needs an accountable review.

Think of it as operational leverage, not mandatory ceremony: skip it for a one-off task with a clear finish line; reach for it when you keep solving the same process problem.

The Gap: “Looks Done” Is Not Done

Give an agent a brief that says “build me a site” and it can produce something convincing in minutes. The page loads. The headline is there. The colors are coherent. Everyone nods.

Then you look closer. A social card points to an image that does not exist. A block of useful content is hidden from assistive technology. A mobile layout overflows by 12 pixels. The agent did not lie exactly; it simply had no mechanism that forced it to find out.

That is the failure mode I care about. The problem is not that the model cannot make a good first attempt. The problem is that the thing doing the work is also being asked to decide whether the work is good.

Separate the Worker from the Judge

The central design decision is a separation of powers:

• The model is the worker. It writes code, drives the browser, gathers observations, and fixes findings.
• The harness is the driver. It owns the state machine, runs the checks, computes the verdict, and decides whether another round is allowed.

The harness is intentionally less clever than the model. That is a feature. Its job is to be predictable: “this gate was measured and passed” means something different from “the agent said it looked fine.”

The Loop: Build, Verify, Iterate, Stop

Spiderloop expresses the workflow as a state machine. A worker receives one bounded instruction at a time, and the driver decides what happens next.

loop:
  step = next_action(state)
  if step.done: break
  observation = worker.do(step)
  verdict = gates.evaluate(observation)
  if not (verdict.pass and verdict.complete):
      worker.fix(verdict.failures)
      continue
  if step.needs_judge:
      judge = critic.judge(observation, brief)
      if judge != accept:
          worker.fix(judge.findings)
          continue
  if stop_conditions_hit(state): halt_and_ask()

report(state)

The key word is complete. A green result cannot mean “nothing failed.” It must mean “everything that should have been measured was measured, and nothing failed.”

What the Runs Found

I launched the two Loki sites independently and checked the same six routes in a real browser. The important distinction is in the evidence: the Spiderloop run has a persisted ledger with completed gates and judge results; the single-pass run has no equivalent ledger, so its results below are a fresh live audit, not a retroactive Spiderloop score.

The accessibility failure is specific, not cosmetic. The single-pass homepage sets aria-hidden on the trait-card group whenever motion is enabled, which removes useful cooling, RGB, display, and I/O information from the accessibility tree. Decorative HUD layers can be hidden; product facts cannot.

That is the value of running the sites separately. The looped result is not “perfect,” and the single-pass result is not worthless. But the persisted checks make the quality claim inspectable instead of asking the author to remember which version felt better.

The Principles I Would Reuse

1. Objective truth before subjective taste

Start with machine-checkable gates: console errors, failed requests, layout shift, horizontal scroll, accessible names, touch-target size, and headline wrapping. Let the model report observations; let pure functions render verdicts.

2. The brief is the judge

Write down the audience, goal, positioning, primary action, constraints, and ambition before building. Subjective review should score alignment to that brief, not the critic’s personal taste.

3. Never allow vacuous green

Track each gate as passed, failed, or notChecked. “Not checked” must never collapse into “passed.”

4. Keep the cheap loop cheap

Editing and re-observing a hot dev server is cheap. A heavyweight visual critic is expensive. Use the critic at a bounded point in the loop, not as a babysitter for every keystroke.

5. Build the brakes early

Iteration caps, stuck detectors, regression detectors, and plateau rules are part of the product. When the diagnosis is wrong, the right result is an honest incomplete state that asks for a human, not a fake green check.

6. Structured failures beat prose

Stable error codes let the driver branch reliably. A useful envelope looks like this:

{
  "error": "The dev server did not start",
  "code": "SL_DEV_SERVER_FAILED",
  "message": "Port 5173 is already in use",
  "nextTool": "find_available_port",
  "userAction": null
}

Same Loop, Different Gate

The architecture generalizes because the loop does not care what “done” means. Change the observation source and the gates:

• Build: functional behavior, visual quality, accessibility, and performance gates.
• Migrate: parity against the old system’s output.
• Fix a bug: reproduce first, then prove the repro is gone without regressing nearby paths.
• Instrument: verify that real events reach the intended sink.

Your gate is your spec. Once you can state the machine-checkable definition of success, the same driver can move the work forward.

Build for the Loop, Not the Prompt

The model is still the interesting part when it makes a surprising design choice or solves a hard implementation detail. But the durable engineering insight is elsewhere: generation is only one state in a larger system.

Loop Engineering means build, verify against objective truth, iterate, and know when to stop. The model supplies capability. The harness supplies boundaries, evidence, and memory. A human still closes the last stretch where taste, context, and judgment matter.