agentxchain 0.8.2 → 0.8.3

package/README.md

@@ -20,18 +20,21 @@ npx agentxchain init
 # 1. Create a project (interactive template selection)
 agentxchain init
 
-# 2. Launch agents — opens a separate Cursor window per agent
+# 2. PM-first kickoff (human + PM align scope first)
 cd my-project/
-agentxchain start
+agentxchain start --agent pm
 
-# 3. For each window: paste the prompt (auto-copied to clipboard), select Agent mode, send
-#    The CLI walks you through one agent at a time.
+# 3. Launch remaining agents after planning is clear
+agentxchain start --remaining
 
-# 4. Release the human lock — agents start claiming turns
+# 4. Start supervisor (watch + auto-nudge)
+agentxchain supervise --autonudge
+
+# 5. Release the human lock — agents start claiming turns
 agentxchain release
 ```
 
-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. No external referee needed.
+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.
 
 ## Commands
 
@@ -39,8 +42,10 @@ Each agent runs in its own Cursor window with a self-polling loop. Agents check
 |---------|-------------|
 | `init` | Create project folder with agents, protocol files, and templates |
 | `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` |
 | `status` | Show lock holder, phase, turn number, agents |
+| `doctor` | Validate local setup (tools, trigger flow, accessibility checks) |
 | `claim` | Human takes control (agents stop claiming) |
 | `release` | Hand lock back to agents |
 | `stop` | Terminate running Claude Code agent sessions |
@@ -60,20 +65,62 @@ agentxchain start --ide claude-code # Claude Code — spawns CLI processes
 
 ```bash
 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 watch --daemon          # run watch in background
