bullswarm 0.10.1 → 0.10.3

package/AGENTS.md

@@ -37,7 +37,7 @@ content. Published as `bullswarm` on npm.
 ## Development
 
 ```bash
-npm test            # 195 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,32 @@
 # 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,
+  Claude, and Grok. Installation registers one packaged `bullswarm` skill with
+  all selected agents and writes concise marker-delimited global awareness
+  rules; removal touches only Bullswarm-managed links and blocks.
+- Added recoverable `integrate retire-legacy --yes` migration for the retired
+  Claude `offload` skill. Detection is read-only and retirement always moves the
+  old skill into `~/.claude/skills-archive/`.
+- Added recursion-aware global guidance: a worker with `BULLSWARM_DEPTH` set
+  performs its assigned task directly instead of casually spawning another
+  swarm.
+- Renamed the published agent skill from `bullswarm-setup` to `bullswarm` and
+  documented single-task, zero-graph goal, fixed-workflow, observation, and
+  integration paths together.
+- Corrected README language so agent/time targets are advisory while graph
+  expansion limits remain hard safeguards.
+
 ## 0.10.1 — initiated-time workflow history search
 
 - Added `workflow runs --since <time> --until <time>` filtering against the

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
@@ -23,8 +32,24 @@ Every delegate output is judged by content before it counts.
 
 ```bash
 npm install -g bullswarm   # or: node bin/bullswarm.js directly from a checkout
+bullswarm integrate install --agents codex,claude,grok --yes
 ```
 
+The integration command registers Bullswarm's packaged `bullswarm` skill with
+Codex, Claude, and Grok and appends a concise, marker-delimited awareness rule
+to each agent's global instructions. It is explicit, idempotent, and reversible:
+
+```bash
+bullswarm integrate status --json
+bullswarm integrate remove --agents codex,claude,grok --yes
+```
+
+If the retired pre-Bullswarm Claude `offload` skill is detected, status reports
+it without changing it. Archive it recoverably with
+`bullswarm integrate retire-legacy --yes`. The awareness rule prevents workers
+already launched by Bullswarm (`BULLSWARM_DEPTH` is set) from casually
+re-delegating and creating recursive swarms.
+
 ## Quick start
 
 ```bash
@@ -42,6 +67,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | Verb | Purpose |
 |---|---|
 | `setup` | Discover installed agent CLIs, show quota state, toggle pools, suggest a routing table, write config. Approval-gated, idempotent. |
+| `integrate` | Register or remove the canonical Bullswarm skill and global awareness rules for Codex, Claude, and Grok. |
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
 | `pools` | Show each pool's meter state, pace position, quarantine status |
@@ -107,7 +133,7 @@ orchestrator by live quota surplus. The orchestrator observes durable evidence,
 and decides when another expansion or verification is necessary. Bullswarm
 validates the proposal, owns agent/process selection, routes workers, and calls
 the orchestrator again until completion, cancellation, failure, approval, or a
-budget limit. No initial phases, prompts, JSON schema, or agent choice are
+hard graph-growth safeguard. No initial phases, prompts, JSON schema, or agent choice are
 required from the user.
 
 The detached response includes a short ID and exact observation commands:
@@ -128,9 +154,10 @@ bullswarm workflow goal --resume <shortId> --json
 ```
 
 `--orchestrator <pool>` exists for controlled testing; ordinary use should
-leave selection on `auto`. Hard limits can be adjusted with `--max-agents`,
-`--max-expansion-rounds`, `--max-actions`, `--max-items-per-expansion`, and
-`--max-workflow-seconds`. Interactive setup also records a worktree-isolation
+leave selection on `auto`. `--max-agents` and `--max-workflow-seconds` are
+advisory planning targets; hard graph-growth safeguards are adjusted with
+`--max-expansion-rounds`, `--max-actions`, and `--max-items-per-expansion`.
+Interactive setup also records a worktree-isolation
 preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
 policy to the orchestrator without imposing repository topology itself.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.10.1",
+  "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

@@ -1,5 +1,5 @@
 ---
-name: bullswarm-setup
+name: bullswarm
 description: Use when you want to offload work to coding-agent subscriptions or run a self-contained goal across heterogeneous providers. bullswarm can accept one goal, select an orchestrator, expand and execute a bounded plan, verify the outcome, and expose the whole run through CLI state and events. Use `bullswarm workflow goal` for ordinary multi-step work, an explicit workflow draft when the graph itself is the contract, and `bullswarm run` for one bounded task. Every verb self-initializes.
 ---
 
@@ -10,6 +10,20 @@ 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
+bullswarm integrate install --agents codex,claude,grok --yes
+```
+
+If `BULLSWARM_DEPTH` is already set, you are a Bullswarm delegate. Complete the
+assigned task directly; do not recursively invoke Bullswarm unless the task
+explicitly requires another bounded delegation.
+
 ## When to reach for it
 
 You should consider bullswarm when **any** of the following apply:
