bullswarm 0.1.4 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md — bullswarm
+
+Instructions for AI agents working in this repository.
+
+## What bullswarm is
+
+A CLI that routes bounded tasks to whichever coding-agent CLI subscription
+has the most quota headroom, paced by live provider meters, verified by
+content. Published as `bullswarm` on npm.
+
+## Non-negotiable doctrine
+
+1. Judge delegate output by CONTENT, not exit code (see `src/lib/verify.js`).
+2. Pace by meter surplus = elapsed% (from provider resets_at) − used%.
+   Weekly/monthly windows pace; 5h windows are burst gates only (M1–M5 in
+   `src/meters/framework.js`).
+3. Connector quirks live in `connectors/*.json`, never in core logic.
+4. Quarantine always auto-releases; recursion depth is core-owned via env
+   (`BULLSWARM_DEPTH`).
+
+## Development
+
+```bash
+npm test            # 61+ tests, no network needed (meters read from cache)
+node bin/bullswarm.js doctor --json   # readiness report
+```
+
+- Zero runtime dependencies. Node >= 18. Tests must never require network:
+  prime `~/.bullswarm/meters/*.json` caches with fresh timestamps if needed.
+- Every verb must work non-interactively (no TTY). The interactive wizard is
+  a human convenience, never a requirement.
+- Version single source: package.json. Release via
+  `node bin/bullswarm.js release patch|minor|major` then `git push --tags`
+  — CI publishes through npm trusted publishing (OIDC), no tokens.
+
+## Adding a connector
+
+Copy an existing file in `connectors/`, set: bin name, configDirs for
+discovery, spawn argv template (`{taskFile}` `{cwd}` `{bullswarmDir}`
+substitutions), authSignatures (output strings meaning auth/throttle
+failure), outputExtraction strategy, meter type, costRank, lanes. Add a
+meter reader in `src/meters/` only if the provider exposes a usage API —
+declared meters are the fallback, never the goal.
+
+## Releasing
+
+1. All tests green.
+2. `node bin/bullswarm.js release patch` (creates commit + tag v*).
+3. `git push && git push --tags`.
+4. GitHub Actions publishes to npm via trusted publishing; verify with
+   `npm view bullswarm version`.

package/connectors/claude-code.json