+agentxchain supervise --autonudge   # run watch + AppleScript nudge loop
+agentxchain supervise --autonudge --send   # auto-press Enter after paste
 agentxchain release --force         # force-release non-human holder lock
 ```
 
+## macOS auto-nudge (AppleScript)
+
+If you want the next agent chat to be nudged automatically when turn changes, use the built-in AppleScript helper.
+
+1) Keep watcher running in your project:
+
+```bash
+agentxchain watch
+# or use the combined command:
+agentxchain supervise --autonudge
+```
+
+2) In another terminal (from `cli/`), start auto-nudge:
+
+```bash
+bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project"
+```
+
+By default this is **paste-only** (safe mode): it opens chat and pastes the nudge message, but does not press Enter.
+
+3) Enable auto-send once confirmed:
+
+```bash
+bash scripts/run-autonudge.sh --project "/absolute/path/to/your-project" --send
+```
+
+Stop it anytime:
+
+```bash
+bash scripts/stop-autonudge.sh
+```
+
+Notes:
+- Requires macOS (`osascript`) and `jq` (`brew install jq`)
+- 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
+
 ## How it works
 
 ### Cursor mode (default)
 
 1. `agentxchain start` opens a **separate Cursor window** for each agent
 2. Each window gets a unique prompt copied to clipboard
-3. Agent prompts include a self-polling loop: read `lock.json` → check if it's my turn → claim → work → release → sleep 60s → repeat
-4. Agents know their rotation order from `agentxchain.json` and only claim when the previous agent released
-5. Human can `claim` to pause and `release` to resume anytime
+3. Recommended first-run flow: `start --agent pm` (kickoff), then `start --remaining`
+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
 
 ### VS Code mode
 

package/bin/agentxchain.js

@@ -13,6 +13,8 @@ import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -41,6 +43,7 @@ program
   .description('Launch agents in your IDE')
   .option('--ide <ide>', 'Target IDE: cursor, vscode, claude-code', 'cursor')
   .option('--agent <id>', 'Launch a specific agent only')
+  .option('--remaining', 'Launch all remaining agents except PM (for PM-first flow)')
   .option('--dry-run', 'Print what would be launched without doing it')
   .action(startCommand);
 
@@ -69,6 +72,14 @@ program
   .option('--daemon', 'Run in background mode')
   .action(watchCommand);
 
+program
+  .command('supervise')
+  .description('Run watch loop and optional auto-nudge together')
+  .option('--autonudge', 'Start AppleScript auto-nudge alongside watch')
+  .option('--send', 'Auto-send nudges (default is paste-only)')
+  .option('--interval <seconds>', 'Auto-nudge poll interval in seconds', '3')
+  .action(superviseCommand);
+
 program
   .command('claim')
   .description('Claim the lock as a human (take control)')
@@ -86,4 +97,9 @@ program
   .description('Update agentxchain CLI to the latest version')
   .action(updateCommand);
 
+program
+  .command('doctor')
+  .description('Check local environment and first-run readiness')
+  .action(doctorCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/",
     "README.md"
   ],
   "scripts": {

package/scripts/agentxchain-autonudge.applescript

@@ -0,0 +1,107 @@
+property projectRoot : ""
+property pollSeconds : 3
+property autoSend : false
+
+on run argv
+  if (count of argv) < 1 then
+    error "Usage: osascript agentxchain-autonudge.applescript <projectRoot> [autoSend:true|false] [pollSeconds]"
+  end if
+
+  set projectRoot to item 1 of argv
+
+  if (count of argv) >= 2 then
+    set sendArg to item 2 of argv
+    if sendArg is "true" then
+      set autoSend to true
+    else
+      set autoSend to false
+    end if
+  end if
+
+  if (count of argv) >= 3 then
+    try
+      set pollSeconds to (item 3 of argv) as integer
+    on error
+      set pollSeconds to 3
+    end try
+  end if
+
+  set triggerPath to projectRoot & "/.agentxchain-trigger.json"
+  set statePath to projectRoot & "/.agentxchain-autonudge.state"
+
+  repeat
+    try
+      set hasTrigger to do shell script "test -f " & quoted form of triggerPath & " && echo yes || echo no"
+      if hasTrigger is "yes" then
+        set agentId to do shell script "jq -r '.agent // empty' " & quoted form of triggerPath
+        set turnNum to do shell script "jq -r '.turn_number // 0' " & quoted form of triggerPath
+
+        if agentId is not "" then
+          set dispatchKey to agentId & ":" & turnNum
+          set lastKey to do shell script "test -f " & quoted form of statePath & " && cat " & quoted form of statePath & " || echo ''"
+
+          if dispatchKey is not lastKey then
+            my nudgeAgent(agentId, turnNum)
+            do shell script "printf %s " & quoted form of dispatchKey & " > " & quoted form of statePath
+          end if
+        end if
+      end if
+    end try
+
+    delay pollSeconds
+  end repeat
+end run
+
+on nudgeAgent(agentId, turnNum)
+  set nudgeText to "Hey " & agentId & ", it is your turn now (turn " & turnNum & "). Read lock.json, claim the lock, check state.md + history.jsonl + planning docs, do your work, and release lock."
+  set the clipboard to nudgeText
+
+  tell application "Cursor" to activate
+  delay 0.5
+  my focusAgentWindow(agentId)
+  delay 0.2
+
+  tell application "System Events"
+    if not (exists process "Cursor") then return
+
+    tell process "Cursor"
+      set frontmost to true
+      keystroke "l" using {command down}
+      delay 0.2
+      keystroke "v" using {command down}
+      if autoSend then
+        delay 0.15
+        key code 36
+      end if
+    end tell
+  end tell
+
+  do shell script "osascript -e " & quoted form of ("display notification \"Nudged " & agentId & " for turn " & turnNum & "\" with title \"AgentXchain\"")
+end nudgeAgent
+
+on focusAgentWindow(agentId)
+  tell application "System Events"
+    if not (exists process "Cursor") then return
+    tell process "Cursor"
+      set frontmost to true
+
+      set didRaise to false
+      repeat with w in windows
+        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
+          end if
+        end try
+      end repeat
+
+      if didRaise is false then
+        try
+          perform action "AXRaise" of window 1
+        end try
+      end if
+    end tell
+  end tell
+end focusAgentWindow

package/scripts/build-binary.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Build standalone binaries for macOS and Linux using Bun.
+# Requires: bun (install via `brew install oven-sh/bun/bun`)
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+cd "$CLI_DIR"
+
+VERSION=$(node -e "console.log(require('./package.json').version)")
+DIST="$CLI_DIR/dist"
+mkdir -p "$DIST"
+
+echo "Building agentxchain v${VERSION}..."
+echo ""
+
+echo "=== macOS arm64 ==="
+bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile="$DIST/agentxchain-macos-arm64"
+echo "  → $DIST/agentxchain-macos-arm64"
+
+echo ""
+echo "=== macOS x64 ==="
+bun build bin/agentxchain.js --compile --target=bun-darwin-x64 --outfile="$DIST/agentxchain-macos-x64"
+echo "  → $DIST/agentxchain-macos-x64"
+
+echo ""
+echo "=== Linux x64 ==="
+bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile="$DIST/agentxchain-linux-x64"
+echo "  → $DIST/agentxchain-linux-x64"
+
+echo ""
+echo "Creating tarballs..."
+cd "$DIST"
+tar -czf "agentxchain-${VERSION}-macos-arm64.tar.gz" agentxchain-macos-arm64
+tar -czf "agentxchain-${VERSION}-macos-x64.tar.gz" agentxchain-macos-x64
+tar -czf "agentxchain-${VERSION}-linux-x64.tar.gz" agentxchain-linux-x64
+
+echo ""
+echo "Done. Upload these to a GitHub release, then update the Homebrew formula with the URLs and SHA256 hashes."
+echo ""
+echo "SHA256 hashes:"
+shasum -a 256 *.tar.gz

package/scripts/publish-npm.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Publish a new version of agentxchain to npm.
+# Usage:
+#   bash scripts/publish-npm.sh                # bump patch + publish
+#   bash scripts/publish-npm.sh minor          # bump minor + publish
+#   bash scripts/publish-npm.sh major          # bump major + publish
+#   bash scripts/publish-npm.sh 0.5.0          # set explicit version + publish
+#   bash scripts/publish-npm.sh patch --dry-run
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+cd "$CLI_DIR"
+
+if [[ ! -f "package.json" ]]; then
+  echo "Error: package.json not found in $CLI_DIR"
+  exit 1
+fi
+
+PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
+BUMP="${1:-patch}"
+DRY_RUN="${2:-}"
+
+if [[ "$BUMP" != "patch" && "$BUMP" != "minor" && "$BUMP" != "major" && ! "$BUMP" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Error: invalid version bump '$BUMP'. Use patch|minor|major|x.y.z"
+  exit 1
+fi
+
+# Load NPM_TOKEN from agentXchain.dev/.env only.
+PARENT_ENV_FILE="${CLI_DIR}/../.env"
+if [[ -f "${PARENT_ENV_FILE}" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "${PARENT_ENV_FILE}"
+  set +a
+fi
+
+CURRENT_VERSION="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version)")"
+echo "Current version: ${CURRENT_VERSION}"
+echo "Package name:    ${PACKAGE_NAME}"
+echo "Requested bump:  ${BUMP}"
+echo ""
+
+if [[ "$DRY_RUN" == "--dry-run" ]]; then
+  echo "Dry run mode. No files changed."
+  exit 0
+fi
+
+# Preflight auth/ownership checks before version bump.
+echo "Running npm preflight checks..."
+if [[ -n "${NPM_TOKEN:-}" ]]; then
+  if ! npm whoami --//registry.npmjs.org/:_authToken="${NPM_TOKEN}" >/dev/null 2>&1; then
+    echo "Error: npm auth failed with NPM_TOKEN from agentxchain.dev/.env"
+    echo "Verify NPM_TOKEN is valid and has package publish permissions."
+    exit 1
+  fi
+  NPM_USER="$(npm whoami --//registry.npmjs.org/:_authToken="${NPM_TOKEN}")"
+else
+  if ! npm whoami >/dev/null 2>&1; then
+    echo "Error: npm auth missing. Run: npm login or set NPM_TOKEN in agentxchain.dev/.env"
+    exit 1
+  fi
+  NPM_USER="$(npm whoami)"
+fi
+echo "npm user:        ${NPM_USER}"
+
+if npm view "${PACKAGE_NAME}" version >/dev/null 2>&1; then
+  # Existing package: confirm owner access.
+  if ! npm owner ls "${PACKAGE_NAME}" | grep -q "^${NPM_USER} "; then
+    echo "Error: npm user '${NPM_USER}' is not an owner of '${PACKAGE_NAME}'."
+    echo "Ask an existing owner to run: npm owner add ${NPM_USER} ${PACKAGE_NAME}"
+    exit 1
+  fi
+  echo "ownership:       ok"
+else
+  echo "package status:  new package or not visible to this auth context"
+fi
+echo ""
+
+echo "Bumping package version..."
+npm version "$BUMP" --no-git-tag-version
+
+NEW_VERSION="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version)")"
+echo "New version: ${NEW_VERSION}"
+echo ""
+
+echo "Publishing to npm..."
+if [[ -n "${NPM_TOKEN:-}" ]]; then
+  npm publish --access public --//registry.npmjs.org/:_authToken="${NPM_TOKEN}"
+else
+  npm publish --access public
+fi
+
+echo ""
+echo "Done. Published agentxchain@${NEW_VERSION}"

package/scripts/run-autonudge.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+APPLESCRIPT_PATH="${SCRIPT_DIR}/agentxchain-autonudge.applescript"
+
+PROJECT_ROOT="$(pwd)"
+AUTO_SEND="false"
+INTERVAL_SECONDS="3"
+
+usage() {
+  cat <<'EOF'
+Usage: bash scripts/run-autonudge.sh [options]
+
+Options:
+  --project <path>     Project root that contains lock.json
+  --send               Auto-send message (presses Enter after paste)
+  --paste-only         Paste only (default, no Enter)
+  --interval <seconds> Poll interval in seconds (default: 3)
+  -h, --help           Show help
+
+Example:
+  bash scripts/run-autonudge.sh --project "$(pwd)" --send --interval 2
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project)
+      PROJECT_ROOT="$2"
+      shift 2
+      ;;
+    --send)
+      AUTO_SEND="true"
+      shift
+      ;;
+    --paste-only)
+      AUTO_SEND="false"
+      shift
+      ;;
+    --interval)
+      INTERVAL_SECONDS="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if ! command -v osascript >/dev/null 2>&1; then
+  echo "osascript not found. This script requires macOS."
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq not found. Install with: brew install jq"
+  exit 1
+fi
+
+if [[ ! -f "${PROJECT_ROOT}/lock.json" ]]; then
+  echo "lock.json not found in: ${PROJECT_ROOT}"
+  echo "Run this from your AgentXchain project root, or pass --project <path>."
+  exit 1
+fi
+
+if [[ ! -f "${APPLESCRIPT_PATH}" ]]; then
+  echo "AppleScript not found: ${APPLESCRIPT_PATH}"
+  exit 1
+fi
+
+WATCH_READY="false"
+for _ in {1..10}; do
+  if pgrep -f "agentxchain.*watch" >/dev/null 2>&1; then
+    WATCH_READY="true"
+    break
+  fi
+  sleep 1
+done
+
+if [[ "${WATCH_READY}" != "true" ]]; then
+  echo "watch process not detected."
+  echo "Run one of these first:"
+  echo "  agentxchain watch"
+  echo "  agentxchain supervise --autonudge"
+  exit 1
+fi
+
+if [[ ! -f "${PROJECT_ROOT}/.agentxchain-trigger.json" ]]; then
+  echo "warning: .agentxchain-trigger.json does not exist yet."
+  echo "auto-nudge will start, but nudges begin only after watch writes a trigger."
+fi
+
+echo ""
+echo "AgentXchain auto-nudge starting..."
+echo "Project:   ${PROJECT_ROOT}"
+echo "Mode:      $( [[ "${AUTO_SEND}" == "true" ]] && echo "auto-send" || echo "paste-only" )"
+echo "Interval:  ${INTERVAL_SECONDS}s"
+echo ""
+echo "Requirements:"
+echo "- Keep 'agentxchain watch' running in another terminal."
+echo "- Grant Accessibility permission to Terminal and Cursor."
+echo ""
+
+osascript "${APPLESCRIPT_PATH}" "${PROJECT_ROOT}" "${AUTO_SEND}" "${INTERVAL_SECONDS}"

package/scripts/stop-autonudge.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PIDS="$(pgrep -f "agentxchain-autonudge.applescript" || true)"
+
+if [[ -z "${PIDS}" ]]; then
+  echo "No running auto-nudge process found."
+  exit 0
+fi
+
+echo "Stopping auto-nudge process(es): ${PIDS}"
+kill ${PIDS}
+echo "Stopped."

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,36 @@ 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.
+4) 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/doctor.js

@@ -0,0 +1,132 @@
+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';
+
+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(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.'
+    };
+  }
+}

package/src/commands/init.js

@@ -245,6 +245,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('');
@@ -264,7 +265,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/start.js

@@ -1,6 +1,5 @@
 import chalk from 'chalk';
 import { loadConfig } from '../lib/config.js';
-import { generateSeedPrompt } from '../lib/seed-prompt.js';
 
 export async function startCommand(opts) {
   const result = loadConfig();
@@ -26,15 +25,36 @@ 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);
+  }
+
+  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 +62,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 +94,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 +107,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;
+}

package/src/commands/supervise.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'fs';
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { loadConfig } from '../lib/config.js';
+
+export async function superviseCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root } = result;
+
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const cliBin = join(currentDir, '../../bin/agentxchain.js');
+  const runNudgeScript = join(currentDir, '../../scripts/run-autonudge.sh');
+  const interval = Number(opts.interval || 3);
+
+  if (opts.autonudge) {
+    if (process.platform !== 'darwin') {
+      console.log(chalk.red('  --autonudge currently supports macOS only.'));
+      process.exit(1);
+    }
+    if (!existsSync(runNudgeScript)) {
+      console.log(chalk.red(`  Auto-nudge script not found: ${runNudgeScript}`));
+      process.exit(1);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Supervisor'));
+  console.log(chalk.dim(`  Project: ${root}`));
+  console.log(chalk.dim(`  Mode: ${opts.autonudge ? 'watch + auto-nudge' : 'watch only'}`));
+  if (opts.autonudge) {
+    console.log(chalk.dim(`  Auto-send: ${opts.send ? 'enabled' : 'disabled (paste-only)'}`));
+    console.log(chalk.dim(`  Nudge poll: ${interval}s`));
+  }
+  console.log('');
+
+  const children = [];
+
+  const watchChild = spawn(process.execPath, [cliBin, 'watch'], {
+    cwd: root,
+    stdio: 'inherit',
+    env: { ...process.env, AGENTXCHAIN_WATCH_DAEMON: '0' }
+  });
+  children.push(watchChild);
+
+  let nudgeChild = null;
+  if (opts.autonudge) {
+    const nudgeArgs = [runNudgeScript, '--project', root, '--interval', String(interval)];
+    nudgeArgs.push(opts.send ? '--send' : '--paste-only');
+    nudgeChild = spawn('bash', nudgeArgs, {
+      cwd: root,
+      stdio: 'inherit'
+    });
+    children.push(nudgeChild);
+  }
+
+  console.log(chalk.green(`  ✓ Watch PID: ${watchChild.pid}`));
+  if (nudgeChild) console.log(chalk.green(`  ✓ Auto-nudge PID: ${nudgeChild.pid}`));
+  console.log(chalk.dim('  Press Ctrl+C to stop supervisor and child processes.'));
+  console.log('');
+
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const child of children) {
+      if (!child.killed) {
+        try { child.kill('SIGTERM'); } catch {}
+      }
+    }
+    setTimeout(() => process.exit(0), 200);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  watchChild.on('exit', code => {
+    if (!shuttingDown) {
+      console.log('');
+      console.log(chalk.red(`  Watch process exited unexpectedly (code ${code ?? 'unknown'}).`));
+      shutdown();
+    }
+  });
+
+  if (nudgeChild) {
+    nudgeChild.on('exit', code => {
+      if (!shuttingDown) {
+        console.log('');
+        console.log(chalk.red(`  Auto-nudge exited unexpectedly (code ${code ?? 'unknown'}).`));
+        shutdown();
+      }
+    });
+  }
+}