---

name: local-dev-workflow description: Standards for creating robust local development startup scripts triggers:

• start.sh
• local dev
• startup script
• run locally
• dev server

---

Local Development Workflow Skill

This skill guides the creation of start.sh scripts that ensure a reliable, conflict-free local development environment.

Core Philosophy

1. Port Sovereignty: Every project gets unique ports (e.g., 3456, 7200) to avoid conflicts with other running projects. Never use default 3000/8000/8080.
2. Idempotency: The script must be safely re-runnable. It should aggressively find and kill any process holding its ports before starting.
3. Transparency: The script should output all running services, their PIDs, and their accessible URLs at the end.
4. One-Click Start: A single script should handle everything: DB (Docker), Backend, Frontend, and Environment setup.

The Standard start.sh Pattern

When asked to "create a start script" or "how to run this locally", generate a start.sh that follows this structure:

1. Define Configuration: Set ports and project names at the top.
2. Cleanup Function: Include a robust kill_port function using lsof.
3. Pre-flight Checks: Check for Docker, Node versions, or ulimit.
4. Environment Setup: Dynamically update .env files or export vars to match the chosen ports.
5. Service Startup: Start dependencies (Docker) -> Backend -> Frontend.
6. Dashboard Output: Print a clear summary of all services and URLs.

Common Tasks

1. Identify Services & Assign Ports

Analyze package.json, docker-compose.yml, or Cargo.toml. Assign random-ish but memorable ports:

• Frontend: 3xxx (e.g., 3456)
• Backend: 7xxx (e.g., 7200)
• DB: 54xx (e.g., 5433 - avoid default 5432)

2. The kill_port Function

Always include this utility to ensure clean restarts:

Copykill_port() {
    local port=$1
    local pid=$(lsof -ti :$port)
    if [ -n "$pid" ]; then
        kill -9 $pid
    fi
}

3. Handling Logs

Redirect logs to a file directory to keep stdout clean, or use a tool like concurrently if preferred by the user. For shell scripts, background processes & with log redirection is standard.

Reference

See resources/start-script-template.md for the canonical template.