add brain

.brain/.agent/skills/engineering-advanced-skills/git-worktree-manager/references/docker-compose-patterns.md

@@ -0,0 +1,62 @@
+# Docker Compose Patterns For Worktrees
+
+## Pattern 1: Override File Per Worktree
+
+Base compose file remains shared; each worktree has a local override.
+
+`docker-compose.worktree.yml`:
+
+```yaml
+services:
+  app:
+    ports:
+      - "3010:3000"
+  db:
+    ports:
+      - "5442:5432"
+  redis:
+    ports:
+      - "6389:6379"
+```
+
+Run:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.worktree.yml up -d
+```
+
+## Pattern 2: `.env` Driven Ports
+
+Use compose variable substitution and write worktree-specific values into `.env.local`.
+
+`docker-compose.yml` excerpt:
+
+```yaml
+services:
+  app:
+    ports: ["${APP_PORT:-3000}:3000"]
+  db:
+    ports: ["${DB_PORT:-5432}:5432"]
+```
+
+Worktree `.env.local`:
+
+```env
+APP_PORT=3010
+DB_PORT=5442
+REDIS_PORT=6389
+```
+
+## Pattern 3: Project Name Isolation
+
+Use unique compose project name so container, network, and volume names do not collide.
+
+```bash
+docker compose -p myapp_wt_auth up -d
+```
+
+## Common Mistakes
+
+- Reusing default `5432` from multiple worktrees simultaneously
+- Sharing one database volume across incompatible migration branches
+- Forgetting to scope compose project name per worktree

.brain/.agent/skills/engineering-advanced-skills/git-worktree-manager/references/port-allocation-strategy.md

@@ -0,0 +1,46 @@
+# Port Allocation Strategy
+
+## Objective
+
+Allocate deterministic, non-overlapping local ports for each worktree to avoid collisions across concurrent development sessions.
+
+## Default Mapping
+
+- App HTTP: `3000`
+- Postgres: `5432`
+- Redis: `6379`
+- Stride per worktree: `10`
+
+Formula by slot index `n`:
+
+- `app = 3000 + (10 * n)`
+- `db = 5432 + (10 * n)`
+- `redis = 6379 + (10 * n)`
+
+Examples:
+
+- Slot 0: `3000/5432/6379`
+- Slot 1: `3010/5442/6389`
+- Slot 2: `3020/5452/6399`
+
+## Collision Avoidance
+
+1. Read `.worktree-ports.json` from existing worktrees.
+2. Skip any slot where one or more ports are already assigned.
+3. Persist selected mapping in the new worktree.
+
+## Operational Notes
+
+- Keep stride >= number of services to avoid accidental overlaps when adding ports later.
+- For custom service sets, reserve a contiguous block per worktree.
+- If you also run local infra outside worktrees, offset bases to avoid global collisions.
+
+## Recommended File Format
+
+```json
+{
+  "app": 3010,
+  "db": 5442,
+  "redis": 6389
+}
+```