agentxchain 0.8.0 → 0.8.2

package/README.md

@@ -1,6 +1,6 @@
 # agentxchain
 
-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.
+CLI for multi-agent coordination in your IDE. Define a team of AI agents, let them take turns building your project — each in its own IDE window.
 
 ## Install
 
@@ -17,59 +17,92 @@ npx agentxchain init
 ## Quick start
 
 ```bash
-agentxchain init                      # create project with agents + hooks
-cd my-project/ && code .              # open in VS Code / Cursor
-# Select an agent from the Chat dropdown (auto-discovered from .github/agents/)
-agentxchain release                   # release human lock to begin turns
+# 1. Create a project (interactive template selection)
+agentxchain init
+
+# 2. Launch agents — opens a separate Cursor window per agent
+cd my-project/
+agentxchain start
+
+# 3. For each window: paste the prompt (auto-copied to clipboard), select Agent mode, send
+#    The CLI walks you through one agent at a time.
+
+# 4. Release the human lock — agents start claiming turns
+agentxchain release
 ```
 
-The `Stop` hook acts as referee: when an agent finishes, it determines the next agent and hands off automatically. No polling process needed.
+Each agent runs in its own Cursor window with a self-polling loop. Agents check `lock.json` every 60 seconds, claim when it's their turn, do their work, release, and go back to waiting. No external referee needed.
 
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `init` | Create project folder with agents, hooks, protocol files, and templates |
-| `generate` | Regenerate VS Code agent files (`.agent.md`, hooks) from `agentxchain.json` |
-| `start` | Show agent setup instructions for your IDE |
-| `status` | Show lock, phase, agents |
-| `claim` | Human takes control |
+| `init` | Create project folder with agents, protocol files, and templates |
+| `start` | Open a Cursor window per agent + copy prompts to clipboard |
+| `generate` | Regenerate agent files from `agentxchain.json` |
+| `status` | Show lock holder, phase, turn number, agents |
+| `claim` | Human takes control (agents stop claiming) |
 | `release` | Hand lock back to agents |
 | `stop` | Terminate running Claude Code agent sessions |
-| `watch` | Fallback referee for non-IDE environments |
+| `watch` | Optional: TTL safety net + status logging |
 | `config` | View/edit config, add/remove agents, change rules |
 | `update` | Self-update CLI from npm |
 
+### IDE options
+
+```bash
+agentxchain start                   # Cursor (default) — one window per agent
+agentxchain start --ide vscode      # VS Code — uses .agent.md custom agents + hooks
+agentxchain start --ide claude-code # Claude Code — spawns CLI processes
+```
+
 ### Additional flags
 
 ```bash
+agentxchain start --agent pm        # launch only one specific agent
+agentxchain start --dry-run         # preview agents without launching
 agentxchain watch --daemon          # run watch in background
 agentxchain release --force         # force-release non-human holder lock
 ```
 
 ## How it works
 
-`agentxchain init` generates native VS Code agent files:
+### Cursor mode (default)
+
+1. `agentxchain start` opens a **separate Cursor window** for each agent
+2. Each window gets a unique prompt copied to clipboard
+3. Agent prompts include a self-polling loop: read `lock.json` → check if it's my turn → claim → work → release → sleep 60s → repeat
+4. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
+5. Human can `claim` to pause and `release` to resume anytime
+
+### VS Code mode
+
+1. `agentxchain init` generates `.github/agents/*.agent.md` (VS Code custom agents) and `.github/hooks/` (lifecycle hooks)
+2. VS Code auto-discovers agents in the Chat dropdown
+3. The `Stop` hook acts as referee — hands off to next agent automatically
 
-- `.github/agents/*.agent.md` — custom agents (auto-discovered by VS Code / Cursor Chat)
-- `.github/hooks/agentxchain.json` — lifecycle hooks (Stop = referee, SessionStart = context injection)
-- `scripts/agentxchain-*.sh` — hook shell scripts
+### Turn rotation
 
-When an agent finishes its response, the Stop hook reads `lock.json`, determines the next agent, and hands off automatically.
+Agents follow a round-robin order defined in `agentxchain.json`:
+- PM waits for: lock free + last released by `human`, `null`, or last agent in rotation
+- Dev waits for: lock free + last released by `pm`
+- QA waits for: lock free + last released by `dev`
+- And so on...
 
 ## Key features
 