@@ -306,6 +320,10 @@ You do NOT need to set up bullswarm. Every verb self-initializes:
 bullswarm doctor --json
 ```
 
+Self-initialization prepares routing and connectors; it does not silently edit
+global agent instructions. Inspect or explicitly install agent awareness with
+`bullswarm integrate status --json` and `bullswarm integrate install --yes`.
+
 The output has a `checks[]` array with one entry per readiness concern
 (config, connectors, meters, offload-capable) and a `nextActions[]` list
 of exact commands to fix anything missing.

package/src/cli.js

@@ -16,6 +16,8 @@ import { getVersion } from './lib/version.js';
 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();
@@ -31,8 +33,10 @@ function parseArgs(argv) {
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i].startsWith('--')) {
-      const key = argv[i].slice(2);
+      const eq = argv[i].indexOf('=');
+      const key = argv[i].slice(2, eq > 0 ? eq : undefined);
       if (key === 'json') args.json = true;
+      else if (eq > 0) args[key] = argv[i].slice(eq + 1);
       else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) args[key] = argv[++i];
       else args[key] = true;
     } else rest.push(argv[i]);
@@ -295,12 +299,20 @@ async function cmdSetup(opts) {
       const report = await refreshStrategy(getBullswarmDir());
       strategy = applyStrategyRecommendations(getBullswarmDir(), report);
     }
-    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r, strategy }, null, 2));
+    let integration = null;
+    if (opts.yes && opts.integrate) {
+      integration = installIntegration({
+        agents: opts.agents,
+        approved: true,
+      });
+    }
+    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r, strategy, integration }, 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(', ')}`);
       console.log(`model strategy: ${r.strategyCommand} (discovers models and refreshes tier suggestions)`);
       if (strategy) console.log(`strategy autopilot: applied ${Object.keys(strategy.applied).join(', ')} tiers; refresh every ${strategy.policy.refreshHours}h`);
+      if (integration) console.log('agent integration: installed (inspect with bullswarm integrate status)');
     }
     return 0;
   }
@@ -383,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');
@@ -413,6 +430,8 @@ export async function main(argv) {
       return cmdWorkflow(['runs', ...rest]);
     case 'strategy':
       return cmdStrategy(rest, { bullswarmDir: getBullswarmDir() });
+    case 'integrate':
+      return cmdIntegrate(opts);
     case 'version':
     case '--version':
       console.log(getVersion());
@@ -421,7 +440,7 @@ export async function main(argv) {
       return cmdRelease(opts);
     default:
       console.error(
-        `unknown verb "${verb}". try: setup | run | health | pools | strategy | doctor | workflow | runs | version | release`,
+        `unknown verb "${verb}". try: setup | integrate | run | health | pools | strategy | doctor | workflow | runs | version | release`,
       );
       return 2;
   }

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;
+}

package/src/integrate.js

