agentxchain 0.8.5 → 0.8.6

package/README.md

@@ -25,7 +25,7 @@ cd my-project/
 agentxchain kickoff
 ```
 
-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. `supervise --autonudge` handles watch + nudging automatically.
+Each agent runs in its own Cursor window for a single turn at a time. The referee loop (`watch` / `supervise --autonudge`) determines the next agent and wakes that specific session.
 
 Agents are now required to maintain `TALK.md` as the human-readable handoff log each turn.
 
@@ -48,6 +48,25 @@ Agents are now required to maintain `TALK.md` as the human-readable handoff log
 | `config` | View/edit config, add/remove agents, change rules |
 | `update` | Self-update CLI from npm |
 
+### Full command list
+
+```bash
+agentxchain init
+agentxchain status
+agentxchain start
+agentxchain kickoff
+agentxchain stop
+agentxchain config
+agentxchain generate
+agentxchain watch
+agentxchain supervise
+agentxchain claim
+agentxchain release
+agentxchain update
+agentxchain doctor
+agentxchain validate
+```
+
 ### IDE options
 
 ```bash
@@ -62,15 +81,21 @@ agentxchain start --ide claude-code # Claude Code — spawns CLI processes
 agentxchain kickoff                # guided first-run PM-first workflow
 agentxchain kickoff --ide vscode   # guided flow for VS Code mode
 agentxchain kickoff --send         # with Cursor auto-nudge auto-send enabled
+agentxchain kickoff --interval 2   # nudge poll interval override
+agentxchain kickoff --no-autonudge # skip auto-nudge prompt
 
 agentxchain start --agent pm        # launch only one specific agent
 agentxchain start --remaining       # launch all agents except PM (PM-first flow)
 agentxchain start --dry-run         # preview agents without launching
 agentxchain validate --mode kickoff # required before --remaining
 agentxchain validate --mode turn --agent pm
+agentxchain validate --json         # machine-readable validation output
 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 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
 ```
 
@@ -120,7 +145,7 @@ Notes:
 1. `agentxchain kickoff` launches PM first for human-product alignment
 2. Each window gets a unique prompt copied to clipboard
 3. Kickoff validates PM signoff and launches remaining agents
-4. Agent prompts include a self-polling loop: read `lock.json` → check if it's my turn → claim → work → release → sleep 60s → repeat
+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
 6. Human can `claim` to pause and `release` to resume anytime
 
@@ -141,7 +166,7 @@ Agents follow a round-robin order defined in `agentxchain.json`:
 ## Key features
 
 - **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
+- **Referee-driven coordination** — `watch`/`supervise` wakes the next correct agent each turn
 - **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

package/bin/agentxchain.js

@@ -94,12 +94,14 @@ program
 program
   .command('claim')
   .description('Claim the lock as a human (take control)')
+  .option('--agent <id>', 'Claim lock as a specific agent (guarded by turn order)')
   .option('--force', 'Force-claim even if an agent holds the lock')
   .action(claimCommand);
 
 program
   .command('release')
   .description('Release the lock (hand back to agents)')
+  .option('--agent <id>', 'Release lock as a specific agent')
   .option('--force', 'Force release even if a non-human holder has the lock')
   .action(releaseCommand);
 

package/package.json

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

package/src/adapters/cursor-local.js

@@ -107,7 +107,7 @@ export async function launchCursorLocal(config, root, opts) {
   console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# watcher / trigger writer')}`);
   console.log(`    ${chalk.bold('agentxchain doctor')}   ${chalk.dim('# check local setup + trigger health')}`);
   console.log('');
-  console.log(chalk.dim('  Agents self-coordinate via lock.json polling (sleep 60s between checks).'));
+  console.log(chalk.dim('  Agents run single turns. Watch/supervise wakes the correct next agent.'));
   console.log(chalk.dim('  Re-paste a prompt: cat .agentxchain-prompts/<agent>.prompt.md | pbcopy'));
   console.log('');
 }
@@ -162,31 +162,34 @@ Project root (strict boundary): "${projectRoot}"
 Work only inside this project folder. Do NOT scan unrelated local directories.
 
 Actions:
-1) Read:
+1) FIRST QUESTION TO HUMAN (mandatory before anything else):
+"Please describe your product idea in one paragraph, in as much detail as possible."
+
+2) Read:
 - .planning/PROJECT.md
 - .planning/REQUIREMENTS.md
 - .planning/ROADMAP.md
 - TALK.md
 - state.md
 - lock.json
