How we built this site with Hekton

There is a lazy version of this story, and I want to start by admitting how tempting it was.

I open a chatbot. I type “build me a personal site with a blog and a clean homepage.” Ninety seconds later I have a pile of files that probably work. I paste them into a repo, push, and go make a coffee feeling like the future has arrived.

I have done this before. I know exactly how it ends. It ends three months later at half past four on a Friday, when something breaks and I am staring at a folder of code I have never actually read, generated by a model I can no longer ask, held together by decisions nobody wrote down. The site works right up until the moment I need to understand it, which is always the moment it has broken.

So this time I did the slower thing. I ran the whole build through Hekton, my agentic engineering factory, where an agent is not allowed to do whatever it likes. That sounds like more work. The surprise, and the reason I am writing this, is that it was less.

The factory, in one paragraph

Hekton is a personal operating system for building software with agents. Every repo gets a classification (platform, lab, or shipped output). Every project gets a contract that says what lives where. A roster of bounded agents called Gremlins each do one narrow job. And the governance is not a wiki page anyone can ignore. It is a set of files in the repo that a script can check.

This site is a “shipped output.” It is not special. The same machinery built the last thing and will build the next one, which is rather the point. A factory you only use once is just a very elaborate way of making one thing.

First move: don’t ask the model to do the boring part

The instinct with a new project is to start generating files. Resist it.

The first real action was classifying the project and handing the skeleton to Quartergremlin, the scaffolding agent:

just scaffold-project -- --type factory-output --name agentic-tekton \
  --title "The Agentic Tekton" --privacy local-first

One command produced about forty files. The repo, a control plane for my notes, the governance files, the full documentation set, and a first commit. Then it created a private remote and pointed at it without pushing, because the first push of anything public is a decision a human should make on purpose, not a thing that happens because a script felt chatty.

Here is the first lesson, and it is deeply unglamorous: a language model should not be generating your directory structure. That is a job for a script. Scripts do not get creative with folder names at two in the morning. The forty files cost zero model tokens and had zero chance of arriving subtly wrong. The expensive thing in this whole setup is the model’s attention, and I had just spent none of it on plumbing.

The cheapest token is the one you never spend.

Second move: spend the attention where it earns its keep

Now the model did the part only it could do. It took a brand brief and turned it into a homepage. Design tokens, an editorial layout, and the one visual motif the brand actually owns: a small node-and-edge diagram of humans and agents handing work to each other. The shape of the picture is the subject of the picture, which is the kind of thing you can only get right with judgement, and judgement is what I was saving the tokens for.

The writing section you are reading right now was not designed from scratch either. The factory keeps a Blog Factory Lab, a reusable engine for content sites, and it already had a working content collection and a publication gate that someone had reviewed once. So I reused it. Reuse is not just faster. It means a decision that was already argued over stays decided, instead of being relitigated by a model that has never heard the argument.

Reuse is determinism you already paid for.

The gremlins on the job

A Gremlin is not a personality. It is a job with a fence around it. The ones that touched this site:

Gremlin	What it did here
Quartergremlin	Scaffolded the classified repo, the notes plane, and the governance files.
Mirror Gremlin	Installed the pre-push hook that stops my repo notes and my vault drifting apart.
Brain Sync Gremlin	Registered the project so its context can be mirrored and drift can be caught early.
Blogger Gremlin	Supplied the post and publication patterns this very article follows.
Infrastructure Gremlin	Turned a deployment manifest into cloud infrastructure, then stopped dead at a gate.

None of them can do another’s job. A bounded agent is an agent you can audit, and an agent you can audit is one you can actually let near your work.

The part where I admit governance is the good bit

I used to think of governance as the tax you pay for doing real work. The thing that turns a fun afternoon of building into a compliance meeting. Building this site changed my mind, because here the controls were not paperwork. They were the things that made going fast safe.

What actually bit, in order:

Classification came before creation, so the project’s paths, naming, and even which GitHub account owned it were settled before a single file existed. No “we’ll tidy it up later,” which is the phrase that has never once been followed by tidying it up later.

Decisions got written down as they were made, in a decision log, at the moment of the decision. Why this is a shipped output and not a lab. Why it stays local until I say otherwise. Why the apex domain is the brand and the build-log blog lives on a subdomain. Not reconstructed from memory a fortnight later, when memory has quietly invented a more flattering version of events.

Validation gates ran against the new project and had to come back clean before any of it counted as done. They did. Zero failures, which is a sentence I do not get to write often.

And the infrastructure had a gate with a human standing at it, which deserves its own section.

The gate

The site needs somewhere to live. A private S3 bucket behind a CDN, a certificate, some DNS. The boring, correct shape that a thousand static sites use, and I did not want a model improvising on it.

The Infrastructure Gremlin works to one rule: the agent plans, the human applies. It reads a deployment manifest, writes the Terraform, can run a read-only plan, explains that plan in plain English, classifies how much damage it could do on a green-amber-red scale, adds a quick architecture review, and then it stops.

manifest -> generate IaC -> plan -> summarise -> classify -> review
   -> [ HUMAN APPROVAL GATE ] -> human applies -> record outputs

The reason is simple enough to fit on a sticky note. A plan reads. An apply changes things, costs money, and is a genuine pain to undo. So the agent is structurally incapable of running the apply. Not “trusted not to.” Incapable. I have met terraform apply on a Friday afternoon and I would not trust myself with it either, let alone something that does not feel fear.

For this site the Terraform is written and the manifest is filled in. The plan and the apply are mine to run, once the design is locked and I have looked at exactly what it is about to do.

What it cost, and what that bought

The headline is not “an AI built a website.” Of course it did. They can all do that now. The headline is the shape of the spend.

The deterministic machinery did the deterministic work for nothing. Reused, pre-reviewed patterns did the repetitive work cheaply. The model’s expensive attention went to two things that genuinely needed a mind: the design and the prose. And every step left a written trace behind it, so the next time I open this repo I start informed instead of starting an investigation.

Design the workflow once, and the workflow builds the rest.

That is the whole argument this site exists to make. The hard part of building with agents was never the agent. It is the operating model you put around it. Get that right and the work gets cheaper and better-governed at the same time, which is not a trade-off anyone promised me and is the main reason I now bother.

Next time I will take the same idea up a level, and ask what happens to the engineering roles themselves when the factory, not the person, becomes the thing that ships.