feat(skills): formalize agent coordination via beadboard-driver

We moved from ad-hoc task claims to a strictly defined 'Skill' system.

Triumphs:
- Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff).
- This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine.
- Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future.

Raw Honest Moment:
Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.

skills/beadboard-driver/tests/generate-agent-name.contract.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const execFileAsync = promisify(execFile);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'generate-agent-name.mjs');
+
+test('generate-agent-name contract: returns structured success', async () => {
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+    env: {
+      ...process.env,
+      BB_NAME_ADJECTIVES: 'green',
+      BB_NAME_NOUNS: 'castle',
+      BB_NAME_MAX_RETRIES: '1',
+    },
+  });
+  const result = JSON.parse(stdout);
+  assert.equal(result.ok, true);
+  assert.equal(result.agent_name, 'green-castle');
+  assert.equal(typeof result.attempts, 'number');
+});

skills/beadboard-driver/tests/resolve-bb.contract.test.mjs

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const execFileAsync = promisify(execFile);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'resolve-bb.mjs');
+
+test('resolve-bb contract: BB_REPO source', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-contract-resolve-'));
+  try {
+    const repo = path.join(root, 'beadboard');
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+
+    const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+      env: { ...process.env, BB_REPO: repo, BB_SKILL_HOME: path.join(root, 'home'), PATH: '' },
+    });
+    const result = JSON.parse(stdout);
+
+    assert.equal(result.ok, true);
+    assert.equal(result.source, 'env');
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});

skills/beadboard-driver/tests/run-tests.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const tests = [
+  path.join(__dirname, 'resolve-bb.contract.test.mjs'),
+  path.join(__dirname, 'generate-agent-name.contract.test.mjs'),
+  path.join(__dirname, 'session-preflight.contract.test.mjs'),
+];
+
+const child = spawn(process.execPath, ['--test', ...tests], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 1);
+});

skills/beadboard-driver/tests/session-preflight.contract.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const execFileAsync = promisify(execFile);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'session-preflight.mjs');
+
+test('session-preflight contract: surfaces BD_NOT_FOUND when missing', async () => {
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+    env: { ...process.env, PATH: '' },
+  });
+  const result = JSON.parse(stdout);
+  assert.equal(result.ok, false);
+  assert.equal(result.error_code, 'BD_NOT_FOUND');
+});
+
+test('session-preflight contract: succeeds with bd + BB_REPO', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-contract-preflight-'));
+  try {
+    const repo = path.join(root, 'beadboard');
+    const toolsDir = path.join(root, 'tools');
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.mkdir(toolsDir, { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+    await fs.writeFile(path.join(toolsDir, 'bd.cmd'), '@echo off\r\necho beads\r\n', 'utf8');
+
+    const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+      env: { ...process.env, PATH: toolsDir, BB_REPO: repo, BB_SKILL_HOME: path.join(root, 'home') },
+    });
+    const result = JSON.parse(stdout);
+    assert.equal(result.ok, true);
+    assert.equal(result.bb.ok, true);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});