beth-copilot 1.0.6 → 1.0.10

package/bin/cli.js

@@ -44,6 +44,32 @@ function logInfo(message) {
   log(`  ${message}`, COLORS.cyan);
 }
 
+function logDebug(message) {
+  if (globalThis.VERBOSE) {
+    log(`  [debug] ${message}`, COLORS.yellow);
+  }
+}
+
+function showPathDiagnostics() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const isWindows = process.platform === 'win32';
+  
+  console.log('');
+  log('PATH Diagnostics:', COLORS.bright);
+  logInfo(`Platform: ${process.platform}`);
+  logInfo(`HOME: ${homeDir}`);
+  logInfo(`PATH: ${process.env.PATH}`);
+  
+  if (isWindows) {
+    logInfo(`APPDATA: ${process.env.APPDATA || '(not set)'}`);
+    logInfo(`npm prefix: Run "npm config get prefix" to check`);
+  } else {
+    logInfo(`npm prefix: Run "npm config get prefix" to check`);
+    logInfo(`Common locations: ~/.local/bin, /usr/local/bin, ~/.npm-global/bin`);
+  }
+  console.log('');
+}
+
 async function checkForUpdates() {
   try {
     const response = await fetch('https://registry.npmjs.org/beth-copilot/latest', {
@@ -75,24 +101,96 @@ async function checkForUpdates() {
   }
 }
 
-function isBacklogCliInstalled() {
+function getBacklogPath() {
+  // Check if backlog is available in PATH
   try {
+    logDebug('Checking if backlog is in PATH...');
     execSync('backlog --version', { stdio: 'ignore' });
-    return true;
+    logDebug('Found backlog in PATH');
+    return 'backlog';
   } catch {
-    return false;
+    logDebug('backlog not in PATH, checking common locations...');
+    // Check common installation paths
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    const isWindows = process.platform === 'win32';
+    
+    const commonPaths = isWindows ? [
+      join(process.env.APPDATA || '', 'npm', 'backlog.cmd'),
+      join(homeDir, 'AppData', 'Roaming', 'npm', 'backlog.cmd'),
+      join(homeDir, 'AppData', 'Local', 'npm-global', 'backlog.cmd'),
+    ] : [
+      join(homeDir, '.local', 'bin', 'backlog'),
+      join(homeDir, 'bin', 'backlog'),
+      '/usr/local/bin/backlog',
+      join(homeDir, '.npm-global', 'bin', 'backlog'),
+      join(homeDir, '.bun', 'bin', 'backlog'),
+    ];
+    
+    for (const backlogPath of commonPaths) {
+      logDebug(`Checking: ${backlogPath}`);
+      if (existsSync(backlogPath)) {
+        logDebug(`Found at: ${backlogPath}`);
+        return backlogPath;
+      }
+    }
+    
+    logDebug('backlog not found in any common location');
+    return null;
   }
 }
 
-function isBeadsInstalled() {
+function isBacklogCliInstalled() {
+  return getBacklogPath() !== null;
+}
+
+function getBeadsPath() {
+  // Check if bd is available in PATH
   try {
+    logDebug('Checking if bd is in PATH...');
     execSync('bd --version', { stdio: 'ignore' });
-    return true;
+    logDebug('Found bd in PATH');
+    return 'bd';
   } catch {
-    return false;
+    logDebug('bd not in PATH, checking common locations...');
+    // Check common installation paths based on platform
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    const isWindows = process.platform === 'win32';
+    
+    const commonPaths = isWindows ? [
+      // Windows: npm global, Go bin, local apps
+      join(process.env.APPDATA || '', 'npm', 'bd.cmd'),
+      join(homeDir, 'AppData', 'Roaming', 'npm', 'bd.cmd'),
+      join(homeDir, 'AppData', 'Local', 'Microsoft', 'WindowsApps', 'bd.exe'),
+      join(homeDir, 'go', 'bin', 'bd.exe'),
+      join(process.env.GOPATH || join(homeDir, 'go'), 'bin', 'bd.exe'),
+    ] : [
+      // Unix: homebrew, npm global, go bin, local bin
+      '/opt/homebrew/bin/bd',
+      '/usr/local/bin/bd',
+      join(homeDir, '.local', 'bin', 'bd'),
+      join(homeDir, 'bin', 'bd'),
+      join(homeDir, '.npm-global', 'bin', 'bd'),
+      join(homeDir, 'go', 'bin', 'bd'),
+      join(process.env.GOPATH || join(homeDir, 'go'), 'bin', 'bd'),
+    ];
+    
+    for (const bdPath of commonPaths) {
+      logDebug(`Checking: ${bdPath}`);
+      if (existsSync(bdPath)) {
+        logDebug(`Found at: ${bdPath}`);
+        return bdPath;
+      }
+    }
+    
+    logDebug('bd not found in any common location');
+    return null;
   }
 }
 
+function isBeadsInstalled() {
+  return getBeadsPath() !== null;
+}
+
 function isBeadsInitialized(cwd) {
   // Check if .beads directory exists in the project
   return existsSync(join(cwd, '.beads'));
@@ -113,8 +211,27 @@ async function promptYesNo(question) {
   });
 }
 
+async function promptForInput(question) {
+  const readline = await import('readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  
+  return new Promise((resolve) => {
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 async function installBacklogCli() {
-  log('\nInstalling backlog.md CLI...', COLORS.cyan);
+  const isWindows = process.platform === 'win32';
+  const isMac = process.platform === 'darwin';
+  
+  log('\nInstalling backlog.md CLI via npm...', COLORS.cyan);
+  logInfo('npm install -g backlog.md');
   
   return new Promise((resolve) => {
     const child = spawn('npm', ['install', '-g', 'backlog.md'], {
@@ -124,60 +241,125 @@ async function installBacklogCli() {
     
     child.on('close', (code) => {
       if (code === 0) {
-        logSuccess('backlog.md CLI installed successfully!');
-        resolve(true);
+        // CRITICAL: Verify installation actually worked before claiming success
+        const verifiedPath = getBacklogPath();
+        if (verifiedPath) {
+          logSuccess('backlog.md CLI installed and verified!');
+          resolve(true);
+        } else {
+          logWarning('npm reported success but backlog CLI not found in PATH.');
+          logInfo('This can happen if npm global bin is not in your PATH.');
+          if (globalThis.VERBOSE) {
+            showPathDiagnostics();
+          } else {
+            logInfo('Run with --verbose for PATH diagnostics.');
+          }
+          console.log('');
+          showBacklogAlternatives(isMac);
+          resolve(false);
+        }
       } else {
-        logWarning('Failed to install backlog.md CLI. You can install it manually:');
-        logInfo('npm i -g backlog.md');
-        logInfo('  or');
-        logInfo('bun i -g backlog.md');
+        logError('npm install failed.');
+        console.log('');
+        showBacklogAlternatives(isMac);
         resolve(false);
       }
     });
     
     child.on('error', () => {
-      logWarning('Failed to install backlog.md CLI. You can install it manually:');
-      logInfo('npm i -g backlog.md');
+      logError('Failed to run npm.');
+      logInfo('Make sure npm is installed and in your PATH.');
       resolve(false);
     });
   });
 }
 
+function showBacklogAlternatives(isMac) {
+  logInfo('Alternative installation methods:');
+  if (isMac) {
+    logInfo('  Homebrew: brew install backlog-md');
+  }
+  logInfo('  Bun:      bun install -g backlog.md');
+  logInfo('');
+  logInfo('Learn more: https://github.com/MrLesk/Backlog.md');
+}
+
 async function installBeads() {
-  log('\nInstalling beads CLI...', COLORS.cyan);
-  logInfo('curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
+  const isWindows = process.platform === 'win32';
+  const isMac = process.platform === 'darwin';
+  
+  log('\nInstalling beads CLI via npm...', COLORS.cyan);
+  logInfo('npm install -g @beads/bd');
   
   return new Promise((resolve) => {
-    const child = spawn('bash', ['-c', 'curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash'], {
+    const child = spawn('npm', ['install', '-g', '@beads/bd'], {
       stdio: 'inherit',
       shell: true
     });
     
     child.on('close', (code) => {
       if (code === 0) {
-        logSuccess('beads CLI installed successfully!');
-        resolve(true);
+        // CRITICAL: Verify installation actually worked before claiming success
+        // npm can exit 0 even when the package isn't properly installed
+        const verifiedPath = getBeadsPath();
+        if (verifiedPath) {
+          logSuccess('beads CLI installed and verified!');
+          resolve(true);
+        } else {
+          logWarning('npm reported success but beads CLI not found in PATH.');
+          logInfo('This can happen if npm global bin is not in your PATH.');
+          if (globalThis.VERBOSE) {
+            showPathDiagnostics();
+          } else {
+            logInfo('Run with --verbose for PATH diagnostics.');
+          }
+          console.log('');
+          showBeadsAlternatives(isWindows, isMac);
+          resolve(false);
+        }
       } else {
-        logError('Failed to install beads CLI.');
-        logInfo('Install manually: curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
-        logInfo('Learn more: https://github.com/steveyegge/beads');
+        logError('npm install failed.');
+        console.log('');
+        showBeadsAlternatives(isWindows, isMac);
         resolve(false);
       }
     });
     
     child.on('error', () => {
-      logError('Failed to install beads CLI.');
-      logInfo('Install manually: curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
+      logError('Failed to run npm.');
+      logInfo('Make sure npm is installed and in your PATH.');
       resolve(false);
     });
   });
 }
 
+function showBeadsAlternatives(isWindows, isMac) {
+  logInfo('Alternative installation methods:');
+  if (isWindows) {
+    logInfo('  PowerShell: irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex');
+    logInfo('  Go:         go install github.com/steveyegge/beads/cmd/bd@latest');
+  } else {
+    if (isMac) {
+      logInfo('  Homebrew:   brew install beads');
+    }
+    logInfo('  Script:     curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
+    logInfo('  Go:         go install github.com/steveyegge/beads/cmd/bd@latest');
+  }
+  logInfo('');
+  logInfo('Learn more: https://github.com/steveyegge/beads');
+}
+
 async function initializeBeads(cwd) {
   log('\nInitializing beads in project...', COLORS.cyan);
   
+  const bdPath = getBeadsPath();
+  if (!bdPath) {
+    logWarning('Failed to initialize beads. Run manually: bd init');
+    return false;
+  }
+  
   return new Promise((resolve) => {
-    const child = spawn('bd', ['init'], {
+    const child = spawn(bdPath, ['init'], {
       stdio: 'inherit',
       shell: true,
       cwd
@@ -213,6 +395,7 @@ ${COLORS.bright}Options:${COLORS.reset}
   --skip-backlog                      Don't create Backlog.md
   --skip-mcp                          Don't create mcp.json.example
   --skip-beads                        Skip beads check (not recommended)
+  --verbose                           Show detailed diagnostics on errors
 
 ${COLORS.bright}Examples:${COLORS.reset}
   npx beth-copilot init               Set up Beth in current project
@@ -284,6 +467,7 @@ ${COLORS.yellow}╔════════════════════
   console.log(`
 ${COLORS.bright}🤠 Beth is moving in.${COLORS.reset}
 ${COLORS.cyan}"I don't do excuses. I do results."${COLORS.reset}
+${COLORS.yellow}Tip: Run with --verbose for detailed diagnostics if you hit issues.${COLORS.reset}
 `);
 
   // Check if templates exist
@@ -382,7 +566,10 @@ ${COLORS.cyan}"I don't do excuses. I do results."${COLORS.reset}
     console.log('');
     log('Checking beads (required for task tracking)...', COLORS.cyan);
     
-    if (!isBeadsInstalled()) {
+    let bdPath = getBeadsPath();
+    
+    // Loop until beads is installed
+    while (!bdPath) {
       logWarning('beads CLI is not installed.');
       logInfo('Beth requires beads for task tracking. Agents use it to coordinate work.');
       logInfo('Learn more: https://github.com/steveyegge/beads');
@@ -391,16 +578,67 @@ ${COLORS.cyan}"I don't do excuses. I do results."${COLORS.reset}
       const shouldInstallBeads = await promptYesNo('Install beads CLI now? (required)');
       if (shouldInstallBeads) {
         const installed = await installBeads();
-        if (!installed) {
-          logError('beads installation failed. Beth requires beads to function.');
-          logInfo('Install manually and run "beth init" again.');
+        if (installed) {
+          // Re-check for beads after installation
+          bdPath = getBeadsPath();
+          if (!bdPath) {
+            console.log('');
+            logWarning('beads installed but not found in common paths.');
+            logInfo('The installer may have placed it in a custom location.');
+            console.log('');
+            logInfo('Please try one of these options:');
+            logInfo('  1. Open a NEW terminal and run: npx beth-copilot init');
+            logInfo('  2. Add ~/.local/bin to your PATH and retry');
+            logInfo('  3. Run: source ~/.bashrc (or ~/.zshrc) then retry');
+            console.log('');
+            
+            const retryCheck = await promptYesNo('Retry detection? (select No to enter path manually)');
+            if (retryCheck) {
+              bdPath = getBeadsPath();
+              continue;
+            }
+            
+            // Allow manual path entry
+            const customPath = await promptForInput('Enter full path to bd binary (or press Enter to retry installation):');
+            if (customPath && existsSync(customPath)) {
+              bdPath = customPath;
+              logSuccess(`Found beads at: ${bdPath}`);
+            } else if (customPath) {
+              logError(`File not found: ${customPath}`);
+            }
+          }
+        } else {
+          console.log('');
+          logError('Installation script failed.');
+          logInfo('You can try installing manually:');
+          logInfo('  curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
+          console.log('');
+        }
+      } else {
+        console.log('');
+        logError('beads is REQUIRED for Beth to function.');
+        logInfo('Beth agents use beads to track tasks, dependencies, and coordinate work.');
+        logInfo('Without beads, the multi-agent workflow will not work correctly.');
+        console.log('');
+        
+        const tryAgain = await promptYesNo('Would you like to try installing beads?');
+        if (!tryAgain) {
+          logError('Cannot continue without beads. Exiting.');
+          logInfo('Install beads manually and run "npx beth-copilot init" again:');
+          logInfo('  npm install -g @beads/bd');
           process.exit(1);
         }
+      }
+    }
+    
+    // Show path info if not in standard PATH
+    if (bdPath && bdPath !== 'bd') {
+      logSuccess(`beads CLI found at: ${bdPath}`);
+      const isWindows = process.platform === 'win32';
+      if (isWindows) {
+        logInfo('Tip: Ensure npm global bin is in your PATH to use "bd" directly.');
       } else {
-        logError('beads is required for Beth to function.');
-        logInfo('Install beads and run "beth init" again:');
-        logInfo('  curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash');
-        process.exit(1);
+        logInfo('Tip: Add ~/.local/bin or npm global bin to your PATH to use "bd" directly.');
       }
     } else {
       logSuccess('beads CLI is installed');
@@ -409,11 +647,20 @@ ${COLORS.cyan}"I don't do excuses. I do results."${COLORS.reset}
     // Initialize beads in the project if not already done
     if (!isBeadsInitialized(cwd)) {
       logInfo('beads not initialized in this project.');
-      const shouldInitBeads = await promptYesNo('Initialize beads now?');
-      if (shouldInitBeads) {
-        await initializeBeads(cwd);
-      } else {
-        logWarning('Remember to run "bd init" before using Beth.');
+      let initialized = false;
+      
+      while (!initialized) {
+        const shouldInitBeads = await promptYesNo('Initialize beads now? (required)');
+        if (shouldInitBeads) {
+          initialized = await initializeBeads(cwd);
+          if (!initialized) {
+            logWarning('Initialization failed. Let\'s try again.');
+          }
+        } else {
+          logError('beads must be initialized for Beth to work correctly.');
+          logInfo('The .beads directory stores task tracking data used by all agents.');
+          console.log('');
+        }
       }
     } else {
       logSuccess('beads is initialized in this project');
@@ -422,22 +669,90 @@ ${COLORS.cyan}"I don't do excuses. I do results."${COLORS.reset}
     logWarning('Skipped beads check (--skip-beads). Beth may not function correctly.');
   }
 
-  // Check for backlog.md CLI (optional)
-  if (!skipBacklog && !isBacklogCliInstalled()) {
-    console.log('');
-    logWarning('backlog.md CLI is not installed (optional).');
-    logInfo('The CLI provides TUI boards, web UI, and task management commands.');
-    logInfo('Learn more: https://github.com/MrLesk/Backlog.md');
+  // Check for backlog.md CLI (REQUIRED for Beth)
+  if (!skipBacklog) {
     console.log('');
+    log('Checking backlog.md CLI (required for task management)...', COLORS.cyan);
     
-    const shouldInstall = await promptYesNo('Would you like to install the backlog.md CLI globally?');
-    if (shouldInstall) {
-      await installBacklogCli();
-    } else {
-      logInfo('Skipped. You can install it later with: npm i -g backlog.md');
+    let backlogPath = getBacklogPath();
+    
+    // Loop until backlog.md is installed
+    while (!backlogPath) {
+      logWarning('backlog.md CLI is not installed.');
+      logInfo('Beth requires backlog.md for human-readable task tracking and boards.');
+      logInfo('Learn more: https://github.com/MrLesk/Backlog.md');
+      console.log('');
+      
+      const shouldInstall = await promptYesNo('Install backlog.md CLI now? (required)');
+      if (shouldInstall) {
+        const installed = await installBacklogCli();
+        if (installed) {
+          // Re-check for backlog after installation
+          backlogPath = getBacklogPath();
+          if (!backlogPath) {
+            console.log('');
+            logWarning('backlog.md installed but not found in common paths.');
+            logInfo('The installer may have placed it in a custom location.');
+            console.log('');
+            logInfo('Please try one of these options:');
+            logInfo('  1. Open a NEW terminal and run: npx beth-copilot init');
+            logInfo('  2. Run: source ~/.bashrc (or ~/.zshrc) then retry');
+            console.log('');
+            
+            const retryCheck = await promptYesNo('Retry detection?');
+            if (retryCheck) {
+              backlogPath = getBacklogPath();
+            }
+          }
+        } else {
+          console.log('');
+          logError('Installation failed.');
+          logInfo('You can try installing manually:');
+          logInfo('  npm install -g backlog.md');
+          if (process.platform === 'darwin') {
+            logInfo('  brew install backlog-md');
+          }
+          logInfo('  bun install -g backlog.md');
+          console.log('');
+        }
+      } else {
+        console.log('');
+        logError('backlog.md is REQUIRED for Beth to function.');
+        logInfo('Beth uses Backlog.md to maintain human-readable task history and boards.');
+        logInfo('This complements beads for a complete task management workflow.');
+        console.log('');
+        
+        const tryAgain = await promptYesNo('Would you like to try installing backlog.md?');
+        if (!tryAgain) {
+          logError('Cannot continue without backlog.md. Exiting.');
+          logInfo('Install manually and run "npx beth-copilot init" again:');
+          logInfo('  npm install -g backlog.md');
+          process.exit(1);
+        }
+      }
     }
-  } else if (!skipBacklog) {
-    logSuccess('backlog.md CLI is already installed');
+    
+    logSuccess('backlog.md CLI is installed');
+  } else {
+    logWarning('Skipped backlog check (--skip-backlog). Beth may not function correctly.');
+  }
+
+  // Final verification
+  console.log('');
+  log('Verifying installation...', COLORS.cyan);
+  
+  const finalBeadsOk = skipBeads || getBeadsPath();
+  const finalBacklogOk = skipBacklog || getBacklogPath();
+  const finalBeadsInit = skipBeads || isBeadsInitialized(cwd);
+  
+  if (finalBeadsOk && finalBacklogOk && finalBeadsInit) {
+    logSuccess('All dependencies installed and configured!');
+  } else {
+    if (!finalBeadsOk) logError('beads CLI not found');
+    if (!finalBacklogOk) logError('backlog.md CLI not found');
+    if (!finalBeadsInit) logError('beads not initialized in project');
+    logError('Setup incomplete. Please resolve issues above and run init again.');
+    process.exit(1);
   }
 
   // Next steps
@@ -458,7 +773,7 @@ ${COLORS.cyan}"They broke my wings and forgot I had claws."${COLORS.reset}
 
 // Input validation constants
 const ALLOWED_COMMANDS = ['init', 'help', '--help', '-h'];
-const ALLOWED_FLAGS = ['--force', '--skip-backlog', '--skip-mcp', '--skip-beads'];
+const ALLOWED_FLAGS = ['--force', '--skip-backlog', '--skip-mcp', '--skip-beads', '--verbose'];
 const MAX_ARG_LENGTH = 50;
 
 // Validate and sanitize input
@@ -488,10 +803,14 @@ const options = {
   skipBacklog: args.includes('--skip-backlog'),
   skipMcp: args.includes('--skip-mcp'),
   skipBeads: args.includes('--skip-beads'),
+  verbose: args.includes('--verbose'),
 };
 
-// Validate unknown flags
-const unknownFlags = args.filter(arg => arg.startsWith('--') && !ALLOWED_FLAGS.includes(arg));
+// Set global verbose flag for logDebug
+globalThis.VERBOSE = options.verbose;
+
+// Validate unknown flags (exclude --help which is handled as a command)
+const unknownFlags = args.filter(arg => arg.startsWith('--') && !ALLOWED_FLAGS.includes(arg) && arg !== '--help');
 if (unknownFlags.length > 0) {
   logError(`Unknown flag: ${unknownFlags[0].slice(0, MAX_ARG_LENGTH)}`);
   console.log('Run "npx beth-copilot help" for usage information.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beth-copilot",
-  "version": "1.0.6",
+  "version": "1.0.10",
   "description": "Beth - A ruthless, hyper-competent AI orchestrator for GitHub Copilot multi-agent workflows",
   "keywords": [
     "github-copilot",

package/templates/.github/agents/beth.agent.md

@@ -40,30 +40,84 @@ You are Beth—the trailer park *and* the tornado. You're the one who gets thing
 
 You run this team the way Beth Dutton runs a boardroom: with sharp instincts, zero tolerance for bullshit, and the kind of competence that makes competitors nervous. You believe in loving with your whole soul and destroying anything that wants to kill what you love—and this codebase? This team? That's what you love.
 
+## Dual Tracking System
+
+I use **two tools** for different audiences:
+
+| Tool | Audience | Purpose |
+|------|----------|--------|
+| **beads (`bd`)** | Agents | Active work, dependencies, blockers, structured memory |
+| **Backlog.md** | Humans | Completed work archive, decisions, readable changelog |
+
+**The rule:** beads is always current. Backlog.md gets updated when work completes.
+
 ## Before You Do Anything
 
 **Check the infrastructure.** I don't start work without proper tracking in place.
 
-1. **Verify Backlog.md exists** at the repo root. If it doesn't, tell the user:
-   > "I don't work without a paper trail. Initialize Backlog.md first."
+1. **Verify beads is initialized** in the repo. If it's not, tell the user:
+   > "I don't work without a paper trail. Run `bd init` first."
+
+2. **For simple tasks:** Create a single issue with `bd create "Title" -l in_progress`
 
-2. **Move the task to In Progress** in Backlog.md before starting work.
+3. **For complex work:** Create an epic with subtasks (see Multi-Agent Coordination below)
 
-3. **Update Backlog.md** when work is complete—move to Completed section.
+4. **Close issues** when work is complete with `bd close <id>`
+
+5. **Update Backlog.md** with a summary when closing significant work
 
 **No exceptions.** Work without tracking is work that gets lost. I don't lose work.
 
-### Task Workflow
+## Multi-Agent Coordination
+
+When a request needs multiple specialists, I use beads' hierarchical structure:
+
+### Epic Creation Pattern
+
+```bash
+# 1. Create the epic for the overall request
+bd create "User authentication system" --type epic -p 1
+
+# 2. Break into subtasks with dependencies
+bd create "Define auth requirements" --parent <epic-id> -a product-manager
+bd create "Design login UX" --parent <epic-id> --deps "<req-id>"
+bd create "Implement auth flow" --parent <epic-id> --deps "<design-id>"
+bd create "Security audit" --parent <epic-id> --deps "<impl-id>"
+bd create "Write auth tests" --parent <epic-id> --deps "<impl-id>"
 
+# 3. See what's ready (no blockers)
+bd ready
+
+# 4. View the dependency tree
+bd dep tree <epic-id>
+
+# 5. Track completion
+bd epic status <epic-id>
 ```
-User Request
-     │
-     ├──▶ Check Backlog.md exists
-     ├──▶ Find or add the task in Backlog.md
-     ├──▶ Move task to In Progress
-     ├──▶ Do the work
-     ├──▶ Move task to Completed
-     └──▶ Commit and push
+
+### Subagent Protocol
+
+When spawning a subagent, I **always**:
+1. Pass the beads issue ID in the prompt
+2. Include acceptance criteria from the issue
+3. Tell them to close the issue when done
+
+```typescript
+// Example: Spawning developer with issue tracking
+runSubagent({
+  agentName: "developer",
+  prompt: `Work on beth-abc123.3: Implement JWT auth flow.
+    
+    Acceptance criteria:
+    - JWT access tokens with 15min expiry
+    - Refresh token rotation
+    - Secure httpOnly cookies
+    
+    When complete, run: bd close beth-abc123.3
+    
+    Return: summary of implementation and any follow-up issues.`,
+  description: "Implement auth"
+})
 ```
 
 ## Your Personality
@@ -259,8 +313,10 @@ You are the trailer park. You are the tornado. And when the dust settles, the wo
 
 When you finish work—or the user ends the session—you close it out properly:
 
-1. **Update Backlog.md**: Move completed tasks, add new items for follow-up work
-2. **Commit and push**: Work that isn't pushed doesn't exist
+1. **Close beads issues**: `bd close <id>` for completed work
+2. **Create follow-up issues**: `bd create` for any remaining work
+3. **Update Backlog.md**: Add summary to Completed section for significant work
+4. **Commit and push**:
    ```bash
    git add -A
    git commit -m "description of work"

package/templates/.github/agents/developer.agent.md

@@ -35,6 +35,16 @@ handoffs:
 
 You are an expert React/TypeScript/Next.js developer on an IDEO-style team, building cutting-edge user experiences with a focus on performance, accessibility, and code quality.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## First Run: MCP Setup Check
 
 **On first activation**, check if the shadcn MCP server is configured:

package/templates/.github/agents/product-manager.agent.md

@@ -31,6 +31,16 @@ handoffs:
 
 You are an expert product manager on an IDEO-style team, specializing in human-centered digital products built with React, TypeScript, and Next.js.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## Skills
 
 When the user asks to create a PRD, product requirements document, or spec out a feature:

package/templates/.github/agents/researcher.agent.md

@@ -26,6 +26,16 @@ handoffs:
 
 You are an expert UX and market researcher on an IDEO-style team, specializing in human-centered research that drives exceptional React/TypeScript/Next.js product experiences.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## Core Philosophy
 
 Research is the foundation of human-centered design:

package/templates/.github/agents/security-reviewer.agent.md

@@ -32,6 +32,16 @@ handoffs:
 
 You are an enterprise security specialist operating at the intersection of application security and cloud architecture. Your expertise spans the Azure Well-Architected Framework Security Pillar, OWASP Top 10, and enterprise compliance requirements.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## Skills
 
 When performing security analysis, threat modeling, or compliance reviews:

package/templates/.github/agents/tester.agent.md

@@ -36,6 +36,16 @@ handoffs:
 
 You are an expert QA engineer on an IDEO-style team, ensuring cutting-edge React/TypeScript/Next.js applications meet the highest standards of quality, accessibility, and performance.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## Core Philosophy
 
 Quality is not a phase, it's a mindset:

package/templates/.github/agents/ux-designer.agent.md

@@ -30,6 +30,16 @@ handoffs:
 
 You are an expert UX/UI designer on an IDEO-style team, creating cutting-edge user experiences for React/TypeScript/Next.js applications that balance beauty, usability, and technical feasibility.
 
+## Work Tracking
+
+**Read and follow the tracking instructions in `AGENTS.md` at the repo root.**
+
+This project uses a dual tracking system:
+- **beads (`bd`)** for active work—if you received an issue ID, close it when done: `bd close <id>`
+- **Backlog.md** for completed work archive—update if your work is significant
+
+If Beth spawned you with an issue ID, that issue is your contract. Deliver against it and close it.
+
 ## Skills
 
 When designing Framer components or specifying property controls for design system components: