@arthai/agents 1.0.4 → 1.0.6

package/skills/restart/SKILL.md

@@ -1,70 +1,226 @@
 ---
 name: restart
-description: "Kill and restart local dev servers. Reads service config from CLAUDE.md. Usage: /restart [service]"
+description: "Discover, restart, and validate local dev servers. Auto-detects Docker vs native, checks health, catches crash loops. Usage: /restart <service> <--preflight>"
 user-invocable: true
-arguments: "<service>"
+arguments: "<service> <--preflight>"
 ---
 
 # Restart Servers Skill
 
-Kill and restart local dev servers using the configuration from CLAUDE.md.
+Discover how services run, restart them safely, and verify they stay healthy.
 
-## Instructions
+## Phase 1: Discover Services
 
-1. **Read CLAUDE.md** in the project root. Look for the **Local Dev Services** table:
+**First, check CLAUDE.md** for a `Local Dev Services` table:
 
 ```markdown
 ## Local Dev Services
 
-| Service  | Port | Directory | Start Command |
-|----------|------|-----------|---------------|
-| Frontend | 3000 | frontend/ | npm run dev |
-| Backend  | 8000 | backend/  | uvicorn app.main:app --reload --port 8000 |
+| Service  | Type   | Port | Directory | Start Command                         | Health Check    | Depends On |
+|----------|--------|------|-----------|---------------------------------------|-----------------|------------|
+| Postgres | docker | 5432 | —         | docker compose up -d postgres         | pg_isready      | Docker     |
+| Backend  | native | 8000 | backend/  | uvicorn app.main:app --reload         | /api/health     | Postgres   |
+| Frontend | native | 3000 | frontend/ | npm run dev                           | /health         | Backend    |
 ```
 
-If CLAUDE.md doesn't have this section, scan the project:
-- `package.json` scripts → find dev/start commands
-- `requirements.txt` / `pyproject.toml` → look for uvicorn/gunicorn/flask
-- `docker-compose.yml` → extract service ports
-- Common ports: frontend 3000, backend 8000
+**If the table is missing or incomplete, auto-discover** by scanning the repo. Check these files in order:
+
+| File | What to extract |
+|------|-----------------|
+| `docker-compose.yml` / `docker-compose.*.yml` | Service names, ports, images, healthcheck configs, volume mounts. These are **docker** type services. |
+| `Dockerfile` / `Dockerfile.*` | What gets containerized — cross-reference with compose to understand which services are Docker-managed. |
+| `package.json` (root + subdirs) | `scripts.dev`, `scripts.start`, `scripts.serve` → these are **native** Node services. Check `proxy` field for backend port. |
+| `Makefile` / `Procfile` / `Justfile` | Process definitions, often with ports and dependency ordering. |
+| `pyproject.toml` / `requirements.txt` | Python services — look for uvicorn/gunicorn/flask/django in deps. |
+| `.env` / `.env.local` / `.env.example` | Port assignments (`PORT=`, `DATABASE_URL=`, `REDIS_URL=`), required env vars. |
+| `turbo.json` / `nx.json` / `pnpm-workspace.yaml` | Monorepo structure — maps workspace packages to services. |
+
+For each discovered service, determine:
+- **Name**: human-readable (e.g., "Backend API", "Postgres")
+- **Type**: `docker` (managed by docker compose) or `native` (runs directly on host)
+- **Port**: what port it listens on
+- **Directory**: where to `cd` before running the start command
+- **Start command**: exact command to launch it
+- **Health check**: endpoint or command to verify it's running (look for `/health`, `/api/health`, `pg_isready`, `redis-cli ping`, etc.)
+- **Depends on**: other services that must be running first (DB before backend, backend before frontend)
+
+**If discovery is ambiguous, ASK the user.** Specifically ask when:
+- Multiple compose files exist and it's unclear which to use (dev vs prod vs test)
+- A service could be Docker OR native (e.g., Postgres has both a compose entry and a local install)
+- No health check endpoint is obvious — ask what URL or command confirms the service is healthy
+- Port conflicts or unusual port assignments are detected
+- You find services but can't determine the dependency order
+
+Present what you found and ask for confirmation:
+```
+Found 3 services:
+  1. Postgres (docker, port 5432) — via docker-compose.yml
+  2. Backend (native, port 8000) — via backend/pyproject.toml
+  3. Frontend (native, port 3000) — via frontend/package.json
+
+Dependencies: Frontend → Backend → Postgres
+
+Health checks:
+  - Postgres: pg_isready -h localhost -p 5432
+  - Backend: curl localhost:8000/api/health
+  - Frontend: curl localhost:3000
+
+Does this look right? Any corrections?
+```
+
+After confirmation (or if CLAUDE.md table already exists), proceed to Phase 2.
+
+**Update CLAUDE.md**: If services were auto-discovered and the user confirmed, write/update the `Local Dev Services` table in CLAUDE.md so future runs skip discovery.
 
-2. **Kill existing processes** for the target service(s):
+## Phase 2: Pre-flight Validation
 
