How to run it
Startup Studio is one PowerShell entry point, studio.ps1. It installs a base roster of seventeen roles machine wide, and each project layers its own facts on top of that base. This page gives the recommended order of operations. The command reference lists every switch and what each one writes.
Steps 1 to 4 are run once for a new machine and a new project. After that, only the loop below repeats.
# 1. install the shared roster and the skills studio.ps1 -Sync # 2. tell a project where its roster comes from studio.ps1 -Connect -Project "my-app" # 3. start that project's own layer, then fill it in studio.ps1 -Tune -Project "my-app" # 4. build the project's roster: base plus layer studio.ps1 -Compose -Project "my-app" # 5. what exists, what has drifted, what to run studio.ps1 -Doctor
Step 3 writes a stack card at .claude\agent-overlays\_project.md: what the project is built with, where authorisation lives, and any shared rule it waives. Skipping it is legitimate, and that project runs the base roster unchanged.
Two commands cover most days.
# a rule that applies to every project edit base\agents\<role>.md studio.ps1 -Sync # something true of one project only edit my-app\.claude\agent-overlays\_project.md studio.ps1 -Compose -Project "my-app"
One question decides which of the two you are running. Would a project on a different stack benefit from this? If it would, the change belongs in the base. If it would not, it belongs in that project's layer.
Never edit .claude\agents\. That directory is generated output. It is rebuilt from scratch on the next compose, so an edit there is live in the current session, invisible to every other project, and then destroyed without warning.
The shared roster. True for every project, and the only part written by hand.
This project's own page. What is true here and nowhere else.
Generated from the two on the left, and rebuilt whenever either one moves.
-Release is the only supported way to ship. It takes the newest dated section of CHANGELOG.md as the note, so the changelog entry is written before the release rather than after it.
studio.ps1 -Release -WhatIf # preview, writes nothing studio.ps1 -Release # your work goes OUT studio.ps1 -Update # upstream comes IN
The last two point in opposite directions and sit one letter apart in a terminal history. -Update rebuilds every roster on the machine from upstream content and publishes nothing, which is wrong twice over if you meant to release. The reference page states what each one writes.
Every request becomes a ticket on one kanban board before work starts, and the description is where the requirements live. The board is the only queue, so nothing is built unasked and nothing asked for is lost.
Raised, not scheduled. Sitting here is a decision that it is not next.
The only place work is picked from. The team takes the top one and works down.
The plan is played back to you first, then built in one pass.
Your turn. You test it and accept it on the ticket. Nothing passes here without you.
You accepted it. Setting this is the one move on the board that is yours alone.
Queued for the next release.
Released on your explicit instruction, with the build reference on the ticket.
Live in production, and only then.
The two highlighted lanes are the ones you are involved in. The reference page marks a single column instead, because it answers a narrower question: who makes the move INTO each one. Both are true and they are not the same question.
The agents drive the board from the terminal and append what they did, decided and assumed, so the ticket becomes the history of that work. They take it as far as UAT and stop, because testing is yours. Specification and working code are under board/, and every column and status key is on the reference page.
Everything above runs in a terminal. Skills run inside a session, live under skills/, and each is a procedure the team follows identically every time.
| Skill | When | What it does |
|---|---|---|
| /warm-start | Opening a session | Hands over the note the last session left about where the work is, after checking it: does the ticket still exist, does the test count still match, has the state it points at been replaced. A stale note reads as measured, which is worse than none. |
| /assess | Before anything is built | The leads take an idea apart from their own disciplines and return a verdict, a measure and every objection. No is a legitimate answer and is most of the value. |
| /reality-check | Before a roadmap decision | Reads what the project actually earned, cost and attracted, and records it with its source and read date. Run it before trusting any claim about traction. |
| /wind-down | Closing a session | Writes what happened back into the project's own documents, read from disk rather than from memory, and commits the result. |
# a session, start to finish /warm-start # where the work actually is # ...the work... /wind-down # write it down, and save it
The last one is the one people skip and the one that costs. A session ending without it loses everything since the last update: what was decided, what is half finished, and where it stopped.
A project's layer holds three kinds of thing. At a glance they look equally important. They are not.
Something simply true here: the stack, how it is deployed, how access is enforced. It contradicts nothing, and most of the layer is this.
Just write itAn extra rule this project needs that the base does not carry. It only adds, so nothing clashes.
Just write itA shared rule waived, weakened or replaced here. It is the only kind that can quietly undo a rule every other project still follows.
Needs a name and a dateAn exception goes at the top of the layer, with an owner and a review date. -Doctor lists every one across every project and flags any that is unowned or overdue. A security gate is not the layer’s to waive: that needs sign-off recorded in the shared governance, because allowing it once turns every awkward review into an exception.
Closing
If I had to boil it down to one thing: keep a single set of instructions for your AI team, and never copy them.
For each project, write down only what's different about that project, on one short page. The version that project actually uses gets built from those two together, and rebuilt whenever either one changes. Copy the instructions and edit the copy instead, and that project stops getting anything you learn afterwards. You won't notice for months.
Start smaller than you think you need to. One project, one page of what makes it different, and only add a second when the first one is genuinely working. Everything I've had to fix along the way came from letting a project quietly do its own thing.
If you're building something of your own, I hope this saves you a few of the months it took me to work this out the hard way.
And if you'd like to build something together, or you just want to tell me where I've got this wrong, please come and find me at projectfreedom.xyz. I'd genuinely like to hear from you.
Good luck!
Please share back and improve this model for everyone's benefit. It's under AGPL-3.0, so that isn't just a request: change it and run it for other people, and your changes come back to everyone too. If that doesn't suit what you're doing, get in touch and we'll sort something out.