agentxchain 0.8.6 → 0.8.7

package/README.md

@@ -16,12 +16,21 @@ npx agentxchain init
 
 ## Quick start
 
+### Happy path: net-new project
+
 ```bash
-# 1. Create a project (interactive template selection)
 agentxchain init
+cd my-project
+agentxchain kickoff
+```
+
+### Happy path: existing project
 
-# 2. Run guided PM-first kickoff wizard
-cd my-project/
+Run these commands from inside your existing project folder:
+
+```bash
+agentxchain doctor
+agentxchain generate
 agentxchain kickoff
 ```
 
@@ -46,6 +55,7 @@ Agents are now required to maintain `TALK.md` as the human-readable handoff log
 | `stop` | Terminate running Claude Code agent sessions |
 | `watch` | Optional: TTL safety net + status logging |
 | `config` | View/edit config, add/remove agents, change rules |
+| `rebind` | Rebuild Cursor workspace/prompt bindings for agents |
 | `update` | Self-update CLI from npm |
 
 ### Full command list
@@ -57,6 +67,7 @@ agentxchain start
 agentxchain kickoff
 agentxchain stop
 agentxchain config
+agentxchain rebind
 agentxchain generate
 agentxchain watch
 agentxchain supervise
@@ -94,6 +105,9 @@ agentxchain watch --daemon          # run watch in background
 agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
 agentxchain supervise --autonudge --send   # auto-press Enter after paste
 agentxchain supervise --interval 2  # set auto-nudge poll interval
+agentxchain rebind                  # regenerate agent prompt/workspace bindings
+agentxchain rebind --open           # regenerate and reopen all Cursor agent windows
+agentxchain rebind --agent pm       # regenerate one agent binding only
 agentxchain claim --agent pm        # guarded claim as agent turn owner
 agentxchain release --agent pm      # guarded release as agent turn owner
 agentxchain release --force         # force-release non-human holder lock
@@ -146,7 +160,7 @@ Notes:
 2. Each window gets a unique prompt copied to clipboard
 3. Kickoff validates PM signoff and launches remaining agents
 4. Agent prompts are single-turn: claim → work → validate → release → stop
-5. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
+5. Agents use the latest `Next owner:` in `TALK.md` to pick who goes next (fallback: config order)
 6. Human can `claim` to pause and `release` to resume anytime
 
 ### VS Code mode
@@ -155,13 +169,12 @@ Notes:
 2. VS Code auto-discovers agents in the Chat dropdown
 3. The `Stop` hook acts as referee — hands off to next agent automatically
 
-### Turn rotation
+### Turn ownership
 
-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...
+Agent turns are handoff-driven:
+- Each turn appends a `Next owner:` in `TALK.md` with a valid agent id
+- `watch`/`supervise` dispatches the next trigger from that handoff
+- `claim --agent <id>` enforces that expected owner (with guarded fallback)
 
 ## Key features
 

package/bin/agentxchain.js

@@ -17,6 +17,7 @@ import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
+import { rebindCommand } from '../src/commands/rebind.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -91,6 +92,13 @@ program
   .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
   .action(superviseCommand);
 
+program
+  .command('rebind')
+  .description('Rebuild Cursor prompt/workspace bindings for agents')
+  .option('--agent <id>', 'Rebind a single agent only')
+  .option('--open', 'Reopen Cursor windows after rebinding')
+  .action(rebindCommand);
+
 program
   .command('claim')
   .description('Claim the lock as a human (take control)')

package/package.json

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

package/scripts/agentxchain-autonudge.applescript

@@ -1,6 +1,7 @@
 property projectRoot : ""
 property pollSeconds : 3
 property autoSend : false
+property lastFailedDispatch : ""
 
 on run argv
   if (count of argv) < 1 then
@@ -41,8 +42,10 @@ on run argv
           set lastKey to do shell script "test -f " & quoted form of statePath & " && cat " & quoted form of statePath & " || echo ''"
 
           if dispatchKey is not lastKey then