+Before touching any running processes, validate the environment is ready:
+
+### 2a. Docker check (if any service type is `docker`)
+```bash
+# Is Docker daemon running?
+docker info > /dev/null 2>&1 && echo "Docker: OK" || echo "Docker: NOT RUNNING"
+```
+If Docker is not running, **stop and tell the user**. Don't proceed.
+
+### 2b. Dependency check (for native services)
 ```bash
-# Kill by port
+# Node services — are node_modules installed?
+[ -d "<directory>/node_modules" ] && echo "node_modules: OK" || echo "node_modules: MISSING — run npm install"
+
+# Python services — is the venv active / deps installed?
+[ -f "<directory>/.venv/bin/python" ] && echo "venv: OK" || echo "venv: MISSING"
+```
+
+### 2c. Environment variables
+```bash
+# Check critical env vars exist (read from .env.example or known requirements)
+[ -f "<directory>/.env" ] || [ -f "<directory>/.env.local" ] && echo "env file: OK" || echo "env file: MISSING"
+```
+
+### 2d. Port availability
+```bash
+# Check if port is already in use by a DIFFERENT process than expected
+lsof -ti:<port> 2>/dev/null
+```
+If a port is occupied by an unexpected process, warn the user before killing it.
+
+### 2e. Pre-flight only mode
+If the user ran `/restart --preflight`, **stop here** and report results. Don't restart anything.
+
+## Phase 3: Restart Services (dependency order)
+
+Restart in dependency order — infrastructure first, then backends, then frontends.
+
+### 3a. Stop services (reverse dependency order)
+```bash
+# For native services — kill by port
 lsof -ti:<port> | xargs kill -9 2>/dev/null
 
+# For docker services — stop the specific service
+docker compose stop <service_name>
+
 # Wait for ports to free
 sleep 2
-```
 
-3. **Start each server** in background using the configured start command:
+# Verify port is actually free
+lsof -ti:<port> 2>/dev/null && echo "WARNING: port <port> still occupied" || echo "Port <port>: free"
+```
 
+### 3b. Start services (dependency order)
 ```bash
-# Run in background
-<start_command> &
+# Docker services first
+docker compose up -d <service_name>
+
+# Then native services — run in background
+cd <directory> && <start_command>
 ```
 
-Use `run_in_background: true` on the Bash tool.
+Use `run_in_background: true` on the Bash tool for native services.
+
+**Wait between dependency layers** — don't start the backend until the DB health check passes. Don't start the frontend until the backend health check passes.
+
+## Phase 4: Post-restart Health Validation
+
+This is the critical phase. A single health check is not enough — services can start and then crash seconds later.
 
-4. **Health check** after startup:
+### 4a. Initial health check (per service, in dependency order)
 
 ```bash
-# Check each service
-curl -sf http://localhost:<port>/health > /dev/null 2>&1 && echo "<service>:UP" || echo "<service>:DOWN"
+# HTTP services
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: UP" || echo "<service>: DOWN"
+
+# Postgres
+pg_isready -h localhost -p <port> 2>/dev/null && echo "Postgres: UP" || echo "Postgres: DOWN"
+
+# Redis
+redis-cli -p <port> ping 2>/dev/null | grep -q PONG && echo "Redis: UP" || echo "Redis: DOWN"
+
+# Docker services
+docker compose ps <service_name> --format '{{.Status}}' | grep -q "Up" && echo "<service>: UP" || echo "<service>: DOWN"
+```
+
+### 4b. Crash loop detection (wait 8 seconds, check again)
+
+```bash
+sleep 8
+
+# Re-check each service
+curl -sf http://localhost:<port><health_path> > /dev/null 2>&1 && echo "<service>: STABLE" || echo "<service>: CRASHED"
+
+# For native services — is the process still running?
+lsof -ti:<port> > /dev/null 2>&1 && echo "<service> process: alive" || echo "<service> process: GONE"
 ```
 
-5. **Report** status of all servers.
+If a service is down on the second check:
+1. **Check logs** — read the last 30 lines of output for error messages
+2. **Report the failure clearly** with the error
+3. **Do NOT retry automatically** — tell the user what went wrong
+
+### 4c. Final status report
+
+```
+✅ Restart complete
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | STABLE  |
+| Frontend | native | 3000 | STABLE  |
+
+All services healthy after 10s stability check.
+```
+
+Or if something failed:
+
+```
+⚠️ Restart partial — 1 service unhealthy
+
+| Service  | Type   | Port | Status  |
+|----------|--------|------|---------|
+| Postgres | docker | 5432 | STABLE  |
+| Backend  | native | 8000 | CRASHED |
+| Frontend | native | 3000 | SKIPPED |
+
+Backend crashed after startup. Last error:
+  ModuleNotFoundError: No module named 'sqlalchemy'
+
+Fix: Run `pip install -r requirements.txt` in backend/ and retry.
+Frontend was skipped because it depends on Backend.
+```
 
 ## Argument Patterns
 
 | User Input | Action |
 |-----------|--------|
-| `/restart` (no args) | Kill and restart all configured servers |
-| `/restart backend` | Kill and restart only the backend service |
-| `/restart frontend` | Kill and restart only the frontend service |
-| `/restart <service>` | Kill and restart the named service |
+| `/restart` (no args) | Discover → validate → restart all services |
+| `/restart backend` | Restart only the named service (and its dependencies if they're down) |
+| `/restart --preflight` | Discover and validate only — don't restart anything |
 
-## If CLAUDE.md Is Missing Service Config
+## Key Principles
 
-Report: "No Local Dev Services table found in CLAUDE.md. Add a table with Service, Port, Directory, and Start Command columns. Or specify the services manually."
+1. **Never guess** — if you can't determine how a service runs, ask
+2. **Dependency order matters** — always start infra → backend → frontend
+3. **One health check isn't enough** — check twice with a gap to catch crash loops
+4. **Report errors with context** — show the actual log output, not just "DOWN"
+5. **Don't retry blindly** — if a service crashes, diagnose and report, don't loop