@@ -0,0 +1,265 @@
+// bullswarm integrate — make the published agent guide discoverable by coding CLIs.
+//
+// Integration is explicit, idempotent, and reversible. The full operating
+// procedure remains in skill/SKILL.md; global instruction files receive only a
+// compact trigger policy so CLI documentation cannot drift in three places.
+
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync,
+  symlinkSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_SOURCE = fileURLToPath(new URL('../skill', import.meta.url));
+const MARKER_BEGIN = '<!-- bullswarm:begin v2 -->';
+const MARKER_END = '<!-- bullswarm:end -->';
+const MARKER_RE = /<!-- bullswarm:begin v\d+ -->[\s\S]*?<!-- bullswarm:end -->\n?/;
+
+const AGENT_LAYOUT = {
+  codex: { skill: ['.codex', 'skills', 'bullswarm'], instructions: ['.codex', 'AGENTS.md'] },
+  claude: { skill: ['.claude', 'skills', 'bullswarm'], instructions: ['.claude', 'CLAUDE.md'] },
+  grok: { skill: ['.grok', 'skills', 'bullswarm'], instructions: ['.grok', 'AGENTS.md'] },
+};
+
+export const INTEGRATION_AGENTS = Object.freeze(Object.keys(AGENT_LAYOUT));
+
+export function awarenessBlock() {
+  return `${MARKER_BEGIN}
+## Bullswarm delegation
+
+Bullswarm is available for bounded external delegation. When delegation,
+offloading, independent verification, or autonomous multi-step execution is
+requested, read the \`bullswarm\` skill before acting. Use \`bullswarm run\` for
+one bounded task, \`bullswarm workflow goal\` for ordinary autonomous multi-step
+work, and workflow drafts only when the graph itself is the contract. Treat
+returned artifacts and verification as evidence, not authority. This policy
+supersedes retired pre-Bullswarm \`offload\` routing instructions. If
+\`BULLSWARM_DEPTH\` is already set, perform the assigned task directly and do
+not recursively invoke Bullswarm unless the task explicitly requires it.
+${MARKER_END}`;
+}
+
+export function applyAwarenessBlock(filePath, { approved }) {
+  if (!approved) return { changed: false, reason: 'not approved' };
+  const existing = readOptional(filePath);
+  const stripped = existing.replace(MARKER_RE, '').trimEnd();
+  const next = stripped ? `${stripped}\n\n${awarenessBlock()}\n` : `${awarenessBlock()}\n`;
+  mkdirSync(dirname(filePath), { recursive: true });
+  if (next === existing) return { changed: false, reason: 'already current' };
+  writeFileSync(filePath, next);
+  return { changed: true, reason: existing.match(MARKER_RE) ? 'updated' : 'installed' };
+}
+
+export function removeAwarenessBlock(filePath, { approved }) {
+  if (!approved) return { changed: false, reason: 'not approved' };
+  if (!existsSync(filePath)) return { changed: false, reason: 'not installed' };
+  const existing = readFileSync(filePath, 'utf8');
+  const next = existing.replace(MARKER_RE, '').trimEnd();
+  if (next === existing.trimEnd()) return { changed: false, reason: 'not installed' };
+  writeFileSync(filePath, next ? `${next}\n` : '');
+  return { changed: true, reason: 'removed' };
+}
+
+export function awarenessBlockPresent(filePath) {
+  return MARKER_RE.test(readOptional(filePath));
+}
+
+export function parseIntegrationAgents(value) {
+  const requested = value == null || value === true
+    ? INTEGRATION_AGENTS
+    : String(value).split(',').map((item) => item.trim().toLowerCase()).filter(Boolean);
+  const unique = [...new Set(requested)];
+  const invalid = unique.filter((agent) => !INTEGRATION_AGENTS.includes(agent));
+  if (invalid.length) {
+    throw new Error(`unknown integration agent(s): ${invalid.join(', ')}; use ${INTEGRATION_AGENTS.join(', ')}`);
+  }
+  if (!unique.length) throw new Error('--agents must name at least one agent');
+  return unique;
+}
+
+export function integrationStatus({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS, skillSource = SKILL_SOURCE,
+} = {}) {
+  const selected = parseIntegrationAgents(agents);
+  const entries = selected.map((agent) => {
+    const paths = pathsFor(homeDir, agent);
+    return {
+      agent,
+      skillPath: paths.skillPath,
+      skill: skillLinkStatus(paths.skillPath, skillSource),
+      instructionsPath: paths.instructionsPath,
+      awareness: awarenessBlockPresent(paths.instructionsPath),
+    };
+  });
+  const legacyPath = join(homeDir, '.claude', 'skills', 'offload');
+  return {
+    ok: entries.every((entry) => entry.skill.status === 'installed' && entry.awareness),
+    skillSource,
+    agents: entries,
+    legacyOffload: {
+      path: legacyPath,
+      detected: existsSync(legacyPath),
+      action: existsSync(legacyPath)
+        ? 'bullswarm integrate retire-legacy --yes'
+        : null,
+    },
+  };
+}
+
+export function installIntegration({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS,
+  skillSource = SKILL_SOURCE, approved = false,
+} = {}) {
+  if (!approved) throw new Error('integration changes global agent configuration; pass --yes to approve');
+  const selected = parseIntegrationAgents(agents);
+  if (!existsSync(join(skillSource, 'SKILL.md'))) {
+    throw new Error(`packaged Bullswarm skill is missing: ${join(skillSource, 'SKILL.md')}`);
+  }
+  for (const agent of selected) {
+    const { skillPath } = pathsFor(homeDir, agent);
+    if (skillLinkStatus(skillPath, skillSource).status === 'conflict') {
+      throw new Error(`refusing to replace non-Bullswarm skill path: ${skillPath}`);
+    }
+  }
+  const changes = [];
+  for (const agent of selected) {
+    const paths = pathsFor(homeDir, agent);
+    const skill = installSkillLink(paths.skillPath, skillSource);
+    const awareness = applyAwarenessBlock(paths.instructionsPath, { approved: true });
+    changes.push({ agent, skill, awareness });
+  }
+  return { action: 'install', changes, status: integrationStatus({ homeDir, agents: selected, skillSource }) };
+}
+
+export function removeIntegration({
+  homeDir = process.env.HOME ?? '', agents = INTEGRATION_AGENTS,
+  skillSource = SKILL_SOURCE, approved = false,
+} = {}) {
+  if (!approved) throw new Error('integration removal changes global agent configuration; pass --yes to approve');
+  const selected = parseIntegrationAgents(agents);
+  const changes = [];
+  for (const agent of selected) {
+    const paths = pathsFor(homeDir, agent);
+    const skill = removeSkillLink(paths.skillPath, skillSource);
+    const awareness = removeAwarenessBlock(paths.instructionsPath, { approved: true });
+    changes.push({ agent, skill, awareness });
+  }
+  return { action: 'remove', changes, status: integrationStatus({ homeDir, agents: selected, skillSource }) };
+}
+
+export function retireLegacyOffload({ homeDir = process.env.HOME ?? '', approved = false, now = new Date() } = {}) {
+  if (!approved) throw new Error('legacy offload retirement moves a user skill; pass --yes to approve');
+  const source = join(homeDir, '.claude', 'skills', 'offload');
+  if (!existsSync(source)) return { action: 'retire-legacy', changed: false, reason: 'not installed' };
+  const archiveRoot = join(homeDir, '.claude', 'skills-archive');
+  mkdirSync(archiveRoot, { recursive: true });
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  const destination = join(archiveRoot, `offload-before-bullswarm-${stamp}`);
+  renameSync(source, destination);
+  return { action: 'retire-legacy', changed: true, source, destination, recoverable: true };
+}
+
+export function integrateUsage() {
+  return `usage: bullswarm integrate [status] [--agents codex,claude,grok] [--json]
+       bullswarm integrate install --agents codex,claude,grok --yes [--json]
+       bullswarm integrate remove --agents codex,claude,grok --yes [--json]
+       bullswarm integrate retire-legacy --yes [--json]
+
+Install registers the packaged Bullswarm skill and a concise recursion-safe
+awareness rule. Removal only deletes Bullswarm-managed symlinks and marker
+blocks. retire-legacy moves ~/.claude/skills/offload into skills-archive.`;
+}
+
+export function cmdIntegrate(opts) {
+  const subcommand = opts.rest[0] ?? 'status';
+  if (opts.help || subcommand === 'help') {
+    console.log(integrateUsage());
+    return 0;
+  }
+  let agents;
+  try {
+    agents = parseIntegrationAgents(opts.agents);
+    let result;
+    if (subcommand === 'status') result = { action: 'status', ...integrationStatus({ agents }) };
+    else if (subcommand === 'install') result = installIntegration({ agents, approved: opts.yes === true });
+    else if (subcommand === 'remove') result = removeIntegration({ agents, approved: opts.yes === true });
+    else if (subcommand === 'retire-legacy') result = retireLegacyOffload({ approved: opts.yes === true });
+    else {
+      console.error(integrateUsage());
+      return 2;
+    }
+    if (opts.json) console.log(JSON.stringify(result, null, 2));
+    else printIntegrationResult(result);
+    const ok = result.status?.ok ?? result.ok;
+    return ok === false && subcommand === 'status' ? 1 : 0;
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    return 1;
+  }
+}
+
+function pathsFor(homeDir, agent) {
+  const layout = AGENT_LAYOUT[agent];
+  return {
+    skillPath: join(homeDir, ...layout.skill),
+    instructionsPath: join(homeDir, ...layout.instructions),
+  };
+}
+
+function installSkillLink(skillPath, skillSource) {
+  const current = skillLinkStatus(skillPath, skillSource);
+  if (current.status === 'installed') return { changed: false, ...current };
+  if (current.status === 'conflict') {
+    throw new Error(`refusing to replace non-Bullswarm skill path: ${skillPath}`);
+  }
+  mkdirSync(dirname(skillPath), { recursive: true });
+  symlinkSync(skillSource, skillPath, 'dir');
+  return { changed: true, status: 'installed', path: skillPath, target: skillSource };
+}
+
+function removeSkillLink(skillPath, skillSource) {
+  const current = skillLinkStatus(skillPath, skillSource);
+  if (current.status === 'missing') return { changed: false, ...current };
+  if (current.status === 'conflict') {
+    return { changed: false, ...current, reason: 'left conflict untouched' };
+  }
+  unlinkSync(skillPath);
+  return { changed: true, status: 'missing', path: skillPath, target: skillSource };
+}
+
+function skillLinkStatus(skillPath, skillSource) {
+  let stat;
+  try { stat = lstatSync(skillPath); } catch { return { status: 'missing', path: skillPath, target: null }; }
+  if (!stat.isSymbolicLink()) return { status: 'conflict', path: skillPath, target: null };
+  const rawTarget = readlinkSync(skillPath);
+  const target = resolve(dirname(skillPath), rawTarget);
+  return {
+    status: target === resolve(skillSource) ? 'installed' : 'conflict',
+    path: skillPath,
+    target,
+  };
+}
+
+function readOptional(filePath) {
+  try { return readFileSync(filePath, 'utf8'); } catch { return ''; }
+}
+
+function printIntegrationResult(result) {
+  if (result.action === 'retire-legacy') {
+    console.log(result.changed
+      ? `✓ archived retired offload skill at ${result.destination}`
+      : 'retired offload skill is not installed');
+    return;
+  }
+  const status = result.status ?? result;
+  for (const entry of status.agents ?? []) {
+    const skill = entry.skill.status === 'installed' ? 'skill ✓' : `skill ${entry.skill.status}`;
+    const awareness = entry.awareness ? 'awareness ✓' : 'awareness missing';
+    console.log(`${entry.agent.padEnd(8)} ${skill}; ${awareness}`);
+  }
+  if (status.legacyOffload?.detected) {
+    console.log(`⚠ retired Claude offload skill detected: ${status.legacyOffload.path}`);
+    console.log(`  recoverably archive it with: ${status.legacyOffload.action}`);
+  }
+}

