arbiter-skill 0.1.0

package/dist/status.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * arbiter status - Check status of a decision plan
+ *
+ * Usage: arbiter-status <plan-id> [--tag <tag>]
+ *
+ * Returns JSON with:
+ * - planId: Plan ID
+ * - title: Plan title
+ * - status: pending|in_progress|completed
+ * - total: Total decisions
+ * - answered: Number answered
+ * - remaining: Number remaining
+ * - decisions: Map of decision ID -> { status, answer }
+ */
+export {};

package/dist/status.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * arbiter status - Check status of a decision plan
+ *
+ * Usage: arbiter-status <plan-id> [--tag <tag>]
+ *
+ * Returns JSON with:
+ * - planId: Plan ID
+ * - title: Plan title
+ * - status: pending|in_progress|completed
+ * - total: Total decisions
+ * - answered: Number answered
+ * - remaining: Number remaining
+ * - decisions: Map of decision ID -> { status, answer }
+ */
+import { findPlanFile, parsePlanFile, parseDecisions } from './utils.js';
+/**
+ * Get status of a decision plan
+ */
+function status(planId, tag) {
+    if (!planId && !tag) {
+        return {
+            planId: '',
+            title: '',
+            status: 'pending',
+            total: 0,
+            answered: 0,
+            remaining: 0,
+            decisions: {},
+            error: 'Either planId or tag is required'
+        };
+    }
+    const file = findPlanFile(planId, tag);
+    if (!file) {
+        return {
+            planId: planId || '',
+            title: '',
+            status: 'pending',
+            total: 0,
+            answered: 0,
+            remaining: 0,
+            decisions: {},
+            error: 'Plan not found'
+        };
+    }
+    const { frontmatter, content } = parsePlanFile(file);
+    const decisions = parseDecisions(content);
+    const decisionMap = {};
+    for (const d of decisions) {
+        decisionMap[d.id] = {
+            status: d.status,
+            answer: d.answer
+        };
+    }
+    return {
+        planId: frontmatter.id,
+        title: frontmatter.title,
+        status: frontmatter.status,
+        total: frontmatter.total,
+        answered: frontmatter.answered,
+        remaining: frontmatter.remaining,
+        decisions: decisionMap
+    };
+}
+// CLI entry point
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(`
+arbiter status - Check status of a decision plan
+
+Usage: arbiter-status <plan-id>
+       arbiter-status --tag <tag>
+
+Example:
+  arbiter-status abc12345
+  arbiter-status --tag nft-marketplace
+`);
+        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 = status(planId, tag);
+    console.log(JSON.stringify(result, null, 2));
+    if (result.error) {
+        process.exit(1);
+    }
+}
+main();

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Type definitions for Arbiter Skill
+ */
+export type Priority = 'low' | 'normal' | 'high' | 'urgent';
+export type Status = 'pending' | 'in_progress' | 'completed';
+export interface DecisionOption {
+    key: string;
+    label: string;
+    note?: string;
+}
+export interface Decision {
+    id: string;
+    title: string;
+    context: string;
+    options: DecisionOption[];
+    allowCustom?: boolean;
+}
+export interface PushArgs {
+    title: string;
+    tag?: string;
+    context?: string;
+    priority?: Priority;
+    notify?: string;
+    agent?: string;
+    session?: string;
+    decisions: Decision[];
+}
+export interface PushResult {
+    planId: string;
+    file: string;
+    total: number;
+    status: 'pending';
+}
+export interface DecisionStatus {
+    status: Status;
+    answer: string | null;
+}
+export interface StatusResult {
+    planId: string;
+    title: string;
+    status: Status;
+    total: number;
+    answered: number;
+    remaining: number;
+    decisions: Record<string, DecisionStatus>;
+    error?: string;
+}
+export interface GetResult {
+    planId: string;
+    status: 'completed';
+    completedAt: string;
+    answers: Record<string, string>;
+    error?: string;
+}
+export interface Frontmatter {
+    id: string;
+    version: number;
+    agent: string;
+    session: string;
+    tag: string;
+    title: string;
+    priority: Priority;
+    status: Status;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+    total: number;
+    answered: number;
+    remaining: number;
+    notify_session?: string;
+}
+export interface ParsedDecision {
+    id: string;
+    status: Status;
+    answer: string | null;
+    answeredAt: string | null;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Arbiter Skill
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Utility functions for Arbiter Skill
+ */
+import type { Frontmatter, ParsedDecision } from './types.js';
+/**
+ * Get the base arbiter directory
+ */
+export declare function getArbiterDir(): string;
+/**
+ * Get the queue directory
+ */
+export declare function getQueueDir(subdir: 'pending' | 'completed' | 'notify'): string;
+/**
+ * Ensure queue directories exist
+ */
+export declare function ensureQueueDirs(): void;
+/**
+ * Slugify a string for use in filenames
+ */
+export declare function slugify(text: string): string;
+/**
+ * Find a plan file by ID or tag
+ */
+export declare function findPlanFile(planId?: string, tag?: string): string | null;
+/**
+ * Parse a plan file and extract frontmatter
+ */
+export declare function parsePlanFile(filepath: string): {
+    frontmatter: Frontmatter;
+    content: string;
+};
+/**
+ * Parse decision blocks from markdown content
+ */
+export declare function parseDecisions(content: string): ParsedDecision[];
+/**
+ * Get current ISO timestamp
+ */
+export declare function nowISO(): string;

package/dist/utils.js

@@ -0,0 +1,114 @@
+/**
+ * Utility functions for Arbiter Skill
+ */
+import { readdirSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+/**
+ * Get the base arbiter directory
+ */
+export function getArbiterDir() {
+    return join(homedir(), '.arbiter');
+}
+/**
+ * Get the queue directory
+ */
+export function getQueueDir(subdir) {
+    return join(getArbiterDir(), 'queue', subdir);
+}
+/**
+ * Ensure queue directories exist
+ */
+export function ensureQueueDirs() {
+    const dirs = ['pending', 'completed', 'notify'];
+    for (const dir of dirs) {
+        const path = getQueueDir(dir);
+        if (!existsSync(path)) {
+            mkdirSync(path, { recursive: true });
+        }
+    }
+}
+/**
+ * Slugify a string for use in filenames
+ */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 30);
+}
+/**
+ * Find a plan file by ID or tag
+ */
+export function findPlanFile(planId, tag) {
+    const dirs = [getQueueDir('pending'), getQueueDir('completed')];
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        const files = readdirSync(dir).filter(f => f.endsWith('.md'));
+        for (const file of files) {
+            const filepath = join(dir, file);
+            // Quick check by filename for planId
+            if (planId && file.includes(planId)) {
+                return filepath;
+            }
+            // Need to read file for tag match
+            if (tag) {
+                try {
+                    const content = readFileSync(filepath, 'utf-8');
+                    const { data } = matter(content);
+                    if (data.tag === tag || data.id === planId) {
+                        return filepath;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse a plan file and extract frontmatter
+ */
+export function parsePlanFile(filepath) {
+    const raw = readFileSync(filepath, 'utf-8');
+    const { data, content } = matter(raw);
+    return {
+        frontmatter: data,
+        content
+    };
+}
+/**
+ * Parse decision blocks from markdown content
+ */
+export function parseDecisions(content) {
+    const decisions = [];
+    // Split by decision headers (## Decision N: ...)
+    const sections = content.split(/^---$/m);
+    for (const section of sections) {
+        // Look for decision metadata
+        const idMatch = section.match(/^id:\s*(.+)$/m);
+        const statusMatch = section.match(/^status:\s*(.+)$/m);
+        const answerMatch = section.match(/^answer:\s*(.+)$/m);
+        const answeredAtMatch = section.match(/^answered_at:\s*(.+)$/m);
+        if (idMatch) {
+            decisions.push({
+                id: idMatch[1].trim(),
+                status: (statusMatch?.[1]?.trim() || 'pending'),
+                answer: answerMatch?.[1]?.trim() === 'null' ? null : answerMatch?.[1]?.trim() || null,
+                answeredAt: answeredAtMatch?.[1]?.trim() === 'null' ? null : answeredAtMatch?.[1]?.trim() || null
+            });
+        }
+    }
+    return decisions;
+}
+/**
+ * Get current ISO timestamp
+ */
+export function nowISO() {
+    return new Date().toISOString();
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "arbiter-skill",
+  "version": "0.1.0",
+  "description": "Clawdbot skill for Arbiter Zebu - async human-in-the-loop decisions",
+  "type": "module",
+  "bin": {
+    "arbiter-push": "./dist/push.js",
+    "arbiter-status": "./dist/status.js",
+    "arbiter-get": "./dist/get.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "push": "node dist/push.js",
+    "status": "node dist/status.js",
+    "get": "node dist/get.js"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "nanoid": "^5.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "clawdbot",
+    "skill",
+    "arbiter",
+    "decisions"
+  ],
+  "author": "Zebu Agency",
+  "license": "MIT"
+}

package/scripts/get.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#
+# arbiter get - Retrieve answers from a completed decision plan
+#
+# Usage: get.sh <plan-id>
+#
+# This script will be implemented in Phase 7.
+# It will read answers from completed decision files.
+#
+
+echo "🚧 arbiter get - Not yet implemented"
+echo "This will retrieve answers from ~/.arbiter/queue/completed/"
+exit 1

package/scripts/push.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#
+# arbiter push - Create a decision file in the queue
+#
+# Usage: push.sh <tag> <title> [options]
+#
+# This script will be implemented in Phase 7.
+# It will create a properly formatted decision file in ~/.arbiter/queue/pending/
+#
+
+echo "🚧 arbiter push - Not yet implemented"
+echo "This will create decision files in ~/.arbiter/queue/pending/"
+exit 1

package/scripts/status.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#
+# arbiter status - Check status of a decision plan
+#
+# Usage: status.sh <plan-id>
+#
+# This script will be implemented in Phase 7.
+# It will check the status of a decision file (pending/completed).
+#
+
+echo "🚧 arbiter status - Not yet implemented"
+echo "This will check decision file status in ~/.arbiter/queue/"
+exit 1

package/src/get.ts

@@ -0,0 +1,99 @@
+#!/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 type { GetResult } from './types.js';
+import { findPlanFile, parsePlanFile, parseDecisions } from './utils.js';
+
+/**
+ * Get answers from a completed decision plan
+ */
+function get(planId?: string, tag?: string): GetResult | { error: string } {
+  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 as 'completed',
+      completedAt: '',
+      answers: {}
+    } as GetResult & { error: string };
+  }
+  
+  const decisions = parseDecisions(content);
+  
+  const answers: Record<string, string> = {};
+  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: string | undefined;
+  let tag: string | undefined;
+  
+  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/src/push.ts

@@ -0,0 +1,161 @@
+#!/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 type { PushArgs, PushResult, Decision } from './types.js';
+import { getQueueDir, ensureQueueDirs, slugify, nowISO } from './utils.js';
+
+/**
+ * Generate the markdown content for a decision plan
+ */
+function generateMarkdown(args: PushArgs & { id: string; agent: string; session: string }): string {
+  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: PushArgs): PushResult {
+  // 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(' ')) as PushArgs;
+    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();