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.
1---2name: dev-local-setup3description: >4 Scaffold a one-command `dev-local` launcher for ANY codebase. Investigates the5 repo to find its services, ports, and infra dependencies, then generates a6 single `scripts/dev-local.sh` (up/down/status/logs/restart) that runs every7 dev server in one tmux session, plus a short skill doc describing it. Use when8 someone says "set up dev-local", "make a one-command dev launcher", "I want9 one script to start this repo", "scaffold dev-local for this project".10user_invocable: true11metadata:12 source: https://skillmd.com/skills/ai-builder-club/dev-local-setup13---1415# Set up a `dev-local` launcher for this codebase1617Goal: produce **one script** (`scripts/dev-local.sh`) that a person or agent runs18to bring the whole local stack up — every long-lived dev server in its own tmux19window, plus any infra (DB, cache, queues) the app needs — and a short skill doc20so it's discoverable later.2122Do NOT start any dev servers yourself. You are *generating* the launcher, not23running it. Build it, syntax-check it, then hand it to the user to run.2425> This is the **local, single-stack** launcher. For **concurrent agents** that each26> need their own isolated stack (one laptop can't run N), see `crabbox-setup` — the27> cloud counterpart. It reuses this script's service/port discovery, so set this up first.2829## Step 1 — Investigate the repo (don't guess)3031Discover the real facts before writing anything:32331. **Package manager & layout** — look for `pnpm-workspace.yaml` / `turbo.json` /34 `nx.json` / `lerna.json` (monorepo) or a single `package.json`, `Cargo.toml`,35 `go.mod`, `pyproject.toml`, `Makefile`, `Procfile`, `docker-compose.yml`.362. **Services to run** — each app/package with a `dev`/`start`/`serve` script, or37 each `Procfile` line, or each `docker-compose` service. Note the exact command38 to start each (e.g. `pnpm --filter <name> run dev`, `npm run dev`, `cargo run`,39 `uvicorn app:app --reload`).403. **Ports** — grep configs and `.env` for the port each service binds41 (`PORT`, `listen(`, `server.port`, framework config like `rsbuild.config`,42 `vite.config`, `next.config`). Record which talks to which.434. **Infra dependencies** — does a backend need Postgres / Supabase / MySQL /44 Redis / Mongo / Kafka? Check `.env`(`.local`), ORM config, `docker-compose`,45 and connection-string defaults. Decide how to provide each locally46 (`supabase start`, a Docker container, an existing `docker-compose`).475. **First-run setup** — migrations, seed, codegen, `install`. Note the commands48 but keep them OUT of the default `up` path (offer a separate subcommand).496. **Env files** — confirm a committed `.env.example`/`.env`; never invent or50 print secrets. The script must not inject credentials.5152Write down a small table: service → command → port → depends-on. That table is53the spec for the script.5455## Step 2 — Generate `scripts/dev-local.sh`5657Adapt the skeleton in `assets/dev-local.template.sh` (same directory as this58skill). Fill in the discovered services, ports, and infra. Keep these59invariants:6061- **One tmux session**, one window per long-lived server. Idempotent: re-running62 `up` leaves existing windows alone instead of duplicating them.63- **Preflight** that fails fast with install hints when a required tool is64 missing (tmux, the package manager, Docker if infra needs it).65- **Infra brought up before servers**, reused if already running.66- Subcommands: `up`, `down` (and `down --all` to stop infra), `status` (window67 list + port check), `logs <name>`, `restart <name>`, `attach`, plus any68 project-specific one-shots (`migrate`, `seed`).69- Resolve repo root from the script's own location so it works from any cwd.70- No secrets in the script. Print URLs and a port check at the end of `up`.7172If the repo has **no infra needs**, drop the Docker/DB parts entirely — keep it73to preflight + tmux windows. Match the script's complexity to the repo; simpler74is better.7576Then: `chmod +x scripts/dev-local.sh` and `bash -n scripts/dev-local.sh` to77syntax-check. Verify the read-only `status` path runs cleanly. Do not run `up`.7879## Step 3 — Write a short skill doc8081Create `.claude/skills/dev-local/SKILL.md` (or the repo's skills location) with:82frontmatter (`name: dev-local`, a `description` listing trigger phrases), a83service/port table, prerequisites, the subcommand list, and brief84troubleshooting (port-in-use, a window exited, infra not running). Keep it to one85screen — it documents the script, it doesn't re-explain it.8687## Step 4 — Hand off8889Tell the user the exact commands: `scripts/dev-local.sh up`, plus any first-run90step (`… migrate`). List the URLs. Note any prerequisite they must install or91start (e.g. Docker Desktop) before the first `up`.9293## Principles9495- **Discover, don't assume.** Ports and start commands come from the repo, never96 from convention alone.97- **Idempotent & safe to re-run.** No duplicate servers, no clobbered infra.98- **Right-sized.** A 3-service monorepo with Postgres+Redis needs the full99 skeleton; a single Vite app needs ~30 lines. Don't over-build.100- **Never run servers or print secrets.** Generate, syntax-check, hand off.