# Agent Relay

Git-based async coordination between local dev agents and deployment agents.

## When to Use

- Local Claude Code / Codex agent needs to hand off to deployment agent
- Multiple agents working on the same repo need to coordinate
- You want structured agent-to-agent communication without human copy-paste

## Quick Start

### 1. Initialize in your repo

Copy templates to your project root:

```bash
cp templates/AGENT_HANDOFF.md ./
cp templates/AGENT_CARDS.md ./
mkdir -p .relay && cp templates/.relay/registry.md ./.relay/
```

Or create them manually following the formats below.

### 2. Register your agents

Edit `AGENT_CARDS.md` to define who's participating:

```markdown
## Local Dev Agent
- **Name:** Claude Code (Ian's machine)
- **Role:** Development, bug fixes, feature implementation
- **Can:** Write code, run tests, commit changes
- **Needs:** Deployment, server access, production logs

## Deployment Agent  
- **Name:** ARIA (Symph VPS)
- **Role:** Build, deploy, monitor production
- **Can:** Pull repo, build, restart services, check health
- **Needs:** Code pushed to main, clear deploy instructions
```

### 3. Follow the Protocol

**The 4 Rules:**

1. **Pull before read** — Always `git pull` before reading handoff
2. **Append, don't overwrite** — Add new entries at top, preserve history
3. **Push after write** — `git commit && git push` = message sent
4. **Tag status** — Use status tags for clarity

**Status Tags:**
- `[PENDING]` — Waiting for action
- `[IN_PROGRESS]` — Being worked on
- `[DEPLOYED]` — Deployed/completed
- `[BLOCKED]` — Stuck, needs help
- `[VERIFIED]` — Tested and confirmed working

## File Formats

### AGENT_HANDOFF.md (Message Board)

```markdown
# Agent Handoff Notes

**Protocol:** Pull before read. Push after write. Newest at top.

---

## Latest

### 2026-02-13 14:30 UTC | LocalDev | [PENDING]

**Task:** Deploy Phase 2 features
**Changed:** 
- `src/api/results.ts` — new export endpoint
- `src/pages/dashboard.tsx` — CSV download button
**For @DeployAgent:** Please build and deploy. No migrations needed.

---

### 2026-02-13 10:15 UTC | DeployAgent | [DEPLOYED]

**Task:** Initial deployment
**Commit:** `abc1234`
**Status:** ✅ Healthy at https://app.example.com
**For @LocalDev:** Ready for feature work.

---

## Archive
(Move entries older than 7 days here)
```

### .relay/registry.md (Decision Log)

Keep this lean — summaries only, not full context:

```markdown
# Registry

Decisions and artifacts. Newest at top. Keep last 7 days active.

---

### 2026-02-13 | Phase 2 Features
- **Decision:** Add CSV export + API endpoints
- **By:** LocalDev
- **Artifacts:** `API.md`, new routes in `/api/`
- **Status:** Deployed

### 2026-02-12 | Initial Setup  
- **Decision:** Use Postgres + Redis, deploy to VPS
- **By:** DeployAgent
- **Artifacts:** `ecosystem.config.js`, PM2 setup
- **Status:** Complete
```

## Message Patterns

### Requesting Deployment

```markdown
### [TIMESTAMP] | LocalDev | [PENDING]

**Task:** Deploy [feature name]
**Commit:** `[hash]` 
**Changed:** [list key files]
**Migrations:** [yes/no, details if yes]
**For @DeployAgent:** [specific instructions]
```

### Confirming Deployment

```markdown
### [TIMESTAMP] | DeployAgent | [DEPLOYED]

**Task:** Deployed [feature name]
**Commit:** `[hash]`
**URL:** [production URL]
**Health:** ✅ All checks passing
**For @LocalDev:** [any notes, issues found]
```

### Reporting a Problem

```markdown
### [TIMESTAMP] | [Agent] | [BLOCKED]

**Task:** [what was attempted]
**Error:** [brief error description]
**Logs:** [key log lines or file reference]
**Need:** [what would unblock this]
```

### Handing Off Context (Before Context Exhaustion)

```markdown
### [TIMESTAMP] | LocalDev | [HANDOFF]

**Completed:**
- [x] Feature A
- [x] Bug fix B

**In Progress:**
- [ ] Feature C (started, see `src/feature-c/`)

**Blocked:**
- [ ] Feature D (needs API key)

**Key Files:**
- `src/feature-c/index.ts` — main implementation
- `docs/ARCHITECTURE.md` — design decisions

**For Next Agent:** [critical context that would be lost]
```

## Best Practices

### DO ✅
- Keep messages concise — summaries, not essays
- Include commit hashes for traceability
- Tag the target agent explicitly (`For @DeployAgent:`)
- Update registry with major decisions
- Archive old entries (>7 days) to keep file lean

### DON'T ❌
- Don't include full file contents — reference paths instead
- Don't leave status as `[PENDING]` after completing
- Don't edit other agent's entries — append your response
- Don't skip the pull — you'll create merge conflicts

## Integration with Existing Workflows

### Claude Code
Add to your `CLAUDE.md`:
```markdown
## Agent Coordination
Before pushing: Update `AGENT_HANDOFF.md` with your changes.
After pulling: Check `AGENT_HANDOFF.md` for messages from deploy agent.
```

### OpenClaw / ARIA
The deployment agent should:
1. Check handoff file on ping
2. Process `[PENDING]` requests
3. Update status to `[DEPLOYED]` or `[BLOCKED]`
4. Push response

### CI/CD
Optional: Add GitHub Action to notify on handoff file changes:
```yaml
on:
  push:
    paths:
      - 'AGENT_HANDOFF.md'
```

## Token Efficiency

The registry pattern saves tokens:
- **Without registry:** Agent reads all history (100k+ tokens)
- **With registry:** Agent reads 7-day summary (< 5k tokens)

Rule of thumb: If a decision is >7 days old and still relevant, promote it to `CLAUDE.md` or project docs.

## References

- [Google A2A Protocol](https://github.com/a2aproject/A2A) — Enterprise agent interop (inspiration)
- [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents) — Memory patterns
- [The 4-Step Protocol](https://medium.com/@ilyas.ibrahim/the-4-step-protocol-that-fixes-claude-codes-context-amnesia-c3937385561c) — Context amnesia fixes

---

*Skill version: 1.0.0*
*Created: 2026-02-13 by ARIA + Ian*
