agentxchain 0.8.4 → 0.8.5

package/README.md

@@ -27,6 +27,8 @@ 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.
 
+Agents are now required to maintain `TALK.md` as the human-readable handoff log each turn.
+
 ## Commands
 
 | Command | What it does |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "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);
@@ -153,16 +153,20 @@ 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:
 - .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:
@@ -176,7 +180,13 @@ Actions:
 - Create .planning/phases/phase-1/PLAN.md and TESTS.md.
 4) Update .planning/PM_SIGNOFF.md:
 - Set "Approved: YES" only when human agrees kickoff is complete.
-5) Do NOT start round-robin agent handoffs yet.
+5) Append kickoff summary to TALK.md with:
+- Status
+- Decision
+- Action
+- Risks/Questions
+- Next owner
+6) Do NOT start round-robin agent handoffs yet.
 
 Context:
 - Project: ${config.project}

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/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:

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.
@@ -93,6 +109,11 @@ ${turnCondition}
 
 YOUR LOOP (run forever, never exit, never say "I'm done"):
 
+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?

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;