bullswarm 0.10.2 → 0.10.3

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 232 tests, no network needed (meters read from cache)
+npm test            # 235 tests, no network needed (meters read from cache)
 node bin/bullswarm.js doctor --json   # readiness report
 node bin/bullswarm.js workflow list   # discover workflows
 node bin/bullswarm.js workflow runs   # ongoing workflow instances

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # bullswarm changelog
 
+## 0.10.3 — contextual help everywhere
+
+- Added side-effect-free `-h` / `--help` handling for the top-level CLI and
+  every command and nested subcommand, including workflow drafts, run history,
+  approvals, actions, integrations, and strategy policy controls.
+- Added a centralized command help tree so contextual help is consistent and
+  intercepted before setup, provider discovery, state writes, or destructive
+  command execution.
+
 ## 0.10.2 — cross-agent skill integration
 
 - Added explicit `bullswarm integrate status|install|remove` support for Codex,

package/README.md

@@ -5,6 +5,15 @@ orchestrator, build and expand the plan, route bounded worker actions by quota,
 verify the result, and finish without an initiating agent authoring a graph.
 Every delegate output is judged by content before it counts.
 
+Every command and nested subcommand supports contextual `-h` / `--help`
+without initializing state or executing the command:
+
+```bash
+bullswarm --help
+bullswarm workflow run --help
+bullswarm workflow draft step add --help
+```
+
 ## The doctrine (non-negotiable)
 
 1. **Judge by CONTENT, not exit code.** Every delegate CLI can exit 0 while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -10,6 +10,10 @@ CLI subscription has the most quota headroom. Every delegate output is
 judged by **content**, not exit code. A non-zero exit is never a success; a
 `verified` output is.
 
