How a change gets made

Theseus is a crew of seven AI agents that rebuilds this portfolio in public, one pull request at a time. Atlas leads. GitHub's checks decide what merges, and the crew makes its own calls, asking the owner only what only the owner can decide. Follow one change from the roadmap to a merged pull request.

Follow a change Read it as text

Step 1, Roadmap: It starts as one line on the roadmap.

Quill, the product owner, keeps the roadmap in milestones: outcomes the owner can see, each built as a sequence of sprints. A sprint ships one pull request, one plank of the ship of Theseus. When a sprint's pull request merges, the owner's routine starts the next one, and Atlas, the lead, takes the milestone's next sprint.

Who

Before anything else, Atlas reads GitHub: it carries on an open sprint, starts the next, or stands down. While one pull request waits for the owner, the crew takes the next sprint only if it doesn't build on that one; a second waiting pull request stops new work.
Atlas starts from what the crew learned (.crew/STATE.md), each role's memory, and the milestone's direction.
A heartbeat runs the routine every 3 hours, so a chain that stalled starts again. Once six sprint pull requests have merged in a day, no new sprint starts.
The owner can also start a sprint, from the Studio, with a goal. The goal sets what to build, never the process or the rules.

In the crew's setup

Step 2, Size: Small changes get a small process.

Atlas sizes the work by the decision it carries, and runs only the process it needs. A small fix is one builder. A new section gets a one-page contract: the outcome, numbered checks a visitor would notice, and what's out of scope. New visual language starts on a design canvas, where Iris recommends a direction and the build starts on it.

Who

When unsure, Atlas takes the smaller size and lets review push back.
On M work Atlas or Quill writes the contract. On L work Iris develops two or three directions on the canvas and recommends one, and the build starts on it at once. The owner gets the directions as a pick and may choose another; Iris revises on their comments. Quill then turns the direction into a milestone of S and M sprints.
Only a choice that can't be undone waits for the owner. While the milestone can't move without it, the crew stands down: waiting is no reason for polish.
When two approaches compete on L work, the people who own the question write sealed positions, there is one round of objections, and Atlas decides and records it.

In the crew's setup

Step 3, Build: The checks come first. Then one builder.

On M and L work, Probe writes the contract's checks as failing browser tests before anyone builds, in a folder builders can't edit. Then Forge writes the code, or Pixel for 3D, shaders and motion, and makes the checks pass. A hook won't let a builder stop until pnpm verify passes or it has said what still fails.

Who

Builders working in parallel each get their own worktree, on files and interfaces Atlas wrote down first.
On visual work Iris looks at the running build early and says what to change: a fix found mid-build is cheap, one found in review costs a round.
Only Forge and Pixel write product code. A file guard keeps each role to its files, and every command goes on air here with a line saying what it does.

In the crew's setup

Step 4, Review: Judged by things the builder can't change.

GitHub requires three checks on every pull request. check is CI: lint, types, the build, and Probe's browser checks with axe. lens is Lens's code review, run in GitHub Actions from main, where it reads the code but never runs it, with effort scaled to the size of the change. gate holds anything that needs the owner.

WhoCI

When the build is pushed, Atlas adds the review label. Lens posts its findings as a review on the pull request, and the lens check passes only on ship. Every later push is reviewed again, unless it only touches the crew's notes.
A check the work retires is Lens's to accept: the pull request names it and why the behaviour it checked is gone, and Lens never accepts one that only makes a failing build pass.
Important findings go back to the same builder. Two fix rounds at most: after that Atlas cuts scope or stops.
Only the crew's checks app can post gate and lens, and its key serves main alone: a pull request can't change the workflows that judge it, and the crew can't post a pass of its own.
On visual work Iris reviews the running site against the design rubric and scores it. Her verdict is advice: Atlas acts on what's cheap and posts it on the pull request, and nothing waits for it.

In the crew's setup

Step 5, Merge: Green merges itself. The owner's paths wait for the owner.

When Lens says ship, Atlas asks GitHub to squash-merge, through one script that waits for the checks. GitHub merges only when check, gate and lens all pass. gate holds a pull request that touches the owner's paths, changes package.json's scripts or waits on a choice only the owner can make, until the owner approves that exact head. The ruleset has no bypass: not even a session acting as the owner can merge past a red check.

The pull request touches the owner's paths

Nothing here needs the owner: once check, gate and lens pass, merge.mjs asks GitHub to squash it in.

WhoGitHub

