meireles.

Shipping My New Homepage with a Team of AI Agents

If you open meireles.com right now, you get a full-viewport poster: a slow-breathing field of teal dither, a couple of floating shader orbs, and one giant wordmark. No scrolling, no cards, no feed. It replaced a perfectly respectable homepage — hero, photos, six project cards, articles, résumé — that looked like everyone else's perfectly respectable homepage.

Here is the part I actually want to write about: I didn't type the code. Not the shader wiring, not the reduced-motion handling, not the page rewrite. It was built by a small team of AI agents running inside Claude Code, working from specs we wrote together, reviewed by another agent whose only job is design taste, and course-corrected by me — once, significantly — when the first shipped version turned out to be the wrong idea.

This is the build log.

The setup

My site's repo is wired for what I think of as orchestrated development. A CLAUDE.md file at the root sets the ground rules, and the important ones are about division of labor:

  • The orchestrator — the main session I talk to — plans, dispatches, and reviews. It does not write feature code.
  • Implementor agents execute. Well-scoped, mechanical work goes to a cheaper, faster model; architecture-sensitive work (bundler config, the CMS pipeline, subtle bugs) goes to a heavier one.
  • A design-reviewer agent runs after any UI change. It checks hierarchy, spacing, responsiveness, and — because this bites everyone — both light and dark mode, every time.
  • There's no test suite on a site like this, so a verify skill encodes what "checked" means: boot the dev server, walk the pages, test dark mode, keyboard navigation, reduced motion.

None of this is exotic. It's a text file, some agent definitions, and discipline. The interesting part is what the discipline produces.

Spec first, always

The poster didn't start as code. It started as an argument — a brainstorming session where the orchestrator asked me one question at a time. What dies from the old homepage? (Everything except the wordmark and nav.) What personality should the shader have? (A layered dither world, cohesive with the ambient accents already on my /ai page.) How interactive? (Reactive touches only; the pointer-tracking playground stays deferred.)

The output was a design spec, committed to the repo before any implementation:

Replace the content-heavy homepage (hero + photo strip + 6 project cards + articles + resume) with a designer-first shader "poster": a full-viewport dither hero built around the meireles. wordmark... First step toward a future experiential space.

Specs in git turn out to matter more with agents than with humans. An agent will cheerfully build the wrong thing with total confidence; a committed spec is the thing you diff its enthusiasm against.

Dispatch

From the spec came an implementation plan, and from the plan, dispatches. The commit trail reads like a relay race:

3bf08ce Add design spec for homepage dither poster redesign
e46e3a2 Add implementation plan for homepage dither poster
a7696b5 Add HomeHero full-viewport dither poster component
36354ef Add Trailheads reactive link rows
b3e183b Rewrite homepage as dither poster with trailheads

The shader itself comes from @paper-design/shaders-react, a genuinely lovely library of WebGL shaders as React components — browse the live gallery at shaders.paper.design. The implementor's job was integration judgment: the canvas must never render on the server, and it must respect people who ask for less motion.

const Dithering = dynamic(
  () => import('@paper-design/shaders-react').then((mod) => mod.Dithering),
  { ssr: false },
)

// inside HomeHero — one full-bleed canvas behind the wordmark
<Dithering
  colorBack="rgba(0, 0, 0, 0)"
  colorFront="rgba(20, 184, 166, 0.5)"
  shape="warp"
  type="8x8"
  size={2.5}
  speed={reducedMotion ? 0 : 0.1}
  style={{ width: '100%', height: '100%' }}
/>

reducedMotion tracks prefers-reduced-motion via a media-query listener, so the poster renders as a still image for anyone who wants it still. The spec also set a hard canvas budget — the page runs at most a handful of small, slow shader canvases on desktop and exactly one on mobile — because "it's pretty" is not a performance strategy.

Notice what the implementors don't do: they don't run lint, typecheck, or git. The orchestrator runs the gates once per batch. Agents are enthusiastic; the process is the adult in the room.

The review gate

After the build, the design-reviewer agent did its pass — and earned its keep. Its notes from this cycle: the floating depth orbs were being swallowed by the legibility scrim (they moved above it and got nudged outward), the hover chips on the link rows read better resting at full invisibility, and the focus rings needed to be solid teal with an offset instead of the subtle default. Small things. Small things are most of what design is.

The part where I was wrong

Then I looked at the shipped page in a real browser, and the direction was off. The first version was a poster plus a page — you could scroll past the shader to a band of "trailhead" links. It diluted the whole gesture. A poster you can scroll past is just a tall hero.

So: revision. The spec got a formal amendment — the commit is literally titled Spec revision 1: no-scroll poster, floating header, Trailheads to /about — and the agents executed it: the hero became exactly 100svh with nothing below, the site header now floats over the shader with its wordmark hidden (the giant one is the logo there), and the trailhead links moved to the bottom of /about, where they self-filter so the About page doesn't link to itself. The scroll-reactivity code, now dead on a page that can't scroll, was deleted rather than left as a souvenir.

This is the honest core of the workflow. The agents didn't catch that the concept was wrong — they can't, really; the first version matched the spec I approved. What they did do was make the correction cheap. Re-specifying and re-shipping the new direction took an evening, not a week, and the paper trail (spec → revision → synced docs) means the repo remembers why.

What this is and isn't

After a few cycles of working this way, my honest scorecard:

It's good at: volume without drift (specs keep parallel work coherent); the review gate catching the polish I'd rationalize skipping; leaving a paper trail my future self can actually follow; making wrong turns cheap to unwind.

It isn't: taste. Every judgment call in this story — what the homepage should feel like, that the first version was wrong, where the line sits between playful and gimmicky — was human. The agents amplified the decisions; they didn't make them.

The poster is phase one. The spec's own words — "first step toward a future experiential space" — are a promise I intend to keep: pointer-tracking, little toys, a homepage that notices you're there. When that ships, it'll get the same treatment: brainstorm, spec, dispatch, review, and at least one revision where I discover what I actually meant.

That last part I can promise.