boot-local

Original source / Raw SKILL.md

---
name: boot-local
description: Kill all running local development processes (worker, edge functions, dev server), wait for termination, then restart them. Dev server runs on port 8080. Use when user says "boot local", "restart local", "reboot dev", or needs to refresh local services.
allowed-tools: Bash, TaskOutput
version: 2.1.0
---

# Boot Local

> Kill and restart all local development services when the dev environment needs a fresh start.

<when_to_use>

## When to Use

Invoke when user says:

- "boot local"
- "restart local"
- "reboot dev"
- "restart all services"
- "kill and restart"
  </when_to_use>

<workflow>
## Workflow

| Phase | Action                                    | Reference                                           |
| ----- | ----------------------------------------- | --------------------------------------------------- |
| 1     | Kill running processes (ports 8080, 3001) | [process-killing.md](references/process-killing.md) |
| 2     | Wait for termination, verify ports free   | [process-killing.md](references/process-killing.md) |
| 3     | Start all 3 services in background        | [service-startup.md](references/service-startup.md) |
| 4     | Verify startup (check logs)               | [service-startup.md](references/service-startup.md) |
| 5     | Display status report                     | Final output                                        |

**Note**: Use `run_in_background: true` for all three start commands to avoid blocking.
</workflow>

<services>
## Services

| Service        | Command                                                       | Port  | URL                                  |
| -------------- | ------------------------------------------------------------- | ----- | ------------------------------------ |
| Worker         | `npm run worker:dev`                                          | 3001  | http://localhost:3001/health         |
| Edge Functions | `npx supabase functions serve --env-file supabase/.env.local` | 54321 | http://127.0.0.1:54321/functions/v1/ |
| Dev Server     | `npm run dev -- --port 8080`                                  | 8080  | http://localhost:8080                |

</services>

<approval_gates>

## Approval Gates

| Gate | Phase | Question                                             |
| ---- | ----- | ---------------------------------------------------- |
| None | -     | No destructive operations; all local process cleanup |

</approval_gates>

<quick_reference>

## Quick Reference

```bash
# Find process on port
netstat -ano | findstr :8080 | findstr LISTENING

# Kill by PID
taskkill //F //PID <pid>

# Start services (use run_in_background: true)
npm run worker:dev
npx supabase functions serve --env-file supabase/.env.local
npm run dev -- --port 8080
```

For detailed steps: [references/process-killing.md](references/process-killing.md)
For error recovery: [references/error-recovery.md](references/error-recovery.md)
</quick_reference>

<references>
## References

- [references/process-killing.md](references/process-killing.md) - Finding and killing processes
- [references/service-startup.md](references/service-startup.md) - Starting dev services
- [references/error-recovery.md](references/error-recovery.md) - Troubleshooting failures
  </references>

<version_history>

## Version History

- **v2.1.0** (2025-01-18): AI optimization updates
  - Add blockquote summary after title
  - Soften directive language per Opus 4.5 guidance

- **v2.0.0** (2025-12-28): Refactored to follow skill-authoring-patterns
  - Added XML tags for structure
  - Created references/ for detailed content
  - Reduced from 197 to ~90 lines

- **v1.0.1** (2025-12-21): Fix edge functions env file
  - Added `--env-file supabase/.env.local`

- **v1.0.0** (2025-12-21): Initial release
  </version_history>


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/process-killing.md

```markdown
# Process Killing

## Phase 1: Kill Running Processes

**IMPORTANT**: First, use KillShell to terminate any background tasks from previous runs.

Then kill orphan processes holding the required ports by PID.

### Step 1: Find PID on Port 8080 (Dev Server)

```bash
netstat -ano | findstr :8080 | findstr LISTENING
```

Parse output to get PID (last column). Example:
```
  TCP    0.0.0.0:8080           0.0.0.0:0              LISTENING       23048
```
PID is 23048.

### Step 2: Kill by PID

```bash
taskkill //F //PID <pid>
```

### Step 3: Repeat for Other Ports

- Port 3001 (worker health check)
- Port 54321 (edge functions - usually not needed)

## Phase 2: Wait for Termination

Verify processes are dead:

```bash
# Wait a moment for processes to fully terminate
timeout /t 2 /nobreak >nul

