dev-bootstrap-application-script

Files (8)

• SKILL.md
• dev.multi-window.sh.template · assets/
• dev.sh.template · assets/
• dev.three-window.sh.template · assets/
• evals.json · evals/
• trigger-queries.json · evals/
• patterns.md · references/
• validate_dev_bootstrap.py · scripts/

SKILL.md (first lines)

# Dev Bootstrap Application Script

## Overview

Generate an idempotent bash script that launches every service in a project's full stack inside named tmux window(s), with up to 4 panes per window. The script handles session detection, window teardown/recreation, dependency ordering, health checks, per-run log capture, and optional reverse-proxy path-prefix bootstrapping (for tailscale serve, cloudflared, etc.).

A ready-made template is bundled at `assets/dev.sh.template`.

## When to Use

- A user asks to "write a dev script", "bootstrap the app in tmux", or "create a dev.sh"
- A user wants to launch multiple services (API, frontend, workers, databases) in one command
- A user has an existing dev script and wants it rewritten following best practices

## Workflow

### Phase 1 — Research the Project

Before writing any code, discover what services the project needs. Read the following files (when present) to build a service inventory:

| File | What to look for |
|---|---|
| `docker-compose.yml` / `compose.yaml` | Infrastructure services (postgres, redis, rabbitmq, etc.) |
| `package.json` | `scripts.dev`, `scripts.start`, framework (Next.js, Vite, Remix, etc.) |
| `Makefile` / `Justfile` | Existing `dev` / `run` / `serve` targets |
| `Procfile` / `Procfile.dev` | Named processes and their commands |
| `pyproject.toml` / `Pipfile` | Python entry points, uvicorn/gunicorn commands |
| `Cargo.toml` / `go.mod` | Build-and-run patterns |
| `.env` / `.env.example` | Environment variables needed at boot |
| `turbo.json` / `pnpm-workspace.yaml` | Monorepo workspace structure |
| `README.md` | "Getting Started" / "Development" sections |
| Frontend router / API client files | Whether routes and API calls are base-path aware |
| Vite/Next/webpack dev config | Base path and dev proxy rewrite behavior |

Produce a **service inventory** — an ordered list of:

```
1. Service name — command — working directory — depends on (if any)
```

Example:

```
1. postgres    — docker compose up -d postgres  — .          — (none)
2. redis       — docker compose up -d redis     — .          — (none)
3. api         — uv run uvicorn app:main        — .          — postgres, redis
4. frontend    — npm run dev                    — ./frontend — api
```

### Phase 2 — Design the Layout

#### Pane Limit

Maximum **4 panes per tmux window**. Beyond 4, panes become unreadably small.

#### Window Count Decision

| Services | Windows | Rationale |
|---|---|---|
| 1-4 | 1 window | Everything fits |
| 5-8 | 2 windows | Group by concern (infra vs app, backend vs frontend) |
| 9+ | 3 windows | Rare — consider if some services should stay in docker |

#### Layout Selection

Pick the tmux preset layout that best matches the pane count:

| Panes | Recommended layout | Visual |
|---|---|---|
| 2 | `even-horizontal` | `[A \| B]` |
| 2 | `even-vertical` | `[A / B]` (stacked) |
| 3 | `main-vertical` | `[A \| B/C]` (main left, two right) |
| 3 | `main-horizontal` | `[A / B\|C]` (main top, two bottom) |
| 4 | `tiled` | `[A\|B / C\|D]` (2x2 grid) |

#### Grouping Heuristic

When splitting across multiple windows, group by concern:

- **Window 1 ("infra")**: databases, caches, message brokers, docker services
- **Window 2 ("app")**: API server, background workers, task queues
- **Window 3 ("frontend")**: dev server, storybook, docs site

### Phase 3 — Write the Script

Start from `assets/dev.sh.template` and fill in the placeholders. Follow these mandatory patterns:

#### Script Structure

```
1. Shebang + header comment with layout diagram
2. set -euo pipefail
3. Parse script args (for optional checks like --skip-tailscale-check)
4. PROJECT_DIR and WINDOW constants
5. Optional Layer 0 preflight (tailscale/dependencies/etc.)
6. tmux prerequisite check
7. Session detection (inside tmux vs new session)
8. Kill existing window (idempotency)
9. Create window + split panes (capture pane IDs)
10. Small post-split delay before send-keys
11. Initialize logs directory (timestamped run dir + latest symlink)
12. Register pane log piping before launching commands
13. Load environment variables
14. Layer 1 launch services (send-keys to each pane)
15. Layer 2 readiness gates (health endpoints/ports)
16. Print operator URLs (local + remote when available)
17. Apply layout + set focus
18. Attach if started detached
```

#### Mandatory Rules

- **Pane IDs, never indices.** Always capture pane IDs with `-P -F '#{pane_id}'` and reference them by variable. Never use `tmux select-pane -t 0`.
- **Idempotent.** `tmux kill-window -t "${SESSION}:${WINDOW}" 2>/dev/null || true` before recreating.
- **Session-aware.** Detect `$TMUX` to decide whether to create a session or reuse the current one.
- **Header comment.** Every script must start with an ASCII layout diagram showing what runs where.
- **Per-run logs + latest link.** Create logs under `logs/YYYYmmdd_HHMMSS/` and refresh `logs/latest -> logs/<run_id>`.
- **Pipe with `-o`.** Use `tmux pipe-pane -o` so re-runs do not stack duplicate pipe commands.
- **Layered startup.** Prefer explicit layers (preflight -> launch -> readiness).

From tzeusy-org/ai-bootstrap, MIT.

More from tzeusy-org/ai-bootstrap