-- **Native VS Code agents** — `.agent.md` files, lifecycle hooks, handoffs
-- **Works in any VS Code fork** — Cursor, VS Code, Windsurf, etc.
-- **Stop hook referee** — deterministic turn coordination via lifecycle hooks
+- **One window per agent** — each agent has its own Cursor window and chat session
+- **Self-polling coordination** — agents check `lock.json` every 60s, no external process needed
+- **Works in Cursor, VS Code, Claude Code** — adapters for each IDE
 - **User-defined teams** — any number of agents, any roles
 - **No API keys or cloud required** — everything runs locally
 - **Human-in-the-loop** — claim/release to intervene anytime
 - **Team templates** — SaaS MVP, Landing Page, Bug Squad, API Builder, Refactor Team
+- **Lock TTL** — `watch` can force-release stale locks as a safety net
 
 ## VS Code extension (optional)
 
-For a richer UI experience, install the extension:
+For a richer UI in VS Code:
 
 ```bash
 code --install-extension cli/vscode-extension/agentxchain-0.1.0.vsix

package/package.json

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

package/src/adapters/cursor-local.js

@@ -1,5 +1,5 @@
 import { execSync } from 'child_process';
-import { writeFileSync } from 'fs';
+import { writeFileSync, mkdirSync, existsSync, symlinkSync, lstatSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
@@ -10,50 +10,83 @@ export async function launchCursorLocal(config, root, opts) {
   const agentEntries = Object.entries(agents);
   const total = agentEntries.length;
 
-  console.log(chalk.bold(`  Opening ${total} Cursor windows for: ${Object.keys(agents).join(', ')}`));
+  console.log(chalk.bold(`  Setting up ${total} agents: ${Object.keys(agents).join(', ')}`));
   console.log('');
 
   const promptDir = join(root, '.agentxchain-prompts');
-  try { execSync(`mkdir -p "${promptDir}"`); } catch {}
+  mkdirSync(promptDir, { recursive: true });
+
+  // Save all prompts first
+  for (const [id, agent] of agentEntries) {
+    const prompt = generatePollingPrompt(id, agent, config);
+    writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
+  }
+
+  // Create per-agent symlinked workspace folders so Cursor opens separate windows
+  const workspacesDir = join(root, '.agentxchain-workspaces');
+  mkdirSync(workspacesDir, { recursive: true });
 
   for (let i = 0; i < agentEntries.length; i++) {
     const [id, agent] = agentEntries[i];
     const prompt = generatePollingPrompt(id, agent, config);
-    const promptFile = join(promptDir, `${id}.prompt.md`);
-    writeFileSync(promptFile, prompt);
 
-    console.log(`  ${chalk.cyan(`Window ${i + 1}/${total}:`)} ${chalk.bold(id)} — ${agent.name}`);
+    // Create symlink: .agentxchain-workspaces/<id> -> project root
+    const agentWorkspace = join(workspacesDir, id);
+    try {
+      if (existsSync(agentWorkspace)) {
+        const stat = lstatSync(agentWorkspace);
+        if (stat.isSymbolicLink()) unlinkSync(agentWorkspace);
+      }
+      if (!existsSync(agentWorkspace)) {
+        symlinkSync(root, agentWorkspace, 'dir');
+      }
+    } catch {}
+
+    console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
+    console.log('');
 
     copyToClipboard(prompt);
-    console.log(chalk.green(`    Prompt copied to clipboard.`));
-    console.log(chalk.dim(`    Also saved to: .agentxchain-prompts/${id}.prompt.md`));
+    console.log(chalk.green(`  ✓ Prompt copied to clipboard.`));
+    console.log(chalk.dim(`    Saved to: .agentxchain-prompts/${id}.prompt.md`));
+
+    // Open a separate Cursor window using the symlinked path
+    openCursorWindow(agentWorkspace);
+    console.log(chalk.dim(`    Cursor window opened for ${id}.`));
 
-    tryOpenCursor(root);
+    console.log('');
+    console.log(`  ${chalk.bold('In the new Cursor window:')}`);
+    console.log(`    1. Open chat (${chalk.bold('Cmd+L')})`);
+    console.log(`    2. Paste the prompt (${chalk.bold('Cmd+V')})`);
+    console.log(`    3. ${chalk.bold('Select Agent mode')} (not Ask/Edit)`);
+    console.log(`    4. Send it (${chalk.bold('Enter')})`);
 
     if (i < agentEntries.length - 1) {
       console.log('');
       await inquirer.prompt([{
         type: 'input',
         name: 'ready',
-        message: chalk.dim(`    Paste prompt in Cursor chat (Cmd+V), send it, then press Enter here for the next agent...`)
+        message: `  Done? Press Enter to open next window (${agentEntries[i + 1][0]})...`
       }]);
+      console.log('');
     } else {
       console.log('');
-      console.log(chalk.dim(`    Paste this last prompt in Cursor chat (Cmd+V) and send it.`));
+      console.log(chalk.dim(`  Last agent. Paste and send, then come back here.`));
+      console.log('');
     }
   }
 
+  console.log(chalk.green(`  ✓ All ${total} agents launched in separate Cursor windows.`));
   console.log('');
-  console.log(chalk.green('  All agent prompts ready.'));
-  console.log('');
-  console.log(`  ${chalk.cyan('Next:')}`);
+  console.log(`  ${chalk.cyan('Now run:')}`);
   console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# release human lock — agents start claiming turns')}`);