-            my nudgeAgent(agentId, turnNum)
-            do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            set nudgedOk to my nudgeAgent(agentId, turnNum, dispatchKey)
+            if nudgedOk then
+              do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+            end if
           end if
         end if
       end if
@@ -52,7 +55,7 @@ on run argv
   end repeat
 end run
 
-on nudgeAgent(agentId, turnNum)
+on nudgeAgent(agentId, turnNum, dispatchKey)
   set nudgeText to "Hey " & agentId & ", it is your turn now (turn " & turnNum & "). Read lock.json, claim the lock, check state.md + history.jsonl + planning docs, do your work, and release lock."
   set the clipboard to nudgeText
 
@@ -60,8 +63,11 @@ on nudgeAgent(agentId, turnNum)
   delay 0.5
   set focusedOk to my focusAgentWindow(agentId)
   if focusedOk is false then
-    do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
-    return
+    if lastFailedDispatch is not dispatchKey then
+      do shell script "osascript -e " & quoted form of ("display notification \"Could not identify a unique window for " & agentId & ".\" with title \"AgentXchain\"")
+      set lastFailedDispatch to dispatchKey
+    end if
+    return false
   end if
   delay 0.2
 
@@ -80,7 +86,9 @@ on nudgeAgent(agentId, turnNum)
     end tell
   end tell
 
+  set lastFailedDispatch to ""
   do shell script "osascript -e " & quoted form of ("display notification \"Nudged " & agentId & " for turn " & turnNum & "\" with title \"AgentXchain\"")
+  return true
 end nudgeAgent
 
 on focusAgentWindow(agentId)
@@ -117,6 +125,10 @@ end focusAgentWindow
 
 on isStrongWindowMatch(windowName, agentId)
   set tokenA to ".agentxchain-workspaces/" & agentId
+  set tokenB to ".agentxchain-workspaces\\" & agentId
+  set tokenC to agentId & ".code-workspace"
   if windowName contains tokenA then return true
+  if windowName contains tokenB then return true
+  if windowName contains tokenC then return true
   return false
 end isStrongWindowMatch

package/src/adapters/cursor-local.js

@@ -1,5 +1,5 @@
 import { execSync } from 'child_process';
-import { writeFileSync, mkdirSync, existsSync, symlinkSync, lstatSync, unlinkSync } from 'fs';
+import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
@@ -29,7 +29,7 @@ export async function launchCursorLocal(config, root, opts) {
     writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
   }
 
-  // Create per-agent symlinked workspace folders so Cursor opens separate windows
+  // Create per-agent workspace files so each Cursor window has a unique identity
   const workspacesDir = join(root, '.agentxchain-workspaces');
   mkdirSync(workspacesDir, { recursive: true });
 
