agentxchain 0.4.3 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # agentxchain
 
-CLI for multi-agent coordination in your IDE. Define a team of AI agents, launch them in Cursor, and let them coordinate via a shared protocol.
+CLI for multi-agent coordination in your IDE. Define a team of AI agents, let them take turns building your project via shared state and lifecycle hooks.
 
 ## Install
 
@@ -14,38 +14,52 @@ Or run without installing:
 npx agentxchain init
 ```
 
-## Quick start
+## Quick start — VS Code / Cursor (recommended)
+
+No API keys or cloud connection needed. Uses native VS Code custom agents.
 
 ```bash
-agentxchain init                      # create a project (template selection)
+agentxchain init                      # create project with agents + hooks
+cd my-project/ && code .              # open in VS Code / Cursor
+# Select an agent from Chat dropdown (auto-discovered from .github/agents/)
+agentxchain release                   # release human lock to begin turns
+```
+
+The `Stop` hook acts as referee: when an agent finishes, it hands off to the next agent automatically.
+
+## Quick start — Cursor Cloud Agents
+
+```bash
+agentxchain init
 cd my-project/
-echo "CURSOR_API_KEY=your_key" >> .env # from cursor.com/settings -> Cloud Agents
-# In Cursor, connect GitHub account (needed for private repos)
-# Cursor Settings -> GitHub integration
-agentxchain start --ide cursor        # launch agents
-agentxchain watch                     # coordinate turns automatically
+echo "CURSOR_API_KEY=your_key" >> .env # cursor.com/settings -> Cloud Agents
+# Connect GitHub in Cursor Settings -> GitHub integration
+agentxchain start --ide cursor        # launch cloud agents
+agentxchain watch                     # coordinate turns
+agentxchain release                   # begin turns (initial lock is human)
 ```
 
-> `CURSOR_API_KEY` is required for Cursor commands (`start/watch/stop/claim/release` when using Cursor sessions). Your Cursor account also needs GitHub access to the target repository.
+> `CURSOR_API_KEY` is required for Cloud commands. Your Cursor account needs GitHub access to the target repository.
 
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `init` | Create project folder with agents, protocol files, and templates |
-| `start` | Launch agents in Cursor, Claude Code, or VS Code (`CURSOR_API_KEY` required for Cursor) |
-| `watch` | The referee — coordinates turns, enforces TTL, wakes agents |
+| `init` | Create project folder with agents, protocol files, hooks, and templates |
+| `generate` | Regenerate VS Code agent files (`.agent.md`, hooks) from `agentxchain.json` |
+| `start` | Launch agents in Cursor Cloud, Claude Code, or VS Code |
+| `watch` | The referee for cloud mode — coordinates turns, enforces TTL, wakes agents |
 | `status` | Show lock, phase, agents, Cursor session info |
 | `claim` | Human takes control (pauses Cursor agents) |
 | `release` | Hand lock back to agents |
-| `stop` | Terminate all running agents |
+| `stop` | Terminate all running cloud agents |
 | `branch` | Show/set Cursor branch override (`cursor.ref`) |
 | `config` | View/edit config, add/remove agents, change rules |
 | `update` | Self-update CLI from npm |
 
 ### Branch selection
 
-By default, Cursor launches use your current local git branch. You can override this when needed.
+By default, Cursor launches use your current local git branch.
 
 ```bash
 agentxchain branch                  # show current/effective branch
