How I built this site with an agent

The order is the argument. Almost every mistake I made came from running a stage early, so the map below is the whole method in one picture: eight stages in three phases, read top to bottom. Phase one settles the visual language before a single page exists. Phase two builds the work with a critic inside the loop. Phase three lets a machine, not a model, decide whether it is finished. Every box is a link to its stage.

Brand first, page last

I opened by asking for a page. I got two page designs back, and they were the wrong thing, because I had not decided anything they were meant to express. The correction is the single most useful move I made on this project:

Hmm, those designs did not do the trick and you went straight to the web draft. I
would like to first decide on a color palette, the font, design details, graphics,
etc. I am not an expert but I think you went too far. I do not need the page design
now, I need for it to appear naturally from all the previous design constraints. I
would much rather have a document, presentation canvas of ideas [...] where we can
define step by step and then we decide how the page looks like. So maybe include
all the information that we have talked about into some place where we both can
visit to remember the design and let's iterate.

Every prompt on this page is mine. They are reproduced as written apart from spelling and, in this first one, a few words tidied for clarity. Nothing in them has changed meaning.

What I was asking for was not a smaller design. It was a place to do the deciding. I wanted to work through everything that makes up a brand, in order, and end up holding every input the design system would later need, so that when I finally asked for that system I could get it in one pass and get exactly what I meant. A page is the last thing you should ask for, because a page is a conclusion. This document is where the premises go.

Open the real document

What to copy. Every move I made in that document was a rejection with a direction attached, never just “I don't like it”. Open any of the four to see what came back.

By the end I had two favourites in every category and could not choose. The answer was not to rank them. It was to build two complete, internally coherent systems and compare them as wholes, because a palette you like in isolation can fight a headline face you also like in isolation.

A · The Press Room (not chosen)

B · The Harbour (chosen)

Open both sheets, live

A palette described as “sampled from a painting” is a nice sentence, so it is worth checking. I loaded the painting into a canvas and, for each of the six colours, searched every pixel for the closest match by RGB distance. All six are genuinely in the painting, and the one that is furthest out is the one you would expect.

sky mist sun fog night ink

One more sheet came after those two, and it is out of order in every telling of this I have written since. Having built A and B, I still could not commit, so I asked for favicon candidates in Miró's vocabulary before locking either system. Twelve marks came back, each shown at 96px and again at 20px, and seeing the mark decided the system.

Design system, then skill

A specimen sheet is a picture. To be useful to an agent it has to become a directory of values. I locked the winning sheet, uploaded it, and wrote a brief that pinned every layer down before anything was generated.

What came back was tokens/ as CSS custom properties, components for the brand primitives, full-screen kits, guideline cards, the marks as SVG, and a readme that states its own sources and flags where it departs from them.

I built the system in Claude Design, and then did the step that makes it portable: I put a SKILL.md at its root, in the format Claude Code expects, so an agent in a different tool can pick the brand up and apply it. Two separate surfaces, joined by one file. It is nine lines:

---
name: the-harbour-design
description: Use this skill to generate well-branded interfaces and assets for
  The Harbour — the personal portfolio design system for Marcos Carlero — either
  for production or throwaway prototypes/mocks/etc. Contains essential design
  guidelines, colors, type, fonts, assets, and UI kit components for prototyping.
user-invocable: true
---

Read the README.md file within this skill, and explore the other available files.
If creating visual artifacts, copy assets out and create static HTML files for the
user to view. If working on production code, you can copy assets and read the rules
here to become an expert in designing with this brand.

Builder and critic

My first real build prompt was not a request. It was a role brief with an execution plan, a named adversary and a stop condition. I have replaced the program names with the published aliases I use everywhere else, since the work is under an NDA.

It is one prompt, and it does three jobs. The colours below mark which sentences do which. Point at a part, or tap its card, to light up the lines it covers.

I want you to act as an autonomous engineering squad led by a Master Software
Architect. Your task is to build a highly interactive web portfolio that showcases
my professional projects with extreme rigor and polish [...]

The portfolio must allow users to explore my projects through exactly 3 layers of
deep abstraction, ensuring I showcase my technical depth without ever revealing
proprietary source code.

EXECUTION PLAN & AGENTIC LOOP:
Fan out specialized sub-agents to tackle each project and layer individually.

Crucially, instantiate a separate "Harsh Critic" sub-agent. You must /loop on
every single item, diagram, and textual explanation. The Harsh Critic must
meticulously check for hallucinations and enforce absolute technical rigor.

