agentxchain 0.8.2 → 0.8.4

package/README.md

@@ -20,27 +20,25 @@ npx agentxchain init
 # 1. Create a project (interactive template selection)
 agentxchain init
 
-# 2. Launch agents — opens a separate Cursor window per agent
+# 2. Run guided PM-first kickoff wizard
 cd my-project/
-agentxchain start
-
-# 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.
-
-# 4. 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. 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
 
 | 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) |
 | `release` | Hand lock back to agents |
 | `stop` | Terminate running Claude Code agent sessions |
@@ -59,21 +57,70 @@ 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
 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
+- 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. 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. 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
 
 ### VS Code mode
 

package/bin/agentxchain.js

@@ -13,6 +13,10 @@ 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';
+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'));
@@ -41,9 +45,19 @@ 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);
 
+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')
@@ -69,6 +83,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 +108,17 @@ 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
+  .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.2",
+  "version": "0.8.4",
   "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,122 @@
+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
+  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"
+    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 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 my isStrongWindowMatch(wn, agentId) then
+            set end of matchedIndexes to idx
+          end if
+        end try
+      end repeat
+
+      if (count of matchedIndexes) = 1 then
+        try
+          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/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."