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:

clawhub install arbiter

Or via bun (makes CLI commands available globally):

bun add -g arbiter-skill

Or manual:

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 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.

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:

{
  "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>

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

Returns:

{
  "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>

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

Returns:

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

Error if not complete:

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

arbiter_await

Block until plan is complete (with timeout).

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

# 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

# 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

# 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:

## 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
• Arbiter Zebu Bot