StudioOSDocs

Reference: every file, stage and rule of a run

This page documents the StudioOS repo and the files a run reads and writes in a client repo. It is for looking up one thing; the walkthrough tells the story. Nothing here has a plot.

run.png — seed 0xe162

CONTENTS.md — 6 sections

Files, and who writes them

files.md

In the StudioOS repo

PIPELINE.md: The orchestrator's instructions: the stages and their order, the round caps, and when to stop and ask. A retro changes it only with the owner's yes.
rubric.md: What the critic scores against, in four parts: strategy, copy, visual and verification. A retro changes it only with the owner's yes.
agents/: The five agent files: studio-strategist.md, studio-copywriter.md, studio-designer.md, studio-developer.md and studio-critic.md. Each sets the agent's job, what it reads and writes, and what it never does.
templates/: Starting files for a run: intake.md and status.md.
RETRO.md: The instructions for a retro, run from this repo on a finished client repo.

In a client repo

blueprint/intake.md: The owner's intake, written in Site Blueprint. The only source of the facts the site states.
blueprint/references/references.json: Reference sites with notes, what to borrow, what to avoid, and a priority. Exported from Site Blueprint; when there is no primary reference, the designer adds picks from the owner's library.
blueprint/blueprint.json: The source of truth for every stage. Its fields are listed below.
blueprint/status.md: The orchestrator's record: the stage, the state, the log, usage, decisions made by agents, open needs, the owner's corrections, and what is waiting on the owner. A new session resumes from it.
blueprint/feedback.md: Every critic round, appended by the orchestrator, and My notes, where the owner's notes override everything else.
blueprint/concepts/: a.md and b.md, the designer's note for each concept: idea, stance, borrowed, layout, type, sections and difference, then the copy changes and decisions made while building.
blueprint/verification.md: The critic's functional and visual tables and the project-checks table the orchestrator fills in. Every row ends in PASS, FAIL or NOT RUN, with evidence.
DESIGN.md: The design tokens, with the developer's Agent decisions below them: the rules every later page follows for heroes, cards and section rhythm.

blueprint.json: one file, every stage

blueprint.json.md

Every agent reads blueprint/blueprint.json, and each writes only its own fields.

project: The name, goal, audience and tone. The strategist sharpens them from the intake.
sitemap: Pages with path, purpose, primaryAction and sections. The strategist writes the structure and each section's notes; the copywriter fills in heading, copy, ctaLabel, ctaHref and contentStatus. A section marked final is the owner's approved copy, and agents leave it alone.
features: What the site does, each with an id, a title and a description. Written by the strategist.
requirements: The intake's must-haves, in the owner's words. Written by the strategist.
acceptanceCriteria: Numbered checks a person or a browser can observe, site-wide or for one page. Written by the strategist; the critic checks every one.
decisions: Three lists: fixed, agentMayDecide and askFirst. The strategist keeps the entries that are there and adds ones specific to the project.
design: The direction, fonts, colors, spacingScale, radii, motionMode and motion. The developer records them from the chosen concept.
contentPolicy: The policy for copy and assets, set before the run. No agent changes it.

Stages 0 to 10, in order

stages.md

Stage	Run by	What it produces
0 Preflight	Orchestrator.	Checks the project, the references or the library, the browser tool and the intake, and creates blueprint/feedback.md. Commit: studio: preflight.
1 Intake	Owner, in Site Blueprint.	blueprint/intake.md and the references. No commit of its own: the preflight has already checked it.
2 Strategy	Strategist.	Purpose, sitemap, sections, requirements and acceptance criteria in blueprint.json. Commit: studio: strategy.
3 Copy	Copywriter.	The heading, copy and button of every section in blueprint.json. Commit: studio: copy.
4 Text review	Critic, then fixes by the strategist and the copywriter.	Cap: one round. Commit: studio: text review.
5a Directions	Designer.	blueprint/concepts/a.md and b.md, one close and one push. Commit: studio: directions.
5b Concept builds	Designer.	Each concept as a live page in its own git worktree. Commit: studio: concepts built.
6 Concept review	Critic, then fixes by the designer.	Cap: two rounds per concept. Commit: studio: concept review.
7 Gate	Owner.	One concept, one with named parts of another, or neither with a reason. Commit: studio: gate.
8 Build	Developer.	The full site page by page, the design tokens, then the content in Sanity. Commit: studio: build.
9 Verification	Critic and the project checks, then fixes by the developer.	Cap: three rounds. Commit: studio: verification.
10 Final review	Owner.	Notes, or acceptance of the site. Commit: studio: done.

Decisions and escalation: who may decide what

decisions.md

The decisions field in blueprint.json holds three lists.

agentMayDecide: The agent decides, and the orchestrator logs it. The owner sees every one at the final review.
askFirst: The stage stops and asks, with the options and the agent's recommendation. Questions are batched into one stop, and work that does not depend on the answer carries on.
fixed: Only the owner changes these.

Four things always go to the owner, whatever the lists say:

A missing business fact: Marked [NEEDS: …] and listed under Needs. The run stops only when a stage cannot proceed without it.
A contradiction: Between the intake, the references and the owner's notes.
A tool or access failure: Such as a dev server that will not start, or missing credentials.
A stage at its loop cap: Still failing the critic after its last allowed round.

Each stop outside the gate and the final review adds one to Interruptions in blueprint/status.md.

Rubric and verification: scored 1 to 3, passed at 2

rubric.md

Four parts: Strategy, copy, visual and verification. The critic reads the part for the work in front of it.
Scores: Every item gets 1 (off), 2 (acceptable) or 3 (intentional), with a one-line reason and a concrete fix for anything below 3. Work passes when no item is below 2.
Weaknesses: Every review looks for at least three concrete weaknesses, each pointing at a page, a section or a sentence and marked blocking or suggestion. The list is never padded to reach three.
Visual scoring: Each page at 1440, 768 and 390 pixels wide, from viewport-height screenshots taken while scrolling. Never from one tall full-page image.
Project checks: pnpm check, pnpm test, pnpm test:e2e and pnpm test:lighthouse. The orchestrator runs all four in every verification round, because a fix can break a check that passed.
blueprint/verification.md: Three tables: functional, one row per acceptance criterion; visual, one row per page and width; project checks, one row per command. Every row has a method, evidence, and PASS, FAIL or NOT RUN with the reason. No PASS without evidence.

Retro: how a lesson gets in

retro.md

Where: From the StudioOS repo, on a client repo whose run is finished.
Facts: A script collects the run's facts into a record under retro/runs/. Records are evidence: their facts are never edited and no record is deleted.
Proposals: Written to retro/proposals.md. Each names one file, an anchor line in it, and the text to add after it, replace it with, or delete, with the evidence behind it.
The owner's answer: Yes, no, or yes with different wording, for each proposal. Nothing is applied without a yes.
Ledger: Each accepted lesson is one commit and one entry in retro/lessons.json. Rejected proposals are recorded too, with the owner's reason.
Scope: A proposal may change only agents/studio-*.md, rubric.md, PIPELINE.md and templates/*.md. One that names any other file is refused.
Reach: A lesson reaches a client project the next time that project is exported from Site Blueprint.