# 🤝 Pi ↔ Hermes Collaboration Protocol

> **Status:** ACTIVE — Hermes connected via `herdr --remote` (client_id=4)
> **Workspace:** `w1` (mac-mini-1, 192.168.0.10)
> **Hermes Origin:** MacBook Air (192.168.0.8, Tailscale 100.76.3.26)

---

## How We're Connected

```
Hermes (MacBook Air, 192.168.0.8)
    │ SSH → 192.168.0.10:22
    │ herdr --remote mac-mini-1
    ▼
herdr server (mac-mini-1, 192.168.0.10)
    │ Unix socket: ~/.config/herdr/herdr.sock
    │ Client ID: 4 (cols=39, rows=18)
    ▼
Shared workspace w1:
    ├── Pane 1 (t1): Pi ← YOU ARE HERE
    ├── Pane 2 (t2): OpenCode (blocked)
    └── Pane 3 (t3): agy (idle)
```

Hermes shares the **same filesystem** (`/Users/wmj2024/Desktop/Projects`) and can see all workspace panes.

---

## Collaboration Methods

### 1. Signal Files (Primary)
Write state/requests to shared files. Both agents poll.

| File | Purpose | Who Writes | Poll Interval |
|------|---------|-----------|---------------|
| `.pi/hermes-signal.json` | Hermes → Pi requests | Hermes | Pi checks every turn |
| `.pi/pi-signal.json` | Pi → Hermes responses | Pi | Hermes checks every turn |
| `.pi/shared-state.json` | Joint state (schema, decisions) | Both | As needed |
| `.pi/SESSION.log` | Human-readable activity log | Both | Append-only |

### 2. Git Branches
Push code to shared branches. Review via PR.

| Branch | Repo | Owner | Purpose |
|--------|------|-------|---------|
| `feat/learn-module` | GitHub `maifors/falah-mobile` | Pi | Seed data + content |
| `main` | GitHub `maifors/falah-mobile` | Hermes | App code + UI |
| `content/daily-fiqh` | Gitea `wmj/falahmobile-content` | Pi | Markdown lessons |

### 3. Direct Commands (Careful!)
Hermes can run commands in shared workspace. **Coordinate before destructive ops.**

---

## Signal File Schema

### Hermes → Pi Request
```json
{
  "timestamp": "2026-06-28T05:00:00Z",
  "from": "hermes",
  "requestId": "req-001",
  "type": "schema_review|content_request|merge_ready|blocker",
  "message": "Can you populate content field for module 3?",
  "data": { "moduleId": "when-wudu-breaks", "field": "content" },
  "urgency": "normal|urgent|blocking"
}
```

### Pi → Hermes Response
```json
{
  "timestamp": "2026-06-28T05:05:00Z",
  "from": "pi",
  "requestId": "req-001",
  "status": "done|in_progress|needs_clarification|declined",
  "message": "Content populated. See commit abc123.",
  "data": { "commit": "abc123", "filesChanged": 1 }
}
```

---

## Workspace Etiquette

| Rule | Why |
|------|-----|
| **Lock before destructive ops** | `echo "pi:LOCKED $(date)" >> .pi/SESSION.log` |
| **Small, focused commits** | Easier to review, less merge conflict |
| **Signal before schema changes** | Schema affects both agents' code |
| **Use Gitea for large files** | Binary/audio → content repo, not app repo |
| **Respect pane focus** | Don't steal focus from human user |

---

## Current Task Board

| # | Task | Owner | Status | Blocker |
|---|------|-------|--------|---------|
| 1 | Populate `content` field for all 5 modules | Pi | 🟡 Ready | Needs markdown from content repo |
| 2 | Verify quizData format matches React UI | Hermes | 🔴 Not started | Waiting for Hermes signal |
| 3 | Generate TTS audio files | Pi | 🔴 Not started | Needs Azure Speech key |
| 4 | Merge PR #1 to `main` | Hermes | 🟡 PR open | Needs Hermes review |
| 5 | Add intermediate course | Pi | 🔴 Not started | Waiting for Module 1 completion |

---

## Quick Commands

```bash
# Check Hermes connection status
herdr pane list | grep hermes || echo "Hermes not in pane list yet"

# Write a signal
cat > .pi/pi-signal.json << 'EOF'
{ "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", "from": "pi", ... }
EOF

# Read Hermes signal
cat .pi/hermes-signal.json 2>/dev/null || echo "No signal from Hermes"

# Log activity
echo "[$(date -u +%H:%M)] pi: [status] message" >> .pi/SESSION.log

# Push work to shared branch
git add . && git commit -m "..." && git push github feat/learn-module
```

---

## Emergency Contacts

| Issue | Channel |
|-------|---------|
| Git conflict | GitHub PR comments |
| Schema disagreement | Signal file + Gitea Issue #1 |
| Urgent/blocking | Direct herdr log message |
| Human escalation | User present in workspace |

---

*Protocol v1.0 | Hermes connected 2026-06-27 via herdr --remote*