arbiter-skill 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# 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
+                                      ↓
+                    Human reviews & answers in Telegram
+                                      ↓
+                    On completion, notification written to
+                    ~/.arbiter/queue/notify/
+                                      ↓
+                    Agent picks up answers (heartbeat or poll)
+```
+
+## JSON Fields
+
+### Push args
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Plan title |
+| `tag` | No | Project tag for filtering |
+| `context` | No | Background for the reviewer |
+| `priority` | No | `low` / `normal` / `high` / `urgent` |
+| `notify` | No | Session key to notify on completion |
+| `decisions` | Yes | Array of decision objects |
+
+### Decision object
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | Yes | Unique ID within the plan |
+| `title` | Yes | Human-readable title |
+| `context` | No | Explanation for the reviewer |
+| `options` | Yes | Array of `{key, label}` |
+| `allowCustom` | No | Allow free-text answers |
+
+## Usage with Clawdbot
+
+See [SKILL.md](./SKILL.md) for full agent integration docs.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: arbiter
+description: Push decisions to Arbiter Zebu for async human review. Use when you need human input on plans, architectural choices, or approval before proceeding.
+metadata: {"openclaw":{"requires":{"bins":["arbiter-push"]}}}
+---
+
+# 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)

package/dist/get.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * arbiter get - Retrieve answers from a completed decision plan
+ *
+ * Usage: arbiter-get <plan-id> [--tag <tag>]
+ *
+ * Returns JSON with:
+ * - planId: Plan ID
+ * - status: completed (or error if not complete)
+ * - completedAt: ISO timestamp
+ * - answers: Map of decision ID -> answer
+ */
+export {};

package/dist/get.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * arbiter get - Retrieve answers from a completed decision plan
+ *
+ * Usage: arbiter-get <plan-id> [--tag <tag>]
+ *
+ * Returns JSON with:
+ * - planId: Plan ID
+ * - status: completed (or error if not complete)
+ * - completedAt: ISO timestamp
+ * - answers: Map of decision ID -> answer
+ */
+import { findPlanFile, parsePlanFile, parseDecisions } from './utils.js';
+/**
+ * Get answers from a completed decision plan
+ */
+function get(planId, tag) {
+    if (!planId && !tag) {
+        return { error: 'Either planId or tag is required' };
+    }
+    const file = findPlanFile(planId, tag);
+    if (!file) {
+        return { error: 'Plan not found' };
+    }
+    const { frontmatter, content } = parsePlanFile(file);
+    if (frontmatter.status !== 'completed') {
+        return {
+            error: `Plan not complete (status: ${frontmatter.status})`,
+            planId: frontmatter.id,
+            status: frontmatter.status,
+            completedAt: '',
+            answers: {}
+        };
+    }
+    const decisions = parseDecisions(content);
+    const answers = {};
+    for (const d of decisions) {
+        if (d.answer !== null) {
+            answers[d.id] = d.answer;
+        }
+    }
+    return {
+        planId: frontmatter.id,
+        status: 'completed',
+        completedAt: frontmatter.completed_at || '',
+        answers
+    };
+}
+// CLI entry point
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(`
+arbiter get - Retrieve answers from a completed decision plan
+
+Usage: arbiter-get <plan-id>
+       arbiter-get --tag <tag>
+
+Example:
+  arbiter-get abc12345
+  arbiter-get --tag nft-marketplace
+
+Note: Returns error if plan is not yet completed.
+`);
+        process.exit(0);
+    }
+    let planId;
+    let tag;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--tag' && args[i + 1]) {
+            tag = args[i + 1];
+            i++;
+        }
+        else if (!args[i].startsWith('-')) {
+            planId = args[i];
+        }
+    }
+    const result = get(planId, tag);
+    console.log(JSON.stringify(result, null, 2));
+    if ('error' in result) {
+        process.exit(1);
+    }
+}
+main();

package/dist/push.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * arbiter push - Create a decision file in the queue
+ *
+ * Usage: arbiter-push <json-args>
+ *
+ * The JSON should contain:
+ * - title: Plan title (required)
+ * - tag: Project tag (optional)
+ * - context: Context for reviewer (optional)
+ * - priority: low|normal|high|urgent (optional, default: normal)
+ * - notify: Session to notify on completion (optional)
+ * - agent: Agent ID (optional, uses CLAWDBOT_AGENT env)
+ * - session: Session key (optional, uses CLAWDBOT_SESSION env)
+ * - decisions: Array of decisions (required)
+ *
+ * Each decision:
+ * - id: Unique ID within the plan
+ * - title: Decision title
+ * - context: Context for this decision
+ * - options: Array of { key, label, note? }
+ * - allowCustom: Allow custom text answer (optional)
+ */
+export {};

package/dist/push.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * arbiter push - Create a decision file in the queue
+ *
+ * Usage: arbiter-push <json-args>
+ *
+ * The JSON should contain:
+ * - title: Plan title (required)
+ * - tag: Project tag (optional)
+ * - context: Context for reviewer (optional)
+ * - priority: low|normal|high|urgent (optional, default: normal)
+ * - notify: Session to notify on completion (optional)
+ * - agent: Agent ID (optional, uses CLAWDBOT_AGENT env)
+ * - session: Session key (optional, uses CLAWDBOT_SESSION env)
+ * - decisions: Array of decisions (required)
+ *
+ * Each decision:
+ * - id: Unique ID within the plan
+ * - title: Decision title
+ * - context: Context for this decision
+ * - options: Array of { key, label, note? }
+ * - allowCustom: Allow custom text answer (optional)
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { nanoid } from 'nanoid';
+import { getQueueDir, ensureQueueDirs, slugify, nowISO } from './utils.js';
+/**
+ * Generate the markdown content for a decision plan
+ */
+function generateMarkdown(args) {
+    const now = nowISO();
+    const total = args.decisions.length;
+    // Build frontmatter
+    const frontmatter = `---
+id: ${args.id}
+version: 1
+agent: ${args.agent}
+session: ${args.session}
+tag: ${args.tag || 'general'}
+title: "${args.title}"
+priority: ${args.priority || 'normal'}
+status: pending
+created_at: ${now}
+updated_at: ${now}
+completed_at: null
+total: ${total}
+answered: 0
+remaining: ${total}
+${args.notify ? `notify_session: ${args.notify}` : ''}
+---`;
+    // Build context section
+    const contextSection = `
+# ${args.title}
+
+${args.context || 'Please review and answer the following decisions.'}
+`;
+    // Build decision sections
+    const decisionSections = args.decisions.map((d, i) => {
+        const optionsMarkdown = d.options
+            .map(o => `- \`${o.key}\` — ${o.label}${o.note ? ` (${o.note})` : ''}`)
+            .join('\n');
+        return `
+---
+
+## Decision ${i + 1}: ${d.title}
+
+id: ${d.id}
+status: pending
+answer: null
+answered_at: null
+${d.allowCustom ? 'allow_custom: true' : ''}
+
+**Context:** ${d.context}
+
+**Options:**
+${optionsMarkdown}
+`;
+    }).join('\n');
+    return frontmatter + contextSection + decisionSections;
+}
+/**
+ * Push a decision plan to the queue
+ */
+function push(args) {
+    // Validate required fields
+    if (!args.title) {
+        throw new Error('title is required');
+    }
+    if (!args.decisions || args.decisions.length === 0) {
+        throw new Error('decisions array is required and must not be empty');
+    }
+    // Validate each decision
+    for (const d of args.decisions) {
+        if (!d.id || !d.title || !d.options || d.options.length === 0) {
+            throw new Error(`Invalid decision: ${JSON.stringify(d)}`);
+        }
+    }
+    const id = nanoid(8);
+    const agent = args.agent || process.env.CLAWDBOT_AGENT || 'unknown';
+    const session = args.session || process.env.CLAWDBOT_SESSION || 'unknown';
+    const filename = `${agent}-${slugify(args.title)}-${id}.md`;
+    const filepath = join(getQueueDir('pending'), filename);
+    const content = generateMarkdown({
+        ...args,
+        id,
+        agent,
+        session
+    });
+    ensureQueueDirs();
+    writeFileSync(filepath, content, 'utf-8');
+    return {
+        planId: id,
+        file: filepath,
+        total: args.decisions.length,
+        status: 'pending'
+    };
+}
+// CLI entry point
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(`
+arbiter push - Create a decision file in the queue
+
+Usage: arbiter-push '<json>'
+
+Example:
+  arbiter-push '{"title":"API Decisions","decisions":[{"id":"auth","title":"Auth Method","context":"Choose auth","options":[{"key":"jwt","label":"JWT tokens"},{"key":"session","label":"Sessions"}]}]}'
+`);
+        process.exit(0);
+    }
+    try {
+        const input = JSON.parse(args.join(' '));
+        const result = push(input);
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+main();