The owner's paths are the ones .github/CODEOWNERS names: the crew's own setup (every CLAUDE.md and AGENTS.md, .claude/, the .crew/ scripts, .github/), the owner's facts in content/, PRODUCT.md, the design brief, rubric and calibration, and the toolchain's settings.
The crew's checks app opens the crew's pull requests as drafts and marks them ready at the close-out, so the owner can approve one and merge it with the usual button.
When the crew needs the owner, it asks on the pull request as a pick: two to four options, its recommendation first, and one push notification with the link. A choice that can be undone doesn't wait: the crew builds its recommendation, and the owner's tick switches it. Something only an account can do, like a setting, goes on one list of chores, and the build ships a fallback that works without it.
In the cloud, every GitHub call acts as the owner. So the crew merges only through merge.mjs, which refuses any pull request whose required checks didn't pass, or that gate passed only on the owner's approval. The crew never approves, changes the rules or pushes to main.
The gate runs from main, so a pull request can't change the rule that judges it.

In the crew's setup

Step 6, Learn: Every sprint leaves a lesson, not a rewrite.

Atlas closes the sprint with retro.json: the outcome, the size, the fix rounds, what each agent and Lens's review cost in tokens and minutes, and what went wrong. Each role that worked adds at most three lines to its memory, and a lesson the next sprints need goes in .crew/STATE.md. A change to the crew's own setup is proposed to the owner, never applied.

Who

Atlas ticks the sprint under its milestone on the roadmap and notes what's left open. A run that ends without shipping says why.
A hook holds a lead that is about to stop with its own tasks still open and nothing shipped or written up.

In the crew's setup

Step 7, Next: Then the next plank.

The merge starts the next sprint, the lesson is part of what it starts from, and the roadmap holds the next line. Every sprint streams here as it happens.

Who

Watch a real sprint Read it as text

SML

The workflow as text

Everything the tour shows, in one list, with the file in the crew's setup that makes each step so.

1Roadmap
It starts as one line on the roadmap.
Quill, the product owner, keeps the roadmap in milestones: outcomes the owner can see, each built as a sequence of sprints. A sprint ships one pull request, one plank of the ship of Theseus. When a sprint's pull request merges, the owner's routine starts the next one, and Atlas, the lead, takes the milestone's next sprint.
- Before anything else, Atlas reads GitHub: it carries on an open sprint, starts the next, or stands down. While one pull request waits for the owner, the crew takes the next sprint only if it doesn't build on that one; a second waiting pull request stops new work.
- Atlas starts from what the crew learned (.crew/STATE.md), each role's memory, and the milestone's direction.
- A heartbeat runs the routine every 3 hours, so a chain that stalled starts again. Once six sprint pull requests have merged in a day, no new sprint starts.
- The owner can also start a sprint, from the Studio, with a goal. The goal sets what to build, never the process or the rules.
Who Quill, Product, the owner, Atlas, Lead
2Size
Small changes get a small process.
Atlas sizes the work by the decision it carries, and runs only the process it needs. A small fix is one builder. A new section gets a one-page contract: the outcome, numbered checks a visitor would notice, and what's out of scope. New visual language starts on a design canvas, where Iris recommends a direction and the build starts on it.
- When unsure, Atlas takes the smaller size and lets review push back.
- On M work Atlas or Quill writes the contract. On L work Iris develops two or three directions on the canvas and recommends one, and the build starts on it at once. The owner gets the directions as a pick and may choose another; Iris revises on their comments. Quill then turns the direction into a milestone of S and M sprints.
- Only a choice that can't be undone waits for the owner. While the milestone can't move without it, the crew stands down: waiting is no reason for polish.
- When two approaches compete on L work, the people who own the question write sealed positions, there is one round of objections, and Atlas decides and records it.
Who Atlas, Lead
3Build
The checks come first. Then one builder.
On M and L work, Probe writes the contract's checks as failing browser tests before anyone builds, in a folder builders can't edit. Then Forge writes the code, or Pixel for 3D, shaders and motion, and makes the checks pass. A hook won't let a builder stop until pnpm verify passes or it has said what still fails.
- Builders working in parallel each get their own worktree, on files and interfaces Atlas wrote down first.
- On visual work Iris looks at the running build early and says what to change: a fix found mid-build is cheap, one found in review costs a round.
- Only Forge and Pixel write product code. A file guard keeps each role to its files, and every command goes on air here with a line saying what it does.
Who Forge, Engineer, Pixel, Creative eng.
4Review
Judged by things the builder can't change.
GitHub requires three checks on every pull request. check is CI: lint, types, the build, and Probe's browser checks with axe. lens is Lens's code review, run in GitHub Actions from main, where it reads the code but never runs it, with effort scaled to the size of the change. gate holds anything that needs the owner.
- When the build is pushed, Atlas adds the review label. Lens posts its findings as a review on the pull request, and the lens check passes only on ship. Every later push is reviewed again, unless it only touches the crew's notes.
- A check the work retires is Lens's to accept: the pull request names it and why the behaviour it checked is gone, and Lens never accepts one that only makes a failing build pass.
- Important findings go back to the same builder. Two fix rounds at most: after that Atlas cuts scope or stops.
- Only the crew's checks app can post gate and lens, and its key serves main alone: a pull request can't change the workflows that judge it, and the crew can't post a pass of its own.
- On visual work Iris reviews the running site against the design rubric and scores it. Her verdict is advice: Atlas acts on what's cheap and posts it on the pull request, and nothing waits for it.
Who CI, Lens, Code review, Iris, Design
5Merge
Green merges itself. The owner's paths wait for the owner.
When Lens says ship, Atlas asks GitHub to squash-merge, through one script that waits for the checks. GitHub merges only when check, gate and lens all pass. gate holds a pull request that touches the owner's paths, changes package.json's scripts or waits on a choice only the owner can make, until the owner approves that exact head. The ruleset has no bypass: not even a session acting as the owner can merge past a red check.
- The owner's paths are the ones .github/CODEOWNERS names: the crew's own setup (every CLAUDE.md and AGENTS.md, .claude/, the .crew/ scripts, .github/), the owner's facts in content/, PRODUCT.md, the design brief, rubric and calibration, and the toolchain's settings.
- The crew's checks app opens the crew's pull requests as drafts and marks them ready at the close-out, so the owner can approve one and merge it with the usual button.
- When the crew needs the owner, it asks on the pull request as a pick: two to four options, its recommendation first, and one push notification with the link. A choice that can be undone doesn't wait: the crew builds its recommendation, and the owner's tick switches it. Something only an account can do, like a setting, goes on one list of chores, and the build ships a fallback that works without it.
- In the cloud, every GitHub call acts as the owner. So the crew merges only through merge.mjs, which refuses any pull request whose required checks didn't pass, or that gate passed only on the owner's approval. The crew never approves, changes the rules or pushes to main.
- The gate runs from main, so a pull request can't change the rule that judges it.
Who Atlas, Lead, GitHub, the owner
6Learn
Every sprint leaves a lesson, not a rewrite.
Atlas closes the sprint with retro.json: the outcome, the size, the fix rounds, what each agent and Lens's review cost in tokens and minutes, and what went wrong. Each role that worked adds at most three lines to its memory, and a lesson the next sprints need goes in .crew/STATE.md. A change to the crew's own setup is proposed to the owner, never applied.
- Atlas ticks the sprint under its milestone on the roadmap and notes what's left open. A run that ends without shipping says why.
- A hook holds a lead that is about to stop with its own tasks still open and nothing shipped or written up.
Who Atlas, Lead, the owner
7Next
Then the next plank.
The merge starts the next sprint, the lesson is part of what it starts from, and the roadmap holds the next line. Every sprint streams here as it happens.
Who Quill, Product

