@yemi33/squad 0.1.9 → 0.1.11

package/README.md

@@ -41,9 +41,11 @@ node ~/.squad/squad.js init
 ## Quick Start
 
 ```bash
-# 1. Link your projects (interactive — prompts for name, description, repo config)
-squad add ~/repo1
-squad add ~/repo2
+# 1. Init + scan — finds all git repos on your machine, multi-select to add
+squad init
+#    → creates config, agents, engine defaults
+#    → scans ~ for git repos (auto-detects host, org, branch)
+#    → shows numbered list, pick with "1,3,5-7" or "all"
 
 # 2. Start the engine (runs in foreground, ticks every 60s)
 squad start
@@ -53,6 +55,13 @@ squad dash
 # → http://localhost:7331
 ```
 
+You can also add/scan repos later:
+```bash
+squad scan              # Re-scan and add more repos
+squad scan ~/code 4     # Scan specific dir, depth 4
+squad add ~/repo        # Add a single repo interactively
+```
+
 ## Setup via Claude Code
 
 If you use Claude Code as your daily driver, you can set up Squad by prompting Claude directly:
@@ -91,8 +100,9 @@ squad work "Explore the codebase and document the architecture"
 
 | Command | Description |
 |---------|-------------|
-| `squad init` | Bootstrap `~/.squad/` with default agents and config |
-| `squad add <dir>` | Link a project (auto-detects settings from git, prompts to confirm) |
+| `squad init` | Bootstrap `~/.squad/` then auto-scan for repos to add |
+| `squad scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
+| `squad add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
 | `squad remove <dir>` | Unlink a project |
 | `squad list` | List all linked projects with descriptions |
 | `squad start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
@@ -121,6 +131,7 @@ You can also run scripts directly: `node ~/.squad/engine.js start`, `node ~/.squ
                     │  mcp-servers.json ← auto-sync │
                     │  agents/          ← 5 agents  │
                     │  playbooks/       ← templates │
+                    │  prd.json         ← squad PRD │
                     │  skills/          ← workflows │
                     │  notes/       ← knowledge  │
                     └──────┬────────────────────────┘
@@ -132,8 +143,6 @@ You can also run scripts directly: `node ~/.squad/engine.js start`, `node ~/.squ
      │  .squad/     │ │  .squad/     │ │  .squad/     │
      │   work-items │ │   work-items │ │   work-items │
      │   pull-reqs  │ │   pull-reqs  │ │   pull-reqs  │
-     │  docs/       │ │  docs/       │ │  docs/       │
-     │   prd-gaps   │ │   prd-gaps   │ │   prd-gaps   │
      │  .claude/    │ │  .claude/    │ │  .claude/    │
      │   skills/    │ │   skills/    │ │   skills/    │
      └──────────────┘ └──────────────┘ └──────────────┘
@@ -141,7 +150,7 @@ You can also run scripts directly: `node ~/.squad/engine.js start`, `node ~/.squ
 
 ## What It Does
 
-- **Auto-discovers work** from PRD gaps, pull requests, and work queues across all linked projects
+- **Auto-discovers work** from squad-level PRD (multi-project), pull requests, and work queues across all linked projects
 - **Dispatches AI agents** (Claude CLI) with full project context, git worktrees, and MCP server access
 - **Routes intelligently** — fixes first, then reviews, then implementation, matched to agent strengths
 - **Learns from itself** — agents write findings, engine consolidates into institutional knowledge
@@ -159,7 +168,7 @@ You can also run scripts directly: `node ~/.squad/engine.js start`, `node ~/.squ
 The web dashboard at `http://localhost:7331` provides:
 
 - **Projects bar** — all linked projects with descriptions (hover for full text)
-- **Command Center** — add work items (per-project, auto-route, or fan-out), notes, and PRD items
+- **Command Center** — add work items, notes, plans, and PRD items (multi-project via `#project` tags)
 - **Squad Members** — agent cards with status, click for charter/history/output detail panel
   - **Live Output tab** — real-time streaming output for working agents (auto-refreshes every 3s)
 - **Work Items** — paginated table with status, source, type, priority, assigned agent, linked PRs, fan-out badges, and retry button for failed items
@@ -186,7 +195,6 @@ When you run `squad add <dir>`, it prompts for project details and saves them to
   "repoName": "MyProject",
   "mainBranch": "main",
   "workSources": {
-    "prd":          { "enabled": true, "path": "docs/prd-gaps.json" },
     "pullRequests": { "enabled": true, "path": ".squad/pull-requests.json" },
     "workItems":    { "enabled": true, "path": ".squad/work-items.json" }
   }
@@ -281,7 +289,7 @@ The engine discovers work from 5 sources, in priority order:
 |----------|--------|---------------|
 | 1 | PRs with changes-requested | `fix` |
 | 2 | PRs pending review | `review` |
-| 3 | PRD items (missing/planned) | `implement` |
+| 3 | Squad PRD items (missing/planned, multi-project) | `implement` |
 | 4 | Per-project work items | item's `type` |
 | 5 | Central work items | item's `type` |
 
@@ -358,10 +366,11 @@ All playbooks use `{{template_variables}}` filled from project config. The `work
 
 Uses `live-output.log` file modification time as a heartbeat:
 - **Process alive + recent output** → healthy, keep running
+- **Process alive + in blocking tool call** → extended timeout (matches tool's timeout + grace period)
 - **Process alive + silent >5min** → hung, kill and mark failed
 - **No process + silent >5min** → orphaned (engine restarted), mark failed
 
-Agents can run for hours as long as they're producing output. The `heartbeatTimeout` (default 5min) only triggers on silence.
+Agents can run for hours as long as they're producing output. The `heartbeatTimeout` (default 5min) only triggers on silence. When an agent is in a blocking tool call (e.g., `TaskOutput` with `block:true`, `Bash` with long timeout), the engine detects this from the live output and extends the timeout automatically.
 
 ### Automated Cleanup (every 10 ticks)
 
@@ -459,6 +468,7 @@ To move to a new machine: `npm install -g @yemi33/squad && squad init --force`,
   dashboard.js           <- Web dashboard server
   dashboard.html         <- Dashboard UI (single-file)
   config.json            <- projects[], agents, engine, claude settings
+  prd.json               <- Squad-level PRD (multi-project items)
   config.template.json   <- Template for new installs
   package.json           <- npm package definition
   mcp-servers.json       <- MCP servers (auto-synced, gitignored)
@@ -500,6 +510,4 @@ Each linked project keeps locally:
     pull-requests.json   <- PR tracker
   <project>/.claude/
     skills/              <- Project-specific skills (requires PR)
-  <project>/docs/
-    prd-gaps.json        <- PRD gap analysis
 ```

package/dashboard.html

@@ -80,6 +80,8 @@
   .prd-item-priority.low { background: rgba(139,148,158,0.15); color: var(--muted); }
   .prd-project-badge { font-size: 9px; padding: 1px 5px; border-radius: 6px; background: rgba(56,139,253,0.12); color: var(--blue); border: 1px solid rgba(56,139,253,0.25); white-space: nowrap; }
 
