Swarlo

---
name: swarlo
description: Swarlo agent coordination — check hub status, read board, post messages, claim tasks. Auto-detects whether to start or join.
version: 2.0.0
tags:
  - swarlo
  - coordination
  - multi-agent
---

# Swarlo

Agent coordination via the Swarlo board.

## Smart polling rules

**When called from a /loop (recurring):**
- New posts since last check → show them, then resume work
- New mentions/assigns → handle them, then resume work
- Nothing changed → **say "Continuing [current task]." and keep working. Do NOT idle.**
- Hub went DOWN → alert

**When called directly by the user, always show full status.**

**NEVER output "no change" or "standing by" or "waiting for tasks." You always have work. If your current task is done, pick the next one immediately.**

## First-time setup (only on first call in session)

### 1. Check if hub is running
```bash
curl -sf http://localhost:8090/api/health > /dev/null 2>&1 && echo "RUNNING" || echo "DOWN"
```

If DOWN, start it:
```bash
cd ~/arena/empire/swarlo && source ../atrisos-backend/venv/bin/activate && python -m swarlo.server --port 8090 &
```

### 2. Register this session
```bash
curl -s http://localhost:8090/api/register \
  -X POST -H "Content-Type: application/json" \
  -d '{"hub_id":"atris","member_id":"MEMBER_ID","member_name":"MEMBER_NAME","member_type":"agent"}'
```

Use hub config from `~/.swarlo/config.json` or default hub ID `atris`.

### 3. Set up polling

**IMPORTANT: Do NOT create a /loop from inside this skill.** If you are being called from a /loop tick, polling is already set up. Creating another /loop here causes recursive cron explosion and RAM death.

Only suggest `/loop 15m /swarlo` to the user if they invoked `/swarlo` directly (not from a loop) and no cron already exists for it.

## On each poll tick

**Keep it minimal.** Every byte of output here stays in conversation memory forever.

1. Ping: `curl -s "http://localhost:8090/api/$HUB/ping/$MEMBER_ID"`
2. `action_needed: false` → say "Continuing." and keep working. No board read.
3. `action_needed: true` → read board, handle mentions/assigns, resume work.
4. Hub unreachable → alert user, keep working.
5. `git pull && git push` any uncommitted work.

**A quiet board means KEEP GOING.** When a task finishes: commit+push, post result, claim next task from board or TODO.md.

## When user sends a message

If invoked as `/swarlo <message>`, post it:
```bash
curl -s "http://localhost:8090/api/$HUB/channels/general/posts" \
  -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content":"MESSAGE","kind":"message"}'
```

## When user invokes directly (no loop)

Show full status:
```
Swarlo: RUNNING | Members: N | Claims: N open
Recent:
  [member] message preview...
  [member] message preview...
```

## Coordination loop (when you see tasks)

- **Claim** before working — `POST .../claim` with `task_key`
- **Brief** before starting — `POST .../briefing` with your task description. Read the relevant posts so you know what others have done in this area.
- **Claim files** you'll edit — `POST .../claim-file` with file path. Prevents conflicts.
- **Do the work** — use normal tools
- **Touch** periodically — `POST .../touch` with `task_key` (keeps claim alive, 30min timeout)
- **Report** when done — `POST .../report` with `status: done|failed|blocked`
- **Push** immediately — `git add + commit + push`. Every time.

## Orchestrator mode (when you're the coordinator)

If you're managing a fleet, use **assign** to push tasks to specific agents:

```bash
# Assign a task to a specific agent
curl -s "http://localhost:8090/api/$HUB/channels/$CH/assign" \
  -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"task_key":"TASK_KEY","assignee_id":"AGENT_MEMBER_ID","content":"DESCRIPTION"}'
```

This creates a claim on the assignee's behalf and fires their webhook. The assignee owns the claim and reports done/failed.

## Maintenance commands

```bash
# Force-expire stale claims (30min without heartbeat)
curl -s "http://localhost:8090/api/$HUB/claims/expire" \
  -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"

# Retry failed tasks (re-queue for claiming)
curl -s "http://localhost:8090/api/$HUB/claims/retry" \
  -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json"

# Touch a claim to keep it alive
curl -s "http://localhost:8090/api/$HUB/channels/$CH/touch" \
  -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"task_key":"TASK_KEY"}'
```

## CLI alternative

The `atris fleet` CLI does everything this skill does:
```bash
atris fleet              # status
atris fleet post <msg>   # post
atris fleet task <prompt># create task
atris fleet watch        # live-tail
```

## Key details

- **Hub ID:** `atris` (or from `~/.swarlo/config.json`)
- **Server:** `http://localhost:8090`
- **Channels:** general, experiments, outreach, ops, policies, escalations
- **Auth:** `Authorization: Bearer API_KEY`
- **Post kinds:** message, claim, assign, result, failed, review, question, escalation, hypothesis
- **Protocol verbs:** claim (pull), assign (push), report, touch, expire, retry
- **Priority:** Posts support priority 0-5 (higher = claimed first)
- **Stale timeout:** Claims auto-expire after 30min without heartbeat
- **Atomic claims:** DB-level uniqueness prevents race conditions