Preparation
Preparation is one conversation, run once per project, that records how your repo works: how to install it, how to verify it, which tests are already red, and how to bring the app up for a test drive. Every agent runcastle launches afterwards reads those answers instead of guessing at them.
Why it exists
Without it, every agent rediscovers your repo from scratch. It guesses the install command, guesses a test filter, and when a test fails it cannot tell whether it broke something or found something that was already broken. In one real build an agent spent two full monorepo test runs guessing at a workspace filter name.
Preparation pays that cost once. The answers are project settings from then on, and the agent that establishes them has to show its work.
Running it
Nothing runs on its own. You start preparation from the project row at the foot of the sidebar (Prepare this project), from the command palette, or from the project screen, which offers it as the first thing to do on a project with no features yet.
It opens a Claude Code terminal in your real checkout, not in a worktree, because half of what it needs to learn can only be settled on your machine: your database, your services, your dev server. The agent asks, runs things, and records what it finds. Answering "we have no database here" is a complete answer.
Come back to it any time. Resume picks up the last conversation; Start fresh begins one that has never seen it.
What it establishes
Eight facts, in this order.
| Fact | What it is |
|---|---|
| Setup command | Takes a clean checkout to a buildable state: dependency install plus codegen. Sandboxed build agents run it once when the container comes up. |
| Verify commands | The exact typecheck, test, and lint commands, one per line. Also where you cap test concurrency, if your suite needs that. |
| Known failing tests | What is already red on your main branch, with a count and the suite names, so build agents do not file your breakage as theirs. |
| Dev command | Starts the dev server. The first localhost URL it prints becomes the Open app link on a test drive. |
| Test drive setup | A shell command run on your machine before the dev server starts: bring up services, create and migrate a database. |
| Test drive teardown | Run after the drive stops: drop the branch database, stop services. |
| Test drive environment |
KEY=VALUE lines applied to all three of the above. This is where a
branch gets its own database name.
|
| Database reset command | Rebuilds your dev database from the migrations in your working tree. Never run automatically; it is offered when runcastle notices migration drift after a drive. |
The drive environment can interpolate the feature being driven, so each branch gets its own database instead of fighting over one:
DB_NAME=myapp_{{id}}
DATABASE_URL=postgres://localhost/myapp_{{id}}
{{slug}} is the feature slug, {{branch}} its branch, and
{{id}} the slug in a form that is legal as a database name. Setup and
teardown then read $DB_NAME like any other shell variable.
Proving it
A recorded command is a claim. At the end of the conversation the agent offers a dry run, which takes the claim and runs it.
A dry run is a real test drive with the branch switch removed. Nothing is checked out. It renders the environment, runs your setup command, starts the dev server, watches for a localhost URL, then runs teardown, all under a reserved slug so nothing it creates collides with a real feature. Four facts can be proven this way:
- Test drive environment: no placeholder was left unsubstituted.
- Test drive setup: it exited zero.
- Dev command: the server started and printed a localhost URL.
- Test drive teardown: it exited zero.
It is all or nothing. If any of them fails, nothing is marked verified, and runcastle stamps the result itself rather than taking the agent's word for it. The other four facts have no equivalent check, so they carry no verification badge at all. That reads as "not provable here", not as "failed".
A dry run and a feature test drive use the same machinery, so only one can hold your machine at a time. If a drive will not start, check whether a dry run is still up and stop it from the preparation screen.
Where the answers live, and who owns them
Values are stored per project in runcastle's own database, alongside a record of where each one came from and what it was measured against. Three of them (setup command, verify commands, known failing tests) fall back to a global default when the project has none.
Each fact records who settled it:
- An agent, working it out with you present. The evidence it recorded sits under the value, so you can see what it actually ran.
- You, by editing the field in Settings or confirming it in the conversation. Preparation never overwrites those. Clear the override to hand the field back. Editing a field also clears its verification, since what was proven is no longer what is stored.
Every fact pins the commit it was established at. When your main branch has moved a long way since, the preparation screen says so. A stale test baseline is worse than none, because agents trust it and file fresh breakage under "already red".
Skipping it
Nothing is blocked. No gate checks whether a project is prepared. You lose the efficiency: build agents work out the verify commands themselves, once per ticket, and a test drive with no dev command gives you a checked-out branch and nothing running. The test drive step will also warn, without stopping you, when the drive commands were never proven.
Preparation is about your repo. runcastle doctor is about your machine.
Neither replaces the other.