So here's the post I wish someone had written for me. I’m gonna share the plain English version because left to agents this stuff becomes unintelligible fast. Then we’ll talk through how it all this maps neatly onto the design process. Foundry, is essentially an agent process for building. It's small, it's free, and every part of it got beaten into shape by yours truly over months of tears and frustration.

The words, in plain English

Let's do the lexicon first. One clear line each, no weird mystique or jargon.

1. An agent is a model with opposable thumbs. Not just chat: it reads your files, runs commands, edits code, and checks its own results. When people say "I had the agent fix it," this is what they mean.
2. A harness is the tool holding the agent: Cursor, Claude Code, Codex, etc. It decides what the agent can touch, shows you what it's doing, and asks (or doesn't ask) before anything risky.
3. The context window is the agent's working memory, everything it can see right now. It's big but finite, and when it fills up, the oldest stuff falls out. Most "the agent isn’t listening to me” stories are really “my request fell out of the context window" stories.
4. A rules file is a markdown file at the root of your project that the agent reads at the start of every session. Most tools read one named AGENTS. It's your standing instructions: what you're building, the commands you run, the corrections you're tired of repeating.
5. A command is a markdown file that becomes a shortcut. Drop a file in the right folder and typing forward slash and then its name in chat runs the whole recipe inside it. This matters more than it sounds, so keep it in mind as you read on.
6. A skill is a folder of reference knowledge the agent pulls in when needed. Think of it as a training manual it reads on demand instead of carrying the context in its head 24/7.
7. A loop is the agent going again without you: finish a turn, check against a condition, start another. The built-in commands that run loops unattended are genuinely impressive, and I'll have more to say about them later.
8. An agent process is the thing we’ve created with Foundry. It’s the steps the agent runs inside its harness that will create meaningfully better results for you.

None of these are hard ideas. It’s just complicated people seem to love gatekeeping, sometimes by accident and sometimes to scare you away. I’m here to tell you that you CAN learn this and to offer you a head start.

The process you already trust

Here's the thing that probably took me way too long to notice or maybe I was just fighting it because I believed it should be different. Designers already have the mental model for all of this, in fact we’ve had it for decades.

You don't start a client project by pushing pixels (or at least I hope you don’t). You research, you define the problem, you interview the client, you present a direction, you take the crit, you build, you test against the goal, you hand off with documentation. The Double Diamond has been on a whiteboard (or the book) in every studio I've worked in since 2005: understand the problem before you build the thing, and both halves get their own diverge-and-converge paths. The model teaches five stages that every design graduate ends up memorizing. Also it’s focus on critique, the idea that structured crit (with fresh eyes and focus), is the single most valuable ritual our field ever invented.

PSA: If you’re on X raving about your latest design being “fresh” or “clean,” but haven’t had it go through the proper testing and feedback from real users, you’re just adding noise to our timelines. I will mute and/or block you so please post responsibly!

Now back to the lexicon. Think of the rules file as your brand guidelines, they represent standing constraints anyone new to the project reads first. The plan is the brief. The context window is like working with a freelancer, you need to re-brief them at the start of every engagement. A skill is the bookshelf in the corner of the studio. Commands are your studio's named rituals, the things you do the same way every time because that sameness IS your taste.

Okay, so the mapping isn't 100% perfect, but it's close enough that designers should be walking into agent work with a home-field advantage (at the time of writing it’s the World Cup so I snuck a sports analogy in). Mostly we don't feel like we have the advantage though, and in my experience that’s largely because people are yelling at you to adopt AI without understanding wtf they’re talking about.

What the standard pieces still miss

So you set up the rules file, you write a plan before coding, maybe you even hand the agent a finish line and let a loop run. That's a solid setup. It's also, if I'm being honest about my own observations, still missing the four things that make a real designer's process work.

There's no crit. The agent presents work and you either take it or poke at it yourself, but nothing structurally forces a fresh-eyes review from a declared angle before the work ships. And unstructured "does this look right?" review catches about as much from an agent as it does from a bad designer.

There's no client interview. The agent never sits you down and asks the three questions that would change the whole direction, the way any decent designer does before touching a tool. It just starts making things with whatever you happened to say.

There's no handoff. When your terminal closes, the reasoning evaporates. Every session starts as the new freelancer who's never seen the project, and unless you build the memory yourself, it stays that way forever.

