- A worktree-aware setup script (bin/setup) diagnoses missing tools, shares a single Docker stack, and isolates ports, databases, and state for safe parallel development.
- The same bin/setup command must work from every Git worktree, turning a checkout into a ready development environment.
- Git worktrees isolate code but not runtime state; setup scripts must handle port, database, and resource name conflicts.
- Setup shares services (e.g., database servers) across worktrees but isolates names per worktree using a derived identity and port allocation with a lock.
- Setup owns bootstrapping the toolchain, running a doctor, ensuring shared services, allocating identity/ports, generating config, creating/migrating databases, and verifying dependencies.
- The doctor should fail early, check all requirements, and print all failures with repair steps (e.g., missing Docker, mise install).
- Shared stack limitations: restarting a shared database interrupts all worktrees; incompatible versions may need a dedicated stack.
- Teardown (bin/teardown) must release port, drop only that worktree's databases, and delete generated state—never affect shared volumes or other checkouts.
- Acceptance test: create a clean worktree, run setup twice concurrently, start both dev servers, run tests, and tear down one without affecting the other.