-  console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# optional: TTL safety net + status logging')}`);
+  console.log('');
+  console.log(`  ${chalk.dim('Other commands:')}`);
   console.log(`    ${chalk.bold('agentxchain status')}   ${chalk.dim('# check who holds the lock')}`);
   console.log(`    ${chalk.bold('agentxchain claim')}    ${chalk.dim('# pause agents and take control')}`);
+  console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# optional: TTL safety net')}`);
   console.log('');
   console.log(chalk.dim('  Agents self-coordinate via lock.json polling (sleep 60s between checks).'));
-  console.log(chalk.dim('  Prompts saved in .agentxchain-prompts/ if you need to re-paste.'));
+  console.log(chalk.dim('  Re-paste a prompt: cat .agentxchain-prompts/<agent>.prompt.md | pbcopy'));
   console.log('');
 }
 
@@ -82,14 +115,12 @@ function copyToClipboard(text) {
   return false;
 }
 
-function tryOpenCursor(root) {
+function openCursorWindow(folderPath) {
   try {
     if (process.platform === 'darwin') {
-      execSync(`open -na "Cursor" --args "${root}"`, { stdio: 'ignore' });
+      execSync(`open -na "Cursor" --args "${folderPath}"`, { stdio: 'ignore' });
       return;
     }
-    execSync(`cursor "${root}"`, { stdio: 'ignore' });
-  } catch {
-    // Cursor not found or can't open — user will open manually
-  }
+    execSync(`cursor --new-window "${folderPath}"`, { stdio: 'ignore' });
+  } catch {}
 }

package/src/commands/init.js

@@ -207,7 +207,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'log.md'), `# ${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`);
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
   const gitignorePath = join(dir, '.gitignore');
-  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/'];
+  const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/'];
   if (!existsSync(gitignorePath)) {
     writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
   } else {
@@ -264,13 +264,7 @@ export async function initCommand(opts) {
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
   console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
-  console.log(`    ${chalk.bold('cursor .')}             ${chalk.dim('# open in Cursor')}`);
-  console.log(`    ${chalk.bold('code .')}               ${chalk.dim('# open in VS Code')}`);
-  console.log(`    ${chalk.dim('(If "command not found": open IDE → Cmd+Shift+P → "Shell Command: Install")')}`);
-  console.log('');
-  console.log(`    ${chalk.dim('In your IDE:')}`);
-  console.log(`    ${chalk.dim('  1. Open Chat (Cmd+L)')}`);
-  console.log(`    ${chalk.dim('  2. Select an agent from the dropdown (auto-discovered from .github/agents/)')}`);
-  console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# release human lock to begin turns')}`);
+  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# opens Cursor windows + copies agent prompts')}`);
+  console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# release human lock — agents start working')}`);
   console.log('');
 }