agentxchain 0.8.2 → 0.8.4

package/src/adapters/cursor-local.js

@@ -9,8 +9,13 @@ export async function launchCursorLocal(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
   const agentEntries = Object.entries(agents);
   const total = agentEntries.length;
+  const selectedAgent = opts.agent ? agents[opts.agent] : null;
+  const isPmKickoff = !!selectedAgent && isPmLike(opts.agent, selectedAgent) && !opts.remaining;
 
   console.log(chalk.bold(`  Setting up ${total} agents: ${Object.keys(agents).join(', ')}`));
+  if (isPmKickoff) {
+    console.log(chalk.dim('  PM kickoff mode: start with human-PM planning before launching the full team.'));
+  }
   console.log('');
 
   const promptDir = join(root, '.agentxchain-prompts');
@@ -18,7 +23,9 @@ export async function launchCursorLocal(config, root, opts) {
 
   // Save all prompts first
   for (const [id, agent] of agentEntries) {
-    const prompt = generatePollingPrompt(id, agent, config);
+    const prompt = isPmKickoff
+      ? generateKickoffPrompt(id, agent, config)
+      : generatePollingPrompt(id, agent, config);
     writeFileSync(join(promptDir, `${id}.prompt.md`), prompt);
   }
 
@@ -28,7 +35,9 @@ export async function launchCursorLocal(config, root, opts) {
 
   for (let i = 0; i < agentEntries.length; i++) {
     const [id, agent] = agentEntries[i];
-    const prompt = generatePollingPrompt(id, agent, config);
+    const prompt = isPmKickoff
+      ? generateKickoffPrompt(id, agent, config)
+      : generatePollingPrompt(id, agent, config);
 
     // Create symlink: .agentxchain-workspaces/<id> -> project root
     const agentWorkspace = join(workspacesDir, id);
@@ -57,8 +66,13 @@ export async function launchCursorLocal(config, root, opts) {
     console.log(`  ${chalk.bold('In the new Cursor window:')}`);
     console.log(`    1. Open chat (${chalk.bold('Cmd+L')})`);
     console.log(`    2. Paste the prompt (${chalk.bold('Cmd+V')})`);
-    console.log(`    3. ${chalk.bold('Select Agent mode')} (not Ask/Edit)`);
-    console.log(`    4. Send it (${chalk.bold('Enter')})`);
+    if (isPmKickoff) {
+      console.log(`    3. ${chalk.bold('Select Agent mode')} and discuss requirements with PM`);
+      console.log(`    4. Update planning docs together (PROJECT / REQUIREMENTS / ROADMAP)`);
+    } else {
+      console.log(`    3. ${chalk.bold('Select Agent mode')} (not Ask/Edit)`);
+      console.log(`    4. Send it (${chalk.bold('Enter')})`);
+    }
 
     if (i < agentEntries.length - 1) {
       console.log('');
@@ -78,12 +92,20 @@ export async function launchCursorLocal(config, root, opts) {
   console.log(chalk.green(`  ✓ All ${total} agents launched in separate Cursor windows.`));
   console.log('');
   console.log(`  ${chalk.cyan('Now run:')}`);
-  console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# release human lock — agents start claiming turns')}`);
+  if (isPmKickoff) {
+    console.log(`    ${chalk.bold('agentxchain start --remaining')} ${chalk.dim('# launch the rest of the team when PM plan is ready')}`);
+    console.log(`    ${chalk.bold('agentxchain supervise --autonudge')} ${chalk.dim('# start watch + auto-nudge')}`);
+    console.log(`    ${chalk.bold('agentxchain release')} ${chalk.dim('# release human lock to begin team turns')}`);
+  } else {
+    console.log(`    ${chalk.bold('agentxchain supervise --autonudge')} ${chalk.dim('# recommended: watch + auto-nudge in one command')}`);
+    console.log(`    ${chalk.bold('agentxchain release')} ${chalk.dim('# release human lock — agents start claiming turns')}`);
+  }
   console.log('');
   console.log(`  ${chalk.dim('Other commands:')}`);
   console.log(`    ${chalk.bold('agentxchain status')}   ${chalk.dim('# check who holds the lock')}`);
   console.log(`    ${chalk.bold('agentxchain claim')}    ${chalk.dim('# pause agents and take control')}`);
-  console.log(`    ${chalk.bold('agentxchain watch')}    ${chalk.dim('# optional: TTL safety net')}`);
+  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('  Re-paste a prompt: cat .agentxchain-prompts/<agent>.prompt.md | pbcopy'));
@@ -124,3 +146,40 @@ function openCursorWindow(folderPath) {
     execSync(`cursor --new-window "${folderPath}"`, { stdio: 'ignore' });
   } catch {}
 }
+
+function isPmLike(agentId, agentDef) {
+  if (agentId === 'pm') return true;
+  const name = String(agentDef?.name || '').toLowerCase();
+  return name.includes('product manager');
+}
+
+function generateKickoffPrompt(agentId, agentDef, config) {
+  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.
+
+Actions:
+1) Read:
+- .planning/PROJECT.md
+- .planning/REQUIREMENTS.md
+- .planning/ROADMAP.md
+- state.md
+- lock.json
+2) Ask the human focused product questions until scope is clear:
+- target user
+- top pain point
+- core workflow
+- MVP boundary
+- success metric
+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) Do NOT start round-robin agent handoffs yet.
+
+Context:
+- Project: ${config.project}
+- Human currently holds lock.
+- Once planning is approved, human will launch remaining agents and run release.`;
+}

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

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from 'fs';
+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();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const lock = loadLock(root);
+  const checks = [];
+
+  checks.push(checkFile('agentxchain.json', existsSync(join(root, 'agentxchain.json')), 'Project config exists'));
+  checks.push(checkFile('lock.json', !!lock, 'Lock file exists'));
+  checks.push(checkBinary('cursor', 'Cursor CLI available (optional for non-macOS launch)'));
+  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());
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Doctor'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(chalk.dim(`  Project root: ${root}`));
+  console.log('');
+
+  for (const c of checks) {
+    const badge = c.level === 'pass'
+      ? chalk.green('PASS')
+      : c.level === 'warn'
+        ? chalk.yellow('WARN')
+        : chalk.red('FAIL');
+    console.log(`  ${badge}  ${c.name}`);
+    if (c.detail) console.log(`        ${chalk.dim(c.detail)}`);
+  }
+
+  const failCount = checks.filter(c => c.level === 'fail').length;
+  const warnCount = checks.filter(c => c.level === 'warn').length;
+
+  console.log('');
+  if (failCount === 0 && warnCount === 0) {
+    console.log(chalk.green('  ✓ Environment looks ready.'));
+  } else if (failCount === 0) {
+    console.log(chalk.yellow(`  Ready with warnings (${warnCount}).`));
+  } else {
+    console.log(chalk.red(`  Not ready: ${failCount} blocking issue(s).`));
+  }
+  console.log('');
+}
+
+function checkFile(name, ok, detail) {
+  return {
+    name,
+    level: ok ? 'pass' : 'fail',
+    detail: ok ? detail : `${name} is missing`
+  };
+}
+
+function checkBinary(cmd, detail) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' });
+    return { name: cmd, level: 'pass', detail };
+  } catch {
+    return { name: cmd, level: 'warn', detail: `${cmd} not found in PATH` };
+  }
+}
+
+function checkPm(config) {
+  if (config.agents?.pm) {
+    return { name: 'PM agent', level: 'pass', detail: 'pm exists in agentxchain.json' };
+  }
+  const hasPmLike = Object.values(config.agents || {}).some(a => String(a?.name || '').toLowerCase().includes('product manager'));
+  if (hasPmLike) {
+    return { name: 'PM agent', level: 'pass', detail: 'Product Manager role detected' };
+  }
+  return { name: 'PM agent', level: 'warn', detail: 'No explicit PM agent. PM-first onboarding will be less clear.' };
+}
+
+function checkWatchProcess() {
+  try {
+    execSync('pgrep -f "agentxchain.*watch" >/dev/null', { stdio: 'ignore' });
+    return { name: 'watch process', level: 'pass', detail: 'watch appears to be running' };
+  } catch {
+    return { name: 'watch process', level: 'warn', detail: 'watch not running (start with `agentxchain watch` or `agentxchain supervise --autonudge`)' };
+  }
+}
+
+function checkTrigger(root) {
+  const triggerPath = join(root, '.agentxchain-trigger.json');
+  if (!existsSync(triggerPath)) {
+    return { name: 'trigger file', level: 'warn', detail: '.agentxchain-trigger.json not found yet' };
+  }
+
+  try {
+    const raw = JSON.parse(readFileSync(triggerPath, 'utf8'));
+    const triggeredAt = new Date(raw.triggered_at).getTime();
+    const ageMs = Date.now() - triggeredAt;
+    if (Number.isFinite(triggeredAt) && ageMs <= 120000) {
+      return { name: 'trigger file', level: 'pass', detail: `fresh trigger (${Math.round(ageMs / 1000)}s ago)` };
+    }
+    return { name: 'trigger file', level: 'warn', detail: 'trigger file is stale; lock may not be advancing' };
+  } catch {
+    return { name: 'trigger file', level: 'warn', detail: 'trigger file exists but is invalid JSON' };
+  }
+}
+
+function checkAccessibility() {
+  if (process.platform !== 'darwin') {
+    return { name: 'macOS Accessibility', level: 'warn', detail: 'only checked on macOS' };
+  }
+
+  try {
+    execSync(
+      'osascript -e \'tell application "System Events" to get name of first process\'',
+      { stdio: 'pipe' }
+    );
+    return { name: 'macOS Accessibility', level: 'pass', detail: 'System Events access available' };
+  } catch {
+    return {
+      name: 'macOS Accessibility',
+      level: 'warn',
+      detail: 'Grant Accessibility to Terminal and Cursor in System Settings.'
+    };
+  }
+}
+
+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

@@ -229,6 +229,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`);
@@ -245,6 +246,7 @@ export async function initCommand(opts) {
   const vsResult = generateVSCodeFiles(dir, config);
 
   const agentCount = Object.keys(agents).length;
+  const kickoffId = pickPmKickoffId(agents);
   console.log('');
   console.log(chalk.green(`  ✓ Created ${chalk.bold(folderName)}/`));
   console.log('');
@@ -253,7 +255,7 @@ export async function initCommand(opts) {
   console.log(`    ${chalk.dim('├──')} state.json / state.md / history.jsonl`);
   console.log(`    ${chalk.dim('├──')} 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)`)}`);
@@ -264,7 +266,18 @@ export async function initCommand(opts) {
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
   console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
-  console.log(`    ${chalk.bold('agentxchain start')}    ${chalk.dim('# opens Cursor windows + copies agent prompts')}`);
-  console.log(`    ${chalk.bold('agentxchain release')}  ${chalk.dim('# release human lock — agents start working')}`);
+  console.log(`    ${chalk.bold(`agentxchain start --agent ${kickoffId}`)} ${chalk.dim('# PM-first kickoff: align scope with human')}`);
+  console.log(`    ${chalk.bold('agentxchain start --remaining')} ${chalk.dim('# launch rest of team after PM planning')}`);
+  console.log(`    ${chalk.bold('agentxchain supervise --autonudge')} ${chalk.dim('# watch + AppleScript nudge loop')}`);
+  console.log(`    ${chalk.bold('agentxchain release')} ${chalk.dim('# release human lock when you are ready')}`);
   console.log('');
 }
+
+function pickPmKickoffId(agents) {
+  if (agents.pm) return 'pm';
+  for (const [id, def] of Object.entries(agents || {})) {
+    const name = String(def?.name || '').toLowerCase();
+    if (name.includes('product manager')) return id;
+  }
+  return Object.keys(agents || {})[0] || 'pm';
+}

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,6 +1,6 @@
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
-import { generateSeedPrompt } from '../lib/seed-prompt.js';
+import { validateProject } from '../lib/validation.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -26,15 +26,52 @@ export async function startCommand(opts) {
     process.exit(1);
   }
 
+  if (opts.agent && opts.remaining) {
+    console.log(chalk.red('  --agent and --remaining cannot be used together.'));
+    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;
+
+  if (launchCount === 0) {
+    console.log(chalk.red('  No agents selected to launch.'));
+    if (opts.remaining) {
+      console.log(chalk.dim('  Tip: this usually means only PM exists.'));
+    }
+    process.exit(1);
+  }
+
   console.log('');
   console.log(chalk.bold(`  ${agentCount} agents configured for ${config.project}`));
+  if (opts.remaining) {
+    console.log(chalk.cyan(`  Launch mode: remaining agents (${launchCount})`));
+  } else if (opts.agent) {
+    console.log(chalk.cyan(`  Launch mode: single agent (${opts.agent})`));
+  }
   console.log('');
 
   if (opts.dryRun) {
     console.log(chalk.yellow('  DRY RUN — showing agents:'));
     console.log('');
-    for (const [id, agent] of Object.entries(config.agents)) {
-      if (opts.agent && opts.agent !== id) continue;
+    for (const [id, agent] of Object.entries(launchConfig.agents)) {
       console.log(`    ${chalk.cyan(id)} — ${agent.name}`);
       console.log(chalk.dim(`    ${agent.mandate.slice(0, 80)}...`));
       console.log('');
@@ -42,12 +79,21 @@ export async function startCommand(opts) {
     return;
   }
 
+  if (!opts.agent && !opts.remaining) {
+    const kickoffId = pickPmAgentId(config);
+    if (kickoffId) {
+      console.log(chalk.yellow(`  Tip: for first run, start with ${chalk.bold(`agentxchain start --agent ${kickoffId}`)}.`));
+      console.log(chalk.dim('  Then use `agentxchain start --remaining` once PM planning is complete.'));
+      console.log('');
+    }
+  }
+
   switch (ide) {
     case 'vscode': {
       console.log(chalk.green('  Agents are set up as VS Code custom agents.'));
       console.log('');
       console.log(chalk.dim('  Your agents in .github/agents/:'));
-      for (const [id, agent] of Object.entries(config.agents)) {
+      for (const [id, agent] of Object.entries(launchConfig.agents)) {
         console.log(`    ${chalk.cyan(id)}.agent.md — ${agent.name}`);
       }
       console.log('');
@@ -65,12 +111,12 @@ export async function startCommand(opts) {
     }
     case 'cursor': {
       const { launchCursorLocal } = await import('../adapters/cursor-local.js');
-      await launchCursorLocal(config, root, opts);
+      await launchCursorLocal(launchConfig, root, opts);
       break;
     }
     case 'claude-code': {
       const { launchClaudeCodeAgents } = await import('../adapters/claude-code.js');
-      await launchClaudeCodeAgents(config, root, opts);
+      await launchClaudeCodeAgents(launchConfig, root, opts);
       break;
     }
     default:
@@ -78,3 +124,38 @@ export async function startCommand(opts) {
       process.exit(1);
   }
 }
+
+function buildLaunchConfig(config, opts) {
+  if (opts.agent) {
+    return {
+      ...config,
+      agents: { [opts.agent]: config.agents[opts.agent] }
+    };
+  }
+
+  if (opts.remaining) {
+    const pmId = pickPmAgentId(config);
+    const agents = { ...config.agents };
+
+    if (pmId && agents[pmId]) {
+      delete agents[pmId];
+    } else {
+      const firstId = Object.keys(agents)[0];
+      if (firstId) delete agents[firstId];
+    }
+
+    return { ...config, agents };
+  }
+
+  return config;
+}
+
+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 null;
+}