docs: add herdr collaboration protocol for Pi ↔ Hermes
- 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
This commit is contained in:
wmj2024
@@ -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*
|
||||
Reference in New Issue
Block a user