agentxchain 0.8.3 → 0.8.5

package/README.md

@@ -20,30 +20,25 @@ npx agentxchain init
 # 1. Create a project (interactive template selection)
 agentxchain init
 
-# 2. PM-first kickoff (human + PM align scope first)
+# 2. Run guided PM-first kickoff wizard
 cd my-project/
-agentxchain start --agent pm
-
-# 3. Launch remaining agents after planning is clear
-agentxchain start --remaining
-
-# 4. Start supervisor (watch + auto-nudge)
-agentxchain supervise --autonudge
-
-# 5. Release the human lock — agents start claiming turns
-agentxchain release
+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 |
 |---------|-------------|
 | `init` | Create project folder with agents, protocol files, and templates |
+| `kickoff` | Guided PM-first flow: PM kickoff, validate, launch remaining, release |
 | `start` | Open a Cursor window per agent + copy prompts to clipboard |
 | `supervise` | Run watcher and optional AppleScript auto-nudge together |
 | `generate` | Regenerate agent files from `agentxchain.json` |
+| `validate` | Enforce PM signoff + waves/phases + turn artifact schema |
 | `status` | Show lock holder, phase, turn number, agents |
 | `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
 | `claim` | Human takes control (agents stop claiming) |
@@ -64,9 +59,15 @@ agentxchain start --ide claude-code # Claude Code — spawns CLI processes
 ### Additional flags
 
 ```bash
+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 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 watch --daemon          # run watch in background
 agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
 agentxchain supervise --autonudge --send   # auto-press Enter after paste
@@ -110,14 +111,15 @@ Notes:
 - Grant Accessibility permissions to Terminal and Cursor
 - The script watches `.agentxchain-trigger.json`, which is written by `agentxchain watch`
 - `run-autonudge.sh` now requires watch to be running first
+- The script only nudges when it finds a unique matching agent window (no random fallback)
 
 ## How it works
 
 ### Cursor mode (default)
 
-1. `agentxchain start` opens a **separate Cursor window** for each agent
+1. `agentxchain kickoff` launches PM first for human-product alignment
 2. Each window gets a unique prompt copied to clipboard
-3. Recommended first-run flow: `start --agent pm` (kickoff), then `start --remaining`
+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
 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

package/bin/agentxchain.js

@@ -15,6 +15,8 @@ import { claimCommand, releaseCommand } from '../src/commands/claim.js';
 import { generateCommand } from '../src/commands/generate.js';
 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -47,6 +49,15 @@ program
   .option('--dry-run', 'Print what would be launched without doing it')
   .action(startCommand);
 
+program
+  .command('kickoff')
+  .description('Guided PM-first first-run workflow')
+  .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
+  .option('--send', 'When using Cursor auto-nudge, auto-send nudges')
+  .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
+  .option('--no-autonudge', 'Skip auto-nudge supervisor prompt')
+  .action(kickoffCommand);
+
 program
   .command('stop')
   .description('Stop all running agent sessions')
@@ -102,4 +113,12 @@ program
   .description('Check local environment and first-run readiness')
   .action(doctorCommand);
 
+program
+  .command('validate')
+  .description('Validate Get Shit Done docs and QA protocol artifacts')
+  .option('--mode <mode>', 'Validation mode: kickoff, turn, full', 'full')
+  .option('--agent <id>', 'Expected agent for last history entry (turn mode)')
+  .option('-j, --json', 'Output as JSON')
+  .action(validateCommand);
+
 program.parse();

package/package.json

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

package/scripts/agentxchain-autonudge.applescript

@@ -58,7 +58,11 @@ on nudgeAgent(agentId, turnNum)
 
   tell application "Cursor" to activate
   delay 0.5
-  my focusAgentWindow(agentId)
+  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
+  end if
   delay 0.2
 
   tell application "System Events"
@@ -85,23 +89,34 @@ on focusAgentWindow(agentId)
     tell process "Cursor"
       set frontmost to true
 
-      set didRaise to false
+      set matchedIndexes to {}
+      set idx to 0
       repeat with w in windows
