falah-mobile/.pi/HERMES_HERDR_PROTOCOL.md

🤝 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

{
  "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

{
  "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

# 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