-2) Ask the human focused product questions until scope is clear:
+3) After receiving that paragraph, summarize it in TALK.md, then ask focused follow-up questions:
 - target user
 - top pain point
 - core workflow
 - MVP boundary
 - success metric
-3) Update planning docs with concrete acceptance criteria and Get Shit Done structure:
+4) Update planning docs with concrete acceptance criteria and Get Shit Done structure:
 - .planning/ROADMAP.md must define Waves and Phases.
 - Create .planning/phases/phase-1/PLAN.md and TESTS.md.
-4) Update .planning/PM_SIGNOFF.md:
+5) Update .planning/PM_SIGNOFF.md:
 - Set "Approved: YES" only when human agrees kickoff is complete.
-5) Append kickoff summary to TALK.md with:
+6) Append kickoff summary to TALK.md with:
 - Status
 - Decision
 - Action
 - Risks/Questions
 - Next owner
-6) Do NOT start round-robin agent handoffs yet.
+7) Do NOT start round-robin agent handoffs yet.
 
 Context:
 - Project: ${config.project}

package/src/commands/claim.js

@@ -11,6 +11,10 @@ export async function claimCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
+  if (opts.agent) {
+    return claimAsAgent({ opts, root, config, lock });
+  }
+
   if (lock.holder === 'human') {
     console.log('');
     console.log(chalk.yellow('  You already hold the lock.'));
@@ -52,6 +56,10 @@ export async function releaseCommand(opts) {
   const lock = loadLock(root);
   if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
 
+  if (opts.agent) {
+    return releaseAsAgent({ opts, root, config, lock });
+  }
+
   if (!lock.holder) {
     console.log(chalk.yellow('  Lock is already free.'));
     return;
@@ -85,6 +93,67 @@ export async function releaseCommand(opts) {
   console.log('');
 }
 
+function claimAsAgent({ opts, root, config, lock }) {
+  const agentId = opts.agent;
+  if (!config.agents?.[agentId]) {
+    console.log(chalk.red(`  Agent "${agentId}" is not defined in agentxchain.json.`));
+    process.exit(1);
+  }
+
+  if (lock.holder && !opts.force) {
+    console.log(chalk.red(`  Lock is currently held by "${lock.holder}".`));
+    console.log(chalk.dim('  Use --force only for recovery scenarios.'));
+    process.exit(1);
+  }
+
+  const expected = pickNextAgent(lock, config);
+  if (!opts.force && expected && expected !== agentId) {
+    console.log(chalk.red(`  Out-of-turn claim blocked. Expected: ${expected}, got: ${agentId}.`));
+    process.exit(1);
+  }
+
+  const lockPath = join(root, LOCK_FILE);
+  const next = {
+    holder: agentId,
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  console.log(chalk.green(`  ✓ Lock claimed by ${agentId} (turn ${next.turn_number})`));
+}
+
+function releaseAsAgent({ opts, root, config, lock }) {
+  const agentId = opts.agent;
+  if (!config.agents?.[agentId]) {
+    console.log(chalk.red(`  Agent "${agentId}" is not defined in agentxchain.json.`));
+    process.exit(1);
+  }
+  if (lock.holder !== agentId && !opts.force) {
+    console.log(chalk.red(`  Lock is held by "${lock.holder}", not "${agentId}".`));
+    process.exit(1);
+  }
+
+  const lockPath = join(root, LOCK_FILE);
+  const next = {
+    holder: null,
+    last_released_by: agentId,
+    turn_number: lock.turn_number + 1,
+    claimed_at: null
+  };
+  writeFileSync(lockPath, JSON.stringify(next, null, 2) + '\n');
+  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 clearBlockedState(root) {
   const statePath = join(root, 'state.json');
   if (!existsSync(statePath)) return;

package/src/commands/watch.js

@@ -50,6 +50,17 @@ 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)) {
+          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.`);
+          lastState = null;
+          return;
+        }
+      }
+
       if (lock.holder && lock.holder !== 'human' && lock.claimed_at) {
         const elapsed = Date.now() - new Date(lock.claimed_at).getTime();
         const ttlMs = ttlMinutes * 60 * 1000;
@@ -129,6 +140,13 @@ function pickNextAgent(lock, config) {
   return agentIds[(lastIndex + 1) % agentIds.length];
 }
 
+function isValidClaimer(lock, config) {
+  if (!lock.holder || lock.holder === 'human') return true;
+  if (!config.agents?.[lock.holder]) return false;
+  const expected = pickNextAgent(lock, config);
+  return lock.holder === expected;
+}
+
 function forceRelease(root, lock, staleAgent, config) {
   const lockPath = join(root, LOCK_FILE);
   const newLock = {
@@ -192,6 +210,39 @@ function blockOnValidation(root, lock, config, validation) {
   }
 }
 
+function blockOnIllegalClaim(root, lock, config, expected) {
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: 'human',
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+
+  const statePath = join(root, 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const current = JSON.parse(readFileSync(statePath, 'utf8'));
+      const nextState = {
+        ...current,
+        blocked: true,
+        blocked_on: `illegal-claim: expected ${expected}, got ${lock.holder}`
+      };
+      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+    } catch {}
+  }
+
+  const logFile = config.log || 'log.md';
+  const logPath = join(root, logFile);
+  if (existsSync(logPath)) {
+    appendFileSync(
+      logPath,
+      `\n---\n\n### [system] (Watch Guard) | Turn ${lock.turn_number}\n\n**Status:** Illegal out-of-turn lock claim detected.\n\n**Action:** Lock assigned to human for intervention.\n\n**Details:** expected \`${expected}\`, got \`${lock.holder}\`.\n\n`
+    );
+  }
+}
+
 function log(type, msg) {
   const time = new Date().toLocaleTimeString();
   const tags = {

package/src/lib/generate-vscode.js

@@ -142,12 +142,13 @@ Create or update these files when your role requires it.
 
 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.
+1. **CLAIM**: Run \`agentxchain claim --agent ${agentId}\`. If blocked, stop.
 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\`.
+5. **RELEASE**: Run \`agentxchain release --agent ${agentId}\`.
    This MUST be the last thing you write.
+6. **STOP**: End your turn. The referee will wake the next agent.
 
 ---
 

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

@@ -107,7 +107,7 @@ ${turnCondition}
 
 ---
 
-YOUR LOOP (run forever, never exit, never say "I'm done"):
+TURN MODE (single turn only, referee wakes you again later):
 
 0. CHECK WORKING DIRECTORY:
    - Run: pwd
@@ -117,18 +117,14 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
 1. READ lock.json.
 
 2. CHECK — is it my turn?
-   - If holder is NOT null → someone else is working. Run the shell command: sleep 60
-     Then go back to step 1.
-   - If holder IS null → check last_released_by:
-     ${isFirstAgent
-       ? `- If last_released_by is null, "human", starts with "system", or "${agentIds[agentIds.length - 1]}" → IT IS YOUR TURN. Go to step 3.`
-       : `- If last_released_by is "${prevAgent}" → IT IS YOUR TURN. Go to step 3.`}
-     - Otherwise → it is another agent's turn. Run the shell command: sleep 60
-       Then go back to step 1.
+   ${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}".`}
+   - If NOT your turn: STOP. Do not claim lock and do not write files.
 
 3. CLAIM the lock:
-   Write lock.json: {"holder":"${agentId}","last_released_by":<keep previous>,"turn_number":<keep previous>,"claimed_at":"<current ISO timestamp>"}
-   Then RE-READ lock.json immediately. If holder is not "${agentId}", someone else won. Go to step 1.
+   Run: agentxchain claim --agent ${agentId}
+   If claim is blocked, STOP.
 
 4. DO YOUR WORK:
    ${readSection}
@@ -142,20 +138,16 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
    If validation fails, fix docs/artifacts first. Do NOT release.
 
 5. RELEASE the lock:
-   Write lock.json: {"holder":null,"last_released_by":"${agentId}","turn_number":<previous + 1>,"claimed_at":null}
+   Run: agentxchain release --agent ${agentId}
    THIS MUST BE THE LAST FILE YOU WRITE.
 
-6. Run the shell command: sleep 60
-   Then go back to step 1.
-
 ---
 
 CRITICAL RULES:
-- ACTUALLY RUN "sleep 60" in the terminal between checks. Do NOT skip this. Do NOT just say "waiting."
 - Never write files or code without holding the lock. Reading is always allowed.
 - One git commit per turn: "Turn N - ${agentId} - description"
 - Max ${maxClaims} consecutive turns. If you have held the lock ${maxClaims} times in a row, 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.
-- NEVER exit or stop. After releasing, always sleep and poll again. You are a persistent agent.`;
+- This session is SINGLE-TURN. After release, STOP and wait for the referee to wake you again.`;
 }