Local environment
localEnvironment describes how the repository stands up an isolated local instance, if it can. The delivery skills read it; they never guess it.
{
"localEnvironment": {
"create": "git worktree add ../<name> -b <branch> <base> && docker compose -p <name> up -d",
"recreate": "pnpm db:reset",
"recreateMode": "inPlace",
"instanceName": "cat .instance-name",
"seed": "pnpm db:seed",
"migrate": "pnpm db:migrate",
"teardown": "docker compose -p <name> down -v",
"instanceBoundTo": "directory",
"fetchOnSessionStart": false
}
}
| Field | Meaning |
|---|---|
create / seed / migrate / teardown |
A command, or null when the repository has no such step. <name> (the instance), <base> (the ref to branch from) and <branch> (the new branch, in your repository's naming convention) are placeholders the tooling may need — a tool that defaults the branch to the instance name mints a nonconforming one. |
recreate |
A command that genuinely returns an instance to <base>'s schema, or null. |
recreateMode |
"inPlace" or "newInstance" — which of the two shapes recreate is. Required whenever recreate carries <name>. |
instanceName |
A command whose output names the instance this checkout belongs to. Needed to resolve <name> in an in-place recreate; null otherwise. |
instanceBoundTo |
What an instance is keyed on: directory (a second checkout gets its own database and ports, and checking out another branch inside it keeps them), branch, or none. |
fetchOnSessionStart |
false by default. From 3.3.0, true has the session-start hook run a bounded, prompt-free git fetch --prune origin for the repository root and print one line only when the current branch is behind its upstream. It never blocks a session — a hung fetch is killed at its deadline and every failure stays silent — and it runs whether or not the plugin update check is enabled. Setup does not write it; turn it on by hand. It shortens the window a stale checkout can open, but the loop still fetches for itself at the start of every iteration. |
`recreate` exists because `migrate` and `seed` only go forward
Migrations do not un-apply and a seed rewrites rows, not schema. An instance living on development-branch schema therefore cannot be brought back to a production-branch base by running them — it stays ahead of the code it is now running, and a hotfix can validate against a schema production does not have.
recreateis the way back, and/devstride:branch-hotfixuses it, says which path it took, and stops to ask rather than guessing when there is no safe command and the schema has diverged.
recreateMode cannot be inferred from the command text — a wrapper script is opaque, and each wrong guess fails in its own way: an in-place command treated as a second instance leaves the session on the old database, while the reverse resets an instance somebody is using. instanceName matters for the same reason: nothing else in the block identifies the current instance, and guessing from a directory name resets a different one, which on a shared machine destroys someone else's data silently.
The shipped default is every command null and instanceBoundTo: "none". With that default, branch-hotfix asks before touching a database and build-item treats the current checkout as the only environment. Setup gathers candidates from compose files, devcontainers, Nix files and package scripts and asks — it never reports a command as detected, because a compose file proves a stack exists, not how your team starts it; and instanceBoundTo is always asked, because no file says whether a second checkout gets its own database.
This block tells the loop what exists — declaring an environment never makes the loop run builds concurrently. Whether two checkouts can be tested at the same time is a property of the repository, not of this block: where the test infrastructure is shared across checkouts, test execution stays serial regardless of what is configured here.