@@ -1,17 +1,43 @@
 {
   "name": "claude-code",
   "bin": "claude",
-  "configDirs": ["~/.claude"],
+  "configDirs": [
+    "~/.claude"
+  ],
   "spawn": {
-    "cmd": ["claude", "-p", "Read the file {taskFile} and follow its instructions exactly.", "--add-dir", "{cwd}", "--no-session"],
+    "cmd": [
+      "claude",
+      "-p",
+      "Read the file {taskFile} and follow its instructions exactly.",
+      "--add-dir",
+      "{cwd}",
+      "--dangerously-skip-permissions"
+    ],
     "cwdMode": "add-dir"
   },
-  "authSignatures": ["unauthorized", "authentication failed", "credit balance"],
-  "outputExtraction": { "strategy": "stdout" },
-  "$comment-meter": "the CALLER pool — competes in analyze/build, wins only when no delegate can take the lane",
-  "meter": { "type": "reader", "window": "weekly+5h" },
+  "authSignatures": [
+    "unauthorized",
+    "authentication failed",
+    "credit balance",
+    "not logged in",
+    "please run /login"
+  ],
+  "outputExtraction": {
+    "strategy": "stdout"
+  },
+  "$comment-meter": "the CALLER pool \u2014 competes in analyze/build, wins only when no delegate can take the lane",
+  "meter": {
+    "type": "reader",
+    "window": "weekly+5h"
+  },
   "costRank": 4,
-  "lanes": ["analyze", "build", "chore"],
-  "flags": { "stealth": false },
+  "lanes": [
+    "analyze",
+    "build",
+    "chore"
+  ],
+  "flags": {
+    "stealth": false
+  },
   "timeoutSec": 900
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     "skill/",
     "mcp/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENTS.md"
   ],
   "scripts": {
     "test": "node --test \"tests/*.test.js\"",

package/skill/SKILL.md

@@ -1,53 +1,50 @@
 ---
 name: bullswarm-setup
-description: Use when the user wants to offload work to other coding-agent subscriptions, asks about bullswarm, or wants quota-aware routing across agent CLIs. Guides the user to run the bullswarm setup wizard, which discovers installed agent CLIs, shows quota state, and configures routing.
+description: Use when the user wants to offload work to other coding-agent subscriptions, asks about bullswarm, or wants quota-aware routing across agent CLIs. bullswarm is fully self-initializing — any agent can use it with no human setup.
 ---
 
-# bullswarm setup companion
+# bullswarm agent guide
 
-You are a guide, not the installer. The CLI owns the flow; you nudge.
+bullswarm routes bounded tasks to whichever coding-agent CLI subscription has
+the most quota headroom, then verifies every delegate's output by content.
+**It requires no human setup.** Every verb self-initializes on first use.
 
-## When to use
+## Quick start (zero-touch)
 
-- The user asks to route/offload work to other agent CLIs (codex, grok, opencode, etc.)
-- The user mentions quota exhaustion on one subscription while others sit idle
-- The user asks what bullswarm is or how to set it up
+```bash
+# 1. Check readiness (also self-heals a missing config):
+bullswarm doctor --json
 
-## What to do
+# 2. See pools with live quota meters:
+bullswarm pools
 
-1. Check whether bullswarm is configured:
+# 3. Offload a task:
+bullswarm run --lane <analyze|build|chore> \
+  --add-dir /abs/path/to/repo --task-file /abs/task.md --json
 
-   ```bash
-   ls ~/.bullswarm/state.json 2>/dev/null && echo configured || echo not-configured
-   ```
+# 4. After every offload round:
+bullswarm health
+```
 
-2. If **not-configured**, tell the user:
+## Reading the verdict
 
-   > bullswarm routes work across your installed coding-agent CLIs, paced by
-   > each subscription's quota window, and verifies every delegate's output
-   > by content before trusting it. Run `bullswarm` (bare) to start the
-   > setup wizard — it discovers your installed agent CLIs, shows their
-   > quota state, and lets you pick which pools to enable. No credentials
-   > are entered anywhere; it only reads what's already on your machine.
+- `ok:true` → read `outFile`; it passed content verification
+- `keepOnClaude:true` → do it in-session; no pool could take it
+- `ok:false` → `why` names the failed gate. `contentUsableDespiteExit:true`
+  means the file is complete despite a non-zero exit — read before re-running.
 
-   Then offer: "Want me to run `bullswarm setup` for you now?"
+## Rules for agents
 
-3. If **configured**, surface the current state:
+- Delegate output is INPUT you verify, never the answer you present. Final
+  synthesis, architecture decisions, and live-context work stay with you.
+- Lanes are work nature: `analyze` (root-cause, review), `build`
+  (implement, tests), `chore` (summarize, convert, smoke-check).
+- Run `bullswarm health` after every round; investigate any `gateFailures`.
+- Never edit `~/.bullswarm/state.json` directly; use the CLI.
+- No TTY needed anywhere: every verb works in scripts and CI.
 
-   ```bash
-   bullswarm pools
-   ```
+## Human customization (optional)
 
-   and remind them of the daily habit:
-
-   > After every offload round, run `bullswarm health` — it re-judges saved
-   > outputs against their verdicts and catches verify-gate failures that
-   > would otherwise be invisible.
-
-## Hard rules
-
-- NEVER edit `~/.bullswarm/` state directly; the CLI owns it.
-- NEVER bypass the wizard's approval gates by writing CLAUDE.md/AGENTS.md
-  blocks yourself — direct the user through `bullswarm setup` so the diff is
-  shown and approved.
-- Delegate output is input to verify, never the answer you present.
+Humans can rerun `bullswarm setup` interactively to pick specific pools or
+approve CLAUDE.md/AGENTS.md integration blocks. Agents should never do this
+on the user's behalf without asking — but never *require* it either.

package/src/cli.js

@@ -245,24 +245,111 @@ function cmdHealth(opts) {
 // --- setup ------------------------------------------------------------------
 
 async function cmdSetup(opts) {
-  const { runWizard } = await import('./setup.js');
+  const { runWizard, autoSetup } = await import('./setup.js');
+  // Agent-friendly: --yes (or no TTY on stdin) initializes with discovered
+  // defaults and never prompts.
+  if (opts.yes || !process.stdin.isTTY) {
+    const r = autoSetup(BULLSWARM_DIR, { reason: opts.yes ? 'flag' : 'non-tty' });
+    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r }, null, 2));
+    else {
+      console.log(`setup complete (${r.reason}): enabled ${r.enabledPools.join(', ')}`);
+      if (r.repaired.length) console.log(`repaired connector files: ${r.repaired.join(', ')}`);
+    }
+    return 0;
+  }
   return runWizard(BULLSWARM_DIR, opts);
 }
 