+        set idx to idx + 1
         try
           set wn to name of w as text
-          if wn contains agentId then
-            perform action "AXRaise" of w
-            set didRaise to true
-            exit repeat
+          if my isStrongWindowMatch(wn, agentId) then
+            set end of matchedIndexes to idx
           end if
         end try
       end repeat
 
-      if didRaise is false then
+      if (count of matchedIndexes) = 1 then
         try
-          perform action "AXRaise" of window 1
+          set targetIndex to item 1 of matchedIndexes
+          perform action "AXRaise" of window targetIndex
+          return true
         end try
+      else if (count of matchedIndexes) > 1 then
+        return false
       end if
     end tell
   end tell
+  return false
 end focusAgentWindow
+
+on isStrongWindowMatch(windowName, agentId)
+  set tokenA to ".agentxchain-workspaces/" & agentId
+  if windowName contains tokenA then return true
+  return false
+end isStrongWindowMatch

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:
@@ -171,8 +175,18 @@ Actions:
 - core workflow
 - MVP boundary
 - success metric
-3) Update planning docs with concrete acceptance criteria.
-4) Do NOT start round-robin agent handoffs yet.
+3) 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:
+- Set "Approved: YES" only when human agrees kickoff is complete.
+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/claim.js

@@ -1,4 +1,4 @@
-import { writeFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
@@ -36,6 +36,7 @@ export async function claimCommand(opts) {
     claimed_at: new Date().toISOString()
   };
   writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  clearBlockedState(root);
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock claimed by ${chalk.bold('human')} (turn ${lock.turn_number})`));
@@ -74,9 +75,24 @@ export async function releaseCommand(opts) {
     claimed_at: null
   };
   writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+  if (who === 'human') {
+    clearBlockedState(root);
+  }
 
   console.log('');
   console.log(chalk.green(`  ✓ Lock released by ${chalk.bold(who)} (turn ${newLock.turn_number})`));
   console.log(chalk.dim('  The Stop hook will coordinate the next agent turn in VS Code.'));
   console.log('');
 }
+
+function clearBlockedState(root) {
+  const statePath = join(root, 'state.json');
+  if (!existsSync(statePath)) return;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (state.blocked || state.blocked_on) {
+      const next = { ...state, blocked: false, blocked_on: null };
+      writeFileSync(statePath, JSON.stringify(next, null, 2) + '\n');
+    }
+  } catch {}
+}

package/src/commands/doctor.js

@@ -3,6 +3,7 @@ import { execSync } from 'child_process';
 import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function doctorCommand() {
   const result = loadConfig();
@@ -21,6 +22,7 @@ export async function doctorCommand() {
   checks.push(checkBinary('jq', 'jq installed (required for auto-nudge)'));
   checks.push(checkBinary('osascript', 'osascript available (required for auto-nudge, macOS)'));
   checks.push(checkPm(config));
+  checks.push(checkValidation(root, config));
   checks.push(checkWatchProcess());
   checks.push(checkTrigger(root));
   checks.push(checkAccessibility());
@@ -130,3 +132,15 @@ function checkAccessibility() {
     };
   }
 }
+
+function checkValidation(root, config) {
+  const validation = validateProject(root, config, { mode: 'kickoff' });
+  if (validation.ok) {
+    return { name: 'kickoff validation', level: 'pass', detail: 'PM signoff + waves/phases look ready' };
+  }
+  return {
+    name: 'kickoff validation',
+    level: 'warn',
+    detail: `Run \`agentxchain validate --mode kickoff\` (${validation.errors.length} issue(s))`
+  };
+}

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/'];
@@ -229,6 +231,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, '.planning', 'REQUIREMENTS.md'), `# Requirements — ${project}\n\n## v1 (MVP)\n\n(PM fills this: numbered list of requirements. Each requirement has one-sentence acceptance criteria.)\n\n| # | Requirement | Acceptance criteria | Phase | Status |\n|---|-------------|-------------------|-------|--------|\n| 1 | | | | Pending |\n\n## v2 (Future)\n\n(Out of scope for MVP. Captured here so they don't creep in.)\n\n## Out of scope\n\n(Explicitly not building.)\n`);
 
   writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${project}\n\n## Phases\n\n| Phase | Description | Status | Requirements |\n|-------|-------------|--------|-------------|\n| 1 | Discovery + setup | In progress | — |\n\n(PM updates this as phases are planned and completed.)\n`);