+  .notes-preview { max-height: 240px; overflow-y: auto; font-size: 12px; line-height: 1.6; color: var(--muted); font-family: Consolas, monospace; white-space: pre-wrap; word-wrap: break-word; background: var(--surface2); border: 1px solid var(--border); border-radius: 6px; padding: 12px 14px; cursor: pointer; transition: border-color 0.2s; }
+  .notes-preview:hover { border-color: var(--blue); }
   .inbox-item { background: var(--surface2); border: 1px solid var(--border); border-left: 3px solid var(--purple); border-radius: 4px; padding: 10px 12px; cursor: pointer; }
   .inbox-item:hover { border-color: var(--blue); border-left-color: var(--blue); }
   .inbox-name { font-weight: 500; font-size: 12px; color: var(--purple); margin-bottom: 4px; display: flex; justify-content: space-between; }
@@ -241,6 +243,28 @@
   .cmd-hints::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
   .cmd-hints code { color: var(--blue); font-size: 10px; background: var(--surface2); padding: 1px 5px; border-radius: 3px; }
 
+  .cmd-history-btn {
+    background: none; border: 1px solid var(--border); color: var(--muted); font-size: 11px;
+    cursor: pointer; padding: 3px 10px; border-radius: 4px; transition: all 0.2s;
+  }
+  .cmd-history-btn:hover { color: var(--text); border-color: var(--text); }
+  .cmd-history-list { list-style: none; padding: 0; margin: 0; }
+  .cmd-history-item {
+    display: flex; align-items: flex-start; gap: 10px; padding: 10px 0;
+    border-bottom: 1px solid var(--border);
+  }
+  .cmd-history-item:last-child { border-bottom: none; }
+  .cmd-history-item-body { flex: 1; min-width: 0; }
+  .cmd-history-item-text { font-size: 12px; color: var(--text); white-space: pre-wrap; word-break: break-word; font-family: Consolas, monospace; }
+  .cmd-history-item-meta { font-size: 10px; color: var(--muted); margin-top: 3px; display: flex; gap: 8px; }
+  .cmd-history-item-meta .chip { background: var(--surface2); padding: 1px 6px; border-radius: 3px; }
+  .cmd-history-resubmit {
+    background: var(--surface2); border: 1px solid var(--border); color: var(--blue);
+    font-size: 11px; cursor: pointer; padding: 4px 10px; border-radius: 4px; white-space: nowrap;
+    transition: all 0.2s; flex-shrink: 0;
+  }
+  .cmd-history-resubmit:hover { background: rgba(88,166,255,0.1); border-color: var(--blue); }
+  .cmd-history-empty { color: var(--muted); font-size: 12px; padding: 20px 0; text-align: center; }
   .cmd-toast {
     display: none; padding: 8px 14px; border-radius: 4px; font-size: 12px;
     margin-top: 10px; animation: fadeIn 0.3s;
@@ -401,6 +425,7 @@
       <span><code>/note</code> team note</span>
       <span><code>/prd</code> PRD item</span>
       <span><code>#project</code> target project</span>
+      <button class="cmd-history-btn" onclick="cmdShowHistory()">Past Commands</button>
     </div>
     <div class="cmd-toast" id="cmd-toast"></div>
   </section>
@@ -745,21 +770,18 @@ async function openInboxInExplorer(name) {
 
 function renderNotes(notes) {
   const el = document.getElementById('notes-list');
-  if (!notes.length) { el.innerHTML = '<p class="empty">No team notes yet.</p>'; return; }
-  el.innerHTML = '<div style="display:flex;flex-direction:column;gap:6px">' +
-    notes.map(d => '<div style="font-size:12px;color:var(--text);padding:6px 10px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;cursor:pointer" onclick="openNotesFile()">' + escHtml(d) + '</div>').join('') +
-  '</div>';
+  if (!notes || !notes.trim()) { el.innerHTML = '<p class="empty">No team notes yet.</p>'; return; }
+  el.innerHTML = '<div class="notes-preview" onclick="openNotesModal()" title="Click to expand">' + escHtml(notes) + '</div>';
 }
 
-async function openNotesFile() {
-  try {
-    const content = await fetch('/api/notes-full').then(r => r.text());
-    document.getElementById('modal-title').textContent = 'Team Notes (notes.md)';
-    document.getElementById('modal-body').textContent = content;
-    document.getElementById('modal-body').style.fontFamily = 'Consolas, monospace';
-    document.getElementById('modal-body').style.whiteSpace = 'pre-wrap';
-    document.getElementById('modal').classList.add('open');
-  } catch {}
+function openNotesModal() {
+  const preview = document.querySelector('.notes-preview');
+  if (!preview) return;
+  document.getElementById('modal-title').textContent = 'Team Notes';
+  document.getElementById('modal-body').textContent = preview.textContent;
+  document.getElementById('modal-body').style.fontFamily = 'Consolas, monospace';
+  document.getElementById('modal-body').style.whiteSpace = 'pre-wrap';
+  document.getElementById('modal').classList.add('open');
 }
 
 function renderPrd(prd) {
@@ -1406,10 +1428,11 @@ function cmdParseInput(raw) {
     type: '',             // work item type (auto-detected)
   };
 
-  // Detect /decide or /note prefix
-  if (/^\/decide\b/i.test(text) || /^\/note\b/i.test(text)) {
+  // Detect /decide, /note, or natural "remember" keyword
+  const rememberPattern = /^(remember|remember that|don't forget|note that|keep in mind)\b/i;
+  if (/^\/decide\b/i.test(text) || /^\/note\b/i.test(text) || rememberPattern.test(text)) {
     result.intent = 'note';
-    text = text.replace(/^\/decide\s*/i, '');
+    text = text.replace(/^\/decide\s*/i, '').replace(/^\/note\s*/i, '').replace(rememberPattern, '').trim();
   } else if (/^\/plan\b/i.test(text)) {
     result.intent = 'plan';
     text = text.replace(/^\/plan\s*/i, '');
@@ -1662,6 +1685,42 @@ function cmdKeyDown(e) {
     }
   }
 
+  // ArrowUp/ArrowDown to navigate command history (only when no popup visible)
+  if (e.key === 'ArrowUp' && !isPopupVisible) {
+    const input = document.getElementById('cmd-input');
+    // Only intercept if cursor is at start of input (or input is single-line)
+    if (input.selectionStart === 0 || !input.value.includes('\n')) {
+      const history = cmdGetHistory();
+      if (history.length === 0) return;
+      if (_cmdHistoryIdx === -1) _cmdHistoryDraft = input.value; // Save current draft
+      if (_cmdHistoryIdx < history.length - 1) {
+        _cmdHistoryIdx++;
+        input.value = history[_cmdHistoryIdx].text;
+        cmdAutoResize();
+        cmdRenderMeta();
+        e.preventDefault();
+        // Move cursor to end
+        setTimeout(() => input.setSelectionRange(input.value.length, input.value.length), 0);
+      }
+      return;
+    }
+  }
+  if (e.key === 'ArrowDown' && !isPopupVisible) {
+    const input = document.getElementById('cmd-input');
+    if (input.selectionStart === input.value.length || !input.value.includes('\n')) {
+      if (_cmdHistoryIdx >= 0) {
+        _cmdHistoryIdx--;
+        const history = cmdGetHistory();
+        input.value = _cmdHistoryIdx >= 0 ? history[_cmdHistoryIdx].text : (_cmdHistoryDraft || '');
+        cmdAutoResize();
+        cmdRenderMeta();
+        e.preventDefault();
+        setTimeout(() => input.setSelectionRange(input.value.length, input.value.length), 0);
+      }
+      return;
+    }
+  }
+
   // Ctrl+Enter to submit
   if (e.key === 'Enter' && e.ctrlKey) {
     e.preventDefault();
@@ -1689,6 +1748,10 @@ async function cmdSubmit() {
     } else {
       await cmdSubmitWorkItem(parsed);
     }
+    // Save to history on success
+    cmdSaveHistory(raw, parsed.intent);
+    _cmdHistoryIdx = -1;
+    _cmdHistoryDraft = '';
     // Clear on success
     input.value = '';
     cmdAutoResize();
@@ -1781,6 +1844,75 @@ async function cmdSubmitPrd(parsed) {
   const projLabel = (parsed.projects || []).length > 0 ? ' (' + parsed.projects.join(', ') + ')' : '';
   showToast('cmd-toast', 'PRD item ' + (data.id || id) + ' added' + projLabel, true);
 }
+// ─── Command History ──────────────────────────────────────────────────────────
+const CMD_HISTORY_KEY = 'squad-cmd-history';
+const CMD_HISTORY_MAX = 50;
+let _cmdHistoryIdx = -1; // -1 = not browsing history
+let _cmdHistoryDraft = ''; // saves current draft when browsing
+
+function cmdGetHistory() {
+  try { return JSON.parse(localStorage.getItem(CMD_HISTORY_KEY) || '[]'); } catch { return []; }
+}
+
+function cmdSaveHistory(raw, intent) {
+  const history = cmdGetHistory();
+  history.unshift({ text: raw, intent, timestamp: new Date().toISOString() });
+  if (history.length > CMD_HISTORY_MAX) history.length = CMD_HISTORY_MAX;
+  localStorage.setItem(CMD_HISTORY_KEY, JSON.stringify(history));
+}
+
+function cmdShowHistory() {
+  const history = cmdGetHistory();
+  const title = document.getElementById('modal-title');
+  const body = document.getElementById('modal-body');
+  title.textContent = 'Past Commands (' + history.length + ')';
+
+  if (history.length === 0) {
+    body.innerHTML = '<div class="cmd-history-empty">No commands yet. Submit something from the command center.</div>';
+  } else {
+    const intentColors = { 'work-item': 'var(--blue)', 'note': 'var(--green)', 'plan': 'var(--purple,#a855f7)', 'prd': 'var(--yellow,#d29922)' };
+    const intentLabels = { 'work-item': 'Work Item', 'note': 'Note', 'plan': 'Plan', 'prd': 'PRD' };
+    body.innerHTML = '<ul class="cmd-history-list">' + history.map((item, i) => {
+      const date = new Date(item.timestamp);
+      const ago = timeSinceStr(date);
+      const intentLabel = intentLabels[item.intent] || item.intent || 'work-item';
+      const intentColor = intentColors[item.intent] || 'var(--blue)';
+      return '<li class="cmd-history-item">' +
+        '<div class="cmd-history-item-body">' +
+          '<div class="cmd-history-item-text">' + escHtml(item.text) + '</div>' +
+          '<div class="cmd-history-item-meta">' +
+            '<span class="chip" style="color:' + intentColor + '">' + intentLabel + '</span>' +
+            '<span>' + ago + '</span>' +
+            '<span>' + date.toLocaleDateString() + ' ' + date.toLocaleTimeString([], {hour:'2-digit',minute:'2-digit'}) + '</span>' +
+          '</div>' +
+        '</div>' +
+        '<button class="cmd-history-resubmit" onclick="cmdResubmit(' + i + ')">Resubmit</button>' +
+      '</li>';
+    }).join('') + '</ul>';
+  }
+
+  document.getElementById('modal').classList.add('open');
+}
+
+function cmdResubmit(idx) {
+  const history = cmdGetHistory();
+  const item = history[idx];
+  if (!item) return;
+  document.getElementById('modal').classList.remove('open');
+  const input = document.getElementById('cmd-input');
+  input.value = item.text;
+  cmdAutoResize();
+  cmdRenderMeta();
+  input.focus();
+}
+
+function timeSinceStr(date) {
+  const s = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (s < 60) return s + 's ago';
+  if (s < 3600) return Math.floor(s / 60) + 'm ago';
+  if (s < 86400) return Math.floor(s / 3600) + 'h ago';
+  return Math.floor(s / 86400) + 'd ago';
+}
 </script>
 </body>
 </html>

package/dashboard.js

@@ -38,6 +38,30 @@ function safeReadDir(dir) {
   try { return fs.readdirSync(dir); } catch { return []; }
 }
 
+// Atomic write with Windows EPERM retry (matches engine.js safeWrite)
+function safeWrite(p, data) {
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  const tmp = p + '.tmp.' + process.pid;
+  try {
+    fs.writeFileSync(tmp, content);
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try { fs.renameSync(tmp, p); return; } catch (e) {
+        if (e.code === 'EPERM' && attempt < 4) {
+          const delay = 50 * (attempt + 1);
+          const start = Date.now(); while (Date.now() - start < delay) {}
+          continue;
+        }
+      }
+    }
+    try { fs.unlinkSync(tmp); } catch {}
+    safeWrite(p, content);
+  } catch {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
 function timeSince(ms) {
   const s = Math.floor((Date.now() - ms) / 1000);
   if (s < 60) return `${s}s ago`;
@@ -184,8 +208,7 @@ function getInbox() {
 }
 
 function getNotes() {
-  const content = safeRead(path.join(SQUAD_DIR, 'notes.md')) || '';
-  return content.split('\n').filter(l => l.startsWith('### ')).map(l => l.replace('### ', '').trim());
+  return safeRead(path.join(SQUAD_DIR, 'notes.md')) || '';
 }
 
 function getPullRequests() {
@@ -481,7 +504,7 @@ const server = http.createServer(async (req, res) => {
       delete item.failReason;
       delete item.failedAt;
       delete item.fanOutAgents;
-      fs.writeFileSync(wiPath, JSON.stringify(items, null, 2));
+      safeWrite(wiPath, items);
 
       // Clear completed dispatch entries so the engine doesn't dedup this item
       const dispatchPath = path.join(SQUAD_DIR, 'engine', 'dispatch.json');
@@ -495,7 +518,7 @@ const server = http.createServer(async (req, res) => {
           // Also clear fan-out entries
           dispatch.completed = dispatch.completed.filter(d => !d.meta?.parentKey || d.meta.parentKey !== dispatchKey);
           if (dispatch.completed.length !== before) {
-            fs.writeFileSync(dispatchPath, JSON.stringify(dispatch, null, 2));
+            safeWrite(dispatchPath, dispatch);
           }
         }
       } catch {}
@@ -544,13 +567,13 @@ const server = http.createServer(async (req, res) => {
           status.status = 'idle';
           delete status.currentTask;
           delete status.dispatched;
-          fs.writeFileSync(statusPath, JSON.stringify(status, null, 2));
+          safeWrite(statusPath, status);
         } catch {}
       }
 
       // Remove item from work-items file
       items.splice(idx, 1);
-      fs.writeFileSync(wiPath, JSON.stringify(items, null, 2));
+      safeWrite(wiPath, items);
 
       // Clear dispatch entries (pending, active, completed + fan-out)
       const dispatchPath = path.join(SQUAD_DIR, 'engine', 'dispatch.json');
@@ -570,7 +593,7 @@ const server = http.createServer(async (req, res) => {
           }
         }
         if (changed) {
-          fs.writeFileSync(dispatchPath, JSON.stringify(dispatch, null, 2));
+          safeWrite(dispatchPath, dispatch);
         }
       } catch {}
 
@@ -611,8 +634,8 @@ const server = http.createServer(async (req, res) => {
       const existing = safeRead(archivePath);
       if (existing) { try { archive = JSON.parse(existing); } catch {} }
       archive.push(item);
-      fs.writeFileSync(archivePath, JSON.stringify(archive, null, 2));
-      fs.writeFileSync(wiPath, JSON.stringify(items, null, 2));
+      safeWrite(archivePath, archive);
+      safeWrite(wiPath, items);
 
       return jsonReply(res, 200, { ok: true, id });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -642,6 +665,7 @@ const server = http.createServer(async (req, res) => {
   if (req.method === 'POST' && req.url === '/api/work-items') {
     try {
       const body = await readBody(req);
+      if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
       let wiPath;
       if (body.project) {
         // Write to project-specific queue
@@ -672,29 +696,24 @@ const server = http.createServer(async (req, res) => {
       if (body.agent) item.agent = body.agent;
       if (body.agents) item.agents = body.agents;
       items.push(item);
-      fs.writeFileSync(wiPath, JSON.stringify(items, null, 2));
+      safeWrite(wiPath, items);
       return jsonReply(res, 200, { ok: true, id });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/notes
+  // POST /api/notes — write to inbox so it flows through normal consolidation
   if (req.method === 'POST' && req.url === '/api/notes') {
     try {
       const body = await readBody(req);
-      const decPath = path.join(SQUAD_DIR, 'notes.md');
-      let content = safeRead(decPath) || '# Squad Notes\n\n## Active Notes\n';
+      if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
+      const inboxDir = path.join(SQUAD_DIR, 'notes', 'inbox');
+      fs.mkdirSync(inboxDir, { recursive: true });
       const today = new Date().toISOString().slice(0, 10);
-      const entry = `\n### ${today}: ${body.title}\n**By:** ${body.author || os.userInfo().username}\n**What:** ${body.what}\n${body.why ? '**Why:** ' + body.why + '\n' : ''}\n---\n`;
-      // Support both old and new marker formats
-      const marker = '## Active Notes';
-      const idx = content.indexOf(marker);
-      if (idx !== -1) {
-        const insertAt = idx + marker.length;
-        content = content.slice(0, insertAt) + '\n' + entry + content.slice(insertAt);
-      } else {
-        content += '\n' + entry;
-      }
-      fs.writeFileSync(decPath, content);
+      const author = body.author || os.userInfo().username;
+      const slug = (body.title || 'note').toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
+      const filename = `${author}-${slug}-${today}.md`;
+      const content = `# ${body.title}\n\n**By:** ${author}\n**Date:** ${today}\n\n${body.what}\n${body.why ? '\n**Why:** ' + body.why + '\n' : ''}`;
+      safeWrite(path.join(inboxDir, filename), content);
       return jsonReply(res, 200, { ok: true });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -703,6 +722,7 @@ const server = http.createServer(async (req, res) => {
   if (req.method === 'POST' && req.url === '/api/plan') {
     try {
       const body = await readBody(req);
+      if (!body.title || !body.title.trim()) return jsonReply(res, 400, { error: 'title is required' });
       // Write as a work item with type 'plan' — engine handles the chaining
       const wiPath = path.join(SQUAD_DIR, 'work-items.json');
       let items = [];
@@ -723,7 +743,7 @@ const server = http.createServer(async (req, res) => {
       if (body.project) item.project = body.project;
       if (body.agent) item.agent = body.agent;
       items.push(item);
-      fs.writeFileSync(wiPath, JSON.stringify(items, null, 2));
+      safeWrite(wiPath, items);
       return jsonReply(res, 200, { ok: true, id, agent: body.agent || '' });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -732,6 +752,7 @@ const server = http.createServer(async (req, res) => {
   if (req.method === 'POST' && req.url === '/api/prd-items') {
     try {
       const body = await readBody(req);
+      if (!body.name || !body.name.trim()) return jsonReply(res, 400, { error: 'name is required' });
       const prdPath = path.join(SQUAD_DIR, 'prd.json');
       let data = { missing_features: [], existing_features: [], open_questions: [] };
       const existing = safeRead(prdPath);
@@ -743,7 +764,7 @@ const server = http.createServer(async (req, res) => {
         rationale: body.rationale || '', status: 'missing', affected_areas: [],
         projects: body.projects || [],
       });
-      fs.writeFileSync(prdPath, JSON.stringify(data, null, 2));
+      safeWrite(prdPath, data);
       return jsonReply(res, 200, { ok: true, id: body.id });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -817,7 +838,7 @@ const server = http.createServer(async (req, res) => {
       } else {
         notes += '\n' + entry;
       }
-      fs.writeFileSync(notesPath, notes);
+      safeWrite(notesPath, notes);
 
       // Move to archive
       const archiveDir = path.join(SQUAD_DIR, 'notes', 'archive');

package/engine/spawn-agent.js

@@ -56,28 +56,66 @@ if (!claudeBin) {
 const debugPath = path.join(__dirname, 'spawn-debug.log');
 fs.writeFileSync(debugPath, `spawn-agent.js at ${new Date().toISOString()}\nclaudeBin=${claudeBin || 'not found'}\nprompt=${promptFile}\nsysPrompt=${sysPromptFile}\nextraArgs=${extraArgs.join(' ')}\n`);
 
-const cliArgs = ['-p', '--system-prompt', sysPrompt, ...extraArgs];
+// Pass system prompt via file to avoid ENAMETOOLONG on Windows (32KB arg limit)
+// Write to a temp file and use shell-based workaround
+const sysTmpPath = sysPromptFile + '.tmp';
+fs.writeFileSync(sysTmpPath, sysPrompt);
+const cliArgs = ['-p', '--system-prompt-file', sysTmpPath, ...extraArgs];
 
 if (!claudeBin) {
   fs.appendFileSync(debugPath, 'FATAL: Cannot find claude-code cli.js\n');
   process.exit(1);
 }
 
-const proc = spawn(process.execPath, [claudeBin, ...cliArgs], {
+// Check if --system-prompt-file is supported by trying it; if not, fall back to inline
+// but truncate to stay under Windows arg limit
+let actualArgs = cliArgs;
+try {
+  // Test: does claude support --system-prompt-file?
+  const testResult = require('child_process').spawnSync(process.execPath, [claudeBin, '--help'], { encoding: 'utf8', timeout: 5000 });
+  if (!(testResult.stdout || '').includes('system-prompt-file')) {
+    // Not supported — fall back to inline but safe: use --append-system-prompt with chunking
+    // or just inline if under 30KB
+    fs.unlinkSync(sysTmpPath);
+    if (Buffer.byteLength(sysPrompt) < 30000) {
+      actualArgs = ['-p', '--system-prompt', sysPrompt, ...extraArgs];
+    } else {
+      // Too large for inline — split: short identity as --system-prompt, rest prepended to user prompt
+      // Extract first section (agent identity) as the system prompt, rest goes into user context
+      const splitIdx = sysPrompt.indexOf('\n---\n');
+      const shortSys = splitIdx > 0 && splitIdx < 2000
+        ? sysPrompt.slice(0, splitIdx)
+        : sysPrompt.slice(0, 1500) + '\n\n[System prompt truncated for CLI arg limit — full context provided below in user message]';
+      actualArgs = ['-p', '--system-prompt', shortSys, ...extraArgs];
+    }
+  }
+} catch {
+  // If help check fails, try file approach anyway
+}
+
+const proc = spawn(process.execPath, [claudeBin, ...actualArgs], {
   stdio: ['pipe', 'pipe', 'pipe'],
   env
 });
 
-fs.appendFileSync(debugPath, `PID=${proc.pid || 'none'}\n`);
+fs.appendFileSync(debugPath, `PID=${proc.pid || 'none'}\nargs=${actualArgs.join(' ').slice(0, 500)}\n`);
 
 // Write PID file for parent engine to verify spawn
 const pidFile = promptFile.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid');
 fs.writeFileSync(pidFile, String(proc.pid || ''));
 
-// Send prompt via stdin
-proc.stdin.write(prompt);
+// Send prompt via stdin — if system prompt was truncated, prepend the full context
+if (Buffer.byteLength(sysPrompt) >= 30000) {
+  // System prompt was too large for CLI — prepend full context to user prompt
+  proc.stdin.write(`## Full Agent Context\n\n${sysPrompt}\n\n---\n\n## Your Task\n\n${prompt}`);
+} else {
+  proc.stdin.write(prompt);
+}
 proc.stdin.end();
 
+// Clean up temp file
+setTimeout(() => { try { fs.unlinkSync(sysTmpPath); } catch {} }, 5000);
+
 // Capture stderr separately for debugging
 let stderrBuf = '';
 proc.stderr.on('data', (chunk) => {

package/engine.js

@@ -506,10 +506,10 @@ function getRepoHostToolRule(project) {
 
 // ─── System Prompt Builder ──────────────────────────────────────────────────
 
+// Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
   const agent = config.agents[agentId];
   const charter = getAgentCharter(agentId);
-  const notes = getNotes();
   project = project || config.project || {};
 
   let prompt = '';
@@ -519,57 +519,66 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `Agent ID: ${agentId}\n`;
   prompt += `Skills: ${(agent.skills || []).join(', ')}\n\n`;
 
-  // Charter (detailed instructions)
+  // Charter (detailed instructions — typically 1-2KB)
   if (charter) {
     prompt += `## Your Charter\n\n${charter}\n\n`;
   }
 
-  // Agent history (past tasks)
-  const history = safeRead(path.join(AGENTS_DIR, agentId, 'history.md'));
-  if (history && history.trim() !== '# Agent History') {
-    prompt += `## Your Recent History\n\n${history}\n\n`;
-  }
-
-  // Project context
+  // Project context (fixed size)
   prompt += `## Project: ${project.name || 'Unknown Project'}\n\n`;
   prompt += `- Repo: ${project.repoName || 'Unknown'} (${project.adoOrg || 'Unknown'}/${project.adoProject || 'Unknown'})\n`;
   prompt += `- Repo ID: ${project.repositoryId || ''}\n`;
   prompt += `- Repo host: ${getRepoHostLabel(project)}\n`;
   prompt += `- Main branch: ${project.mainBranch || 'main'}\n\n`;
 
-  // Project conventions (from CLAUDE.md)
-  if (project.localPath) {
-    const claudeMd = safeRead(path.join(project.localPath, 'CLAUDE.md'));
-    if (claudeMd && claudeMd.trim()) {
-      // Truncate to 4KB to avoid bloating the system prompt
-      const truncated = claudeMd.length > 4096 ? claudeMd.slice(0, 4096) + '\n\n...(truncated)' : claudeMd;
-      prompt += `## Project Conventions (from CLAUDE.md)\n\n${truncated}\n\n`;
-    }
-  }
-
-  // Critical rules
+  // Critical rules (fixed size)
   prompt += `## Critical Rules\n\n`;
   prompt += `1. Use git worktrees — NEVER checkout on main working tree\n`;
   prompt += `2. ${getRepoHostToolRule(project)}\n`;
-  prompt += `3. Follow the project conventions above (from CLAUDE.md) if present\n`;
+  prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
   prompt += `4. Write learnings to: ${SQUAD_DIR}/notes/inbox/${agentId}-${dateStamp()}.md\n`;
   prompt += `5. Do NOT write to agents/*/status.json — the engine manages agent status automatically\n`;
   prompt += `6. If you discover a repeatable workflow, save it as a skill:\n`;
   prompt += `   - Squad-wide: \`${SKILLS_DIR}/<name>.md\` (no PR needed)\n`;
   prompt += `   - Project-specific: \`<project>/.claude/skills/<name>.md\` (requires a PR since it modifies the repo)\n\n`;
 
+  return prompt;
+}
+
+// Bulk context: history, notes, conventions, skills — prepended to user/task prompt.
+// This is the content that grows over time and would bloat the system prompt.
+function buildAgentContext(agentId, config, project) {
+  project = project || config.project || {};
+  const notes = getNotes();
+  let context = '';
+
+  // Agent history (past tasks)
+  const history = safeRead(path.join(AGENTS_DIR, agentId, 'history.md'));
+  if (history && history.trim() !== '# Agent History') {
+    context += `## Your Recent History\n\n${history}\n\n`;
+  }
+
+  // Project conventions (from CLAUDE.md)
+  if (project.localPath) {
+    const claudeMd = safeRead(path.join(project.localPath, 'CLAUDE.md'));
+    if (claudeMd && claudeMd.trim()) {
+      const truncated = claudeMd.length > 8192 ? claudeMd.slice(0, 8192) + '\n\n...(truncated)' : claudeMd;
+      context += `## Project Conventions (from CLAUDE.md)\n\n${truncated}\n\n`;
+    }
+  }
+
   // Skills
   const skillIndex = getSkillIndex();
   if (skillIndex) {
-    prompt += skillIndex + '\n';
+    context += skillIndex + '\n';
   }
 
-  // Team notes
+  // Team notes (the big one — can be 50KB)
   if (notes) {
-    prompt += `## Team Notes\n\n${notes}\n\n`;
+    context += `## Team Notes (MUST READ)\n\n${notes}\n\n`;
   }
 
-  return prompt;
+  return context;
 }
 
 function sanitizeBranch(name) {
@@ -631,12 +640,18 @@ function spawnAgent(dispatchItem, config) {
     }
   }
 
-  // Build the system prompt
+  // Build lean system prompt (identity + rules, ~2-4KB) and bulk context (history, notes, skills)
   const systemPrompt = buildSystemPrompt(agentId, config, project);
+  const agentContext = buildAgentContext(agentId, config, project);
+
+  // Prepend bulk context to task prompt — keeps system prompt small and stable
+  const fullTaskPrompt = agentContext
+    ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPrompt}`
+    : taskPrompt;
 
   // Write prompt and system prompt to temp files (avoids shell escaping issues)
   const promptPath = path.join(ENGINE_DIR, `prompt-${id}.md`);
-  safeWrite(promptPath, taskPrompt);
+  safeWrite(promptPath, fullTaskPrompt);
 
   const sysPromptPath = path.join(ENGINE_DIR, `sysprompt-${id}.md`);
   safeWrite(sysPromptPath, systemPrompt);
@@ -896,6 +911,7 @@ function completeDispatch(id, result = 'success', reason = '') {
 }
 
 // ─── Dependency Gate ─────────────────────────────────────────────────────────
+// Returns: true (deps met), false (deps pending), 'failed' (dep failed — propagate)
 function areDependenciesMet(item, config) {
   const deps = item.depends_on;
   if (!deps || deps.length === 0) return true;
@@ -911,7 +927,12 @@ function areDependenciesMet(item, config) {
   const workItems = safeJson(wiPath) || [];
   for (const depId of deps) {
     const depItem = workItems.find(w => w.sourcePlan === sourcePlan && w.planItemId === depId);
-    if (!depItem || depItem.status !== 'done') return false;
+    if (!depItem) {
+      log('warn', `Dependency ${depId} not found for ${item.id} (plan: ${sourcePlan}) — treating as unmet`);
+      return false;
+    }
+    if (depItem.status === 'failed') return 'failed'; // Propagate failure
+    if (depItem.status !== 'done') return false;
   }
   return true;
 }
@@ -948,6 +969,14 @@ function checkPlanCompletion(meta, config) {
   const planItems = workItems.filter(w => w.sourcePlan === planFile && w.planItemId !== 'PR');
   if (planItems.length === 0) return;
   if (!planItems.every(w => w.status === 'done')) return;
+
+  // Dedup guard: check if PR item already exists for this plan
+  const existingPrItem = workItems.find(w => w.sourcePlan === planFile && w.planItemId === 'PR');
+  if (existingPrItem) {
+    log('debug', `Plan ${planFile} already has PR item ${existingPrItem.id} — skipping`);
+    if (plan.status !== 'completed') { plan.status = 'completed'; plan.completedAt = ts(); safeWrite(path.join(PLANS_DIR, planFile), plan); }
+    return;
+  }
   log('info', `All ${planItems.length} items in plan ${planFile} completed — creating PR work item`);
   const maxNum = workItems.reduce((max, i) => {
     const m = (i.id || '').match(/(\d+)$/);
@@ -993,20 +1022,27 @@ function chainPlanToPrd(dispatchItem, meta, config) {
     return;
   }
 
-  // Find the plan file — look for recently created .md files in plans/
-  const planFiles = fs.readdirSync(planDir)
-    .filter(f => f.endsWith('.md'))
-    .map(f => ({ name: f, mtime: fs.statSync(path.join(planDir, f)).mtimeMs }))
-    .sort((a, b) => b.mtime - a.mtime);
-
-  // Use the most recently modified plan file (the one the plan agent just wrote)
-  const planFile = planFiles[0];
-  if (!planFile) {
-    log('warn', `Plan chaining: no .md plan files found in plans/ after task ${dispatchItem.id}`);
-    return;
+  // Use the plan filename from dispatch meta (set during plan task creation)
+  // Falls back to mtime-based detection if meta doesn't have it
+  let planFileName = meta?.planFileName || meta?.item?._planFileName;
+  if (planFileName && fs.existsSync(path.join(planDir, planFileName))) {
+    // Exact match from meta — no guessing
+  } else {
+    // Fallback: find most recently modified .md file
+    const planFiles = fs.readdirSync(planDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => ({ name: f, mtime: fs.statSync(path.join(planDir, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    planFileName = planFiles[0]?.name;
+    if (!planFileName) {
+      log('warn', `Plan chaining: no .md plan files found in plans/ after task ${dispatchItem.id}`);
+      return;
+    }
+    log('info', `Plan chaining: using mtime fallback — found ${planFileName}`);
   }
 
-  const planPath = path.join(planDir, planFile.name);
+  const planFile = { name: planFileName };
+  const planPath = path.join(planDir, planFileName);
   let planContent;
   try { planContent = fs.readFileSync(planPath, 'utf8'); } catch (e) {
     log('error', `Plan chaining: failed to read plan file ${planFile.name}: ${e.message}`);
@@ -1165,6 +1201,10 @@ function updateWorkItemStatus(meta, status, reason) {
       const anySuccess = results.some(r => r.status === 'done');
       const allDone = target.fanOutAgents ? results.length >= target.fanOutAgents.length : false;
 
+      // Timeout: if dispatched > 6 hours ago and not all agents reported, treat partial results as final
+      const dispatchAge = target.dispatched_at ? Date.now() - new Date(target.dispatched_at).getTime() : 0;
+      const timedOut = !allDone && dispatchAge > 6 * 60 * 60 * 1000 && results.length > 0;
+
       if (anySuccess) {
         target.status = 'done';
         delete target.failReason;
@@ -1172,9 +1212,11 @@ function updateWorkItemStatus(meta, status, reason) {
         target.completedAgents = Object.entries(target.agentResults)
           .filter(([, r]) => r.status === 'done')
           .map(([a]) => a);
-      } else if (allDone) {
+      } else if (allDone || timedOut) {
         target.status = 'failed';
-        target.failReason = 'All fan-out agents failed';
+        target.failReason = timedOut
+          ? `Fan-out timed out: ${results.length}/${(target.fanOutAgents || []).length} agents reported (all failed)`
+          : 'All fan-out agents failed';
         target.failedAt = ts();
       }
     } else {
@@ -2628,6 +2670,26 @@ function runCleanup(config, verbose = false) {
           } catch {}
         }
 
+        // Skip worktrees for active shared-branch plans
+        if (shouldClean) {
+          try {
+            const planDir = path.join(SQUAD_DIR, 'plans');
+            if (fs.existsSync(planDir)) {
+              for (const pf of fs.readdirSync(planDir).filter(f => f.endsWith('.json'))) {
+                const plan = safeJson(path.join(planDir, pf));
+                if (plan?.branch_strategy === 'shared-branch' && plan?.feature_branch && plan?.status !== 'completed') {
+                  const planBranch = sanitizeBranch(plan.feature_branch);
+                  if (dir === planBranch || dir.includes(planBranch) || planBranch.includes(dir)) {
+                    shouldClean = false;
+                    if (verbose) console.log(`  Skipping worktree ${dir}: active shared-branch plan`);
+                    break;
+                  }
+                }
+              }
+            }
+          } catch {}
+        }
+
         if (shouldClean) {
           try {
             execSync(`git worktree remove "${wtPath}" --force`, { cwd: root, stdio: 'pipe' });
@@ -2663,8 +2725,23 @@ function runCleanup(config, verbose = false) {
   // 5. Clean spawn-debug.log
   try { fs.unlinkSync(path.join(ENGINE_DIR, 'spawn-debug.log')); } catch {}
 
-  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies > 0) {
-    log('info', `Cleanup: ${cleaned.tempFiles} temp files, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies`);
+  // 6. Prune old output archive files (keep last 30 per agent)
+  for (const agentId of Object.keys(config.agents || {})) {
+    const agentDir = path.join(SQUAD_DIR, 'agents', agentId);
+    if (!fs.existsSync(agentDir)) continue;
+    try {
+      const outputFiles = fs.readdirSync(agentDir)
+        .filter(f => f.startsWith('output-') && f.endsWith('.log') && f !== 'output.log')
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(agentDir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+      for (const old of outputFiles.slice(30)) {
+        try { fs.unlinkSync(path.join(agentDir, old.name)); cleaned.files++; } catch {}
+      }
+    } catch {}
+  }
+
+  if (cleaned.tempFiles + cleaned.liveOutputs + cleaned.worktrees + cleaned.zombies + (cleaned.files || 0) > 0) {
+    log('info', `Cleanup: ${cleaned.tempFiles} temp files, ${cleaned.liveOutputs} live outputs, ${cleaned.worktrees} worktrees, ${cleaned.zombies} zombies, ${cleaned.files || 0} old output archives`);
   }
 
   return cleaned;
@@ -2693,6 +2770,11 @@ function saveCooldowns() {
   if (_cooldownWritePending) return;
   _cooldownWritePending = true;
   setTimeout(() => {
+    // Prune expired entries (>24h) before saving
+    const now = Date.now();
+    for (const [k, v] of dispatchCooldowns) {
+      if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
+    }
     const obj = Object.fromEntries(dispatchCooldowns);
     safeWrite(COOLDOWN_PATH, obj);
     _cooldownWritePending = false;
@@ -3187,8 +3269,17 @@ function discoverFromWorkItems(config, project) {
   for (const item of items) {
     if (item.status !== 'queued' && item.status !== 'pending') continue;
 
-    // Dependency gate: skip items whose depends_on are not yet met
-    if (item.depends_on && item.depends_on.length > 0 && !areDependenciesMet(item, config)) continue;
+    // Dependency gate: skip items whose depends_on are not yet met; propagate failure
+    if (item.depends_on && item.depends_on.length > 0) {
+      const depStatus = areDependenciesMet(item, config);
+      if (depStatus === 'failed') {
+        item.status = 'failed';
+        item.failReason = 'Dependency failed — cannot proceed';
+        log('warn', `Marking ${item.id} as failed: dependency failed (plan: ${item.sourcePlan})`);
+        continue;
+      }
+      if (!depStatus) continue;
+    }
 
     const key = `work-${project?.name || 'default'}-${item.id}`;
     if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) { skipped.gated++; continue; }
@@ -3593,6 +3684,8 @@ function discoverCentralWorkItems(config) {
         vars.task_description = item.title;
         vars.notes_content = '';
         try { vars.notes_content = fs.readFileSync(path.join(SQUAD_DIR, 'notes.md'), 'utf8'); } catch {}
+        // Track expected plan filename in meta for chainPlanToPrd
+        item._planFileName = planFileName;
       }
 
       // Inject ask-specific variables for the ask playbook
@@ -3615,7 +3708,7 @@ function discoverCentralWorkItems(config) {
         agentRole,
         task: item.title || item.description?.slice(0, 80) || item.id,
         prompt,
-        meta: { dispatchKey: key, source: 'central-work-item', item }
+        meta: { dispatchKey: key, source: 'central-work-item', item, planFileName: item._planFileName || null }
       });
 
       item.status = 'dispatched';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/squad",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Multi-agent AI dev team that runs from ~/.squad/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "squad": "bin/squad.js"

package/squad.js

@@ -165,12 +165,6 @@ async function addProject(targetDir) {
     mainBranch,
     prUrlBase,
     workSources: {
-      prd: {
-        enabled: true,
-        path: 'docs/prd-gaps.json',
-        itemFilter: { status: ['missing', 'planned'] },
-        cooldownMinutes: 30
-      },
       pullRequests: {
         enabled: true,
         path: '.squad/pull-requests.json',
@@ -244,11 +238,174 @@ function listProjects() {
   }
 }
 
+// ─── Scan & Multi-Select ─────────────────────────────────────────────────────
+
+function findGitRepos(rootDir, maxDepth = 3) {
+  const repos = [];
+  const visited = new Set();
+
+  function walk(dir, depth) {
+    if (depth > maxDepth || visited.has(dir)) return;
+    visited.add(dir);
+    try {
+      // Skip common non-project dirs
+      const base = path.basename(dir);
+      if (['node_modules', '.git', '.hg', 'AppData', '$Recycle.Bin', 'Windows', 'Program Files',
+           'Program Files (x86)', '.cache', '.npm', '.yarn', '.nuget', 'worktrees'].includes(base)) return;
+
+      const gitDir = path.join(dir, '.git');
+      if (fs.existsSync(gitDir)) {
+        repos.push(dir);
+        return; // Don't recurse into git repos (they may have nested submodules)
+      }
+
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() || entry.isSymbolicLink()) {
+          walk(path.join(dir, entry.name), depth + 1);
+        }
+      }
+    } catch {} // permission errors, etc.
+  }
+
+  walk(rootDir, 0);
+  return repos;
+}
+
+async function scanAndAdd() {
+  const homeDir = process.env.USERPROFILE || process.env.HOME || '';
+  const scanRoot = rest[0] || homeDir;
+  const maxDepth = parseInt(rest[1]) || 3;
+
+  console.log(`\n  Scanning for git repos in: ${scanRoot}`);
+  console.log(`  Max depth: ${maxDepth}\n`);
+
+  const repos = findGitRepos(scanRoot, maxDepth);
+  if (repos.length === 0) {
+    console.log('  No git repositories found.\n');
+    rl.close();
+    return;
+  }
+
+  const config = loadConfig();
+  const linkedPaths = new Set((config.projects || []).map(p => path.resolve(p.localPath)));
+
+  // Enrich repos with auto-discovered metadata
+  const enriched = repos.map(repoPath => {
+    const detected = autoDiscover(repoPath);
+    const alreadyLinked = linkedPaths.has(path.resolve(repoPath));
+    return {
+      path: repoPath,
+      name: detected.name || detected.repoName || path.basename(repoPath),
+      host: detected.repoHost || '?',
+      org: detected.org || '',
+      project: detected.project || '',
+      repoName: detected.repoName || path.basename(repoPath),
+      mainBranch: detected.mainBranch || 'main',
+      description: detected.description || '',
+      linked: alreadyLinked,
+    };
+  });
+
+  console.log(`  Found ${enriched.length} git repo(s):\n`);
+  enriched.forEach((r, i) => {
+    const tag = r.linked ? ' (already linked)' : '';
+    const hostTag = r.host === 'ado' ? 'ADO' : r.host === 'github' ? 'GitHub' : 'git';
+    console.log(`  ${String(i + 1).padStart(3)}. ${r.name} [${hostTag}]${tag}`);
+    console.log(`       ${r.path}`);
+  });
+
+  console.log('\n  Enter numbers to add (comma-separated, ranges ok, e.g. "1,3,5-7")');
+  console.log('  Or "all" to add all unlinked repos, "q" to quit.\n');
+
+  const answer = await ask('Select repos', '');
+  if (!answer || answer.toLowerCase() === 'q') {
+    console.log('  Cancelled.\n');
+    rl.close();
+    return;
+  }
+
+  // Parse selection
+  let indices;
+  if (answer.toLowerCase() === 'all') {
+    indices = enriched.map((_, i) => i).filter(i => !enriched[i].linked);
+  } else {
+    indices = [];
+    for (const part of answer.split(',')) {
+      const trimmed = part.trim();
+      const rangeMatch = trimmed.match(/^(\d+)\s*-\s*(\d+)$/);
+      if (rangeMatch) {
+        const start = parseInt(rangeMatch[1]) - 1;
+        const end = parseInt(rangeMatch[2]) - 1;
+        for (let i = start; i <= end; i++) indices.push(i);
+      } else {
+        const n = parseInt(trimmed) - 1;
+        if (!isNaN(n)) indices.push(n);
+      }
+    }
+  }
+
+  // Filter valid, unlinked selections
+  const toAdd = [...new Set(indices)]
+    .filter(i => i >= 0 && i < enriched.length && !enriched[i].linked)
+    .map(i => enriched[i]);
+
+  if (toAdd.length === 0) {
+    console.log('  Nothing to add.\n');
+    rl.close();
+    return;
+  }
+
+  console.log(`\n  Adding ${toAdd.length} project(s)...\n`);
+
+  for (const repo of toAdd) {
+    const prUrlBase = repo.host === 'github'
+      ? (repo.org && repo.repoName ? `https://github.com/${repo.org}/${repo.repoName}/pull/` : '')
+      : (repo.org && repo.project && repo.repoName
+        ? `https://${repo.org}.visualstudio.com/DefaultCollection/${repo.project}/_git/${repo.repoName}/pullrequest/`
+        : '');
+
+    const project = {
+      name: repo.name,
+      description: repo.description,
+      localPath: repo.path.replace(/\\/g, '/'),
+      repositoryId: '',
+      adoOrg: repo.org,
+      adoProject: repo.project,
+      repoName: repo.repoName,
+      mainBranch: repo.mainBranch,
+      prUrlBase,
+      workSources: {
+        pullRequests: { enabled: true, path: '.squad/pull-requests.json', cooldownMinutes: 30 },
+        workItems: { enabled: true, path: '.squad/work-items.json', cooldownMinutes: 0 },
+        specs: { enabled: true, filePatterns: ['docs/**/*.md'], statePath: '.squad/spec-tracker.json', lookbackDays: 7 },
+      }
+    };
+
+    config.projects.push(project);
+
+    // Create project-local state files
+    const squadDir = path.join(repo.path, '.squad');
+    if (!fs.existsSync(squadDir)) fs.mkdirSync(squadDir, { recursive: true });
+    for (const [f, content] of Object.entries({ 'pull-requests.json': '[]', 'work-items.json': '[]' })) {
+      const fp = path.join(squadDir, f);
+      if (!fs.existsSync(fp)) fs.writeFileSync(fp, content);
+    }
+
+    console.log(`  + ${repo.name} (${repo.path})`);
+  }
+
+  saveConfig(config);
+  console.log(`\n  Done. ${config.projects.length} total project(s) linked.`);
+  console.log(`  Run "node squad.js list" to verify.\n`);
+  rl.close();
+}
+
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
 const [cmd, ...rest] = process.argv.slice(2);
 
-function initSquad() {
+async function initSquad() {
   const config = loadConfig();
   if (!config.projects) config.projects = [];
   if (!config.engine) config.engine = { tickInterval: 60000, staleThreshold: 1800000, maxConcurrent: 3, inboxConsolidateThreshold: 5, agentTimeout: 600000, maxTurns: 100 };
@@ -264,13 +421,15 @@ function initSquad() {
   }
   saveConfig(config);
   console.log(`\n  Squad initialized at ${SQUAD_HOME}`);
-  console.log(`  Projects: ${config.projects.length}`);
-  console.log(`\n  Add a project:`);
-  console.log(`    node squad add <project-dir>\n`);
+  console.log(`  Config, agents, and engine defaults created.\n`);
+
+  // Auto-chain into scan
+  console.log('  Now let\'s find your repos...\n');
+  await scanAndAdd();
 }
 
 const commands = {
-  init: () => initSquad(),
+  init: () => initSquad().catch(e => { console.error(e); process.exit(1); }),
   add: () => {
     const dir = rest[0];
     if (!dir) { console.log('Usage: node squad add <project-dir>'); process.exit(1); }
@@ -282,6 +441,7 @@ const commands = {
     removeProject(dir);
   },
   list: () => listProjects(),
+  scan: () => scanAndAdd().catch(e => { console.error(e); process.exit(1); }),
 };
 
 if (cmd && commands[cmd]) {
@@ -291,7 +451,8 @@ if (cmd && commands[cmd]) {
   console.log('  Usage: node squad <command>\n');
   console.log('  Commands:');
   console.log('    init                    Initialize squad (no projects)');
-  console.log('    add <project-dir>       Link a project');
+  console.log('    scan [dir] [depth]      Scan for git repos and multi-select to add');
+  console.log('    add <project-dir>       Link a single project');
   console.log('    remove <project-dir>    Unlink a project');
   console.log('    list                    List linked projects\n');
   console.log('  After init, also use:');