StudioOSOne run, seven steps
One site built by AI agents, seen from the owner's side
This is a single StudioOS run, start to finish: from the intake the owner writes to the retro after the site is accepted. Each step shows what the owner does, what the agents do, and the two moments the run waits for a person. Spoiler: the owner's part is the short one.
1. Write the intake: the only facts the site may state
Every run starts in Site Blueprint, the owner's app for the intake, the references and the export. The intake answers six questions: what the site is, who it is for, what a visitor should do, the tone, the must-haves, and the known facts.
Next come the references: sites saved with notes on what to borrow and what to avoid. Saved once, they live in the owner's reference library with notes on what is good, what is weak and what kind of site each suits, and they are reused across projects. When a project has no primary reference, the designer picks from the library.
Then the export: Site Blueprint writes the intake, the references and blueprint/blueprint.json into a client repo built on Astrokit.
The Known facts list deserves the most care. It is the only source of facts the site may state. A price, a name or a figure left out of it will not appear on the site; the agents put a [NEEDS: …] marker where it belongs. The quality of the whole run is decided here.
2. Start the run: one command, and a file that remembers
In the client repo, one command starts the run. The same command resumes it.
claude "Read blueprint/studio/PIPELINE.md and run it here."The session that reads PIPELINE.md becomes the orchestrator. It dispatches the agents one at a time and keeps blueprint/status.md current: the stage, the state, and one log line per dispatch. A new session that runs the same command reads status.md and picks up where the last one stopped.
Each stage that passes is committed to git as studio: <stage name>, so the history of the run is the history of the repo.
3. While it runs: mostly nothing
Strategy, copy, the text review, both design directions, both concept builds and the concept review run without the owner. The agents go one at a time, and each stage that passes is committed.
The run stops only to ask, and only for these reasons:
- A missing fact
- The agent marks it [NEEDS: …] and carries on. The run stops only if a stage cannot proceed without it.
- An ask-first decision
- Anything listed under decisions.askFirst in blueprint.json, such as adding a major dependency.
- A contradiction
- The intake, the references and the owner's notes disagree.
- A tool or access failure
- A dev server that will not start, or missing credentials.
- A loop cap
- A stage still fails the critic after its last allowed round.
When it stops, the question waits under Waiting on you in blueprint/status.md, with the options and the agent's recommendation. To steer without being asked, the owner writes under My notes in blueprint/feedback.md. Those notes override everything else, the intake included.
4. The gate: two live concepts, four possible answers
When the concept review is done, the run stops. This is the first of the two decisions the owner always makes.
The owner gets two URLs, concept A and concept B, each a live page served from its own git worktree. One stays close to the references; the other pushes further. Both use the real copy. Next to each: its idea, the critic's latest scores, any open issues, and every place the designer shortened the copy.
The answer is one of four:
- A
- The copywriter settles the designer's cuts to the copy, concept A is merged into the base branch, and the worktrees are removed.
- B
- The same steps, with concept B merged instead.
- A with named parts of B
- Concept A is merged the same way, and the parts the owner named become the developer's first task.
- Neither, with a reason
- The designer writes a third concept, c, that answers the reason. It is built and reviewed, and the run returns to the gate with all three.
5. Build and verification: up to three rounds to pass
The developer extends the chosen concept into the whole site, one scope at a time: the home page and the footer first, then every other page in sitemap order. It reuses the concept's blocks and tokens instead of re-deciding them, records the design tokens, then moves the content into Sanity.
Verification runs the project's checks: type check, unit tests, end-to-end tests and Lighthouse. The critic opens every page at 1440, 768 and 390 pixels wide, checks every acceptance criterion in a browser, and writes PASS, FAIL or NOT RUN, with evidence, into blueprint/verification.md.
Anything that fails goes back to the developer. After each fix, the critic re-checks what failed and every project check runs again, because a fix can break something that passed. After three rounds, whatever still fails goes to the owner as an open issue.
6. Final review: accept, or send notes
When verification is done, the run stops for the last time. The owner gets what was built and how to run it; the PASS, FAIL and NOT RUN counts, with every criterion that did not pass and why; every decision the agents made on their own; and every [NEEDS: …] marker still on the site.
Notes on wording go to the copywriter, everything else to the developer, and the affected checks run again before the owner looks once more.
When the owner accepts the site, the run is done and commits as studio: done. Accepting is the second and last decision only the owner makes.
7. Retro: corrections become instructions
Every time the owner changed or rejected what an agent produced, the run wrote the owner's words under Corrections in blueprint/status.md. The retro runs afterwards, from the StudioOS repo, and reads them along with the rest of the run's record.
It proposes small changes to the agents' own instructions, the rubric, the pipeline or the templates, each with its evidence. The owner answers each one: yes, no, or yes with different wording. Nothing changes without a yes, and each accepted lesson is its own commit.
A lesson reaches a client project the next time that project is exported from Site Blueprint, so the next run starts from what this one taught.
Want the exact files and rules?
The docs list every file a run reads and writes, stages 0 to 10 with their round caps, and the rules for when the run stops to ask.