@@ -39,17 +39,13 @@ export async function launchCursorLocal(config, root, opts) {
       ? generateKickoffPrompt(id, agent, config, root)
       : generatePollingPrompt(id, agent, config, root);
 
-    // 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 {}
+    // Create workspace file: .agentxchain-workspaces/<id>.code-workspace
+    const agentWorkspace = join(workspacesDir, `${id}.code-workspace`);
+    const workspaceJson = {
+      folders: [{ path: root }],
+      settings: { 'agentxchain.agentId': id }
+    };
+    writeFileSync(agentWorkspace, JSON.stringify(workspaceJson, null, 2) + '\n');
 
     console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
     console.log('');

package/src/commands/claim.js

@@ -2,6 +2,7 @@ import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
+import { resolveNextAgent } from '../lib/next-owner.js';
 
 export async function claimCommand(opts) {
   const result = loadConfig();
@@ -106,7 +107,7 @@ function claimAsAgent({ opts, root, config, lock }) {
     process.exit(1);
   }
 
-  const expected = pickNextAgent(lock, config);
+  const expected = pickNextAgent(root, lock, config);
   if (!opts.force && expected && expected !== agentId) {
     console.log(chalk.red(`  Out-of-turn claim blocked. Expected: ${expected}, got: ${agentId}.`));
     process.exit(1);
@@ -145,13 +146,8 @@ function releaseAsAgent({ opts, root, config, lock }) {
   console.log(chalk.green(`  ✓ Lock released by ${agentId} (turn ${next.turn_number})`));
 }
 
-function pickNextAgent(lock, config) {
-  const agentIds = Object.keys(config.agents || {});
-  if (agentIds.length === 0) return null;
-  const lastAgent = lock.last_released_by;
-  if (!lastAgent || !agentIds.includes(lastAgent)) return agentIds[0];
-  const lastIndex = agentIds.indexOf(lastAgent);
-  return agentIds[(lastIndex + 1) % agentIds.length];
+function pickNextAgent(root, lock, config) {
+  return resolveNextAgent(root, config, lock).next;
 }
 
 function clearBlockedState(root) {

package/src/commands/rebind.js

@@ -0,0 +1,77 @@
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+import { generatePollingPrompt } from '../lib/seed-prompt-polling.js';
+
+export async function rebindCommand(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 agentEntries = Object.entries(config.agents || {});
+  if (agentEntries.length === 0) {
+    console.log(chalk.red('No agents configured in agentxchain.json.'));
+    process.exit(1);
+  }
+
+  const selected = opts.agent
+    ? agentEntries.filter(([id]) => id === opts.agent)
+    : agentEntries;
+
+  if (opts.agent && selected.length === 0) {
+    console.log(chalk.red(`Agent "${opts.agent}" not found in agentxchain.json.`));
+    process.exit(1);
+  }
+
+  const promptDir = join(root, '.agentxchain-prompts');
+  const workspacesDir = join(root, '.agentxchain-workspaces');
+  mkdirSync(promptDir, { recursive: true });
+  mkdirSync(workspacesDir, { recursive: true });
+
+  for (const [id, def] of selected) {
+    const prompt = generatePollingPrompt(id, def, config, root);
+    writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
+
+    const wsPath = join(workspacesDir, `${id}.code-workspace`);
+    const workspaceJson = {
+      folders: [{ path: root }],
+      settings: { 'agentxchain.agentId': id }
+    };
+    writeFileSync(wsPath, JSON.stringify(workspaceJson, null, 2) + '\n');
+
+    if (opts.open) {
+      openCursorWindow(wsPath);
+    }
+  }
+
+  const statePath = join(root, '.agentxchain-autonudge.state');
+  if (existsSync(statePath)) {
+    rmSync(statePath, { force: true });
+  }
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Rebound ${selected.length} agent session(s).`));
+  console.log(chalk.dim(`  Prompts:     ${join('.agentxchain-prompts', opts.agent ? `${opts.agent}.prompt.md` : '')}`));
+  console.log(chalk.dim(`  Workspaces:  ${join('.agentxchain-workspaces', opts.agent ? `${opts.agent}.code-workspace` : '')}`));
+  console.log(chalk.dim('  Auto-nudge dispatch state reset.'));
+  if (!opts.open) {
+    console.log(chalk.dim('  Use `agentxchain rebind --open` to reopen agent windows now.'));
+  }
+  console.log('');
+}
+
+function openCursorWindow(targetPath) {
+  try {
+    if (process.platform === 'darwin') {
+      execSync(`open -na "Cursor" --args "${targetPath}"`, { stdio: 'ignore' });
+      return;
+    }
+    execSync(`cursor --new-window "${targetPath}"`, { stdio: 'ignore' });
+  } catch {}
+}
+

package/src/commands/watch.js

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
 import { notifyHuman as sendNotification } from '../lib/notify.js';
 import { validateProject } from '../lib/validation.js';
+import { resolveNextAgent } from '../lib/next-owner.js';
 
 export async function watchCommand(opts) {
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
@@ -51,8 +52,8 @@ export async function watchCommand(opts) {
       const stateKey = `${lock.holder}:${lock.turn_number}`;
 
       if (lock.holder && lock.holder !== 'human') {
-        const expected = pickNextAgent(lock, config);
-        if (!isValidClaimer(lock, config)) {
+        const expected = pickNextAgent(root, lock, config);
+        if (!isValidClaimer(root, lock, config)) {
           log('warn', `Illegal claim detected: holder=${lock.holder}, expected=${expected}. Handing lock to HUMAN.`);
           blockOnIllegalClaim(root, lock, config, expected);
           sendNotification(`Illegal claim detected (${lock.holder}). Human intervention required.`);
@@ -108,7 +109,7 @@ export async function watchCommand(opts) {
           }
         }
 
-        const next = pickNextAgent(lock, config);
+        const next = pickNextAgent(root, lock, config);
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Next: ${chalk.bold(next)}.`);
         writeTrigger(root, next, lock, config);
         lastState = stateKey;
@@ -129,21 +130,14 @@ export async function watchCommand(opts) {
   });
 }
 
-function pickNextAgent(lock, config) {
-  const agentIds = Object.keys(config.agents);
-  if (agentIds.length === 0) return null;
-  const lastAgent = lock.last_released_by;
-
-  if (!lastAgent || !agentIds.includes(lastAgent)) return agentIds[0];
-
-  const lastIndex = agentIds.indexOf(lastAgent);
-  return agentIds[(lastIndex + 1) % agentIds.length];
+function pickNextAgent(root, lock, config) {
+  return resolveNextAgent(root, config, lock).next;
 }
 
-function isValidClaimer(lock, config) {
+function isValidClaimer(root, lock, config) {
   if (!lock.holder || lock.holder === 'human') return true;
   if (!config.agents?.[lock.holder]) return false;
-  const expected = pickNextAgent(lock, config);
+  const expected = pickNextAgent(root, lock, config);
   return lock.holder === expected;
 }
 

package/src/lib/generate-vscode.js

@@ -232,12 +232,29 @@ if [ -z "$HOLDER" ] || [ "$HOLDER" = "null" ]; then
   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 fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync('agentxchain.json','utf8'));
+    const ids = Object.keys(cfg.agents || {});
+    const lock = JSON.parse(fs.readFileSync('lock.json','utf8'));
+    const talkFile = cfg.talk_file || 'TALK.md';
+    let fromTalk = '';
+    try {
+      const talk = fs.readFileSync(talkFile, 'utf8').split(/\\r?\\n/);
+      for (let i = talk.length - 1; i >= 0; i -= 1) {
+        const m = talk[i].trim().match(/^(?:-|\\*)?\\s*\\**next\\s*owner\\**\\s*:\\s*(.+)$/i);
+        if (!m) continue;
+        let candidate = String(m[1] || '').replace(/[\\*_]/g, '').replace(/\\(.*?\\)/g, '').trim().split(/[\\s,]+/)[0].toLowerCase();
+        if (ids.includes(candidate)) { fromTalk = candidate; break; }
+      }
+    } catch {}
+    if (fromTalk) {
+      process.stdout.write(fromTalk);
+      process.exit(0);
+    }
+    const last = lock.last_released_by || '';
     const idx = ids.indexOf(last);
-    const next = ids[(idx + 1) % ids.length];
-    process.stdout.write(next);
+    const next = idx >= 0 ? ids[(idx + 1) % ids.length] : ids[0];
+    process.stdout.write(next || '');
   " -- "$LAST" 2>/dev/null)
 
   if [ -z "$NEXT" ]; then

package/src/lib/next-owner.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export function resolveNextAgent(root, config, lock = {}) {
+  const agents = Object.keys(config.agents || {});
+  if (agents.length === 0) return { next: null, source: 'none', raw: null };
+
+  const talkFile = config.talk_file || 'TALK.md';
+  const talkPath = join(root, talkFile);
+  const fromTalk = parseNextOwnerFromTalk(talkPath, agents);
+  if (fromTalk) {
+    return { next: fromTalk, source: 'talk', raw: fromTalk };
+  }
+
+  const last = lock.last_released_by;
+  if (last && agents.includes(last)) {
+    const idx = agents.indexOf(last);
+    return { next: agents[(idx + 1) % agents.length], source: 'fallback-cyclic', raw: null };
+  }
+
+  return { next: agents[0], source: 'fallback-first', raw: null };
+}
+
+function parseNextOwnerFromTalk(talkPath, validAgentIds) {
+  if (!existsSync(talkPath)) return null;
+
+  let text = '';
+  try {
+    text = readFileSync(talkPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  if (!text.trim()) return null;
+
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const match = line.match(/^(?:-|\*)?\s*\**next\s*owner\**\s*:\s*(.+)$/i);
+    if (!match) continue;
+
+    const candidate = normalizeAgentId(match[1]);
+    if (candidate && validAgentIds.includes(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function normalizeAgentId(raw) {
+  if (!raw) return null;
+  let value = String(raw).trim();
+  value = value.replace(/[`*_]/g, '').trim();
+  value = value.replace(/\(.*?\)/g, '').trim();
+  value = value.split(/[,\s]+/)[0];
+  value = value.toLowerCase();
+  return /^[a-z0-9_-]+$/.test(value) ? value : null;
+}
+

package/src/lib/seed-prompt-polling.js

@@ -9,12 +9,6 @@ export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '
 
   const agentIds = Object.keys(config.agents);
   const myIndex = agentIds.indexOf(agentId);
-  const prevAgent = myIndex === 0 ? null : agentIds[myIndex - 1];
-  const isFirstAgent = myIndex === 0;
-
-  const turnCondition = isFirstAgent
-    ? `It is YOUR turn when lock.json shows holder=null AND (last_released_by is null, "human", "system", OR the LAST agent in the rotation: "${agentIds[agentIds.length - 1]}")`
-    : `It is YOUR turn when lock.json shows holder=null AND last_released_by="${prevAgent}"`;
 
   const readSection = useSplit
     ? `READ THESE FILES:
@@ -37,6 +31,7 @@ c. Append ONE line to "${historyFile}":
    {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
 d. Append ONE handoff entry to "${talkFile}" with:
    Turn, Status, Decision, Action, Risks/Questions, Next owner.
+   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
 e. Update state.json if phase or blocked status changed.`
     : `WRITE (in this order):
 a. Do your actual work: write code, create files, run commands, make decisions.
@@ -49,6 +44,7 @@ b. Append ONE message to ${logFile}:
    **Next:** What the next agent should focus on.
 c. Append ONE handoff entry to "${talkFile}" with:
    Turn, Status, Decision, Action, Risks/Questions, Next owner.
+   IMPORTANT: "Next owner" must be a valid agent id from [${agentIds.join(', ')}].
 d. Update state.json if phase or blocked status changed.`;
 
   const verifySection = verifyCmd
@@ -101,9 +97,9 @@ GET SHIT DONE FRAMEWORK (mandatory):
 
 ---
 
-TEAM ROTATION: ${agentIds.join(' → ')} → (repeat)
+TEAM IDS: ${agentIds.join(', ')}
 YOUR POSITION: ${agentId} (index ${myIndex} of ${agentIds.length})
-${turnCondition}
+Turn assignment is handoff-driven: previous owner writes "Next owner" in TALK.md.
 
 ---
 
@@ -115,11 +111,11 @@ TURN MODE (single turn only, referee wakes you again later):
    - Never run broad searches outside this project root.
 
 1. READ lock.json.
+   Also read .agentxchain-trigger.json when present.
 
 2. CHECK — is it my turn?
-   ${isFirstAgent
-    ? `- It is your turn only when lock holder is null and last_released_by is null/human/system/${agentIds[agentIds.length - 1]}.`
-    : `- It is your turn only when lock holder is null and last_released_by is "${prevAgent}".`}
+   - It is your turn when lock holder is null AND trigger.agent is "${agentId}".
+   - If trigger file is missing, you may still attempt claim; claim guardrails enforce expected next owner.
    - If NOT your turn: STOP. Do not claim lock and do not write files.
 
 3. CLAIM the lock: