agentxchain 0.8.4 → 0.8.6

package/README.md

@@ -25,7 +25,9 @@ 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.
 
 ## Commands
 
@@ -46,6 +48,25 @@ Each agent runs in its own Cursor window with a self-polling loop. Agents check
 | `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
@@ -60,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
 ```
 
@@ -118,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
 
@@ -139,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.4",
+  "version": "0.8.6",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/src/adapters/cursor-local.js

@@ -24,8 +24,8 @@ export async function launchCursorLocal(config, root, opts) {
   // Save all prompts first
   for (const [id, agent] of agentEntries) {
     const prompt = isPmKickoff
-      ? generateKickoffPrompt(id, agent, config)
-      : generatePollingPrompt(id, agent, config);
+      ? generateKickoffPrompt(id, agent, config, root)
+      : generatePollingPrompt(id, agent, config, root);
     writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
   }
 
@@ -36,8 +36,8 @@ export async function launchCursorLocal(config, root, opts) {
   for (let i = 0; i < agentEntries.length; i++) {
     const [id, agent] = agentEntries[i];
     const prompt = isPmKickoff
-      ? generateKickoffPrompt(id, agent, config)
-      : generatePollingPrompt(id, agent, config);
+      ? generateKickoffPrompt(id, agent, config, root)
+      : generatePollingPrompt(id, agent, config, root);
 
     // Create symlink: .agentxchain-workspaces/<id> -> project root
     const agentWorkspace = join(workspacesDir, id);
@@ -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('');
 }
@@ -153,30 +153,43 @@ function isPmLike(agentId, agentDef) {
   return name.includes('product manager');
 }
 
-function generateKickoffPrompt(agentId, agentDef, config) {
+function generateKickoffPrompt(agentId, agentDef, config, projectRoot) {
   return `You are "${agentId}" — ${agentDef.name}.
 
 This is PM kickoff mode. Your job now is to collaborate with the human and finalize scope before autonomous turns begin.
 
+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) Do NOT start round-robin agent handoffs yet.
+6) Append kickoff summary to TALK.md with:
+- Status
+- Decision
+- Action
+- Risks/Questions
+- Next owner
+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/init.js

@@ -183,6 +183,7 @@ export async function initCommand(opts) {
     project,
     agents,
     log: 'log.md',
+    talk_file: 'TALK.md',
     state_file: 'state.md',
     history_file: 'history.jsonl',
     rules: {
@@ -205,6 +206,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'state.md'), `# ${project} — Current State\n\n## Architecture\n\n(Agents update this each turn with current decisions.)\n\n## Active Work\n\n(What's in progress right now.)\n\n## Open Issues\n\n(Bugs, blockers, risks.)\n\n## Next Steps\n\n(What should happen next.)\n`);
   writeFileSync(join(dir, 'history.jsonl'), '');
   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, 'TALK.md'), `# ${project} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n## How to write entries\n\nUse this exact structure:\n\n## Turn N — <agent_id> (<role>)\n- Status:\n- Decision:\n- Action:\n- Risks/Questions:\n- Next owner:\n\n---\n\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/', '.agentxchain-workspaces/'];
@@ -253,7 +255,7 @@ export async function initCommand(opts) {
   console.log(`    ${chalk.dim('├──')} agentxchain.json  ${chalk.dim(`(${agentCount} agents)`)}`);
   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('├──')} TALK.md / log.md / HUMAN_TASKS.md`);
   console.log(`    ${chalk.dim('├──')} .planning/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md / PM_SIGNOFF.md`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} research/ / phases/`);

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

@@ -15,7 +15,7 @@ export function generateVSCodeFiles(dir, config) {
 
   for (const id of agentIds) {
     const agent = config.agents[id];
-    const md = buildAgentMd(id, agent, config, agentIds);
+    const md = buildAgentMd(id, agent, config, agentIds, dir);
     writeFileSync(join(agentsDir, `${id}.agent.md`), md);
   }
 
@@ -33,13 +33,14 @@ export function generateVSCodeFiles(dir, config) {
   return { agentsDir, hooksDir, scriptsDir, agentCount: agentIds.length };
 }
 
-function buildAgentMd(agentId, agentDef, config, allAgentIds) {
+function buildAgentMd(agentId, agentDef, config, allAgentIds, projectRoot) {
   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 talkFile = config.talk_file || 'TALK.md';
   const useSplit = config.state_file || config.history_file;
 
   const handoffs = otherAgents.map(otherId => {
@@ -77,10 +78,12 @@ hooks:
     ? `Read these files at the start of your turn:
 - \`${stateFile}\` — living project state (primary context)
 - \`${historyFile}\` — last 3 lines for recent turns
+- \`${talkFile}\` — team handoff updates (read latest entries)
 - \`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)
+- \`${talkFile}\` — team handoff updates (read latest entries)
 - \`lock.json\` — current lock holder
 - \`state.json\` — phase and blocked status`;
 
@@ -90,13 +93,15 @@ hooks:
 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.`
+4. Append one handoff entry to \`${talkFile}\` with: Turn, Status, Decision, Action, Risks/Questions, Next owner.
+5. 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.`;
+3. Append one handoff entry to \`${talkFile}\` with: Turn, Status, Decision, Action, Risks/Questions, Next owner.
+4. 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.`
@@ -110,6 +115,15 @@ ${agentDef.mandate}
 
 ---
 
+## Project boundary
+
+- Project root: \`${projectRoot}\`
+- Work only inside this project folder.
+- Never scan unrelated local directories.
+- Start your turn by checking \`pwd\`.
+
+---
+
 ## Project documentation
 
 Read the files relevant to your role in the \`.planning/\` folder:
@@ -128,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

@@ -1,5 +1,6 @@
-export function generatePollingPrompt(agentId, agentDef, config) {
+export function generatePollingPrompt(agentId, agentDef, config, projectRoot = '.') {
   const logFile = config.log || 'log.md';
+  const talkFile = config.talk_file || 'TALK.md';
   const maxClaims = config.rules?.max_consecutive_claims || 2;
   const verifyCmd = config.rules?.verify_command || null;
   const stateFile = config.state_file || 'state.md';
@@ -19,10 +20,12 @@ export function generatePollingPrompt(agentId, agentDef, config) {
     ? `READ THESE FILES:
 - "${stateFile}" — the living project state. Read fully. Primary context.
 - "${historyFile}" — turn history. Read last 3 lines for recent context.
+- "${talkFile}" — team handoff updates. Read the latest 5 entries.
 - lock.json — who holds the lock.
 - state.json — phase and blocked status.`
     : `READ THESE FILES:
 - "${logFile}" — the message log. Read last few messages.
+- "${talkFile}" — team handoff updates. Read the latest 5 entries.
 - lock.json — who holds the lock.
 - state.json — phase and blocked status.`;
 
@@ -32,7 +35,9 @@ a. Do your actual work: write code, create files, run commands, make decisions.
 b. Update "${stateFile}" — OVERWRITE with current project state.
 c. Append ONE line to "${historyFile}":
    {"turn": N, "agent": "${agentId}", "summary": "what you did", "files_changed": [...], "verify_result": "pass|fail|skipped", "timestamp": "ISO8601"}
-d. Update state.json if phase or blocked status changed.`
+d. Append ONE handoff entry to "${talkFile}" with:
+   Turn, Status, Decision, Action, Risks/Questions, Next owner.
+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.
 b. Append ONE message to ${logFile}:
@@ -42,7 +47,9 @@ b. Append ONE message to ${logFile}:
    **Decision:** What you decided and why.
    **Action:** What you did. Commands, files, results.
    **Next:** What the next agent should focus on.
-c. Update state.json if phase or blocked status changed.`;
+c. Append ONE handoff entry to "${talkFile}" with:
+   Turn, Status, Decision, Action, Risks/Questions, Next owner.
+d. Update state.json if phase or blocked status changed.`;
 
   const verifySection = verifyCmd
     ? `
@@ -58,6 +65,15 @@ ${agentDef.mandate}
 
 ---
 
+PROJECT ROOT (strict boundary):
+- Absolute project root: "${projectRoot}"
+- You MUST work only inside this project root.
+- Do NOT scan your home directory or unrelated folders.
+- If unsure, run: pwd
+- If not in project root, run: cd "${projectRoot}"
+
+---
+
 PROJECT DOCUMENTATION (.planning/ folder):
 
 These files give you project context. Read the ones relevant to your role.
@@ -91,23 +107,24 @@ ${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
+   - If not inside "${projectRoot}", run: cd "${projectRoot}"
+   - Never run broad searches outside this project root.
 
 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}
@@ -121,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.`;
 }

package/src/lib/validation.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 export function validateProject(root, config, opts = {}) {
   const mode = opts.mode || 'full';
   const expectedAgent = opts.expectedAgent || null;
+  const talkFile = config.talk_file || 'TALK.md';
 
   const errors = [];
   const warnings = [];
@@ -18,6 +19,7 @@ export function validateProject(root, config, opts = {}) {
     '.planning/qa/UX-AUDIT.md',
     '.planning/qa/ACCEPTANCE-MATRIX.md',
     '.planning/qa/REGRESSION-LOG.md',
+    talkFile,
     'state.md',
     'history.jsonl',
     'lock.json',
@@ -56,6 +58,10 @@ export function validateProject(root, config, opts = {}) {
   errors.push(...history.errors);
   warnings.push(...history.warnings);
 
+  const talk = validateTalkFile(root, talkFile, { requireEntry: mode !== 'kickoff' });
+  errors.push(...talk.errors);
+  warnings.push(...talk.warnings);
+
   const qaSignals = validateQaArtifacts(root);
   warnings.push(...qaSignals.warnings);
 
@@ -160,6 +166,26 @@ function validateQaArtifacts(root) {
   return result;
 }
 
+function validateTalkFile(root, talkFile, opts) {
+  const result = { errors: [], warnings: [] };
+  const text = readText(root, talkFile);
+  if (!text) {
+    result.errors.push(`${talkFile} is missing or unreadable.`);
+    return result;
+  }
+
+  const hasTurnEntry = /##\s*Turn\s+\d+/i.test(text);
+  if (!hasTurnEntry) {
+    if (opts.requireEntry) {
+      result.errors.push(`${talkFile} has no turn entries.`);
+    } else {
+      result.warnings.push(`${talkFile} has no turn entries yet.`);
+    }
+  }
+
+  return result;
+}
+
 function readText(root, rel) {
   const path = join(root, rel);
   if (!existsSync(path)) return null;