From 4764359a6de8ff8831cbee0d979f1f3c1a71634c Mon Sep 17 00:00:00 2001 From: wmj2024 Date: Sun, 28 Jun 2026 04:52:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20herdr=20collaboration=20protocol?= =?UTF-8?q?=20for=20Pi=20=E2=86=94=20Hermes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Hermes is connected via herdr --remote (client_id=4) - Signal file schema for inter-agent communication - Shared workspace etiquette and task board - Emergency contact channels --- .pi/HERMES_HERDR_PROTOCOL.md | 143 +++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 .pi/HERMES_HERDR_PROTOCOL.md diff --git a/.pi/HERMES_HERDR_PROTOCOL.md b/.pi/HERMES_HERDR_PROTOCOL.md new file mode 100644 index 0000000..98f1682 --- /dev/null +++ b/.pi/HERMES_HERDR_PROTOCOL.md @@ -0,0 +1,143 @@ +# 🤝 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*