@yemi33/squad 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 yemi33
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 yemi33
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -172,7 +172,7 @@ The web dashboard at `http://localhost:7331` provides:
 
 ## Project Config
 
-When you run `squad.js add <dir>`, it prompts for project details and saves them to `config.json`. Each project entry looks like:
+When you run `squad add <dir>`, it prompts for project details and saves them to `config.json`. Each project entry looks like:
 
 ```json
 {
@@ -205,7 +205,7 @@ The init script also creates `<project>/.squad/` with empty `work-items.json` an
 
 ### Auto-Discovery
 
-When you run `squad.js add`, the tool automatically detects what it can from the repo:
+When you run `squad add`, the tool automatically detects what it can from the repo:
 
 | What | How |
 |------|-----|
@@ -227,7 +227,7 @@ Agents need MCP tools to interact with your repo host (create PRs, post review c
 
 **Example:** If you use Azure DevOps, configure the `azure-ado` MCP server in your Claude Code settings. If you use GitHub, configure the `github` MCP server. Agents will discover and use whichever tools are available.
 
-Manually refresh with `node engine.js mcp-sync`.
+Manually refresh with `squad mcp-sync`.
 
 ## Work Items
 
@@ -235,7 +235,7 @@ All work items use the shared `playbooks/work-item.md` template, which provides
 
 **Per-project** — scoped to one repo. Select a project in the Command Center dropdown.
 
-**Central (auto-route)** — agent gets all project descriptions and decides where to work. Use "Auto (agent decides)" in the dropdown, or `node engine.js work "title"`. Can span multiple repos.
+**Central (auto-route)** — agent gets all project descriptions and decides where to work. Use "Auto (agent decides)" in the dropdown, or `squad work "title"`. Can span multiple repos.
 
 ### Fan-Out (Parallel Multi-Agent)
 
@@ -328,9 +328,10 @@ Routing rules in `routing.md`. Charters in `agents/{name}/charter.md`. Both are
 | `implement.md` | Build a PRD item in a git worktree, create PR |
 | `review.md` | Review a PR, post findings to repo host |
 | `fix.md` | Fix review feedback on existing PR branch |
-| `analyze.md` | Generate PRD gap analysis in a worktree |
 | `explore.md` | Read-only codebase exploration |
 | `test.md` | Run tests and report results |
+| `build-and-test.md` | Build project and run test suite |
+| `plan-to-prd.md` | Convert a plan into PRD gap items |
 
 All playbooks use `{{template_variables}}` filled from project config. The `work-item.md` playbook uses `{{scope_section}}` to inject project-specific or multi-project context. Playbooks are fully customizable — edit them to match your workflow.
 
@@ -355,7 +356,7 @@ Agents can run for hours as long as they're producing output. The `heartbeatTime
 | Orphaned worktrees | >24 hours old, no active dispatch references them |
 | Zombie processes | In memory but no matching dispatch |
 
-Manual cleanup: `node engine.js cleanup`
+Manual cleanup: `squad cleanup`
 
 ## Self-Improvement Loop
 
@@ -374,7 +375,7 @@ When a reviewer flags issues, the engine creates `feedback-<author>-from-<review
 `engine/metrics.json` tracks per agent: tasks completed, errors, PRs created/approved/rejected, reviews done. Visible in CLI (`status`) and dashboard with color-coded approval rates.
 
 ### 5. Skills
-Agents save repeatable workflows to `skills/<name>.md` with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in dashboard alongside decisions.
+Agents save repeatable workflows to `skills/<name>.md` with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in the dashboard Skills section.
 
 See `docs/self-improvement.md` for the full breakdown.
 
@@ -408,9 +409,9 @@ Engine behavior is controlled via `config.json`. Key settings:
 
 The engine and all spawned agents use the Node binary that started the engine (`process.execPath`). After upgrading Node, restart the engine:
 
-```powershell
-node ~/.squad/engine.js stop
-node ~/.squad/engine.js
+```bash
+squad stop
+squad start
 ```
 
 ## Portability
@@ -418,41 +419,45 @@ node ~/.squad/engine.js
 **Portable (works on any machine):** Engine, dashboard, playbooks, charters, routing, notes, skills, docs, work items.
 
 **Machine-specific (reconfigure per machine):**
-- `config.json` — contains absolute paths to project directories. Re-link via `node squad.js add <dir>`.
+- `config.json` — contains absolute paths to project directories. Re-link via `squad add <dir>`.
 - `mcp-servers.json` — auto-synced from `~/.claude.json` on engine start.
 
