Rebuilding this site with agents, in phases that cannot collide

Context#

Until November 2026 this site described a frontend architecture advisory. The practice behind it had become something else: an engineering studio whose products are built by AI agents and checked before release. The site had to say so, and the repositioning was a good test of the method on a codebase that has nothing to do with religious text: a Next.js static export on Cloudflare Pages, a Turborepo with three packages, seven articles, a hand-rolled MDX renderer, and no test runner at all.

The rules were the ones every Al Marfa repository runs under. Every behaviour change is test-driven, with the red run shown before the change and the green run after. Nothing is pushed or released without the owner. No agent edits a file another agent owns.

What the audit found before anything was built#

The first version of the plan was reviewed against its sources before a line of code changed, and three claims in the approved mock were wrong.

• The homepage said 362 Qur'an word matches had been "reviewed by a person". The source plan records that the agent decided those cards itself; the owner's read is still to come.
• The evaluation copy said a 150-verse sample had found zero errors. The decision record says 2 wrong words in 120 verses, with 19 more found by targeted sweeps.
• The Work page listed a product as a preview that had shipped five days earlier.

All three were corrected in the copy document, with a table naming each source file, before the phases were cut. The hero became "Checked twice, released by people", a line that is true today, with the stronger line held back until the owner's review lands. A site whose pitch is "evidence before claims" cannot launch on claims the evidence does not support.

Constraints#

• Static export only. No server runtime, no edge functions. Server components by default. The mobile navigation stays a CSS-only disclosure.
• The taxonomy is one file. Pages never restate it. Retiring an expertise area means a redirect and a test, not a deleted page.
• One worktree per phase, one branch per phase. Agents never share a checkout.
• Red before green, both shown. A phase that reports only a passing suite is sent back.
• Cheaper agents build; the lead reviews. Sonnet did the implementation. The orchestrating session wrote the briefs, read every diff and every test output, and merged.

Method#

1. A phase manifest with file ownership. Each phase lists the paths it may edit. Two phases share a wave only when their dependencies are met and their owned paths are disjoint. The schedule that falls out of this is the real parallelism, not the dependency graph: the taxonomy migration and the parser extension had nothing in common and ran together; the page copy had to wait for both.
2. Phase 0 lands the runner. Vitest in every package, a test task in Turborepo that also invalidates on content edits, pnpm test in CI between type-check and build, and the move from Node 20 (end of life) to Node 22. The same phase centralised which routes search engines may index into one table, so the sitemap and the page metadata can no longer disagree. Three tests were red before that table existed.
3. Wave 2, three phases in parallel. The MDX renderer was first pinned with characterisation tests, then extended red-first to render bold, code, links, tables, fenced code, quotes and a chart block. The seven old expertise slugs became seven new ones, with every retired URL redirected straight to its final target and a test that no redirect target is itself a source. The SEO layer dropped a keyword seed every article had been carrying and gained a knowsAbout hook for the organisation schema.
4. Wave 3. Page copy from an approved document, verbatim, guarded by source-text tests that fail on any retired positioning string or on the hero claiming more than the record supports. The first case study, with its chart rows checked to sum to 100.
5. Each brief carried the rules and the red tests by name. Agents reported the failing output, the passing output, the files touched against their ownership list, and anything they could not do. When a test could not be seen red because the old code already satisfied it, they said so and either reconstructed the red by reverting the change or recorded the test as a guard.

Results#

What the review found#

• Agents stop at the boundary when the boundary is explicit. Every report listed its files against its ownership list. One phase found a file it needed that the manifest had not assigned and left it for the phase that owned it rather than widening scope.
• The red run catches tests that prove nothing. Three of the tests agents wrote passed against the old code. Each was reported as such, and two were made to fail by deliberately breaking the behaviour before being restored. Without the rule those tests would have counted as coverage.
• Briefs drift from reality; the agent should say so. One brief quoted sitemap priorities that did not match the live file. The agent kept the live values, said why, and offered the one-line change if the brief's numbers were wanted. That is the right answer, and it only happens when the brief asks for disagreement to be reported rather than resolved silently.
• Caching hides stale builds. A cached Turborepo build could ship an article edit without rebuilding. Declaring the content directory as a task input fixed it; a test runner alone would not have.

What we would change#

• Cut the visual phase in two from the start. Tokens and header changes touch no page file and could have run beside the page copy. They were split later, at the cost of one idle hour.
• Give phases that write prose a figures file, not a brief. Every number the site shows now lives in one module with its source path. The case studies should draw from the same place so a figure is corrected once.
• Reconstruct the red by default. When a fix arrives with its test, revert the fix, run, confirm the failure is the one claimed, restore. Two agents did this unprompted; it should be in every brief.

Why this transfers#

Nothing here depends on the subject. A file-ownership manifest, worktrees, red-first tests, a central table for anything two places must agree on, and a lead who reads the diffs apply to an Angular upgrade or an Nx migration exactly as they applied to this static site. What the religious-text products add is the discipline that a wrong answer is not a typo. Running that discipline on an ordinary web codebase is what this rebuild was for.