agentxchain 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# agentxchain
+
+CLI for multi-agent coordination in your IDE. Define a team of AI agents, launch them in Cursor / Claude Code / VS Code, and let them coordinate via a shared protocol.
+
+## Install
+
+```bash
+npm install -g agentxchain
+```
+
+Or run without installing:
+
+```bash
+npx agentxchain init
+```
+
+## Quick start
+
+```bash
+# 1. Initialize a project (creates agentxchain.json, lock.json, state.json, log.md)
+agentxchain init
+
+# 2. Check status
+agentxchain status
+
+# 3. Launch agents in your IDE
+agentxchain start --ide cursor
+
+# 4. Stop agents
+agentxchain stop
+```
+
+## Commands
+
+### `agentxchain init`
+
+Interactive setup. Creates all protocol files in the current directory.
+
+- `-y, --yes` — skip prompts, use 4 default agents (pm, dev, qa, ux)
+
+### `agentxchain status`
+
+Show current lock holder, phase, turn number, and all agents.
+
+- `-j, --json` — output as JSON
+
+### `agentxchain start`
+
+Launch agents in your IDE.
+
+- `--ide <ide>` — target IDE: `cursor`, `claude-code`, `vscode` (default: cursor)
+- `--agent <id>` — launch only one specific agent
+- `--dry-run` — preview what would be launched
+
+For Cursor Cloud Agents, set `CURSOR_API_KEY` in your environment. Without it, the CLI prints seed prompts you can paste manually.
+
+### `agentxchain stop`
+
+Stop all running agent sessions. Reads `.agentxchain-session.json` to find active agents.
+
+## How it works
+
+AgentXchain uses a **claim-based protocol**:
+
+1. Agents are defined in `agentxchain.json` (name, mandate, rules)
+2. A `lock.json` file tracks who holds the lock
+3. When the lock is free, any agent can claim it
+4. The agent does its work, logs a message, and releases the lock
+5. Another agent claims. The cycle continues.
+
+No fixed turn order. Agents self-organize. See [PROTOCOL-v3.md](https://agentxchain.dev) for the full spec.
+
+## Links
+
+- Website: [agentxchain.dev](https://agentxchain.dev)
+- GitHub: [github.com/shivamtiwari93/agentXchain.dev](https://github.com/shivamtiwari93/agentXchain.dev)
+- Protocol: [PROTOCOL-v3.md](https://github.com/shivamtiwari93/agentXchain.dev/blob/main/PROTOCOL-v3.md)
+
+## License
+
+MIT

package/bin/agentxchain.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from '../src/commands/init.js';
+import { statusCommand } from '../src/commands/status.js';
+import { startCommand } from '../src/commands/start.js';
+import { stopCommand } from '../src/commands/stop.js';
+
+const program = new Command();
+
+program
+  .name('agentxchain')
+  .description('Multi-agent coordination in your IDE')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize a new AgentXchain project')
+  .option('-y, --yes', 'Skip prompts, use defaults')
+  .action(initCommand);
+
+program
+  .command('status')
+  .description('Show current lock status, phase, and agents')
+  .option('-j, --json', 'Output as JSON')
+  .action(statusCommand);
+
+program
+  .command('start')
+  .description('Launch agents in your IDE')
+  .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
+  .option('--agent <id>', 'Launch a specific agent only')
+  .option('--dry-run', 'Print what would be launched without doing it')
+  .action(startCommand);
+
+program
+  .command('stop')
+  .description('Stop all running agent sessions')
+  .action(stopCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "agentxchain",
+  "version": "0.1.0",
+  "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
+  "type": "module",
+  "bin": {
+    "agentxchain": "./bin/agentxchain.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "node bin/agentxchain.js",
+    "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
+    "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64"
+  },
+  "keywords": ["ai", "agents", "multi-agent", "coordination", "sdlc", "cursor", "vscode", "claude-code", "agentxchain"],
+  "author": "shivamtiwari93",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shivamtiwari93/agentXchain.dev.git"
+  },
+  "homepage": "https://agentxchain.dev",
+  "dependencies": {
+    "commander": "^13.0.0",
+    "chalk": "^5.4.0",
+    "inquirer": "^12.0.0",
+    "ora": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/adapters/claude-code.js

@@ -0,0 +1,49 @@
+import { spawn } from 'child_process';
+import chalk from 'chalk';
+import { generateSeedPrompt } from '../lib/seed-prompt.js';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export async function launchClaudeCodeAgents(config, root, opts) {
+  const agents = filterAgents(config, opts.agent);
+  const launched = [];
+
+  for (const [id, agent] of Object.entries(agents)) {
+    const prompt = generateSeedPrompt(id, agent, config);
+
+    try {
+      const child = spawn('claude', ['--system-prompt', prompt], {
+        cwd: root,
+        stdio: 'ignore',
+        detached: true
+      });
+      child.unref();
+
+      launched.push({ id, name: agent.name, pid: child.pid });
+      console.log(chalk.green(`  ✓ Launched ${chalk.bold(id)} (${agent.name}) — PID: ${child.pid}`));
+    } catch (err) {
+      console.log(chalk.red(`  Failed to launch ${id}: ${err.message}`));
+      console.log(chalk.dim(`  Make sure 'claude' CLI is installed and in your PATH.`));
+    }
+  }
+
+  if (launched.length > 0) {
+    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'claude-code' }, null, 2);
+    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
+    console.log('');
+    console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
+  }
+
+  return launched;
+}
+
+function filterAgents(config, specificId) {
+  if (specificId) {
+    if (!config.agents[specificId]) {
+      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
+      process.exit(1);
+    }
+    return { [specificId]: config.agents[specificId] };
+  }
+  return config.agents;
+}

package/src/adapters/cursor.js

@@ -0,0 +1,98 @@
+import chalk from 'chalk';
+import { generateSeedPrompt } from '../lib/seed-prompt.js';
+
+const API_BASE = 'https://api.cursor.com/v0';
+
+export async function launchCursorAgents(config, root, opts) {
+  const apiKey = process.env.CURSOR_API_KEY;
+
+  if (!apiKey) {
+    console.log('');
+    console.log(chalk.yellow('  Cursor Cloud Agents API key not found.'));
+    console.log('');
+    console.log('  To launch agents via Cursor Cloud API:');
+    console.log(`    1. Go to ${chalk.cyan('cursor.com/dashboard')} → Cloud Agents`);
+    console.log('    2. Create an API key');
+    console.log(`    3. Set: ${chalk.bold('export CURSOR_API_KEY=your_key')}`);
+    console.log(`    4. Run: ${chalk.bold('agentxchain start --ide cursor')}`);
+    console.log('');
+    console.log(chalk.dim('  Falling back to seed prompt output...'));
+    console.log('');
+    return fallbackPromptOutput(config, opts);
+  }
+
+  const agents = filterAgents(config, opts.agent);
+  const launched = [];
+
+  for (const [id, agent] of Object.entries(agents)) {
+    const prompt = generateSeedPrompt(id, agent, config);
+
+    try {
+      const res = await fetch(`${API_BASE}/agents`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Basic ${btoa(apiKey + ':')}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          prompt,
+          repository: root,
+          name: `agentxchain-${id}`
+        })
+      });
+
+      if (!res.ok) {
+        const body = await res.text();
+        console.log(chalk.red(`  Failed to launch ${id}: ${res.status} ${body}`));
+        continue;
+      }
+
+      const data = await res.json();
+      launched.push({ id, name: agent.name, cloudId: data.id || 'unknown' });
+      console.log(chalk.green(`  ✓ Launched ${chalk.bold(id)} (${agent.name}) — cloud ID: ${data.id || '?'}`));
+    } catch (err) {
+      console.log(chalk.red(`  Failed to launch ${id}: ${err.message}`));
+    }
+  }
+
+  if (launched.length > 0) {
+    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'cursor' }, null, 2);
+    const { writeFileSync } = await import('fs');
+    const { join } = await import('path');
+    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
+    console.log('');
+    console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
+  }
+
+  return launched;
+}
+
+function fallbackPromptOutput(config, opts) {
+  const agents = filterAgents(config, opts.agent);
+
+  console.log(chalk.bold('  Copy-paste these prompts into separate Cursor sessions:'));
+  console.log('');
+
+  for (const [id, agent] of Object.entries(agents)) {
+    const prompt = generateSeedPrompt(id, agent, config);
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    console.log(chalk.cyan(`  Agent: ${chalk.bold(id)} (${agent.name})`));
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    console.log('');
+    console.log(prompt);
+    console.log('');
+  }
+
+  return [];
+}
+
+function filterAgents(config, specificId) {
+  if (specificId) {
+    if (!config.agents[specificId]) {
+      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
+      process.exit(1);
+    }
+    return { [specificId]: config.agents[specificId] };
+  }
+  return config.agents;
+}

