Dev Local Setup

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.