+  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${project}\n\nApproved: NO\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
 
   // QA structure
   writeFileSync(join(dir, '.planning', 'qa', 'TEST-COVERAGE.md'), `# Test Coverage — ${project}\n\n## Coverage Map\n\n| Feature / Area | Unit tests | Integration tests | E2E tests | Manual QA | UX audit | Status |\n|---------------|-----------|------------------|----------|----------|---------|--------|\n| (QA fills this as testing progresses) | | | | | | |\n\n## Coverage gaps\n\n(Areas with no tests or insufficient coverage.)\n`);
@@ -252,9 +255,9 @@ 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`);
+  console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} PROJECT.md / REQUIREMENTS.md / ROADMAP.md / PM_SIGNOFF.md`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('├──')} research/ / phases/`);
   console.log(`    ${chalk.dim('│')}    ${chalk.dim('└──')} qa/  ${chalk.dim('TEST-COVERAGE / BUGS / UX-AUDIT / ACCEPTANCE-MATRIX')}`);
   console.log(`    ${chalk.dim('├──')} .github/agents/  ${chalk.dim(`(${agentCount} .agent.md files)`)}`);

package/src/commands/kickoff.js

@@ -0,0 +1,119 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
+import { startCommand } from './start.js';
+import { releaseCommand } from './claim.js';
+import { superviseCommand } from './supervise.js';
+
+export async function kickoffCommand(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 pmId = pickPmAgentId(config);
+  const ide = opts.ide || 'cursor';
+
+  if (!pmId) {
+    console.log(chalk.red('No agents configured.'));
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Kickoff Wizard'));
+  console.log(chalk.dim(`  Project: ${config.project}`));
+  console.log(chalk.dim(`  PM agent: ${pmId}`));
+  console.log(chalk.dim(`  IDE: ${ide}`));
+  console.log('');
+
+  await startCommand({ ide, agent: pmId, remaining: false, dryRun: false });
+
+  console.log(chalk.cyan('  PM kickoff launched.'));
+  console.log(chalk.dim('  Discuss product scope with PM, then mark .planning/PM_SIGNOFF.md as Approved: YES.'));
+  console.log('');
+
+  const { readyForValidation } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'readyForValidation',
+    message: 'Is PM kickoff complete and signoff updated?',
+    default: false
+  }]);
+
+  if (!readyForValidation) {
+    console.log('');
+    console.log(chalk.yellow('  Kickoff paused.'));
+    console.log(chalk.dim('  Resume later with: agentxchain validate --mode kickoff && agentxchain start --remaining'));
+    console.log('');
+    return;
+  }
+
+  const validation = validateProject(root, config, { mode: 'kickoff' });
+  if (!validation.ok) {
+    console.log('');
+    console.log(chalk.red('  Kickoff validation failed.'));
+    for (const err of validation.errors) {
+      console.log(chalk.dim(`   - ${err}`));
+    }
+    if (validation.warnings.length > 0) {
+      console.log(chalk.yellow('  Warnings:'));
+      for (const warn of validation.warnings) {
+        console.log(chalk.dim(`   - ${warn}`));
+      }
+    }
+    console.log('');
+    console.log(chalk.bold('  Run: agentxchain validate --mode kickoff'));
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log(chalk.green('  ✓ Kickoff validation passed.'));
+  console.log('');
+
+  await startCommand({ ide, remaining: true, agent: undefined, dryRun: false });
+
+  const { doRelease } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'doRelease',
+    message: 'Release human lock now so agents can start?',
+    default: true
+  }]);
+
+  if (doRelease) {
+    await releaseCommand({ force: false });
+  } else {
+    console.log(chalk.dim('  Lock remains with human. Run `agentxchain release` when ready.'));
+  }
+
+  if (ide === 'cursor' && opts.autonudge !== false) {
+    const { startSupervisor } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'startSupervisor',
+      message: 'Start supervisor with auto-nudge now?',
+      default: true
+    }]);
+
+    if (startSupervisor) {
+      await superviseCommand({
+        autonudge: true,
+        send: !!opts.send,
+        interval: opts.interval || '3'
+      });
+    } else {
+      console.log('');
+      console.log(chalk.dim('  Start later with: agentxchain supervise --autonudge'));
+      console.log('');
+    }
+  }
+}
+
+function pickPmAgentId(config) {
+  if (config.agents?.pm) return 'pm';
+  for (const [id, def] of Object.entries(config.agents || {})) {
+    const name = String(def?.name || '').toLowerCase();
+    if (name.includes('product manager')) return id;
+  }
+  return Object.keys(config.agents || {})[0] || null;
+}

package/src/commands/start.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -30,6 +31,22 @@ export async function startCommand(opts) {
     process.exit(1);
   }
 
+  if (opts.remaining) {
+    const kickoffValidation = validateProject(root, config, { mode: 'kickoff' });
+    if (!kickoffValidation.ok) {
+      console.log(chalk.red('  PM kickoff is incomplete. Cannot run --remaining yet.'));
+      console.log(chalk.dim('  Fix these first:'));
+      for (const e of kickoffValidation.errors) {
+        console.log(chalk.dim(`   - ${e}`));
+      }
+      console.log('');
+      console.log(chalk.dim('  Suggested next step: complete .planning/PM_SIGNOFF.md and roadmap waves/phases, then run:'));
+      console.log(chalk.bold('    agentxchain validate --mode kickoff'));
+      console.log('');
+      process.exit(1);
+    }
+  }
+
   const launchConfig = buildLaunchConfig(config, opts);
   const launchAgentIds = Object.keys(launchConfig.agents || {});
   const launchCount = launchAgentIds.length;

package/src/commands/validate.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+import { validateProject } from '../lib/validation.js';
+
+export async function validateCommand(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 mode = opts.mode || 'full';
+  const validation = validateProject(root, config, {
+    mode,
+    expectedAgent: opts.agent || null
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(validation, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
+    console.log(chalk.dim('  ' + '─'.repeat(44)));
+    console.log(chalk.dim(`  Root: ${root}`));
+    console.log('');
+
+    if (validation.ok) {
+      console.log(chalk.green('  ✓ Validation passed.'));
+    } else {
+      console.log(chalk.red(`  ✗ Validation failed (${validation.errors.length} errors).`));
+    }
+
+    if (validation.errors.length > 0) {
+      console.log('');
+      console.log(chalk.red('  Errors:'));
+      for (const e of validation.errors) console.log(`    - ${e}`);
+    }
+
+    if (validation.warnings.length > 0) {
+      console.log('');
+      console.log(chalk.yellow('  Warnings:'));
+      for (const w of validation.warnings) console.log(`    - ${w}`);
+    }
+    console.log('');
+  }
+
+  if (!validation.ok) process.exit(1);
+}

package/src/commands/watch.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 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';
 
 export async function watchCommand(opts) {
   if (opts.daemon && process.env.AGENTXCHAIN_WATCH_DAEMON !== '1') {
@@ -82,6 +83,20 @@ export async function watchCommand(opts) {
       }
 
       if (stateKey !== lastState) {
+        if (lock.last_released_by && config.agents?.[lock.last_released_by]) {
+          const validation = validateProject(root, config, {
+            mode: 'turn',
+            expectedAgent: lock.last_released_by
+          });
+          if (!validation.ok) {
+            log('warn', `Validation failed after ${lock.last_released_by}. Handing lock to HUMAN.`);
+            blockOnValidation(root, lock, config, validation);
+            sendNotification('Validation failed. Human action required: run agentxchain validate.');
+            lastState = null;
+            return;
+          }
+        }
+
         const next = pickNextAgent(lock, config);
         log('free', `Lock free (released by ${lock.last_released_by || 'none'}). Next: ${chalk.bold(next)}.`);
         writeTrigger(root, next, lock, config);
@@ -142,6 +157,41 @@ function writeTrigger(root, agentId, lock, config) {
   }, null, 2) + '\n');
 }
 
+function blockOnValidation(root, lock, config, validation) {
+  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 message = validation.errors[0] || 'Validation failed';
+      const nextState = {
+        ...current,
+        blocked: true,
+        blocked_on: `validation: ${message}`
+      };
+      writeFileSync(statePath, JSON.stringify(nextState, null, 2) + '\n');
+    } catch {}
+  }
+
+  const logFile = config.log || 'log.md';
+  const logPath = join(root, logFile);
+  if (existsSync(logPath)) {
+    const summary = validation.errors.map(e => `- ${e}`).join('\n');
+    appendFileSync(
+      logPath,
+      `\n---\n\n### [system] (Watch Validation) | Turn ${lock.turn_number}\n\n**Status:** Validation failed after ${lock.last_released_by}.\n\n**Action:** Lock assigned to human for intervention.\n\n**Errors:**\n${summary}\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:

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.
@@ -75,6 +91,14 @@ These files give you project context. Read the ones relevant to your role.
 
 When your role requires it, CREATE or UPDATE these files.
 
