# Claude's Server Process Checklist

## When Starting Any Server or Long-Running Process

### Before Starting
- [ ] **Define Purpose**: Why am I starting this server?
  - Testing implementation?
  - Running integration tests?
  - Demonstrating functionality?
- [ ] **Define Success**: What constitutes success?
  - Health endpoint responds?
  - Specific tests pass?
  - User can access frontend?
- [ ] **Plan Exit**: When will I stop this server?
  - After verification?
  - After tests complete?
  - After demonstration?

### Starting the Server
```bash
# ✅ CORRECT: With lifecycle management
npm start &
SERVER_PID=$!
echo "Server started with PID: $SERVER_PID"

# ❌ WRONG: Fire and forget
npm start &
# Now what?
```

### Waiting for Ready
```bash
# ✅ CORRECT: With timeout
for i in {1..10}; do
  curl -s localhost:3000/api/health && break
  [ $i -eq 10 ] && { echo "Server failed to start"; kill $SERVER_PID; exit 1; }
  sleep 1
done

# ❌ WRONG: Waiting indefinitely
npm start &
# [waiting forever...]
```

### Testing/Verification
```bash
# ✅ CORRECT: Quick verification
curl -s localhost:3000/api/health | grep "healthy"
echo "✅ Server verified"

# ❌ WRONG: Leaving it running for "later"
npm start &
echo "Server is running for testing"
# [moves to next phase with server still running]
```

### Cleanup
```bash
# ✅ CORRECT: Always cleanup
kill $SERVER_PID
wait $SERVER_PID 2>/dev/null
echo "Server stopped"

# ❌ WRONG: Forgetting to cleanup
# [server left running as orphan process]
```

## Complete Pattern Template

```bash
#!/bin/bash
# Claude's Server Testing Pattern

echo "Starting server for verification..."

# 1. Start with PID tracking
npm start &
SERVER_PID=$!

# 2. Set cleanup trap
trap "kill $SERVER_PID 2>/dev/null" EXIT

# 3. Wait with timeout
READY=false
for i in {1..10}; do
  if curl -s localhost:3000/api/health 2>/dev/null; then
    READY=true
    break
  fi
  sleep 1
done

# 4. Check readiness
if [ "$READY" = false ]; then
  echo "❌ Server failed to start"
  exit 1
fi

echo "✅ Server is ready"

# 5. Run verification
curl -s localhost:3000/api/health
# Run any other quick tests

# 6. Cleanup
kill $SERVER_PID
trap - EXIT

echo "✅ Server verification complete"
echo "Continuing with workflow..."
```

## Decision Tree

```
Need to test server?
├─ YES
│  ├─ Start server (capture PID)
│  ├─ Wait for ready (max 10 seconds)
│  ├─ Is it ready?
│  │  ├─ YES → Run tests → Stop server → Continue
│  │  └─ NO → Stop attempt → Report error → Handle failure
│  └─ Server stopped
└─ NO → Continue without starting server
```

## Common Scenarios

### Scenario 1: Implementation Verification
```bash
# Purpose: Verify the code works
# Duration: < 30 seconds
# Action: Start, test health, stop
```

### Scenario 2: Integration Testing
```bash
# Purpose: Run tests against live server
# Duration: Length of test suite
# Action: Start, run tests, stop
```

### Scenario 3: Demonstration
```bash
# Purpose: Show working application
# Duration: Brief demo
# Action: Start, show features, stop
```

## Red Flags to Avoid

🚫 **Never Do This:**
- Start server without capturing PID
- Wait without timeout
- Move to next phase with server running
- Assume server will stop itself
- Leave servers running "for later"

## Green Flags to Follow

✅ **Always Do This:**
- Capture PID immediately
- Set maximum wait time
- Verify server is ready
- Stop server after use
- Confirm cleanup completed

## Mental Model Reminder

**Servers are like ovens:**
- You turn them on for a purpose
- You use them for that purpose
- You turn them off when done
- You don't leave them running

**NOT like tasks:**
- Tasks complete themselves
- Servers run forever
- You must stop them

## Workflow Integration

When implementing any phase that involves a server:

1. **State the purpose**: "I'm starting the server to verify it works"
2. **Show the lifecycle**: "Starting... Testing... Stopping..."
3. **Confirm completion**: "Server tested and stopped successfully"
4. **Continue workflow**: "Moving to the next phase..."

## Emergency Recovery

If I ever get stuck on a server:

```bash
# Find and kill any running node processes
pkill -f node

# Or specific to the project
pkill -f "npm start"

# Verify cleanup
ps aux | grep node
```

## Final Reminder

**Every server I start in the workflow MUST be stopped before continuing to the next phase.**

No exceptions. This ensures:
- Clean workflow progression
- No orphaned processes
- No user intervention needed
- Predictable behavior
- Professional quality

---

This checklist ensures I handle server processes correctly every time, preventing the critical flaw from recurring.