# Verify port 8080 is free
netstat -ano | findstr :8080 | findstr LISTENING
# Should return empty (no output)
```

If ports are still in use, wait additional time or force kill by PID.

## Commands Reference

```bash
# Kill commands (Windows)
taskkill //F //IM node.exe //FI "WINDOWTITLE eq *vite*"
taskkill //F //IM deno.exe
taskkill //F //PID <pid>

# Find processes by port
netstat -ano | findstr :<port> | findstr LISTENING
```

```

### references/service-startup.md

```markdown
# Service Startup

## Phase 3: Start Services

**CRITICAL**: All three services MUST be started in background mode so they run concurrently.

### Start All Three in Parallel

Use the Bash tool with `run_in_background: true` for ALL THREE commands:

```bash
# Start worker in background
cd C:/users/zac/eos-implementer-hub && npm run worker:dev
# Run with: run_in_background: true

# Start edge functions in background (with env file for API keys)
cd C:/users/zac/eos-implementer-hub && npx supabase functions serve --env-file supabase/.env.local
# Run with: run_in_background: true

# Start dev server on port 8080 in background
cd C:/users/zac/eos-implementer-hub && npm run dev -- --port 8080
# Run with: run_in_background: true
```

## Phase 4: Verify Startup

Use TaskOutput with `block: false` to check each background task's output.

### Expected Outputs

| Service | Success Indicator |
|---------|-------------------|
| Worker | `[AutomationWorker] Worker started successfully` |
| Edge Functions | `Serving functions on http://127.0.0.1:54321/functions/v1/` |
| Dev Server | `VITE ready` and `Local: http://localhost:8080/` |

**Note**: If port 8080 is in use, Vite will auto-increment. Note the actual port in the summary.

## Phase 5: Summary Report

Display final status:

```markdown
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Boot Local Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Service        | Status  | URL                                    |
|----------------|---------|----------------------------------------|
| Worker         | Running | http://localhost:3001/health           |
| Edge Functions | Running | http://127.0.0.1:54321/functions/v1/*  |
| Dev Server     | Running | http://localhost:8080                  |

Edge functions available:
- ai-chat
- ai-debrief
- impersonation-start
- impersonation-end
- process-past-due-invoices
- + more

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Start Commands Reference

```bash
# Start services
npm run worker:dev                                           # Worker with watch
npx supabase functions serve --env-file supabase/.env.local  # Edge functions
npm run dev -- --port 8080                                   # Vite on 8080

# Verify services
curl http://localhost:3001/health           # Worker health
curl http://127.0.0.1:54321/functions/v1/   # Edge functions
curl http://localhost:8080                   # Dev server
```

```

### references/error-recovery.md

```markdown
# Error Recovery

## Port 8080 Still In Use After Kill

If port 8080 is still occupied:

1. Find the process:
   ```bash
   netstat -ano | findstr :8080
   ```

2. Kill by PID:
   ```bash
   taskkill //F //PID <pid>
   ```

3. If still fails, inform user to manually close the application

## Edge Functions Fail to Start

If `npx supabase functions serve` fails:

1. Check if local Supabase is running:
   ```bash
   npx supabase status
   ```

2. If not running, start it:
   ```bash
   npx supabase start
   ```

3. Then retry edge functions:
   ```bash
   npx supabase functions serve --env-file supabase/.env.local
   ```

## Worker Fails to Start

If worker fails:

1. Check for build errors in output

2. Try rebuilding:
   ```bash
   npm run worker:build
   ```

3. Check if port 3001 is in use:
   ```bash
   netstat -ano | findstr :3001
   ```

## Dev Server Auto-Increments Port

If Vite shows a different port than 8080:

- This means port 8080 was still in use
- Note the actual port in the summary
- Inform user of the actual URL

## All Services Fail to Start

Full reset procedure:

1. Kill all Node processes:
   ```bash
   taskkill //F //IM node.exe
   ```

2. Kill all Deno processes:
   ```bash
   taskkill //F //IM deno.exe
   ```

3. Wait for processes to terminate:
   ```bash
   timeout /t 5 /nobreak
   ```

4. Restart Supabase:
   ```bash
   npx supabase stop
   npx supabase start
   ```

5. Retry boot-local skill

```