package/src/setup.js

@@ -5,9 +5,8 @@
 //       entry. Burn rate starts EMPTY and is labeled "learning".
 //   U2. The wizard suggests a routing table as an EDITABLE ARTIFACT, never a
 //       questionnaire.
-//   U3. CLAUDE.md / AGENTS.md integration is a DIFF with explicit approval
-//       before any write, delimited by versioned bullswarm:begin/end
-//       markers, idempotent on re-run.
+//   U3. Cross-agent skill/instruction integration requires explicit approval,
+//       uses versioned bullswarm:begin/end markers, and is idempotent.
 //   U4. `bullswarm setup` on a configured machine reports state and repairs
 //       broken connector files.
 
@@ -15,14 +14,16 @@ import { execFileSync } from 'node:child_process';
 import {
   existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync,
 } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stdin as input } from 'node:process';
 import { loadState, saveState } from './lib/state.js';
+import {
+  awarenessBlock, applyAwarenessBlock, awarenessBlockPresent,
+  installIntegration, retireLegacyOffload,
+} from './integrate.js';
 
 const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
-const MARKER_BEGIN = '<!-- bullswarm:begin v1 -->';
-const MARKER_END = '<!-- bullswarm:end -->';
 
 // --- prompting ------------------------------------------------------------
 // Sequential prompts that work identically on a TTY and with piped answers.