+Every command and nested subcommand supports side-effect-free `-h` / `--help`.
+When a flag or argument is uncertain, inspect the exact surface before acting,
+for example `bullswarm workflow draft step add --help`.
+
 This skill is registered globally by:
 
 ```bash

package/src/cli.js

@@ -17,6 +17,7 @@ import { release } from './lib/release.js';
 import { cmdWorkflow } from './workflow/cli.js';
 import { cmdStrategy, maybeRefreshStrategy } from './strategy-cli.js';
 import { cmdIntegrate, installIntegration } from './integrate.js';
+import { helpForArgs } from './help.js';
 
 export function getBullswarmDir() {
   const h = process.env.BULLSWARM_HOME?.trim();
@@ -394,6 +395,11 @@ async function cmdDoctor(opts) {
 // --- main ---------------------------------------------------------------------
 
 export async function main(argv) {
+  const help = helpForArgs(argv);
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const [verb, ...rest] = argv;
   const opts = parseArgs(rest);
   const { ensureSetup } = await import('./setup.js');

package/src/help.js

@@ -0,0 +1,150 @@
+// Central CLI help tree. Help is resolved before setup or command dispatch so
+// `--help` is side-effect free even for commands that normally touch state.
+
+const top = `Usage: bullswarm <command> [options]
+
+Route bounded work across coding-agent subscriptions and verify the result.
+
+Commands:
+  setup        discover and configure installed coding agents
+  integrate    register Bullswarm guidance with Codex, Claude, and Grok
+  run          dispatch one bounded task
+  health       re-judge saved delegate outputs
+  pools        show routing pools, meters, and quarantine state
+  strategy     discover models and manage tier assignments
+  doctor       report installation readiness
+  workflow     create, execute, observe, and audit workflows
+  runs         alias for workflow runs
+  version      print the installed version
+  release      create a version commit and tag
+
+Run bullswarm <command> --help for command-specific help.`;
+
+const leaf = (usage, body = '') => `Usage: ${usage}${body ? `\n\n${body}` : ''}`;
+
+const HELP = {
+  _text: top,
+  setup: { _text: leaf('bullswarm setup [--yes] [--integrate] [--agents <list>] [--json]',
+    'Discover installed agent CLIs and initialize routing. Without --yes on a TTY, opens the interactive wizard.') },
+  integrate: {
+    _text: leaf('bullswarm integrate <status|install|remove|retire-legacy> [options]',
+      'Manage the canonical Bullswarm skill and recursion-safe global awareness rules.'),
+    status: { _text: leaf('bullswarm integrate status [--agents codex,claude,grok] [--json]') },
+    install: { _text: leaf('bullswarm integrate install [--agents codex,claude,grok] --yes [--json]') },
+    remove: { _text: leaf('bullswarm integrate remove [--agents codex,claude,grok] --yes [--json]') },
+    'retire-legacy': { _text: leaf('bullswarm integrate retire-legacy --yes [--json]',
+      'Recoverably archive the retired Claude offload skill.') },
+  },
+  run: { _text: leaf('bullswarm run --lane <analyze|build|chore> --add-dir <dir> (--task-file <file> | --prompt <text>) [options]',
+    'Options: --effort <high|medium|low>, --timeout <seconds>, --json. Routes one task and verifies its content.') },
+  health: { _text: leaf('bullswarm health [--json]', 'Re-judge saved outputs and report failed gates or quarantine clusters.') },
+  pools: { _text: leaf('bullswarm pools [--force] [--json]', 'Show live meter, quota-surplus, burst-gate, and quarantine state.') },
+  doctor: { _text: leaf('bullswarm doctor [--json]', 'Self-initialize if needed and report readiness without dispatching work.') },
+  version: { _text: leaf('bullswarm version') },
+  release: { _text: leaf('bullswarm release <patch|minor|major> [--dry-run]') },
+  strategy: {
+    _text: leaf('bullswarm strategy <command> [options]',
+      'Commands: refresh, apply, show, assign, clear-assignment, set-subscription, auto.'),
+    refresh: { _text: leaf('bullswarm strategy refresh [--json] [--apply --yes] [--refresh-hours <n>]') },
+    recommend: { _text: leaf('bullswarm strategy recommend [--json] [--apply --yes]', 'Alias for strategy refresh.') },
+    apply: { _text: leaf('bullswarm strategy apply --yes [--refresh-hours <n>]') },
+    show: { _text: leaf('bullswarm strategy show [--json]') },
+    assign: { _text: leaf('bullswarm strategy assign <high|medium|low> --pool <pool> --model <model>') },
+    'clear-assignment': { _text: leaf('bullswarm strategy clear-assignment <high|medium|low>') },
+    'set-subscription': { _text: leaf('bullswarm strategy set-subscription <pool> [--plan <name>] [--monthly-usd <n|unknown>] [--included-usd <n|unknown>] [--quota-window <name>]') },
+    auto: {
+      _text: leaf('bullswarm strategy auto <status|off> [--yes]'),
+      status: { _text: leaf('bullswarm strategy auto status') },
+      off: { _text: leaf('bullswarm strategy auto off --yes') },
+    },
+  },
+  workflow: {
+    _text: leaf('bullswarm workflow <command> [options]',
+      'Commands: goal, run, validate, list, draft, runs, capabilities, inspect, tui, watch, events, steer, action, approval.'),
+    goal: { _text: leaf('bullswarm workflow goal "<goal>" [--cwd <dir>] [--detach] [--json] [planning options]',
+      'Use --resume <shortId|runId> to resume. Planning options include --orchestrator, --max-agents, --max-expansion-rounds, --max-actions, --max-items-per-expansion, --max-workflow-seconds, --concurrency, and --retry-attempts.') },
+    run: { _text: leaf('bullswarm workflow run <file-or-name> [--input k=v]... [--resume <shortId|runId>] [--json] [--quiet]') },
+    validate: { _text: leaf('bullswarm workflow validate <file-or-name>') },
+    list: { _text: leaf('bullswarm workflow list [--json]') },
+    capabilities: { _text: leaf('bullswarm workflow capabilities [--json]') },
+    inspect: { _text: leaf('bullswarm workflow inspect <file-or-name>') },
+    tui: { _text: leaf('bullswarm workflow tui [<runId>] [--json] [--all] [--show <runId>] [--cancel <runId>]') },
+    watch: { _text: leaf('bullswarm workflow watch <runId> [--interval <seconds>] [--heartbeat <seconds>] [--jsonl] [--once]') },
+    events: { _text: leaf('bullswarm workflow events <runId> [--after <sequence>] [--json]') },
+    steer: { _text: leaf('bullswarm workflow steer <runId> --message <guidance> [--json]') },
+    action: {
+      _text: leaf('bullswarm workflow action <command> ...', 'Commands: show.'),
+      show: { _text: leaf('bullswarm workflow action show <runId> <actionId> [--json]') },
+    },
+    approval: {
+      _text: leaf('bullswarm workflow approval <approve|reject> <runId> [--json]'),
+      approve: { _text: leaf('bullswarm workflow approval approve <runId> [--json]') },
+      reject: { _text: leaf('bullswarm workflow approval reject <runId> [--json]') },
+    },
+    runs: runsHelp(),
+    draft: draftHelp(),
+  },
+};
+
+// Top-level `runs` is a documented alias and gets the same nested help.
+HELP.runs = HELP.workflow.runs;
+
+export const HELP_PATHS = Object.freeze(collectPaths(HELP));
+
+export function helpForArgs(argv) {
+  const wantsHelp = argv.includes('--help') || argv.includes('-h') || argv[0] === 'help';
+  if (!wantsHelp) return null;
+  const tokens = argv[0] === 'help' ? argv.slice(1) : argv;
+  let node = HELP;
+  for (const token of tokens) {
+    if (token === '--help' || token === '-h' || token.startsWith('-')) continue;
+    if (!node[token]) break;
+    node = node[token];
+  }
+  return node._text ?? HELP._text;
+}
+
+function runsHelp() {
+  return {
+    _text: leaf('bullswarm workflow runs [list] [--all|--historical] [--name <workflow>] [--since <time>] [--until <time>] [--limit <n>] [--json]',
+      'Commands: show <id>, delete <id> --yes. Time filters use the workflow initiation timestamp.'),
+    list: { _text: leaf('bullswarm workflow runs list [--all|--historical] [--name <workflow>] [--since <time>] [--until <time>] [--limit <n>] [--json]') },
+    show: { _text: leaf('bullswarm workflow runs show <shortId|runId> [--json]') },
+    delete: { _text: leaf('bullswarm workflow runs delete <shortId|runId> --yes [--force] [--json]') },
+  };
+}
+
+function draftHelp() {
+  return {
+    _text: leaf('bullswarm workflow draft <command> [options]',
+      'Commands: create, show, list, phase, step, set, validate, export, delete, run.'),
+    create: { _text: leaf('bullswarm workflow draft create <name> [--description <text>] [--input k=v]... [--required <keys>] [--json]') },
+    show: { _text: leaf('bullswarm workflow draft show <name> [--json]') },
+    list: { _text: leaf('bullswarm workflow draft list [--json]') },
+    phase: {
+      _text: leaf('bullswarm workflow draft phase <add|remove> <draft> <phase> [--json]'),
+      add: { _text: leaf('bullswarm workflow draft phase add <draft> <phase> [--json]') },
+      remove: { _text: leaf('bullswarm workflow draft phase remove <draft> <phase> [--json]') },
+    },
+    step: {
+      _text: leaf('bullswarm workflow draft step <add|remove|set> <draft> <phase> <step-id> [options]'),
+      add: { _text: leaf('bullswarm workflow draft step add <draft> <phase> <step-id> [--type <run|fanout|verify|decide>] [--lane <lane>] [--prompt <text>] [step options]') },
+      remove: { _text: leaf('bullswarm workflow draft step remove <draft> <phase> <step-id> [--json]') },
+      set: { _text: leaf('bullswarm workflow draft step set <draft> <phase> <step-id> <field> --value <text> [--json]') },
+    },
+    set: { _text: leaf('bullswarm workflow draft set <draft> <field> --value <text> [--json]') },
+    validate: { _text: leaf('bullswarm workflow draft validate <name> [--json]') },
+    export: { _text: leaf('bullswarm workflow draft export <name> <out-file> [--json]') },
+    delete: { _text: leaf('bullswarm workflow draft delete <name> --yes [--json]') },
+    run: { _text: leaf('bullswarm workflow draft run <name> [--input k=v]... [--resume <shortId|runId>] [--json] [--quiet]') },
+  };
+}
+
+function collectPaths(node, prefix = []) {
+  const paths = prefix.length ? [prefix] : [[]];
+  for (const [name, child] of Object.entries(node)) {
+    if (name === '_text') continue;
+    paths.push(...collectPaths(child, [...prefix, name]));
+  }
+  return paths;
+}