Arbiter

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

Security Scan

The skill does what it claims (creates local decision files for a human-in-the-loop Arbiter bot); its code, CLI, and declared requirements are internally consistent, but it writes data to the user's home directory and hands decisions to an out‑of‑band human-review system, so you should avoid putting secrets in plans and verify the Arbiter bot/service before installing.

Purpose & Capability

Name/description match the actual behavior: the code provides arbiter-push/status/get CLIs that create/read markdown decision files in ~/.arbiter/queue for Arbiter Zebu. Required binary (arbiter-push) aligns with the skill's purpose. No unrelated credentials, binaries, or unusual paths are requested.

Instruction Scope

The SKILL.md and source instruct the agent to write decision content to ~/.arbiter/queue/pending and to read from pending/completed. This is within scope for a human-review workflow, but it means any content you push (including potentially sensitive plan text) will be persisted locally and consumed by the Arbiter Zebu bot (README states human answers arrive via Telegram). The skill itself does not call remote endpoints, but the human-review system will move data off your agent when humans interact with it.

Install Mechanism

Registry metadata lists no install spec, but the package includes package.json, bin entries, and SKILL.md offers installation via ClawHub, bun (global), or manual git clone. That mismatch is not malicious but is worth noticing: there is no registry-level install script, so installing requires following SKILL.md instructions or using an external package manager (npm/bun). The repo referenced (github.com/5hanth/arbiter-skill.git) should be verified before use.

Credentials

No sensitive environment variables are required. Two optional variables (CLAWDBOT_AGENT, CLAWDBOT_SESSION) are used only to label plans for agent/session detection. No unrelated keys/tokens are requested.

Persistence & Privilege

The skill does not request permanent/always-on inclusion and leaves model invocation defaults unchanged. It writes files under the user's home (~/.arbiter) which is necessary for the stated workflow but is a persistence decision you should accept knowingly.

Assessment

This skill is coherent with its description: it creates/reads markdown files in ~/.arbiter/queue and expects an Arbiter Zebu process (and humans via Telegram) to answer reviews. Before installing: (1) verify the referenced GitHub repo/author and that you trust the Arbiter Zebu service and any humans who will see plans; (2) never include secrets or credentials in decision plans because they will be written to disk and readable by the Arbiter process/humans; (3) install only via the method you trust (ClawHub or inspect the npm/bun package first); (4) if you want to prevent autonomous use, consider restricting model invocation or reviewing skill permissions in your agent configuration. The skill contains no obfuscated code or network calls in the skill itself, but data will leave your agent when humans review it via Arbiter Zebu.

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