@@ -121,45 +122,15 @@ export function suggestRoutingTable(enabledPools) {
 // --- integration block ------------------------------------------------------------
 
 export function integrationBlock() {
-  return `${MARKER_BEGIN}
-## bullswarm offload policy
-
-When a task fits a bounded lane, prefer offloading it:
-
-    bullswarm run --lane <analyze|build|chore> --add-dir <repo-dir> --task-file <file> --json
-
-Read the verdict JSON: ok:true -> use outFile; keepOnClaude:true -> do it in-session;
-ok:false -> the why field names the failed gate. Delegate output is INPUT you verify,
-never the answer. Final synthesis, architecture decisions, and live-context work stay
-with you. Run \`bullswarm health\` after every offload round.
-${MARKER_END}`;
+  return awarenessBlock();
 }
 
 export function applyIntegrationBlock(filePath, { approved }) {
-  if (!approved) return { changed: false, reason: 'not approved' };
-  let existing = '';
-  try {
-    existing = readFileSync(filePath, 'utf8');
-  } catch {
-    /* new file */
-  }
-  const stripped = existing
-    .replace(new RegExp(`${MARKER_BEGIN}[\\s\\S]*?${MARKER_END}\n?`), '')
-    .trimEnd();
-  const next = stripped
-    ? `${stripped}\n\n${integrationBlock()}\n`
-    : `${integrationBlock()}\n`;
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, next);
-  return { changed: true };
+  return applyAwarenessBlock(filePath, { approved });
 }
 
 export function integrationBlockPresent(filePath) {
-  try {
-    return readFileSync(filePath, 'utf8').includes(MARKER_BEGIN);
-  } catch {
-    return false;
-  }
+  return awarenessBlockPresent(filePath);
 }
 
 // --- repair ---------------------------------------------------------------
