arbiter

# Arbiter Skill

Push decisions to Arbiter Zebu for async human review. Use when you need human input on plans, architectural choices, or approval before proceeding.

## Installation

**Quick install via ClawHub:**
```bash
clawhub install arbiter
```

**Or via bun (makes CLI commands available globally):**
```bash
bun add -g arbiter-skill
```

**Or manual:**
```bash
git clone https://github.com/5hanth/arbiter-skill.git
cd arbiter-skill && npm install && npm run build
ln -s $(pwd) ~/.clawdbot/skills/arbiter
```

### Prerequisites

- [Arbiter Zebu](https://github.com/5hanth/arbiter-zebu) bot running (or just `bunx arbiter-zebu`)
- `~/.arbiter/queue/` directory (created automatically by the bot)

## Environment Variables

Set these in your agent's environment for automatic agent/session detection:

| Variable | Description | Example |
|----------|-------------|---------|
| `CLAWDBOT_AGENT` | Agent ID | `ceo`, `swe1` |
| `CLAWDBOT_SESSION` | Session key | `agent:ceo:main` |

## When to Use

- Plan review before implementation
- Architectural decisions with tradeoffs
- Anything blocking that needs human judgment
- Multiple related decisions as a batch

**Do NOT use for:**
- Simple yes/no that doesn't need explanation
- Urgent real-time decisions (use direct message instead)
- Technical questions you can research yourself

## Tools

### arbiter_push

Create a decision plan for human review.

**CLI:** `arbiter-push '<json>'` — takes a single JSON argument containing all fields.

```bash
arbiter-push '{
  "title": "API Design Decisions",
  "tag": "nft-marketplace",
  "context": "SWE2 needs these decided before API work",
  "priority": "normal",
  "notify": "agent:swe2:main",
  "decisions": [
    {
      "id": "auth-strategy",
      "title": "Auth Strategy", 
      "context": "How to authenticate admin users",
      "options": [
        {"key": "jwt", "label": "JWT tokens", "note": "Stateless"},
        {"key": "session", "label": "Sessions", "note": "More control"},
        {"key": "oauth", "label": "OAuth", "note": "External provider"}
      ]
    },
    {
      "id": "database",
      "title": "Database Choice",
      "context": "Primary datastore",
      "options": [
        {"key": "postgresql", "label": "PostgreSQL + JSONB"},
        {"key": "mongodb", "label": "MongoDB"}
      ],
      "allowCustom": true
    }
  ]
}'
```

**JSON Fields:**

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Plan title |
| `tag` | No | Tag for filtering (e.g., project name) |
| `context` | No | Background for reviewer |
| `priority` | No | `low`, `normal`, `high`, `urgent` (default: normal) |
| `notify` | No | Session to notify when complete |
| `agent` | No | Agent ID (auto-detected from `CLAWDBOT_AGENT` env) |
| `session` | No | Session key (auto-detected from `CLAWDBOT_SESSION` env) |
| `decisions` | Yes | Array of decisions |

**Decision object:**

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique ID within plan |
| `title` | Yes | Decision title |
| `context` | No | Explanation for reviewer |
| `options` | Yes | Array of `{key, label, note?}` |
| `allowCustom` | No | Allow free-text answer (default: false) |
| `default` | No | Suggested option key |

**Returns:**

```json
{
  "planId": "abc123",
  "file": "~/.arbiter/queue/pending/ceo-api-design-abc123.md",
  "total": 2,
  "status": "pending"
}
```

### arbiter_status

Check the status of a decision plan.

**CLI:** `arbiter-status <plan-id>` or `arbiter-status --tag <tag>`

```bash
arbiter-status abc12345
# or
arbiter-status --tag nft-marketplace
```

**Returns:**

```json
{
  "planId": "abc123",
  "title": "API Design Decisions",
  "status": "in_progress",
  "total": 3,
  "answered": 1,
  "remaining": 2,
  "decisions": {
    "auth-strategy": {"status": "answered", "answer": "jwt"},
    "database": {"status": "pending", "answer": null},
    "caching": {"status": "pending", "answer": null}
  }
}
```

### arbiter_get

Get answers from a completed plan.

**CLI:** `arbiter-get <plan-id>` or `arbiter-get --tag <tag>`

```bash
arbiter-get abc12345
# or
arbiter-get --tag nft-marketplace
```

**Returns:**

```json
{
  "planId": "abc123",
  "status": "completed",
  "completedAt": "2026-01-30T01:45:00Z",
  "answers": {
    "auth-strategy": "jwt",
    "database": "postgresql",
    "caching": "redis"
  }
}
```

**Error if not complete:**

```json
{
  "error": "Plan not complete",
  "status": "in_progress",
  "remaining": 2
}
```

### arbiter_await

Block until plan is complete (with timeout).

```bash
arbiter-await abc12345 --timeout 3600
```

Polls every 30 seconds until complete or timeout.

**Returns:** Same as `arbiter_get` on completion.

## Usage Examples

### Example 1: Plan Review

```bash
# Push plan decisions (single JSON argument)
RESULT=$(arbiter-push '{"title":"Clean IT i18n Plan","tag":"clean-it","priority":"high","notify":"agent:swe3:main","decisions":[{"id":"library","title":"i18n Library","options":[{"key":"i18next","label":"i18next"},{"key":"formatjs","label":"FormatJS"}]},{"id":"keys","title":"Key Structure","options":[{"key":"flat","label":"Flat (login.button)"},{"key":"nested","label":"Nested ({login:{button}})"}]}]}')

PLAN_ID=$(echo $RESULT | jq -r '.planId')
echo "Pushed plan $PLAN_ID — waiting for human review"
```

### Example 2: Check and Proceed

```bash
# Check if decisions are ready
STATUS=$(arbiter-status --tag nft-marketplace)

if [ "$(echo $STATUS | jq -r '.status')" == "completed" ]; then
  ANSWERS=$(arbiter-get --tag nft-marketplace)
  AUTH=$(echo $ANSWERS | jq -r '.answers["auth-strategy"]')
  echo "Using auth strategy: $AUTH"
  # Proceed with implementation
else
  echo "Still waiting for $(echo $STATUS | jq -r '.remaining') decisions"
fi
```

### Example 3: Blocking Wait

```bash
# Wait up to 1 hour for decisions
ANSWERS=$(arbiter-await abc12345 --timeout 3600)

if [ $? -eq 0 ]; then
  # Got answers, proceed
  echo "Decisions ready: $ANSWERS"
else
  echo "Timeout waiting for decisions"
fi
```

## Best Practices

1. **Batch related decisions** — Don't push one at a time
2. **Provide context** — Human needs to understand tradeoffs
3. **Use tags** — Makes filtering easy (`--tag project-name`)
4. **Set notify** — So blocked agents get woken up
5. **Use priority sparingly** — Reserve `urgent` for true blockers

## File Locations

| Path | Purpose |
|------|---------|
| `~/.arbiter/queue/pending/` | Plans awaiting review |
| `~/.arbiter/queue/completed/` | Answered plans (archive) |
| `~/.arbiter/queue/notify/` | Agent notifications |

## Checking Notifications (Agent Heartbeat)

In your HEARTBEAT.md, add:

```markdown
## Check Arbiter Notifications

1. Check if `~/.arbiter/queue/notify/` has files for my session
2. If yes, read answers and proceed with blocked work
3. Delete notification file after processing
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Plan not showing in Arbiter | Check file is valid YAML frontmatter |
| Answers not appearing | Check `arbiter_status`, may be incomplete |
| Notification not received | Ensure `--notify` was set correctly |

## See Also

- [Arbiter Zebu Architecture](https://github.com/5hanth/arbiter-zebu/blob/main/ARCHITECTURE.md)
- [Arbiter Zebu Bot](https://github.com/5hanth/arbiter-zebu)