wmj2024
4764359a6d
- 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
144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
# 🤝 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*
|