RETARD

Problem

Standing up a new site or brand-adapted scaffold from a reference site normally means a human manually inspecting the target, describing its structure and voice in a brief, and hoping an agent-driven build stays faithful to that brief or, alternately, correctly discards it in favor of locked brand tokens. There was no deterministic, machine-checkable pipeline that captured a real site, produced a structured profile of it, and then executed a build plan against independently verifiable gates rather than trusting the model's own account of what it did. The failure mode this was built to close isn't the model writing bad code, it's the model writing code, claiming a task is done, and that claim being the only signal anyone checks. A prose handoff between pipeline stages (reverse-engineering output described in Markdown, fed to a planner as more Markdown) has the same problem one layer up: a generated summary of a site is not the same thing as a validated structured profile of it, and nothing stops drift between what a stage reports and what it actually produced. Any agent-driven build system that trusts self-reported success or parsed prose as its source of truth inherits both failure modes at once.

What was built

A local CLI, RETARD, that takes a URL plus optional reference images and an objective, and either profiles the target (reverse-engineering its brand and content) or drives a full build: capturing the site, analyzing it, generating a validated ProjectSpec, planning a task graph, and executing that graph through Claude Code with each task checked by real, independent verification commands (typecheck, lint, test, build) rather than the agent's own claim of success. Build mode also accepts an explicit cost ceiling and target directory on the command line, and build targets are confined to a single allow-listed root directory on both the CLI and browser paths so a build can never be pointed at an arbitrary location on disk. A companion hosted console exposes the profiling half of this to the Evolve Agentic tools catalog for a same-session browser workflow, running as a launchd-managed local service so it survives host restarts without a manual relaunch; the full multi-hour build mode remains CLI-only because the console's job runner has a fixed timeout an order of magnitude shorter than a real build takes. A separate integration wired the same reverse-engineering engine into the broader Evolve Agentic tools suite as one of its registered tools, exercised by its own dedicated test suite (335 tests) distinct from both the engine's and the console's, so a regression in the shared tools kit can't hide behind either project's own green run. Jobs submitted through the console persist to disk as records, though the underlying page capture (full HTML plus screenshot) is deliberately not persisted alongside them, so a restored job is a status record, not something that can resume mid-capture.

Technical approach

The system enforces a hard boundary between model output and system state: agent-to-agent handoff never parses generated Markdown, only validated Zod schemas, and ProjectSpec JSON is the sole source of truth, with any Markdown purely a generated view. Execution correctness is decoupled from the model's self-report entirely: a task is verified by running its own gate commands against the actual repo state, and several real defects were only found by running full builds against real sites rather than by the (green) test suite, because a fake SDK in tests returns on the first turn and never exercises multi-turn planning failure modes like a maxTurns: 1 cap that failed on every real call, or a lint step seeded with no eslint config that silently failed every task that depended on it regardless of code quality. One subtler bug: the executor committed its own work as designed, leaving a clean git tree, but the orchestrator's mutating-git guard (meant to live in the reviewer hook) flagged the clean tree as evidence of nothing having happened and halted a run whose work was in fact complete, an invariant that was documented but not actually enforced in the right place. Billing runs entirely on a Claude Max subscription rather than a metered key: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are stripped from the child process environment so Claude Code falls back to subscription OAuth, a deliberate choice since the alternative (a metered key) would silently move cost onto a different, unbounded surface. Measured per-call overhead of driving Claude Code (~53.5k input tokens) turned out not to be reducible by supplying a custom system prompt, a hypothesis the team tested and rejected with real numbers rather than assuming. The two rebuild modes (auto vs locked brand tokens) are asserted against each other in the test suite specifically because they carry opposite planner instructions and a regression in one could silently make the other behave like it.

Creative approach

Craft

There is no end-user-facing visual craft here in the ordinary sense; the console's browser form is a thin submit-and-poll interface. The craft is procedural: verification commands as the aesthetic of trust, and a task-graph shape that mirrors how a careful engineer would actually break down a rebuild rather than how a model would naturally chunk it. That shows up as a fixed sequence of four independent quality gates, typecheck, lint, test, build, run against the real repo state after every task, never against the model's account of what it changed, and the same four gates run again at the project level before any milestone is considered closed. It also shows up in a rule the codebase enforces on itself: the console's own build step typechecks against the engine's compiled output rather than its source, specifically so that a signature drift in the engine surfaces as a console compile failure instead of silently shipping. Task granularity got tuned by hand more than once, the planner initially trended toward too many small tasks, was constrained toward fewer, and then over-corrected into producing single oversized tasks that failed for an unrelated reason, so the current shape of the task graph is the residue of that back-and-forth rather than a first draft.

Reframe

The deepest insight is treating 'the model said it worked' as categorically untrustworthy input, not a shortcut worth taking even under time pressure. Every layer of the pipeline, from Zod-validated handoffs instead of parsed prose to independent verification commands instead of self-reports, is the same principle applied at a different altitude: agents are good planners and bad witnesses, so the system is built to never ask an agent to testify about its own success. The same principle produced a genuine surprise during the build: the orchestrator's own guard against a mutating git tree, meant to catch an agent that silently made changes it never reported, fired on a run where the executor had done exactly what it was supposed to do and committed its own work, leaving a clean tree that the guard read as evidence nothing had happened. The rule that agents shouldn't be trusted to report their own state turned out to cut both ways: a system built not to trust the model can still misfire if the non-model check itself is wired to the wrong signal, which is why the fix moved the guard to the reviewer hook rather than loosening the rule.

Process and what failed

The project's own defect log is unusually candid about what only surfaced by actually running the thing: a greenfield target failing both engine gates before any spec could pass, a .gitignore that ignored runtime directories but missed one nested path a real target needed, a planner validated against rules that only a real site's complexity could trigger (invented scripts, shared file ownership, lockfile conflicts), and the author's own explicit admission that a 'prefer few tasks' fix overcorrected into producing a single oversized task that then failed for a different reason. A live service was found to be silently serving the previous day's build after a code change with no restart, discovered only by comparing a health-check timestamp against the actual compiled artifact's mtime. The tenth and final task of the best recorded build run failed on a Tailwind v3/v4 postcss config mismatch the agent introduced itself, left as an open, expected-fixable item rather than papered over.

Outcome

The engine and console both pass their full test suites (421 and 291 tests respectively), the broader tools-suite integration passes its own 335 tests with 19 tools registered, and the CLI has completed real, costed build runs producing working brand-adapted scaffolds committed to disk. The best recorded run completed 9 of 10 planned tasks and committed each of them before the final task blocked on a Tailwind v3/v4 postcss config mismatch the agent had introduced itself, for roughly $18 of Max subscription quota rather than metered API spend. The profiling half is live inside the Evolve Agentic tools catalog; the full multi-hour build mode is deliberately CLI-only and not exposed through the browser front door, which has a much shorter job timeout than a real build takes. What's still open at the last recorded handoff: getting one more full build run to 10 of 10, and exercising the auto brand mode and reference-image input end to end through a real build rather than only through the studio locked-token path that's been proven so far.