@@ -54,20 +68,39 @@ agentxchain branch --use-current    # pin to whatever branch you're on now
 agentxchain branch --unset          # remove pin; follow active git branch
 ```
 
-### Additional command flags
+### Additional flags
 
 ```bash
 agentxchain watch --daemon          # run watch in background
 agentxchain release --force         # force-release non-human holder lock
 ```
 
+## VS Code plugin
+
+`agentxchain init` generates native VS Code agent files:
+
+- `.github/agents/*.agent.md` — custom agents (auto-discovered by VS Code Chat)
+- `.github/hooks/agentxchain.json` — lifecycle hooks (Stop = referee, SessionStart = context injection)
+- `scripts/agentxchain-*.sh` — hook shell scripts
+
+VS Code extension (optional, for UI):
+- Status bar: lock holder, turn, phase (live-updated via file watcher)
+- Sidebar: agent dashboard with quick actions
+- Commands: Claim, Release, Status, Generate
+
+Install the extension:
+```bash
+code --install-extension cli/vscode-extension/agentxchain-0.1.0.vsix
+```
+
 ## Key features
 
+- **Native VS Code agents** — `.agent.md` files, lifecycle hooks, handoffs
 - **Claim-based coordination** — no fixed turn order; agents self-organize
+- **Stop hook referee** — deterministic turn coordination via VS Code hooks
 - **User-defined teams** — any number of agents, any roles
-- **Cursor Cloud Agents** — launch and manage agents via API
-- **Branch-safe launching** — defaults to active git branch; optional `branch` override
-- **Project `.env` loading** — CLI auto-reads `CURSOR_API_KEY` from project root `.env`
+- **Cursor Cloud Agents** — launch and manage via API (optional)
+- **Branch-safe launching** — defaults to active git branch
 - **Lock TTL** — stale locks auto-released after timeout
 - **Verify command** — agents must pass tests before releasing
 - **Human-in-the-loop** — claim/release to intervene anytime

package/bin/agentxchain.js

@@ -10,6 +10,7 @@ import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 import { claimCommand, releaseCommand } from '../src/commands/claim.js';
 import { branchCommand } from '../src/commands/branch.js';
+import { generateCommand } from '../src/commands/generate.js';
 
 const program = new Command();
 
@@ -59,6 +60,11 @@ program
   .option('--unset', 'Remove override and follow active git branch automatically')
   .action(branchCommand);
 
+program
+  .command('generate')
+  .description('Regenerate VS Code agent files (.agent.md, hooks) from agentxchain.json')
+  .action(generateCommand);
+
 program
   .command('watch')
   .description('Watch lock.json and coordinate agent turns (the referee)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/src/commands/generate.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+import { generateVSCodeFiles } from '../lib/generate-vscode.js';
+
+export async function generateCommand() {
+  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 agentIds = Object.keys(config.agents || {});
+
+  if (agentIds.length === 0) {
+    console.log(chalk.red('  No agents configured in agentxchain.json.'));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold('  Generating VS Code agent files...'));
+  console.log(chalk.dim(`  Project: ${config.project}`));
+  console.log('');
+
+  const vsResult = generateVSCodeFiles(root, config);
+
+  console.log(chalk.green(`  ✓ Generated ${vsResult.agentCount} agent files`));
+  console.log('');
+
+  for (const id of agentIds) {
+    const name = config.agents[id].name;
+    console.log(`    ${chalk.cyan(id)}.agent.md — ${name}`);
+  }
+
+  console.log('');
+  console.log(chalk.dim('  Files written:'));
+  console.log(`    .github/agents/  ${chalk.dim(`(${vsResult.agentCount} .agent.md files)`)}`);
+  console.log(`    .github/hooks/   ${chalk.dim('agentxchain.json')}`);
+  console.log(`    scripts/         ${chalk.dim('session-start, stop, pre-tool hooks')}`);
+  console.log('');
+  console.log(chalk.dim('  VS Code will auto-discover agents from .github/agents/.'));
+  console.log(chalk.dim('  Select an agent from the Chat dropdown to start a turn.'));
+  console.log('');
+}

package/src/commands/init.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
+import { generateVSCodeFiles } from '../lib/generate-vscode.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -194,7 +195,7 @@ export async function initCommand(opts) {
     }
   };
 
-  const lock = { holder: null, last_released_by: null, turn_number: 0, claimed_at: null };
+  const lock = { holder: 'human', last_released_by: null, turn_number: 0, claimed_at: new Date().toISOString() };
   const state = { phase: 'discovery', blocked: false, blocked_on: null, project };
 
   // Core protocol files
@@ -247,6 +248,9 @@ export async function initCommand(opts) {
 
   writeFileSync(join(dir, '.planning', 'qa', 'BUGS.md'), `# Bugs — ${project}\n\n## Open\n\n(QA adds bugs here with reproduction steps.)\n\n## Fixed\n\n(Bugs move here when dev confirms the fix and QA verifies it.)\n`);
 
+  // VS Code agent files (.github/agents/, .github/hooks/, scripts/)
+  const vsResult = generateVSCodeFiles(dir, config);
+
   const agentCount = Object.keys(agents).length;
   console.log('');
   console.log(chalk.green(`  ✓ Created ${chalk.bold(folderName)}/`));
@@ -255,10 +259,13 @@ export async function initCommand(opts) {
   console.log(`    ${chalk.dim('├──')} lock.json`);
   console.log(`    ${chalk.dim('├──')} state.json / state.md / history.jsonl`);
   console.log(`    ${chalk.dim('├──')} log.md / HUMAN_TASKS.md`);
-  console.log(`    ${chalk.dim('└──')} .planning/`);
-  console.log(`         ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md`);
-  console.log(`         ${chalk.dim('├──')} research/ / phases/`);
-  console.log(`         ${chalk.dim('└──')} qa/  ${chalk.dim('TEST-COVERAGE / BUGS / UX-AUDIT / ACCEPTANCE-MATRIX')}`);
+  console.log(`    ${chalk.dim('├──')} .planning/`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} research/ / phases/`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} qa/  ${chalk.dim('TEST-COVERAGE / BUGS / UX-AUDIT / ACCEPTANCE-MATRIX')}`);
+  console.log(`    ${chalk.dim('├──')} .github/agents/  ${chalk.dim(`(${agentCount} .agent.md files)`)}`);
+  console.log(`    ${chalk.dim('├──')} .github/hooks/   ${chalk.dim('agentxchain.json')}`);
+  console.log(`    ${chalk.dim('└──')} scripts/         ${chalk.dim('hook shell scripts')}`);
   console.log('');
   console.log(`  ${chalk.dim('Agents:')} ${Object.keys(agents).join(', ')}`);
   console.log('');
@@ -267,5 +274,6 @@ export async function initCommand(opts) {
   console.log(`    ${chalk.bold('edit .env')}            ${chalk.dim('# set CURSOR_API_KEY (required for Cursor mode)')}`);
   console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# launch agents in Cursor')}`);
   console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# start the referee')}`);
+  console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# begin automation (initial lock is human)')}`);
   console.log('');
 }

package/src/lib/generate-vscode.js

@@ -0,0 +1,286 @@
+import { writeFileSync, mkdirSync, existsSync, readFileSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { generateSeedPrompt } from './seed-prompt.js';
+
+export function generateVSCodeFiles(dir, config) {
+  const agentsDir = join(dir, '.github', 'agents');
+  const hooksDir = join(dir, '.github', 'hooks');
+  const scriptsDir = join(dir, 'scripts');
+
+  mkdirSync(agentsDir, { recursive: true });
+  mkdirSync(hooksDir, { recursive: true });
+  mkdirSync(scriptsDir, { recursive: true });
+
+  const agentIds = Object.keys(config.agents);
+
+  for (const id of agentIds) {
+    const agent = config.agents[id];
+    const md = buildAgentMd(id, agent, config, agentIds);
+    writeFileSync(join(agentsDir, `${id}.agent.md`), md);
+  }
+
+  writeFileSync(join(hooksDir, 'agentxchain.json'), buildHooksJson());
+  writeFileSync(join(scriptsDir, 'agentxchain-session-start.sh'), SESSION_START_SCRIPT);
+  writeFileSync(join(scriptsDir, 'agentxchain-stop.sh'), buildStopScript(config));
+  writeFileSync(join(scriptsDir, 'agentxchain-pre-tool.sh'), PRE_TOOL_SCRIPT);
+
+  try {
+    chmodSync(join(scriptsDir, 'agentxchain-session-start.sh'), 0o755);
+    chmodSync(join(scriptsDir, 'agentxchain-stop.sh'), 0o755);
+    chmodSync(join(scriptsDir, 'agentxchain-pre-tool.sh'), 0o755);
+  } catch {}
+
+  return { agentsDir, hooksDir, scriptsDir, agentCount: agentIds.length };
+}
+
+function buildAgentMd(agentId, agentDef, config, allAgentIds) {
+  const otherAgents = allAgentIds.filter(id => id !== agentId);
+  const verifyCmd = config.rules?.verify_command || null;
+  const maxClaims = config.rules?.max_consecutive_claims || 2;
+  const stateFile = config.state_file || 'state.md';
+  const historyFile = config.history_file || 'history.jsonl';
+  const logFile = config.log || 'log.md';
+  const useSplit = config.state_file || config.history_file;
+
+  const handoffs = otherAgents.map(otherId => {
+    const other = config.agents[otherId];
+    return `  - label: "Hand off to ${other.name}"
+    agent: ${otherId}
+    prompt: "Previous agent finished. Read lock.json, claim it, and do your work as ${other.name}."
+    send: true`;
+  });
+
+  handoffs.push(`  - label: "Request Human Review"
+    agent: agent
+    prompt: "An agent requests human review. Check HUMAN_TASKS.md and lock.json."
+    send: false`);
+
+  const toolsList = "['search', 'fetch', 'editFiles', 'terminalLastCommand', 'codebase', 'usages']";
+
+  const frontmatter = `---
+name: "${agentDef.name}"
+description: "${escapeYaml(agentDef.mandate.split('\n')[0].slice(0, 120))}"
+tools: ${toolsList}
+model: ['claude-sonnet-4-5-20250514', 'gpt-4.1']
+handoffs:
+${handoffs.join('\n')}
+hooks:
+  Stop:
+    - type: command
+      command: "./scripts/agentxchain-stop.sh"
+  SessionStart:
+    - type: command
+      command: "./scripts/agentxchain-session-start.sh"
+---`;
+
+  const readInstructions = useSplit
+    ? `Read these files at the start of your turn:
+- \`${stateFile}\` — living project state (primary context)
+- \`${historyFile}\` — last 3 lines for recent turns
+- \`lock.json\` — current lock holder
+- \`state.json\` — phase and blocked status`
+    : `Read these files at the start of your turn:
+- \`${logFile}\` — message log (read last few messages)
+- \`lock.json\` — current lock holder
+- \`state.json\` — phase and blocked status`;
+
+  const writeInstructions = useSplit
+    ? `When you finish your work, write in this order:
+1. Your actual work: code, files, commands, decisions.
+2. Overwrite \`${stateFile}\` with current project state.
+3. Append one line to \`${historyFile}\`:
+   \`{"turn": N, "agent": "${agentId}", "summary": "...", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}\`
+4. Update \`state.json\` if phase or blocked status changed.`
+    : `When you finish your work, write in this order:
+1. Your actual work: code, files, commands, decisions.
+2. Append one message to \`${logFile}\`:
+   \`### [${agentId}] (${agentDef.name}) | Turn N\`
+   with Status, Decision, Action, Next sections.
+3. Update \`state.json\` if phase or blocked status changed.`;
+
+  const verifyInstructions = verifyCmd
+    ? `\n## Verify before release\nBefore releasing the lock, run: \`${verifyCmd}\`\nIf it fails, fix the problem and run again. Do NOT release with a failing verification.`
+    : '';
+
+  const body = `# ${agentDef.name}
+
+You are "${agentId}" on an AgentXchain team.
+
+${agentDef.mandate}
+
+---
+
+## Project documentation
+
+Read the files relevant to your role in the \`.planning/\` folder:
+- \`.planning/PROJECT.md\` — Vision, constraints, stack (PM writes)
+- \`.planning/REQUIREMENTS.md\` — Requirements with acceptance criteria (PM writes)
+- \`.planning/ROADMAP.md\` — Phased delivery plan (PM maintains)
+- \`.planning/research/\` — Domain research
+- \`.planning/phases/\` — Per-phase plans, reviews, tests, bugs
+- \`.planning/qa/\` — TEST-COVERAGE, BUGS, UX-AUDIT, ACCEPTANCE-MATRIX, REGRESSION-LOG (QA maintains)
+
+Create or update these files when your role requires it.
+
+---
+
+## Your turn
+
+The AgentXchain system coordinates turns. When prompted, do this:
+
+1. **CLAIM**: Write \`lock.json\` with \`holder="${agentId}"\` and \`claimed_at\` = current time. Re-read to confirm.
+2. **READ**: ${readInstructions}
+3. **THINK**: What did the previous agent do? What is most important for YOUR role? What is one risk?
+4. **WORK**: ${writeInstructions}${verifyInstructions}
+5. **RELEASE**: Write \`lock.json\`: \`holder=null\`, \`last_released_by="${agentId}"\`, \`turn_number\` = previous + 1, \`claimed_at=null\`.
+   This MUST be the last thing you write.
+
+---
+
+## Rules
+
+- Never write files without holding the lock.
+- One git commit per turn: "Turn N - ${agentId} - description"
+- Max ${maxClaims} consecutive turns. If limit hit, do a short turn and release.
+- ALWAYS release the lock. A stuck lock blocks the entire team.
+- ALWAYS find at least one problem, risk, or question about the previous work. Blind agreement is forbidden.
+`;
+
+  return frontmatter + '\n\n' + body;
+}
+
+function escapeYaml(str) {
+  return str.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+
+function buildHooksJson() {
+  const hooks = {
+    hooks: {
+      SessionStart: [
+        {
+          type: 'command',
+          command: './scripts/agentxchain-session-start.sh'
+        }
+      ],
+      Stop: [
+        {
+          type: 'command',
+          command: './scripts/agentxchain-stop.sh'
+        }
+      ]
+    }
+  };
+  return JSON.stringify(hooks, null, 2) + '\n';
+}
+
+function buildStopScript(config) {
+  const verifyCmd = config.rules?.verify_command || '';
+  const verifyBlock = verifyCmd
+    ? `
+# Run verify command before allowing release
+if [ -z "$HOLDER" ] || [ "$HOLDER" = "null" ]; then
+  VERIFY_CMD="${verifyCmd}"
+  if [ -n "$VERIFY_CMD" ]; then
+    if ! eval "$VERIFY_CMD" > /dev/null 2>&1; then
+      echo '{"hookSpecificOutput":{"hookEventName":"Stop","decision":"block","reason":"Verification failed: '"$VERIFY_CMD"'. Fix the issue and release the lock."}}'
+      exit 0
+    fi
+  fi
+fi
+`
+    : '';
+
+  return `#!/bin/bash
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+if [ ! -f "lock.json" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+LOCK=$(cat lock.json 2>/dev/null)
+HOLDER=$(echo "$LOCK" | jq -r '.holder // empty')
+TURN=$(echo "$LOCK" | jq -r '.turn_number // 0')
+${verifyBlock}
+if [ -z "$HOLDER" ] || [ "$HOLDER" = "null" ]; then
+  LAST=$(echo "$LOCK" | jq -r '.last_released_by // empty')
+
+  if [ ! -f "agentxchain.json" ]; then
+    echo '{"continue":true}'
+    exit 0
+  fi
+
+  NEXT=$(node -e "
+    const cfg = JSON.parse(require('fs').readFileSync('agentxchain.json','utf8'));
+    const ids = Object.keys(cfg.agents);
+    const last = process.argv[1] || '';
+    const idx = ids.indexOf(last);
+    const next = ids[(idx + 1) % ids.length];
+    process.stdout.write(next);
+  " -- "$LAST" 2>/dev/null)
+
+  if [ -z "$NEXT" ]; then
+    echo '{"continue":true}'
+    exit 0
+  fi
+
+  NEXT_NAME=$(node -e "
+    const cfg = JSON.parse(require('fs').readFileSync('agentxchain.json','utf8'));
+    const a = cfg.agents[process.argv[1]];
+    process.stdout.write(a ? a.name : process.argv[1]);
+  " -- "$NEXT" 2>/dev/null)
+
+  echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"Stop\\",\\"decision\\":\\"block\\",\\"reason\\":\\"Turn $TURN complete. Next agent: $NEXT ($NEXT_NAME). Read lock.json, claim it, and do your work.\\"}}"
+elif [ "$HOLDER" = "human" ]; then
+  echo '{"continue":true}'
+else
+  echo '{"continue":true}'
+fi
+`;
+}
+
+const SESSION_START_SCRIPT = `#!/bin/bash
+if [ ! -f "lock.json" ] || [ ! -f "state.json" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+LOCK=$(cat lock.json 2>/dev/null)
+STATE=$(cat state.json 2>/dev/null)
+
+HOLDER=$(echo "$LOCK" | jq -r '.holder // "none"')
+TURN=$(echo "$LOCK" | jq -r '.turn_number // 0')
+LAST=$(echo "$LOCK" | jq -r '.last_released_by // "none"')
+PHASE=$(echo "$STATE" | jq -r '.phase // "unknown"')
+BLOCKED=$(echo "$STATE" | jq -r '.blocked // false')
+PROJECT=$(echo "$STATE" | jq -r '.project // "unknown"')
+
+CONTEXT="AgentXchain context: Project=$PROJECT | Phase=$PHASE | Turn=$TURN | Lock=$HOLDER | Last released by=$LAST | Blocked=$BLOCKED"
+
+echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"SessionStart\\",\\"additionalContext\\":\\"$CONTEXT\\"}}"
+`;
+
+const PRE_TOOL_SCRIPT = `#!/bin/bash
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+WRITE_TOOLS="editFiles|createFile|create_file|replace_string_in_file|deleteFile"
+
+if echo "$TOOL_NAME" | grep -qE "^($WRITE_TOOLS)\$"; then
+  if [ -f "lock.json" ]; then
+    HOLDER=$(cat lock.json | jq -r '.holder // empty')
+    if [ -z "$HOLDER" ] || [ "$HOLDER" = "null" ]; then
+      echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"You must claim lock.json before writing files. Write holder=your_agent_id first."}}'
+      exit 0
+    fi
+  fi
+fi
+
+echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+`;