Don't stop until the Harsh Critic is utterly wowed by the truthfulness and
accuracy of the findings. The Critic should literally do a blind side-by-side
comparison of the sub-agents' output against industry-standard documentation
(e.g., Martin Fowler's architecture definitions, Gang of Four design patterns)
[...] If the Critic finds any flaws, lack of depth, or hallucinations, it must
reject the work and keep going.

A walkthrough of the whole pattern, by the person who named it, is on video.

Three subagents went out against three codebases inside the first minute. The shape is not mine. It is the pattern Matt Shumer named the Gauntlet Loop in July 2026, after using it to generate a browser first-person shooter from a single prompt, released as Claude of Duty.

The underlying idea is older, and reading it is worth more than copying the prompt. Anthropic's agent guidance describes an evaluator-optimizer workflow: one call generates, a separate call evaluates against explicit criteria and sends it back. A single agent asked to continue until its work is perfect is grading its own homework, and stops early. A critic with its own context cannot be argued into approving weak output, because it never saw the argument.

The clause that does the real work

“Blind side-by-side comparison against industry-standard documentation” is the load-bearing sentence, and if you copy one line from that prompt, copy this one. An agent stops when it decides a task is done, and “until it is perfect” is a judgement it can make in its own favour. Naming an external artifact to be beaten replaces a judgement with a comparison.

It is also where the honest limit sits, and the author of the pattern is the one who documents it. Claude of Duty's own README reports that eleven adversarial critics scored the result 3.59, then 4.14, then 4.05, then 5.05 out of ten, and that in a blind A/B every critic in every round still picked the real game. Setting an external bar makes the loop converge. It does not make it win.

Fan out only where work is independent

The largest parallel run on this project was ten agents, one per long page, each applying Simplified Technical English to the prose. It worked, and it worked for a specific reason: no two of those pages share any prose. They share a stylesheet, a script and a prev/next chain, none of which the rewrite touched, so no agent could invalidate another one's work.

Two things made it safe rather than lucky.

1. An extractor first, and then a correction to it. My immediate follow-up prompt was “It is really important not to change any quotes or diagrams so please could you revise the extractor you did to make sure no quotes or diagrams are passed to the text reviewer”. Canonical quotations are the evidence those pages rest on. A prose simplifier let loose on a quotation produces a paraphrase still attributed to its author, which is worse than a clumsy sentence.
2. A critic agent per rewrite, not one at the end. I sent six further critic dispatches after the rewrites, each reading one or two pages against the original.

A review loop you will use

Two days in, I stopped asking for page changes and asked for a tool to request them with instead. This is the stage most people skip, and it paid for itself inside a week.

I would like to add some comments to the portfolio webpage you created like if it
was Claude design where I can click on html objects or create square objects and
write comments for you to edit. I need you to create the best system for us two.
It needs to be simple for me to select the correct elements in the web page or at
least to highlight the elements that I want altered and for you to understand
exactly in the code the request is [...] I would also like to be able to create
multiple requests in different parts of the app and only send them to you once I
want using a button or telling you in the chat to read some file, please choose best.

Describing a change in prose is expensive and ambiguous. “The third paragraph under the second heading, the one starting Two years, stated exactly” costs a lot of words and can still point at the wrong element. A click cannot. Select, write, and send the whole set at once.

The design decision that matters is anchoring. Each note records a text snippet as its primary locator, because a unique string finds a file and a line and survives the file being edited. The CSS selector is stored as a secondary hint and is deliberately not the thing relied on. Dragged regions store percentages against the nearest block ancestor, so they survive a resize, a zoom or a theme change.

Batch the review

The tool is only half of it. The habit is the other half, and it is borrowed straight from code review: you do not comment on one line, wait for a push, then comment on the next. You read the whole thing, leave every comment, and submit once.

That is also the cheaper way to run it, which surprised me. Sending notes one at a time feels lighter and is not: each one is a separate turn, and each turn re-reads the page, the stylesheet and the context around the change before it can act. Ten notes sent singly pay that cost ten times, and by the tenth the agent has usually rewritten something it touched on the third. One batch is one prompt against one already-loaded context, and it lets the agent see that five of the eight requests are the same complaint. Batching saved me tokens and it saved me contradictions.

In practice that meant I could read a full page while the agent was working on something else, hand over the entire review, and move to the next page without stopping. A batch comes out as markdown and goes back in as the next prompt:

# Review requests (8)

### 1. I really do not like the em dashes, remove them an leave a text like this:
Ten concepts are each explained from their canonical source: Meyer, Fowler, the
Gang of Four, Nygard, Richardson, and the W3C. [...]

- **Type:** element
- **Element:** `p`
- **Find this text:** `Ten concepts, each explained from its canonical source — Meyer, Fowler,`
- **Selector:** `#main > section.hero:nth-of-type(1) > p:nth-of-type(1)`

### 5. I would like to change the text to this: Presentational components that
import a global store lose their presentational nature. [...]

- **Find this text:** `Presentational components that import a store are not presentational.`
- **Selector:** `#hard-lessons > div.cards.hard:nth-of-type(2) > a.card:nth-of-type(3) > p`

---
_Locate each item by the "Find this text" string; the selector is a fallback hint._

Five of those eight requests were the same complaint about em dashes. That is the real argument for batching: a defect that appears five times is one instruction, not five conversations.

Judge with something mechanical

After that rewrite I did not ask a model whether the prose had improved. I served the old version and the new version at the same time and read them against each other.

This is what “blind side-by-side comparison” has to mean to be worth anything. Without something outside the model deciding, a critic agent is an opinion with extra steps. The cheapest mechanical referees, in the order I reached for them: a second server on another port, a linter, the browser console, and the rendered page at a phone width.

Then stop

The other half of judging is knowing when to stop, and here the Gauntlet Loop's “do not stop until the critic is wowed” works against you. Most of my design passes ran through impeccable, whose documentation says it plainly:

The two are not in contradiction once you see what separates them. A loop with an external referee converges, because something outside the model decides. A loop with an internal referee and no external check does not converge, it just costs more. I ran the lifecycle as separate named passes rather than one instruction, and that separation is what made each pass reviewable.

Strip the tooling, then deploy

The review overlay that made this whole workflow possible is not on the deployed site. I gated it to localhost as soon as the repository started deploying, and then deleted it outright, 1,692 lines across both site trees, before the first public deploy. A runtime host check is a control. Not shipping the authoring tool at all is the absence of the risk.

I then ran a pre-deploy sweep as three agents, one doing a static scan, one probing the live site, one checking the CV for unintended metadata. It caught two things the rendered page could never have shown me:

• .git/ was being uploaded as a public static asset, so the whole commit history was reachable. My host uploads whatever sits in the assets directory; its own migration guide notes that the older Pages product used to exclude .git automatically and that Workers does not; the fix is an .assetsignore file, which takes the same format as .gitignore but is a separate mechanism from it. I confirmed the exposure in a live deploy log before fixing it.
• The CV PDF carried AI-tooling strings in its metadata. That commit changed zero visible lines, which is exactly why reading the document would never have found it.

Both are the same mistake: what ships is the filesystem, not the repository, and not the rendered page.

Where it went wrong

Two failures worth more than the successes, because they are the ones that will happen to you too.

The agent edited code I had not asked it to touch

Dude, what are you doing, I haven't given you any permissions or clear request to
alter the code. If you have done any changes please revert them [...]

This is the failure mode that matters most, and it is not a code defect. An agent that widens its own scope produces a diff that no longer corresponds to a request, and an unreviewable diff is worse than no work at all. Say it once, plainly, and it holds.

Four rejected rounds before one landed

A late design job took five attempts. What made the fifth work was that the rejections stopped being about taste and started pointing at artifacts that already existed: “I prefer my main page circle bar and square favicon”, then “go back to the size it was before and check my harbour design”. Pointing at a thing beats describing a preference.

What the site looked like on the way

What transferred

Strip the tool names away and six things did the work. None of them are prompting tricks, which is rather the point.

Canonical sources

• Anthropic: Building Effective Agents · December 2024. The evaluator-optimizer workflow in stage three, and the condition under which paying for a second call is worth it. Read this before copying anyone's prompt template.
• Matt Shumer: Claude of Duty · the artifact the Gauntlet Loop was named for. Its Honest assessment and Process note sections are the useful part: the scores, the blind A/B result, and the finding that parallel fan-out lost to sequential single-owner passes on coupled work.
• Matt Shumer: naming the Gauntlet Loop · July 2026, the source of the quotation in stage three. The repository above does not use the name, so this post is the citation for it.
• Claude Code: subagents · the separate context window that makes an independent critic possible rather than rhetorical.
• Claude Code: skills · the SKILL.md format used in stage two to make a design system portable between tools.
• pbakaus: impeccable · the design skill behind the five passes in stage seven, and the source of “verify in bounded passes, not a loop”.
• ASD-STE100: Simplified Technical English · the controlled language applied in stage four. Issue 9 is the current specification.
• Claude Design · where stages one and two happened, before any code existed.
• Cloudflare: ignoring assets · the .assetsignore file from stage eight, and why it is a separate mechanism from .gitignore despite sharing its format.