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"},...

# Arbiter Skill

Agent-side CLI for pushing decisions to [Arbiter Zebu](https://github.com/5hanth/arbiter-zebu). Works with Clawdbot/OpenClaw agents or standalone.

## Install

**Via ClawHub (for Clawdbot/OpenClaw):**
```bash
clawhub install arbiter
```

**Via npm/bun (standalone CLI):**
```bash
bun add -g arbiter-skill
```

## Prerequisites

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

## CLI Commands

### arbiter-push

Push a decision plan for human review:

```bash
arbiter-push '{
  "title": "API Design Decisions",
  "tag": "my-project",
  "priority": "high",
  "notify": "agent:swe1:main",
  "decisions": [
    {
      "id": "auth",
      "title": "Auth Method",
      "context": "How to authenticate users",
      "options": [
        {"key": "jwt", "label": "JWT tokens"},
        {"key": "session", "label": "Server sessions"},
        {"key": "oauth", "label": "OAuth provider"}
      ]
    },
    {
      "id": "database",
      "title": "Database Choice",
      "context": "Primary datastore",
      "options": [
        {"key": "pg", "label": "PostgreSQL"},
        {"key": "mongo", "label": "MongoDB"}
      ]
    }
  ]
}'
```

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

### arbiter-status

Check plan status:

```bash
arbiter-status '{"planId": "abc123"}'
# or by tag
arbiter-status '{"tag": "my-project"}'
```

### arbiter-get

Get answers from a completed plan:

```bash
arbiter-get '{"planId": "abc123"}'
```

Returns:
```json
{
  "planId": "abc123",
  "status": "completed",
  "answers": {
    "auth": "jwt",
    "database": "pg"
  }
}
```

## How It Works

```
arbiter-push writes markdown → ~/.arbiter/queue/pending/
                                      ↓
                    Arbiter Zebu bot detects new file
                                      ↓...