+GET SHIT DONE FRAMEWORK (mandatory):
+- Plan in waves and phases (not ad hoc tasks).
+- Keep .planning/ROADMAP.md updated with explicit Wave and Phase sections.
+- For every active phase, maintain:
+  - .planning/phases/phase-N/PLAN.md
+  - .planning/phases/phase-N/TESTS.md
+- QA must keep acceptance matrix and UX audit current with evidence, not placeholders.
+
 ---
 
 TEAM ROTATION: ${agentIds.join(' → ')} → (repeat)
@@ -85,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?
@@ -108,6 +137,10 @@ YOUR LOOP (run forever, never exit, never say "I'm done"):
 
    ${writeSection}${verifySection}
 
+   VALIDATE (mandatory before release):
+   Run: agentxchain validate --mode turn --agent ${agentId}
+   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}
    THIS MUST BE THE LAST FILE YOU WRITE.

package/src/lib/validation.js

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+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 = [];
+
+  const mustExist = [
+    '.planning/PROJECT.md',
+    '.planning/REQUIREMENTS.md',
+    '.planning/ROADMAP.md',
+    '.planning/PM_SIGNOFF.md',
+    '.planning/qa/TEST-COVERAGE.md',
+    '.planning/qa/BUGS.md',
+    '.planning/qa/UX-AUDIT.md',
+    '.planning/qa/ACCEPTANCE-MATRIX.md',
+    '.planning/qa/REGRESSION-LOG.md',
+    talkFile,
+    'state.md',
+    'history.jsonl',
+    'lock.json',
+    'state.json'
+  ];
+
+  for (const rel of mustExist) {
+    if (!existsSync(join(root, rel))) {
+      errors.push(`Missing required file: ${rel}`);
+    }
+  }
+
+  const signoff = readText(root, '.planning/PM_SIGNOFF.md');
+  const signoffApproved = /approved\s*:\s*yes/i.test(signoff || '');
+  if (!signoffApproved) {
+    if (mode === 'kickoff' || mode === 'full') {
+      errors.push('PM signoff is not approved. Set "Approved: YES" in .planning/PM_SIGNOFF.md.');
+    } else {
+      warnings.push('PM signoff is not approved.');
+    }
+  }
+
+  const roadmap = readText(root, '.planning/ROADMAP.md') || '';
+  if (!/\bwave\b/i.test(roadmap)) {
+    errors.push('ROADMAP.md must define at least one Wave.');
+  }
+  if (!/\bphase\b/i.test(roadmap)) {
+    errors.push('ROADMAP.md must define at least one Phase.');
+  }
+
+  const phaseStatus = validatePhaseArtifacts(root);
+  errors.push(...phaseStatus.errors);
+  warnings.push(...phaseStatus.warnings);
+
+  const history = validateHistory(root, config, { expectedAgent, requireEntry: mode !== 'kickoff' });
+  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);
+
+  return { ok: errors.length === 0, mode, errors, warnings };
+}
+
+function validatePhaseArtifacts(root) {
+  const result = { errors: [], warnings: [] };
+  const phasesDir = join(root, '.planning', 'phases');
+  if (!existsSync(phasesDir)) {
+    result.errors.push('Missing .planning/phases directory.');
+    return result;
+  }
+
+  const entries = safeReadDir(phasesDir).filter(name => !name.startsWith('.'));
+  if (entries.length === 0) {
+    result.errors.push('No phase artifacts found. Add .planning/phases/phase-*/PLAN.md and TESTS.md.');
+    return result;
+  }
+
+  let hasAnyPlan = false;
+  let hasAnyTests = false;
+  for (const name of entries) {
+    const plan = join(phasesDir, name, 'PLAN.md');
+    const tests = join(phasesDir, name, 'TESTS.md');
+    if (existsSync(plan)) hasAnyPlan = true;
+    if (existsSync(tests)) hasAnyTests = true;
+  }
+
+  if (!hasAnyPlan) result.errors.push('No phase PLAN.md found under .planning/phases/.');
+  if (!hasAnyTests) result.errors.push('No phase TESTS.md found under .planning/phases/.');
+  return result;
+}
+
+function validateHistory(root, config, opts) {
+  const result = { errors: [], warnings: [] };
+  const historyPath = join(root, 'history.jsonl');
+  if (!existsSync(historyPath)) {
+    result.errors.push('history.jsonl is missing.');
+    return result;
+  }
+
+  const lines = (readFileSync(historyPath, 'utf8') || '')
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean);
+
+  if (lines.length === 0) {
+    if (opts.requireEntry) {
+      result.errors.push('history.jsonl has no entries.');
+    } else {
+      result.warnings.push('history.jsonl has no entries yet.');
+    }
+    return result;
+  }
+
+  const lastRaw = lines[lines.length - 1];
+  let last;
+  try {
+    last = JSON.parse(lastRaw);
+  } catch {
+    result.errors.push('Last history.jsonl entry is not valid JSON.');
+    return result;
+  }
+
+  const requiredFields = ['turn', 'agent', 'summary', 'files_changed', 'verify_result', 'timestamp'];
+  for (const f of requiredFields) {
+    if (!(f in last)) result.errors.push(`Last history entry missing field: ${f}`);
+  }
+
+  if (last.agent && !config.agents?.[last.agent]) {
+    result.errors.push(`Last history agent "${last.agent}" is not in agentxchain.json.`);
+  }
+  if (!Array.isArray(last.files_changed)) {
+    result.errors.push('Last history entry: files_changed must be an array.');
+  }
+  if (last.verify_result && !['pass', 'fail', 'skipped'].includes(last.verify_result)) {
+    result.errors.push('Last history entry: verify_result must be pass|fail|skipped.');
+  }
+  if (opts.expectedAgent && last.agent !== opts.expectedAgent) {
+    result.errors.push(`Last history entry agent "${last.agent}" does not match expected "${opts.expectedAgent}".`);
+  }
+
+  return result;
+}
+
+function validateQaArtifacts(root) {
+  const result = { warnings: [] };
+  const checks = [
+    ['.planning/qa/TEST-COVERAGE.md', /\(QA fills this as testing progresses\)/i, 'TEST-COVERAGE.md still looks uninitialized'],
+    ['.planning/qa/ACCEPTANCE-MATRIX.md', /\(QA fills this from REQUIREMENTS\.md\)/i, 'ACCEPTANCE-MATRIX.md still looks uninitialized'],
+    ['.planning/qa/UX-AUDIT.md', /\(QA adds UX issues here\)/i, 'UX-AUDIT.md issues table appears unmodified']
+  ];
+
+  for (const [rel, placeholderRegex, message] of checks) {
+    const text = readText(root, rel);
+    if (text && placeholderRegex.test(text)) {
+      result.warnings.push(message);
+    }
+  }
+
+  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;
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function safeReadDir(path) {
+  try {
+    return readdirSync(path);
+  } catch {
+    return [];
+  }
+}