Set up a dev-local launcher for this codebase
Goal: produce one script (scripts/dev-local.sh) that a person or agent runs
to bring the whole local stack up — every long-lived dev server in its own tmux
window, plus any infra (DB, cache, queues) the app needs — and a short skill doc
so it's discoverable later.
Do NOT start any dev servers yourself. You are generating the launcher, not
running it. Build it, syntax-check it, then hand it to the user to run.
This is the local, single-stack launcher. For concurrent agents that each
need their own isolated stack (one laptop can't run N), see crabbox-setup — the
cloud counterpart. It reuses this script's service/port discovery, so set this up first.
Step 1 — Investigate the repo (don't guess)
Discover the real facts before writing anything:
- Package manager & layout — look for
pnpm-workspace.yaml / turbo.json /
nx.json / lerna.json (monorepo) or a single package.json, Cargo.toml,
go.mod, pyproject.toml, Makefile, Procfile, docker-compose.yml.
- Services to run — each app/package with a
dev/start/serve script, or
each Procfile line, or each docker-compose service. Note the exact command
to start each (e.g. pnpm --filter <name> run dev, npm run dev, cargo run,
uvicorn app:app --reload).
- Ports — grep configs and
.env for the port each service binds
(PORT, listen(, server.port, framework config like rsbuild.config,
vite.config, next.config). Record which talks to which.
- Infra dependencies — does a backend need Postgres / Supabase / MySQL /
Redis / Mongo / Kafka? Check
.env(.local), ORM config, docker-compose,
and connection-string defaults. Decide how to provide each locally
(supabase start, a Docker container, an existing docker-compose).
- First-run setup — migrations, seed, codegen,
install. Note the commands
but keep them OUT of the default up path (offer a separate subcommand).
- Env files — confirm a committed
.env.example/.env; never invent or
print secrets. The script must not inject credentials.
Write down a small table: service → command → port → depends-on. That table is
the spec for the script.
Step 2 — Generate scripts/dev-local.sh
Adapt the skeleton in assets/dev-local.template.sh (same directory as this
skill). Fill in the discovered services, ports, and infra. Keep these
invariants:
- One tmux session, one window per long-lived server. Idempotent: re-running
up leaves existing windows alone instead of duplicating them.
- Preflight that fails fast with install hints when a required tool is
missing (tmux, the package manager, Docker if infra needs it).
- Infra brought up before servers, reused if already running.
- Subcommands:
up, down (and down --all to stop infra), status (window
list + port check), logs <name>, restart <name>, attach, plus any
project-specific one-shots (migrate, seed).
- Resolve repo root from the script's own location so it works from any cwd.
- No secrets in the script. Print URLs and a port check at the end of
up.
If the repo has no infra needs, drop the Docker/DB parts entirely — keep it
to preflight + tmux windows. Match the script's complexity to the repo; simpler
is better.
Then: chmod +x scripts/dev-local.sh and bash -n scripts/dev-local.sh to
syntax-check. Verify the read-only status path runs cleanly. Do not run up.
Step 3 — Write a short skill doc
Create .claude/skills/dev-local/SKILL.md (or the repo's skills location) with:
frontmatter (name: dev-local, a description listing trigger phrases), a
service/port table, prerequisites, the subcommand list, and brief
troubleshooting (port-in-use, a window exited, infra not running). Keep it to one
screen — it documents the script, it doesn't re-explain it.
Step 4 — Hand off
Tell the user the exact commands: scripts/dev-local.sh up, plus any first-run
step (… migrate). List the URLs. Note any prerequisite they must install or
start (e.g. Docker Desktop) before the first up.
Principles
- Discover, don't assume. Ports and start commands come from the repo, never
from convention alone.
- Idempotent & safe to re-run. No duplicate servers, no clobbered infra.
- Right-sized. A 3-service monorepo with Postgres+Redis needs the full
skeleton; a single Vite app needs ~30 lines. Don't over-build.
- Never run servers or print secrets. Generate, syntax-check, hand off.