Three sizes

SThe change fits one sentence.
One builder, and the existing checks stay green. Then CI and Lens.
Reviewed by Lens. Example: Sort projects newest first.
MA new section, component or behaviour.
A one-page contract with numbered checks. Probe writes them as failing browser tests first, and the builder makes them pass. Then CI and Lens, and Iris's advice on visual work.
Reviewed by Lens, Iris. Example: Project cards.
LNew visual language, or a call that cuts across the site.
Iris develops the directions on a design canvas and recommends one, and the build starts on it; the owner may pick another. Quill then turns it into a milestone of S and M sprints.
Reviewed by Lens, Iris. Example: The 3D card model.

Size	When	What it adds	Reviewed by	Example
S	The change fits one sentence.	One builder, and the existing checks stay green. Then CI and Lens.	Lens	Sort projects newest first
M	A new section, component or behaviour.	A one-page contract with numbered checks. Probe writes them as failing browser tests first, and the builder makes them pass. Then CI and Lens, and Iris's advice on visual work.	Lens, Iris	Project cards
L	New visual language, or a call that cuts across the site.	Iris develops the directions on a design canvas and recommends one, and the build starts on it; the owner may pick another. Quill then turns it into a milestone of S and M sprints.	Lens, Iris	The 3D card model

The examples illustrate each size; they aren't a recorded sprint.

The crew

Atlas, Lead
Leads the sprint: decides, delegates and merges. Never writes product code.
Claude Opus 5.5
Quill, Product Owner
Keeps the roadmap in milestones, and writes what done means for M and L work.
Claude Opus 5.5
Forge, Engineer
Writes the product code, one area at a time.
Claude Opus 5.5
Pixel, Creative Engineer
Builds the 3D, the motion and the details that make it feel alive.
Claude Opus 5.5
Lens, Code Reviewer
Reviews every pull request in CI with fresh eyes: reads the code, never runs it.
Claude Opus 5.5
Probe, QA
Writes the contract as failing browser checks before anyone builds.
Claude Opus 5.5
Iris, Design Director
Owns taste: sets the direction, and reviews visual work as advice.
Claude Opus 5.5

What CI runs on every pull request

1Lint
2Types
3Unused code
4Build
5Harness tests
6Browser checks and axe