+// --- doctor -------------------------------------------------------------------
+// Machine-readable readiness report for agents: what works, what's missing,
+// exactly which command fixes each gap. Never prompts.
+
+async function cmdDoctor(opts) {
+  const { discoverConnectors, isConfigured, autoSetup } = await import('./setup.js');
+  const checks = [];
+  let configured = isConfigured(BULLSWARM_DIR);
+
+  checks.push({
+    id: 'config',
+    ok: configured,
+    detail: configured ? `${BULLSWARM_DIR}/state.json present` : 'no config yet',
+    fix: 'bullswarm setup --yes   # or run any verb; it self-initializes',
+  });
+
+  // Self-heal before reporting when not configured — an agent calling
+  // doctor should end up ready-to-use in the same invocation.
+  if (!configured) {
+    autoSetup(BULLSWARM_DIR, { reason: 'doctor' });
+    configured = true;
+    checks[0] = { ...checks[0], ok: true, detail: `initialized at ${BULLSWARM_DIR} (was missing)` };
+  }
+
+  const discovered = discoverConnectors();
+  const found = discovered.filter((d) => d.discovered && !d.broken);
+  checks.push({
+    id: 'connectors',
+    ok: found.length > 0,
+    detail: `${found.length} agent CLI(s) found: ${found.map((d) => d.name).join(', ') || '(none)'}`,
+    fix: found.length ? null : 'install at least one agent CLI (codex, grok, opencode…) — echo pool still works',
+  });
+
+  try {
+    const { pools } = await buildPoolsLive(BULLSWARM_DIR, Date.now(), {
+      getReadings: getAllMeterReadings,
+    });
+    const live = pools.filter((p) => p.meterSource === 'live' || p.meterSource === 'cache');
+    const enabled = pools.filter((p) => p.enabled);
+    checks.push({
+      id: 'meters',
+      ok: enabled.length > 0,
+      detail: `${live.length}/${pools.length} pools with provider meters; ${enabled.length} enabled`,
+      fix: enabled.length ? null : 'bullswarm setup --yes',
+    });
+    checks.push({
+      id: 'offload-capable',
+      ok: enabled.some((p) => p.name !== 'echo') || enabled.length > 0,
+      detail: `enabled pools: ${enabled.map((p) => p.name).join(', ') || 'none'}`,
+      fix: null,
+    });
+  } catch (err) {
+    checks.push({ id: 'meters', ok: false, detail: err.message, fix: 'check network / re-run' });
+  }
+
+  const report = {
+    version: getVersion(),
+    configured,
+    ok: checks.every((c) => c.ok),
+    checks,
+    nextActions: checks.filter((c) => !c.ok && c.fix).map((c) => c.fix),
+  };
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`bullswarm doctor (v${report.version}) — ${report.ok ? 'READY' : 'DEGRADED'}`);
+    for (const c of checks) {
+      console.log(`  ${c.ok ? '✓' : '✗'} ${c.id}: ${c.detail}`);
+      if (!c.ok && c.fix) console.log(`      fix: ${c.fix}`);
+    }
+  }
+  return report.ok ? 0 : 1;
+}
+
 // --- main ---------------------------------------------------------------------
 
 export async function main(argv) {
   const [verb, ...rest] = argv;
   const opts = parseArgs(rest);
+  const { ensureSetup } = await import('./setup.js');
+
+  // Agent-friendly guarantee: EVERY verb works on a fresh machine. If config
+  // is missing, self-initialize with discovered defaults (never prompts).
+  ensureSetup(BULLSWARM_DIR);
 
-  if (!verb || verb === 'setup') {
-    if (!existsSync(join(BULLSWARM_DIR, 'state.json')) || verb === 'setup') {
-      return cmdSetup(opts);
-    }
-  }
   switch (verb) {
     case undefined:
-      return cmdSetup(opts); // bare bullswarm with config present still guides
+      // Bare bullswarm: interactive wizard for humans on a TTY, auto-setup
+      // + status for everyone else (agents, scripts).
+      if (opts.yes || !process.stdin.isTTY) return cmdSetup({ ...opts, yes: true });
+      return cmdSetup(opts);
     case 'setup':
       return cmdSetup(opts);
     case 'run':
@@ -271,6 +358,8 @@ export async function main(argv) {
       return cmdHealth(opts);
     case 'pools':
       return cmdPools(opts);
+    case 'doctor':
+      return cmdDoctor(opts);
     case 'version':
       console.log(getVersion());
       return 0;
@@ -278,7 +367,7 @@ export async function main(argv) {
       return cmdRelease(opts);
     default:
       console.error(
-        `unknown verb "${verb}". try: setup | run | health | pools | version | release`,
+        `unknown verb "${verb}". try: setup | run | health | pools | doctor | version | release`,
       );
       return 2;
   }

package/src/setup.js

@@ -185,6 +185,63 @@ export function repairConnectors(bullswarmDir) {
   return repaired;
 }
 
+// --- auto-setup ---------------------------------------------------------------
+// Zero-touch initialization: enable every discovered pool, write config,
+// never prompt. Used by `setup --yes`, by any verb on first use, and by
+// non-TTY invocations (agents). Humans who want choices run plain
+// `bullswarm setup` on a terminal.
+
+export function autoSetup(bullswarmDir, { reason = 'auto' } = {}) {
+  const state = loadState(bullswarmDir);
+  const discovered = discoverConnectors();
+  const repaired = repairConnectors(bullswarmDir);
+
+  const usable = discovered.filter((d) => !d.broken && d.discovered);
+  // Always include the deterministic echo pool so offloading works even on
+  // a machine with zero other agent CLIs installed.
+  const enabled = new Set(usable.map((d) => d.name));
+  enabled.add('echo');
+
+  state.pools ??= {};
+  for (const d of discovered.filter((x) => !x.broken)) {
+    state.pools[d.name] ??= {};
+    state.pools[d.name].enabled = enabled.has(d.name);
+  }
+
+  const chosen = discovered.filter((d) => enabled.has(d.name));
+  const table = suggestRoutingTable(chosen);
+
+  mkdirSync(join(bullswarmDir, 'connectors'), { recursive: true });
+  saveState(bullswarmDir, state);
+  writeFileSync(
+    join(bullswarmDir, 'routing.json'),
+    `${JSON.stringify(table, null, 2)}\n`,
+  );
+
+  return {
+    initialized: true,
+    reason,
+    enabledPools: [...enabled],
+    discoveredCount: usable.length,
+    repaired,
+    routingTable: table,
+  };
+}
+
+export function isConfigured(bullswarmDir) {
+  return existsSync(join(bullswarmDir, 'state.json'));
+}
+
+/**
+ * Idempotent first-use guarantee for every verb: if config is missing,
+ * initialize it silently. Returns null when already configured, else the
+ * autoSetup result (callers may surface it).
+ */
+export function ensureSetup(bullswarmDir) {
+  if (isConfigured(bullswarmDir)) return null;
+  return autoSetup(bullswarmDir, { reason: 'first-use' });
+}
+
 // --- wizard -------------------------------------------------------------------
 
 export async function runWizard(bullswarmDir, opts = {}) {