-To move to a new machine: clone `~/.squad/`, delete `engine/control.json`, re-run `node squad.js add` for each project.
+To move to a new machine: `npm install -g @yemi33/squad && squad init --force`, then re-run `squad add` for each project.
 
 ## File Layout
 
 ```
 ~/.squad/
-  squad.js               <- CLI: init, add, remove, list projects
+  bin/
+    squad.js             <- Unified CLI entry point (npm package)
+  squad.js               <- Project management: init, add, remove, list
   engine.js              <- Engine daemon
   engine/
     spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
-    control.json         <- running/paused/stopped
-    dispatch.json        <- pending/active/completed queue
-    log.json             <- Audit trail (capped at 500)
-    metrics.json         <- Per-agent quality metrics
+    ado-mcp-wrapper.js   <- ADO MCP authentication wrapper
+    control.json         <- running/paused/stopped (runtime)
+    dispatch.json        <- pending/active/completed queue (runtime)
+    log.json             <- Audit trail, capped at 500 (runtime)
+    metrics.json         <- Per-agent quality metrics (runtime)
   dashboard.js           <- Web dashboard server
-  dashboard.html         <- Dashboard UI
+  dashboard.html         <- Dashboard UI (single-file)
   config.json            <- projects[], agents, engine, claude settings
-  config.template.json   <- Template for reference
+  config.template.json   <- Template for new installs
+  package.json           <- npm package definition
   mcp-servers.json       <- MCP servers (auto-synced, gitignored)
   routing.md             <- Dispatch rules table (editable)
   team.md                <- Team roster
-  notes.md           <- Team rules + consolidated learnings
-  work-items.json        <- Central work queue (agent decides which project)
-  TODO.md                <- Future improvements roadmap
+  notes.md               <- Team rules + consolidated learnings (runtime)
+  work-items.json        <- Central work queue (runtime)
   playbooks/
     work-item.md         <- Shared work item template
     implement.md         <- Build a PRD item
     review.md            <- Review a PR
     fix.md               <- Fix review feedback
-    analyze.md           <- Generate new PRD
     explore.md           <- Codebase exploration
     test.md              <- Run tests
+    build-and-test.md    <- Build project and run test suite
+    plan-to-prd.md       <- Convert plan to PRD gap items
   skills/
     README.md            <- Skill format guide
     <name>.md            <- Agent-created reusable workflows
@@ -460,7 +465,7 @@ To move to a new machine: clone `~/.squad/`, delete `engine/control.json`, re-ru
     {name}/
       charter.md         <- Agent identity and boundaries (editable)
       status.json        <- Current state (runtime)
-      history.md         <- Task history (last 20, runtime)
+      history.md         <- Task history, last 20 (runtime)
       live-output.log    <- Streaming output while working (runtime)
       output.log         <- Final output after completion (runtime)
   identity/

package/TODO.md

@@ -6,21 +6,21 @@ Ordered by difficulty: quick wins first, larger efforts later.
 
 ## Quick Wins (< 1 hour each)
 
-- [ ] **Output.log append, not overwrite** — keep all dispatch outputs, not just the last one. Rotate by dispatch ID.
-- [ ] **Persistent cooldowns** — save cooldown state to disk so engine restarts don't re-dispatch everything
-- [ ] **Worktree cleanup on merge/close** — when `pollPrStatus` detects a PR merged or abandoned, auto-remove its worktree. Currently only `runCleanup` catches old worktrees on a timer.
-- [ ] **Discovery skip logging** — log why items were skipped during discovery (cooldown, already dispatched, no idle agent) so users can diagnose "why isn't my work item being picked up?"
-- [ ] **Idle threshold alert** — if all agents are idle for >N minutes, notify via Teams/dashboard
-- [ ] **Config validation at startup** — verify all project paths exist, all agents defined, all playbooks exist. Fail fast with clear errors instead of silently skipping.
-- [ ] **macOS/Linux browser launch** — replace Windows `start` command with `open` (macOS) / `xdg-open` (Linux)
-- [ ] **Health check endpoint** — `/api/health` returning engine state, project reachability, agent statuses for monitoring
-- [ ] **Fan-out per-agent timeout** — when `@everyone` dispatches, set individual deadlines per agent instead of relying only on global `agentTimeout`
+- [x] **Output.log append, not overwrite** — per-dispatch archive at `output-{id}.log` + latest copy at `output.log`
+- [x] **Persistent cooldowns** — saved to `engine/cooldowns.json`, loaded at startup, 24hr auto-prune
+- [x] **Worktree cleanup on merge/close** — `handlePostMerge` removes worktrees when PR merges or is abandoned
+- [x] **Discovery skip logging** — PRD and work item discovery log skip counts by reason at debug level
+- [x] **Idle threshold alert** — warns when all agents idle >15min (configurable via `engine.idleAlertMinutes`)
+- [x] **Config validation at startup** — checks agents, project paths, playbooks, routing.md. Fatal errors exit(1).
+- [x] **macOS/Linux browser launch** — already platform-aware (was done previously)
+- [x] **Health check endpoint** — `GET /api/health` returning engine state, agents, project reachability, uptime
+- [x] **Fan-out per-agent timeout** — fan-out items carry `meta.deadline`, configurable via `engine.fanOutTimeout`
 
 ## Small Effort (1–3 hours each)
 
 - [ ] **Auto-retry with backoff** — when an agent errors, auto-retry with exponential backoff (5min, 15min, cap at 3 attempts) instead of requiring manual dashboard retry.
 - [ ] **Auto-escalation** — if an agent errors 3 times in a row, pause their dispatch and alert via dashboard/Teams
-- [ ] **Post-merge hooks** — when a PR merges, trigger configurable actions: clean up worktree, update PRD item status to `done`, notify Teams, update metrics
+- [x] **Post-merge hooks** — `handlePostMerge`: worktree cleanup, PRD status → implemented, prsMerged metric, Teams notification
 - [ ] **Pending dispatch explanation** — show in dashboard why each pending item hasn't been dispatched (no idle agent? cooldown? max concurrency?)
 - [ ] **Work item editing** — edit title, description, type, priority, agent assignment from the dashboard UI (currently requires editing JSON)
 - [ ] **Bulk operations** — retry/delete/reassign multiple work items at once

package/bin/squad.js

@@ -1,164 +1,164 @@
-#!/usr/bin/env node
-/**
- * Squad CLI — Central AI dev team manager
- *
- * Usage:
- *   squad init                     Bootstrap ~/.squad/ with default config and agents
- *   squad add <project-dir>        Link a project (interactive)
- *   squad remove <project-dir>     Unlink a project
- *   squad list                     List linked projects
- *   squad start                    Start the engine
- *   squad stop                     Stop the engine
- *   squad status                   Show engine status
- *   squad pause / resume           Pause/resume dispatching
- *   squad dash                     Start the dashboard
- *   squad work <title> [opts-json] Add a work item
- *   squad spawn <agent> <prompt>   Manually spawn an agent
- *   squad dispatch                 Force a dispatch cycle
- *   squad discover                 Dry-run work discovery
- *   squad cleanup                  Run cleanup manually
- *   squad plan <file|text> [proj]  Run a plan
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawn, execSync } = require('child_process');
-
-const SQUAD_HOME = path.join(require('os').homedir(), '.squad');
-const PKG_ROOT = path.resolve(__dirname, '..');
-
-const [cmd, ...rest] = process.argv.slice(2);
-
-// ─── Init: bootstrap ~/.squad/ from package templates ───────────────────────
-
-function init() {
-  if (fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
-    console.log(`\n  Squad already installed at ${SQUAD_HOME}`);
-    console.log('  To reinitialize config: squad init --force\n');
-    if (!rest.includes('--force')) return;
-  }
-
-  console.log(`\n  Bootstrapping Squad to ${SQUAD_HOME}...\n`);
-  fs.mkdirSync(SQUAD_HOME, { recursive: true });
-
-  // Copy all package files to ~/.squad/
-  const exclude = new Set([
-    'bin', 'node_modules', '.git', '.claude', 'package.json',
-    'package-lock.json', 'LICENSE', '.npmignore', '.gitignore',
-  ]);
-
-  copyDir(PKG_ROOT, SQUAD_HOME, exclude);
-
-  // Create config from template if it doesn't exist
-  const configPath = path.join(SQUAD_HOME, 'config.json');
-  if (!fs.existsSync(configPath)) {
-    const tmpl = path.join(SQUAD_HOME, 'config.template.json');
-    if (fs.existsSync(tmpl)) {
-      fs.copyFileSync(tmpl, configPath);
-    }
-  }
-
-  // Ensure runtime directories exist
-  const dirs = [
-    'engine', 'notes/inbox', 'notes/archive',
-    'identity', 'plans',
-  ];
-  for (const d of dirs) {
-    fs.mkdirSync(path.join(SQUAD_HOME, d), { recursive: true });
-  }
-
-  // Run squad.js init to populate config with defaults
-  execSync(`node "${path.join(SQUAD_HOME, 'squad.js')}" init`, { stdio: 'inherit' });
-
-  console.log('\n  Next steps:');
-  console.log('    squad add ~/my-project    Link your first project');
-  console.log('    squad start               Start the engine');
-  console.log('    squad dash                Open the dashboard\n');
-}
-
-function copyDir(src, dest, exclude) {
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    if (exclude.has(entry.name)) continue;
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      copyDir(srcPath, destPath, new Set()); // only exclude at top level
-    } else {
-      // Don't overwrite user-modified files (except on --force)
-      if (fs.existsSync(destPath) && !rest.includes('--force')) {
-        // Always update engine code files
-        if (!entry.name.endsWith('.js') && !entry.name.endsWith('.html')) continue;
-      }
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-// ─── Delegate: run commands against installed ~/.squad/ ─────────────────────
-
-function ensureInstalled() {
-  if (!fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
-    console.log('\n  Squad is not installed. Run: squad init\n');
-    process.exit(1);
-  }
-}
-
-function delegate(script, args) {
-  ensureInstalled();
-  const child = spawn(process.execPath, [path.join(SQUAD_HOME, script), ...args], {
-    stdio: 'inherit',
-    cwd: SQUAD_HOME,
-  });
-  child.on('exit', code => process.exit(code || 0));
-}
-
-// ─── Command routing ────────────────────────────────────────────────────────
-
-const engineCmds = new Set([
-  'start', 'stop', 'status', 'pause', 'resume',
-  'queue', 'sources', 'discover', 'dispatch',
-  'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
-]);
-
-if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-  console.log(`
-  Squad — Central AI dev team manager
-
-  Setup:
-    squad init                     Bootstrap ~/.squad/ (first time)
-    squad add <project-dir>        Link a project (interactive)
-    squad remove <project-dir>     Unlink a project
-    squad list                     List linked projects
-
-  Engine:
-    squad start                    Start engine daemon
-    squad stop                     Stop the engine
-    squad status                   Show agents, projects, queue
-    squad pause / resume           Pause/resume dispatching
-    squad dispatch                 Force a dispatch cycle
-    squad discover                 Dry-run work discovery
-    squad work <title> [opts]      Add a work item
-    squad spawn <agent> <prompt>   Manually spawn an agent
-    squad plan <file|text> [proj]  Run a plan
-    squad cleanup                  Clean temp files, worktrees, zombies
-
-  Dashboard:
-    squad dash                     Start web dashboard (default :7331)
-
-  Home: ${SQUAD_HOME}
-`);
-} else if (cmd === 'init') {
-  init();
-} else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
-  delegate('squad.js', [cmd, ...rest]);
-} else if (cmd === 'dash' || cmd === 'dashboard') {
-  delegate('dashboard.js', rest);
-} else if (engineCmds.has(cmd)) {
-  delegate('engine.js', [cmd, ...rest]);
-} else {
-  console.log(`  Unknown command: ${cmd}`);
-  console.log('  Run "squad help" for usage.\n');
-  process.exit(1);
-}
+#!/usr/bin/env node
+/**
+ * Squad CLI — Central AI dev team manager
+ *
+ * Usage:
+ *   squad init                     Bootstrap ~/.squad/ with default config and agents
+ *   squad add <project-dir>        Link a project (interactive)
+ *   squad remove <project-dir>     Unlink a project
+ *   squad list                     List linked projects
+ *   squad start                    Start the engine
+ *   squad stop                     Stop the engine
+ *   squad status                   Show engine status
+ *   squad pause / resume           Pause/resume dispatching
+ *   squad dash                     Start the dashboard
+ *   squad work <title> [opts-json] Add a work item
+ *   squad spawn <agent> <prompt>   Manually spawn an agent
+ *   squad dispatch                 Force a dispatch cycle
+ *   squad discover                 Dry-run work discovery
+ *   squad cleanup                  Run cleanup manually
+ *   squad plan <file|text> [proj]  Run a plan
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+const SQUAD_HOME = path.join(require('os').homedir(), '.squad');
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+// ─── Init: bootstrap ~/.squad/ from package templates ───────────────────────
+
+function init() {
+  if (fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log(`\n  Squad already installed at ${SQUAD_HOME}`);
+    console.log('  To reinitialize config: squad init --force\n');
+    if (!rest.includes('--force')) return;
+  }
+
+  console.log(`\n  Bootstrapping Squad to ${SQUAD_HOME}...\n`);
+  fs.mkdirSync(SQUAD_HOME, { recursive: true });
+
+  // Copy all package files to ~/.squad/
+  const exclude = new Set([
+    'bin', 'node_modules', '.git', '.claude', 'package.json',
+    'package-lock.json', 'LICENSE', '.npmignore', '.gitignore',
+  ]);
+
+  copyDir(PKG_ROOT, SQUAD_HOME, exclude);
+
+  // Create config from template if it doesn't exist
+  const configPath = path.join(SQUAD_HOME, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    const tmpl = path.join(SQUAD_HOME, 'config.template.json');
+    if (fs.existsSync(tmpl)) {
+      fs.copyFileSync(tmpl, configPath);
+    }
+  }
+
+  // Ensure runtime directories exist
+  const dirs = [
+    'engine', 'notes/inbox', 'notes/archive',
+    'identity', 'plans',
+  ];
+  for (const d of dirs) {
+    fs.mkdirSync(path.join(SQUAD_HOME, d), { recursive: true });
+  }
+
+  // Run squad.js init to populate config with defaults
+  execSync(`node "${path.join(SQUAD_HOME, 'squad.js')}" init`, { stdio: 'inherit' });
+
+  console.log('\n  Next steps:');
+  console.log('    squad add ~/my-project    Link your first project');
+  console.log('    squad start               Start the engine');
+  console.log('    squad dash                Open the dashboard\n');
+}
+
+function copyDir(src, dest, exclude) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (exclude.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, new Set()); // only exclude at top level
+    } else {
+      // Don't overwrite user-modified files (except on --force)
+      if (fs.existsSync(destPath) && !rest.includes('--force')) {
+        // Always update engine code files
+        if (!entry.name.endsWith('.js') && !entry.name.endsWith('.html')) continue;
+      }
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ─── Delegate: run commands against installed ~/.squad/ ─────────────────────
+
+function ensureInstalled() {
+  if (!fs.existsSync(path.join(SQUAD_HOME, 'engine.js'))) {
+    console.log('\n  Squad is not installed. Run: squad init\n');
+    process.exit(1);
+  }
+}
+
+function delegate(script, args) {
+  ensureInstalled();
+  const child = spawn(process.execPath, [path.join(SQUAD_HOME, script), ...args], {
+    stdio: 'inherit',
+    cwd: SQUAD_HOME,
+  });
+  child.on('exit', code => process.exit(code || 0));
+}
+
+// ─── Command routing ────────────────────────────────────────────────────────
+
+const engineCmds = new Set([
+  'start', 'stop', 'status', 'pause', 'resume',
+  'queue', 'sources', 'discover', 'dispatch',
+  'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
+]);
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(`
+  Squad — Central AI dev team manager
+
+  Setup:
+    squad init                     Bootstrap ~/.squad/ (first time)
+    squad add <project-dir>        Link a project (interactive)
+    squad remove <project-dir>     Unlink a project
+    squad list                     List linked projects
+
+  Engine:
+    squad start                    Start engine daemon
+    squad stop                     Stop the engine
+    squad status                   Show agents, projects, queue
+    squad pause / resume           Pause/resume dispatching
+    squad dispatch                 Force a dispatch cycle
+    squad discover                 Dry-run work discovery
+    squad work <title> [opts]      Add a work item
+    squad spawn <agent> <prompt>   Manually spawn an agent
+    squad plan <file|text> [proj]  Run a plan
+    squad cleanup                  Clean temp files, worktrees, zombies
+
+  Dashboard:
+    squad dash                     Start web dashboard (default :7331)
+
+  Home: ${SQUAD_HOME}
+`);
+} else if (cmd === 'init') {
+  init();
+} else if (cmd === 'add' || cmd === 'remove' || cmd === 'list') {
+  delegate('squad.js', [cmd, ...rest]);
+} else if (cmd === 'dash' || cmd === 'dashboard') {
+  delegate('dashboard.js', rest);
+} else if (engineCmds.has(cmd)) {
+  delegate('engine.js', [cmd, ...rest]);
+} else {
+  console.log(`  Unknown command: ${cmd}`);
+  console.log('  Run "squad help" for usage.\n');
+  process.exit(1);
+}