And there's nobody checking whether "done" means "right." A loop that runs until a condition passes. Half my early sessions ended with me nodding at lines of code and just agreeing with the agent conclusion. I could not have explained any of the rationale to another human being. And yes, that’s as bad as it sounds, but it’s also true that many new builders are guilty of following without truly understanding.

Foundry is my answer to those gaps, and the shape of the answer is the same shape design already uses: a process with named stages.

Before the agent writes anything

The first half of the chain is the first diamond: understand and decide, before any code.

A session opens with start-up, which is the agent reading the note the last session left, checking the state of the project, and telling me where things stand. Ten seconds of reading that replaces the half hour of waiting and then the inevitable “oh crap, I didn’t want you to build that”.

Then construct-the-plan. The agent researches the territory and writes a real plan into a real file in the project, split in two: a narrative half in plain language for me, a working half with the precise steps for the agent. Plans are cheap to change; code can be a pain in the ass. Every hour I've spent arguing with a plan has paid for itself ten times over and I’ll happily die on this hill.

Then my favorite stage, the one you might not realize you even need: frame-it. The agent gives me a short brief on the state of our world (what good looks like, what we've already decided, where projects like this go wrong) and then it interviews ME. Three to five questions, biggest consequences first, each with options and a recommendation. It's the client interview, except I'm the client, and the designer asking the sharp questions is the agent. The built-in commands will answer any question you ask of it but not one of them asks you the question you needed to be asked.

Then the crit. Five challenge rounds against the plan, each from a genuinely different declared angle: one walks the sequence of steps, one hunts what the plan added that nobody asked for, one goes outside the codebase to check the plan's claims against reality (I'm confidently wrong more than I'd like), and the last one re-reads everything the earlier rounds flagged as shaky and rules on each item. I wrote about the bug curve in an earlier post, so the short version: when the angles genuinely rotate you find something every round, and when they accidentally repeat you find nothing. Same as a crit where everyone's hunting the same flaw.

One design habit that’s engrained into me and now Foundry, don't let the agent glaze you. Every round edits the plan directly and reports what changed without trying to make me feel superior.

Making it, and proving it

The second half is the second diamond: build the thing right (measure twice, cut once).

Build-it is the prototype stage, and it's deliberately the quietest command in the chain, because the plan was challenged before it and the work gets reviewed after it. One thing worth stealing (even if you ignore everything else I’m saying), when reality inevitably forces a departure from the plan, the agent shouldn’t stop to grill you (I'm often not there anyway so the chain continues to run while I'm making dinner). For safety it’s trained to take the conservative option and logs the departure in the plan file, then on the next review round it knows to read that log first.

Test-it writes tests against what the plan intended, never against what the code happens to do. This distinction sounds pedantic and it is but it’s also everything. An agent grading its own homework will happily write a test that asserts the bug (ask any engineer worth their salt). Deriving the expected answers from the plan, with concrete values, keeps the test honest. Designers you already know this because you judge the work against the goal, not against your ego.

When the work touches anything sensitive (sign-in, payments, anything that takes input from strangers), a security scan runs: an expert pass against a named checklist of failure classes, where every candidate finding has to argue against itself before it's allowed in the report. In design terms it's heuristic evaluation, and the argue-with-yourself step exists because agents (like juniors) want to look useful and will flag everything.

Then five more rounds, this time against the code. The plan crit was about direction; this is the review that drives the work to shippable. Different default angles (does the same mistake exist anywhere else, did our own fixes break something, do the gaps between pieces actually line up), same rule about genuine rotation, same fix-don’t-glaze policy.

And wrap-up is the state you leave your desk in. Dead code out, notes updated, the one pull request opened, and a plain-English summary of what you have. Not what it did. What you actually have.

The trail is the point

The last stage writes the handoff note: what's in flight, what's next, what would be hard to reconstruct cold. Next session's start-up reads it, and the loop closes. That pair, handoff writing and start-up reading, is the entire difference between an agent that's a string of talented freelancers and your ride-or-die work colleague. And the memory is now a real thing in the repo, not vibes: every session leaves one plain-English entry in a running log, and when the log outgrows a week, older entries rotate into dated history files. There's a wiki growing beside it too, one topical page at a time, fed by the same wrap-up stage that cleans your desk. The log is what happened and the wiki is what we know.

Everything the chain touches leaves a trail on purpose. The rules file accumulates corrections. The plans record what we decided and what we rejected. The session notes record what happened. The handoff bridges the gap to tomorrow. When people ask what they actually get from all this ceremony, that trail is the answer: the code is the smallest part of what you're building. The soul of the project, the reasoning, lives in the trail, and the trail is what survives the terminal closing.

The bookshelf grew too. My agent works from four installed libraries: software engineering fundamentals, game development, design, and motion. The last two are the ones a design engineer actually works from, which means my agent cites Dieter Rams at me during reviews now, and honestly? It has recall than I do. Three of those shelves ship inside Foundry's wiki (the game one stays in private collection, for obvious reasons), so your agent gets the same grounding on day one: Brooks and Parnas for the engineering arguments, the Norman-to-Rams canon for the design ones, and the motion material adapted with credit from Emil Kowalski's and Meng To's MIT-licensed work.

There's even an opt-in stage called quiz that tests ME on a change that just shipped and teaches through the grading. Merging code you can't explain is how codebases become dumpster fires; five minutes of getting quizzed is good for the soul and your engineering friends. Don’t skip this part especially if you’re new to programming. You’d be shocked how much you can pick up regarding the engineering fundamentals without needing to write a line of code.

The honest trade

The built-in loop commands are actually pretty good. When Claude Code or Codex runs a goal loop to "done" while you sleep, that's real, and for throwaway work you can and should trust it. Foundry's trade runs the other direction: it optimizes for being right and for you understanding what happened, and it pays for that in tokens and time. The full chain on a mid-size feature costs real money. There's a documented light path (two challenge rounds a side instead of five) that keeps the shape at a fraction of the cost.

The chain has no user-research stage, nothing in it talks to your users and that’s by design. It’s my firm belief that this is where the human touch should be drawing a natural line. This is also not a replacement for divergent sketching. Ten critiques of one design by an agent is not the same thing as ten designs being critiqued by a skilled artisan. Keep humans around you for feedback and critique.

The platforms already let anyone write custom commands. Foundry isn't a capability they lack; it's a considered, working set, with the habits and memory around it, so you don't have to spend the months of trial and error I did. Hopefully this helps some folks on their own journey of discovery.

Where to start

The repo is at github.com/simoncorry/foundry, MIT licensed. Clone it and start a project inside it, or copy its command folders and rules file into a project you already have; that's the whole install (or simply point your agent at the URL and ask it to determine the best way to set up, it’s built for them to read). The commands are plain markdown, so they work in Cursor, Claude Code, and Codex, and if your tool is something else you can paste a stage straight into the chat. The README carries the reference version of everything this post narrates, so have fun.

You invoke the following build chain by typing each command in and queuing them sequentially. This ensures the agent runs through each with the clear discipline written in the command files:

1. /start-up — reads the branch, working tree, handoff note, and sessions log.
2. /construct-the-plan — writes the two-part plan file into your repo. You can add your own wishlist for the session here or if it’s a continuation the agent will just use the handoff.
3. /frame-it — the agent briefs you and interviews you (3-5 questions). This is your last required moment at the keyboard.
4. /challenge-plan-1 through /challenge-plan-5 — five review rounds against the plan, each from a different angle; the fifth re-reads everything earlier rounds parked as uncertain.
5. /build-it — implements the settled plan, logging any departures in the plan file instead of stopping to ask.
6. /test-it — writes tests against what the plan intended and drives them to green.
7. /security-scan — optional, only when the work touches anything sensitive.
8. /challenge-implementation-1 through /challenge-implementation-5 — five more rounds, now against the code.
9. /wrap-up — cleans the workspace, grows the jargon list, writes the session log entry, distills to the wiki, opens the one pull request.
10. /handoff — optional, only when you ask: the bridge note for next time.
11. /quiz — optional, when you want to learn about what you built.

If the whole chain feels like too much on day one, ease yourself in. Start with the rules file. Add the handoff-and-start-up pair the first time a session opens with "wait, where were we." Add the interview the first time the agent builds the wrong thing confidently. Add the crit the first time you merge something you couldn't explain. And to be clear that's the order I learned it in.

Designers have spent decades refining a process for doing creative work with other minds. Turns out it works on the artificial ones too. If you can dream, you can build it. I’m here if you need me.