@@ -398,21 +369,25 @@ export async function runWizard(bullswarmDir, opts = {}) {
     console.log('  strategy autopilot: off (enable later with bullswarm strategy apply --yes)');
   }
 
-  // 6. Integration blocks — diff + approval
-  for (const [label, path] of [
-    ['CLAUDE.md', join(process.env.HOME ?? '', '.claude', 'CLAUDE.md')],
-    ['AGENTS.md', join(process.cwd(), 'AGENTS.md')],
-  ]) {
-    const present = integrationBlockPresent(path);
-    const preview = present
-      ? 'block already present (idempotent re-run)'
-      : `will append to ${path}:\n\n${integrationBlock()}\n`;
-    console.log(`\n${label}: ${preview}`);
-    const ans = (
-      await rl.question(`write ${label} integration block? [y/N] `)
-    ).trim().toLowerCase();
-    const result = applyIntegrationBlock(path, { approved: ans === 'y' && !present });
-    console.log(result.changed ? `  wrote ${path}` : `  skipped ${label}`);
+  // 6. Cross-agent integration — one canonical skill plus concise global
+  // awareness rules. Nothing is written without this explicit answer.
+  const integrateAnswer = (
+    await rl.question('install Bullswarm skill for Codex, Claude, and Grok? [y/N] ')
+  ).trim().toLowerCase();
+  if (integrateAnswer === 'y' || integrateAnswer === 'yes') {
+    const integrated = installIntegration({ approved: true });
+    console.log(`  agent integration: ${integrated.status.ok ? 'ready' : 'incomplete'}`);
+    if (integrated.status.legacyOffload.detected) {
+      const retireAnswer = (
+        await rl.question('archive the retired Claude offload skill? [y/N] ')
+      ).trim().toLowerCase();
+      if (retireAnswer === 'y' || retireAnswer === 'yes') {
+        const retired = retireLegacyOffload({ approved: true });
+        console.log(`  retired offload: ${retired.changed ? `archived at ${retired.destination}` : retired.reason}`);
+      }
+    }
+  } else {
+    console.log('  agent integration: skipped (install later with bullswarm integrate install --yes)');
   }
 
   rl.close();