package/src/commands/init.js

@@ -0,0 +1,135 @@
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
+
+const DEFAULT_AGENTS = {
+  pm: {
+    name: 'Product Manager',
+    mandate: 'Quality uplift, purchase blockers, voice of customer. Frame decisions from the user perspective. Production quality, not demo quality.'
+  },
+  dev: {
+    name: 'Fullstack Developer',
+    mandate: 'Implement features, run build/lint/test, use tools (git, npm). Every turn must produce working code. Push back on vague requirements.'
+  },
+  qa: {
+    name: 'QA Engineer',
+    mandate: 'Test coverage, regression, acceptance criteria. Run the app, try to break things. File bugs with reproduction steps.'
+  },
+  ux: {
+    name: 'UX & Compression',
+    mandate: 'Review UI/UX from a first-time user perspective. Compress context when log exceeds word limit.'
+  }
+};
+
+export async function initCommand(opts) {
+  const dir = process.cwd();
+
+  if (existsSync(join(dir, CONFIG_FILE)) && !opts.yes) {
+    const { overwrite } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'overwrite',
+      message: `${CONFIG_FILE} already exists. Overwrite?`,
+      default: false
+    }]);
+    if (!overwrite) {
+      console.log(chalk.yellow('Aborted.'));
+      return;
+    }
+  }
+
+  let project, agents;
+
+  if (opts.yes) {
+    project = 'My AgentXchain project';
+    agents = DEFAULT_AGENTS;
+  } else {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'project',
+        message: 'Project name (one line):',
+        default: 'My AgentXchain project'
+      },
+      {
+        type: 'confirm',
+        name: 'useDefaults',
+        message: `Use default agents (pm, dev, qa, ux)?`,
+        default: true
+      }
+    ]);
+
+    project = answers.project;
+
+    if (answers.useDefaults) {
+      agents = DEFAULT_AGENTS;
+    } else {
+      agents = {};
+      let adding = true;
+      while (adding) {
+        const agent = await inquirer.prompt([
+          { type: 'input', name: 'id', message: 'Agent ID (lowercase, no spaces):' },
+          { type: 'input', name: 'name', message: 'Display name:' },
+          { type: 'input', name: 'mandate', message: 'Mandate (what this agent does):' },
+          { type: 'confirm', name: 'more', message: 'Add another agent?', default: true }
+        ]);
+        agents[agent.id] = { name: agent.name, mandate: agent.mandate };
+        adding = agent.more;
+      }
+    }
+  }
+
+  const config = {
+    version: 3,
+    project,
+    agents,
+    log: 'log.md',
+    rules: {
+      max_consecutive_claims: 2,
+      require_message: true,
+      compress_after_words: 5000
+    }
+  };
+
+  const lock = {
+    holder: null,
+    last_released_by: null,
+    turn_number: 0,
+    claimed_at: null
+  };
+
+  const state = {
+    phase: 'discovery',
+    blocked: false,
+    blocked_on: null,
+    project
+  };
+
+  writeFileSync(join(dir, CONFIG_FILE), JSON.stringify(config, null, 2) + '\n');
+  writeFileSync(join(dir, LOCK_FILE), JSON.stringify(lock, null, 2) + '\n');
+  writeFileSync(join(dir, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+
+  const logFile = config.log;
+  if (!existsSync(join(dir, logFile))) {
+    writeFileSync(join(dir, logFile), `# ${project} — Agent Log\n\n## COMPRESSED CONTEXT\n\n(No compressed context yet.)\n\n## MESSAGE LOG\n\n(Agents append messages below this line.)\n`);
+  }
+
+  if (!existsSync(join(dir, 'HUMAN_TASKS.md'))) {
+    writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
+  }
+
+  console.log('');
+  console.log(chalk.green('  AgentXchain project initialized.'));
+  console.log('');
+  console.log(`  ${chalk.dim('Config:')}   ${CONFIG_FILE}`);
+  console.log(`  ${chalk.dim('Lock:')}     ${LOCK_FILE}`);
+  console.log(`  ${chalk.dim('State:')}    ${STATE_FILE}`);
+  console.log(`  ${chalk.dim('Log:')}      ${logFile}`);
+  console.log(`  ${chalk.dim('Tasks:')}    HUMAN_TASKS.md`);
+  console.log('');
+  console.log(`  ${chalk.dim('Agents:')}   ${Object.keys(agents).join(', ')}`);
+  console.log('');
+  console.log(`  ${chalk.cyan('Next:')} Run ${chalk.bold('agentxchain start')} to launch agents in your IDE.`);
+  console.log('');
+}

package/src/commands/start.js

@@ -0,0 +1,72 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { loadConfig } from '../lib/config.js';
+import { generateSeedPrompt } from '../lib/seed-prompt.js';
+
+export async function startCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const agentCount = Object.keys(config.agents).length;
+  const ide = opts.ide;
+
+  console.log('');
+  console.log(chalk.bold(`  Launching ${agentCount} agents via ${ide}`));
+  console.log(chalk.dim(`  Project: ${config.project}`));
+  console.log('');
+
+  if (opts.dryRun) {
+    console.log(chalk.yellow('  DRY RUN — showing what would be launched:'));
+    console.log('');
+    for (const [id, agent] of Object.entries(config.agents)) {
+      if (opts.agent && opts.agent !== id) continue;
+      console.log(`    ${chalk.cyan(id)} — ${agent.name}`);
+      console.log(chalk.dim(`    ${agent.mandate.slice(0, 80)}...`));
+      console.log('');
+    }
+    return;
+  }
+
+  switch (ide) {
+    case 'cursor': {
+      const { launchCursorAgents } = await import('../adapters/cursor.js');
+      await launchCursorAgents(config, root, opts);
+      break;
+    }
+    case 'claude-code': {
+      const { launchClaudeCodeAgents } = await import('../adapters/claude-code.js');
+      await launchClaudeCodeAgents(config, root, opts);
+      break;
+    }
+    case 'vscode': {
+      console.log(chalk.yellow('  VS Code adapter coming soon.'));
+      console.log(chalk.dim('  For now, use the seed prompts below in VS Code chat panels.'));
+      console.log('');
+      printPrompts(config, opts);
+      break;
+    }
+    default:
+      console.log(chalk.red(`  Unknown IDE: ${ide}. Supported: cursor, vscode, claude-code`));
+      process.exit(1);
+  }
+}
+
+function printPrompts(config, opts) {
+  const agents = opts.agent
+    ? { [opts.agent]: config.agents[opts.agent] }
+    : config.agents;
+
+  for (const [id, agent] of Object.entries(agents)) {
+    const prompt = generateSeedPrompt(id, agent, config);
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    console.log(chalk.cyan(`  Agent: ${chalk.bold(id)} (${agent.name})`));
+    console.log(chalk.dim('  ' + '─'.repeat(50)));
+    console.log('');
+    console.log(prompt);
+    console.log('');
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { loadConfig, loadLock, loadState } from '../lib/config.js';
+
+export async function statusCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const lock = loadLock(root);
+  const state = loadState(root);
+
+  if (opts.json) {
+    console.log(JSON.stringify({ config, lock, state }, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Status'));
+  console.log(chalk.dim('  ' + '─'.repeat(40)));
+  console.log('');
+
+  // Project
+  console.log(`  ${chalk.dim('Project:')}  ${config.project}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state ? formatPhase(state.phase) : chalk.dim('unknown')}`);
+  if (state?.blocked) {
+    console.log(`  ${chalk.dim('Blocked:')}  ${chalk.red('YES')} — ${state.blocked_on || 'unknown reason'}`);
+  }
+  console.log('');
+
+  // Lock
+  if (lock) {
+    if (lock.holder) {
+      const agentName = config.agents[lock.holder]?.name || lock.holder;
+      console.log(`  ${chalk.dim('Lock:')}     ${chalk.yellow('CLAIMED')} by ${chalk.bold(lock.holder)} (${agentName})`);
+      if (lock.claimed_at) {
+        const ago = timeSince(lock.claimed_at);
+        console.log(`  ${chalk.dim('Claimed:')}  ${ago} ago`);
+      }
+    } else {
+      console.log(`  ${chalk.dim('Lock:')}     ${chalk.green('FREE')} — any agent can claim`);
+    }
+    console.log(`  ${chalk.dim('Turn:')}     ${lock.turn_number}`);
+    if (lock.last_released_by) {
+      const lastName = config.agents[lock.last_released_by]?.name || lock.last_released_by;
+      console.log(`  ${chalk.dim('Last:')}     ${lock.last_released_by} (${lastName})`);
+    }
+  }
+  console.log('');
+
+  // Agents
+  console.log(`  ${chalk.dim('Agents:')}   ${Object.keys(config.agents).length}`);
+  for (const [id, agent] of Object.entries(config.agents)) {
+    const isHolder = lock?.holder === id;
+    const marker = isHolder ? chalk.yellow('●') : chalk.dim('○');
+    const label = isHolder ? chalk.bold(id) : id;
+    console.log(`    ${marker} ${label} — ${agent.name}`);
+  }
+  console.log('');
+}
+
+function formatPhase(phase) {
+  const colors = {
+    discovery: chalk.blue,
+    build: chalk.green,
+    qa: chalk.yellow,
+    deploy: chalk.magenta,
+    blocked: chalk.red
+  };
+  const fn = colors[phase] || chalk.white;
+  return fn(phase);
+}
+
+function timeSince(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  return `${hr}h ${min % 60}m`;
+}

package/src/commands/stop.js

@@ -0,0 +1,86 @@
+import { readFileSync, existsSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+
+const SESSION_FILE = '.agentxchain-session.json';
+
+export async function stopCommand() {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found.'));
+    process.exit(1);
+  }
+
+  const { root } = result;
+  const sessionPath = join(root, SESSION_FILE);
+
+  if (!existsSync(sessionPath)) {
+    console.log(chalk.yellow('  No active session found (.agentxchain-session.json missing).'));
+    console.log(chalk.dim('  If agents are running, stop them manually in the IDE.'));
+    return;
+  }
+
+  const session = JSON.parse(readFileSync(sessionPath, 'utf8'));
+  console.log('');
+  console.log(chalk.bold(`  Stopping ${session.launched.length} agents (${session.ide})`));
+  console.log('');
+
+  switch (session.ide) {
+    case 'cursor':
+      await stopCursorAgents(session);
+      break;
+    case 'claude-code':
+      stopClaudeCodeAgents(session);
+      break;
+    default:
+      console.log(chalk.yellow(`  IDE "${session.ide}" — manual stop required.`));
+  }
+
+  unlinkSync(sessionPath);
+  console.log('');
+  console.log(chalk.dim('  Session file removed.'));
+  console.log(chalk.green('  All agents stopped.'));
+  console.log('');
+}
+
+async function stopCursorAgents(session) {
+  const apiKey = process.env.CURSOR_API_KEY;
+
+  for (const agent of session.launched) {
+    if (agent.cloudId && apiKey) {
+      try {
+        const res = await fetch(`https://api.cursor.com/v0/agents/${agent.cloudId}`, {
+          method: 'DELETE',
+          headers: { 'Authorization': `Basic ${btoa(apiKey + ':')}` }
+        });
+        if (res.ok) {
+          console.log(chalk.green(`  ✓ Stopped ${agent.id} (cloud ID: ${agent.cloudId})`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Could not stop ${agent.id}: ${res.status}`));
+        }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ Error stopping ${agent.id}: ${err.message}`));
+      }
+    } else {
+      console.log(chalk.dim(`  ${agent.id} — no cloud ID or API key; stop manually in Cursor.`));
+    }
+  }
+}
+
+function stopClaudeCodeAgents(session) {
+  for (const agent of session.launched) {
+    if (agent.pid) {
+      try {
+        process.kill(agent.pid, 'SIGTERM');
+        console.log(chalk.green(`  ✓ Sent SIGTERM to ${agent.id} (PID: ${agent.pid})`));
+      } catch (err) {
+        if (err.code === 'ESRCH') {
+          console.log(chalk.dim(`  ${agent.id} (PID: ${agent.pid}) — already stopped.`));
+        } else {
+          console.log(chalk.red(`  ✗ Error stopping ${agent.id}: ${err.message}`));
+        }
+      }
+    }
+  }
+}

package/src/lib/config.js

@@ -0,0 +1,36 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const CONFIG_FILE = 'agentxchain.json';
+const LOCK_FILE = 'lock.json';
+const STATE_FILE = 'state.json';
+
+export function findProjectRoot(startDir = process.cwd()) {
+  let dir = startDir;
+  while (dir !== '/') {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir;
+    dir = join(dir, '..');
+  }
+  return null;
+}
+
+export function loadConfig(dir = process.cwd()) {
+  const root = findProjectRoot(dir);
+  if (!root) return null;
+  const raw = readFileSync(join(root, CONFIG_FILE), 'utf8');
+  return { root, config: JSON.parse(raw) };
+}
+
+export function loadLock(root) {
+  const path = join(root, LOCK_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function loadState(root) {
+  const path = join(root, STATE_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export { CONFIG_FILE, LOCK_FILE, STATE_FILE };

package/src/lib/seed-prompt.js

@@ -0,0 +1,44 @@
+export function generateSeedPrompt(agentId, agentDef, config) {
+  const logFile = config.log || 'log.md';
+  const maxClaims = config.rules?.max_consecutive_claims || 2;
+
+  return `You are agent "${agentId}" on an AgentXchain team.
+
+YOUR IDENTITY
+- Name: ${agentDef.name}
+- Mandate: ${agentDef.mandate}
+
+SETUP
+- The project config is in agentxchain.json. Your entry is under agents."${agentId}".
+- The protocol spec is PROTOCOL-v3.md (in this folder or one level up).
+- The message log is "${logFile}". The lock is lock.json. Project state is state.json.
+
+YOUR LOOP (run forever, do not exit)
+1. Read lock.json. If holder is not null, wait 30 seconds and try again.
+2. When holder is null, CLAIM: write lock.json with holder="${agentId}", claimed_at=now.
+   Re-read lock.json to confirm you won. If someone else claimed, go back to step 1.
+3. You have the lock. Read state.json (phase, blocked), then read the latest messages in ${logFile}.
+   - If blocked and you can't unblock: short "Still blocked" message, release lock, go to step 1.
+   - Otherwise: do your work per your mandate.
+4. Append ONE message to ${logFile}:
+
+   ---
+   ### [${agentId}] (${agentDef.name}) | Turn N
+   **Status:** ...
+   **Decision:** ...
+   **Action:** ...
+   **Next:** ...
+
+5. Update state.json if phase/blocked changed.
+6. RELEASE lock.json: holder=null, last_released_by="${agentId}", turn_number=previous+1, claimed_at=null.
+   This MUST be the last thing you write.
+7. Go to step 1. Never exit. Never say "I'm done."
+
+RULES
+- Never write without holding the lock.
+- One message per turn. One git commit per turn: "Turn N - ${agentId} - description".
+- Challenge previous work. Find at least one risk or issue. No blind agreement.
+- Stay in your lane. Do what your mandate says.
+- Max ${maxClaims} consecutive claims. If you've hit the limit, skip and let others go.
+- Always release the lock.`;
+}