docs: add hot-reload dev script design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-04-13-hot-reload-dev-script-design.md

@@ -0,0 +1,80 @@
+# Hot-Reload Dev Script Design (dev.sh)
+
+## 1. Overview
+
+`dev.sh` is a development script that starts all backend microservices with file-watching hot-reload. When any `.go` file changes in a service's directory, only that specific service is recompiled and restarted.
+
+## 2. Architecture
+
+```
+dev.sh
+├── Load .env (same as start.sh)
+├── Start all services in dependency order (background)
+└── Run multiple concurrent file watchers (background)
+    ├── watcher(gateway)        → monitors gateway/         → restart gateway
+    ├── watcher(userService)    → monitors services/userService/    → restart userService
+    ├── watcher(assetService)   → monitors services/assetService/   → restart assetService
+    ├── watcher(socialService)  → monitors services/socialService/  → restart socialService
+    ├── watcher(galleryService) → monitors services/galleryService/ → restart galleryService
+    └── watcher(activityService) → monitors services/activityService/ → restart activityService
+```
+
+## 3. Service Startup Order
+
+Same as `start.sh`:
+1. userService (port 20000)
+2. assetService (port 20003)
+3. socialService (port 20002)
+4. galleryService (port 20004)
+5. activityService (port 20005)
+6. gateway (port 8080)
+
+## 4. Watcher Behavior
+
+For each service:
+- **Monitor**: `<service_dir>/**/*.go`
+- **Trigger**: Any `.go` file create/modify/write event
+- **Debounce**: 300ms cooldown — after a restart is triggered, ignore further events for 300ms to avoid rapid successive rebuilds.
+- **Action** (executed inside service's own module directory, matching `start.sh`):
+  1. Recompile: `cd <service_dir> && go build -o <binary> .`
+  2. **Build-failure safety**: If build fails, log the error and keep the old process running
+  3. Only after successful build: kill the running service process
+  4. Restart with same arguments as `start.sh`
+  5. Log the event to console (cyan color)
+
+## 5. Dependencies
+
+- **Mac**: `fswatch` (install via `brew install fswatch`)
+- **Linux**: `inotifywait` (install via package manager)
+
+If the required tool is not installed, the script prints a clear installation instruction and exits.
+
+## 6. Signal Handling
+
+- `Ctrl+C` / SIGINT / SIGTERM: Use a `trap` to catch signals — stop all services and watchers, then exit
+- On exit: Kill all service processes and watcher processes in reverse startup order (gateway first, then services)
+
+## 7. Logging
+
+- Each service logs to `/tmp/<service_name>.log` (same as start.sh)
+- Console output shows which file changed and which service was restarted
+- Hot-reload events are printed in distinct color (cyan)
+
+## 8. File Structure
+
+```
+backend/
+├── dev.sh          # Main dev script (new)
+└── start.sh        # Production start script (existing)
+```
+
+## 9. Edge Cases
+
+- **Build failure**: Old process keeps running; error is logged to console and `/tmp/<service>.log`
+- **Watched directory missing**: Script exits with error if monitored directory does not exist
+- **Tool not found**: Script prints installation instructions and exits
+- **Rapid file changes**: 300ms debounce prevents immediate successive rebuilds; each batch of changes triggers at most one restart
+
+## 10. No Changes to Existing Files
+
+`dev.sh` does not modify any existing files. It only reads `start.sh` for reference and adds a new file.