@yemi33/squad 0.1.5 → 0.1.7

package/dashboard.html

@@ -78,6 +78,7 @@
   .prd-item-priority.high { background: rgba(248,81,73,0.15); color: var(--red); }
   .prd-item-priority.medium { background: rgba(210,153,34,0.15); color: var(--yellow); }
   .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; }
 
   .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); }
@@ -232,7 +233,7 @@
 
   /* Hints bar */
   .cmd-hints {
-    display: flex; gap: 12px; margin-top: 2px; font-size: 10px; color: var(--muted);
+    display: flex; gap: 12px; margin-top: 4px; font-size: 10px; color: var(--muted);
     letter-spacing: 0.2px; padding: 0 4px; overflow-x: auto; white-space: nowrap;
     scrollbar-width: thin; scrollbar-color: var(--border) transparent;
   }
@@ -387,7 +388,7 @@
   <section class="cmd-center">
     <h2>Command Center</h2>
     <div class="cmd-input-wrap" id="cmd-input-wrap">
-      <textarea id="cmd-input" rows="1" placeholder='What do you need? e.g. "Fix the auth bug @dallas" or "/note always use feature flags"'
+      <textarea id="cmd-input" rows="1" placeholder='What do you need? e.g. "Fix the auth bug @dallas", "explain the dispatch flow", or "/note always use feature flags"'
         oninput="cmdInputChanged()" onkeydown="cmdKeyDown(event)"></textarea>
       <button class="cmd-send-btn" id="cmd-send-btn" onclick="cmdSubmit()">Send <kbd>Ctrl+Enter</kbd></button>
     </div>
@@ -410,8 +411,9 @@
   </section>
 
   <section id="work-items-section" style="overflow:visible">
-    <h2>Work Items <span class="count" id="wi-count">0</span></h2>
+    <h2>Work Items <span class="count" id="wi-count">0</span> <button class="pr-pager-btn" style="font-size:9px;padding:2px 8px;margin-left:8px" onclick="toggleWorkItemArchive()">See Archive</button></h2>
     <div id="work-items-content"><p class="empty">No work items. Add tasks via Command Center above.</p></div>
+    <div id="work-items-archive" style="display:none;margin-top:12px"></div>
   </section>
 
   <section class="prd-panel" id="prd-section">
@@ -680,10 +682,14 @@ function renderPrdProgress(prog) {
       const prLinks = (i.prs || []).map(pr =>
         '<a class="pr-title" href="' + escHtml(pr.url || '#') + '" target="_blank" style="font-size:10px;margin-left:4px" title="' + escHtml(pr.title || '') + '">' + escHtml(pr.id) + '</a>'
       ).join(' ');
+      const projBadges = (i.projects || []).map(p =>
+        '<span class="prd-project-badge">' + escHtml(p) + '</span>'
+      ).join(' ');
       return '<div class="prd-item-row">' +
         '<span>' + statusIcon(i.status) + '</span>' +
         '<span class="prd-item-id">' + escHtml(i.id) + '</span>' +
         '<span class="prd-item-name" title="' + escHtml(i.name) + '">' + escHtml(i.name) + '</span>' +
+        (projBadges ? '<span>' + projBadges + '</span>' : '') +
         (prLinks ? '<span>' + prLinks + '</span>' : '') +
         '<span class="prd-item-priority ' + (i.priority || '') + '">' + escHtml(i.priority || '') + '</span>' +
       '</div>';
@@ -1197,11 +1203,23 @@ function wiRow(item) {
     '</td>' +
     '<td>' + prLink + '</td>' +
     '<td><span class="pr-date">' + shortTime(item.created) + '</span></td>' +
-    '<td><button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--red);border-color:var(--red)" onclick="event.stopPropagation();deleteWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Delete work item and kill agent">&#x2715;</button></td>' +
+    '<td style="white-space:nowrap">' +
+      ((item.status === 'done' || item.status === 'failed') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--muted);border-color:var(--border);margin-right:4px" onclick="event.stopPropagation();archiveWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Archive work item">&#x1F4E6;</button>' : '') +
+      '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--red);border-color:var(--red)" onclick="event.stopPropagation();deleteWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Delete work item and kill agent">&#x2715;</button>' +
+    '</td>' +
   '</tr>';
 }
 
 function renderWorkItems(items) {
+  // Sort: active/dispatched first, then by most recent activity
+  const statusOrder = { dispatched: 0, pending: 1, queued: 1, failed: 2, done: 3 };
+  items.sort((a, b) => {
+    const sa = statusOrder[a.status] ?? 2, sb = statusOrder[b.status] ?? 2;
+    if (sa !== sb) return sa - sb;
+    const ta = a.completedAt || a.dispatched_at || a.created || '';
+    const tb = b.completedAt || b.dispatched_at || b.created || '';
+    return tb.localeCompare(ta); // most recent first
+  });
   allWorkItems = items;
   const el = document.getElementById('work-items-content');
   const countEl = document.getElementById('wi-count');
@@ -1261,6 +1279,44 @@ async function deleteWorkItem(id, source) {
   } catch (e) { alert('Delete error: ' + e.message); }
 }
 
+async function archiveWorkItem(id, source) {
+  try {
+    const res = await fetch('/api/work-items/archive', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, source: source || undefined })
+    });
+    if (res.ok) { refresh(); } else {
+      const d = await res.json();
+      alert('Archive failed: ' + (d.error || 'unknown'));
+    }
+  } catch (e) { alert('Archive error: ' + e.message); }
+}
+
+let wiArchiveVisible = false;
+async function toggleWorkItemArchive() {
+  const el = document.getElementById('work-items-archive');
+  wiArchiveVisible = !wiArchiveVisible;
+  if (!wiArchiveVisible) { el.style.display = 'none'; return; }
+  el.style.display = 'block';
+  el.innerHTML = '<p class="empty">Loading archive...</p>';
+  try {
+    const items = await fetch('/api/work-items/archive').then(r => r.json());
+    if (!items.length) { el.innerHTML = '<p class="empty">No archived work items.</p>'; return; }
+    el.innerHTML = '<div style="font-size:10px;color:var(--muted);margin-bottom:6px;font-weight:600;text-transform:uppercase;letter-spacing:0.5px">Archived (' + items.length + ')</div>' +
+      '<div class="pr-table-wrap"><table class="pr-table"><thead><tr><th>ID</th><th>Title</th><th>Type</th><th>Status</th><th>Agent</th><th>Archived</th></tr></thead><tbody>' +
+      items.map(function(i) {
+        return '<tr style="opacity:0.6">' +
+          '<td><span class="pr-id">' + escHtml(i.id || '') + '</span></td>' +
+          '<td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">' + escHtml(i.title || '') + '</td>' +
+          '<td><span class="dispatch-type ' + (i.type || '') + '">' + escHtml(i.type || '') + '</span></td>' +
+          '<td style="color:' + (i.status === 'done' ? 'var(--green)' : 'var(--red)') + '">' + escHtml(i.status || '') + '</td>' +
+          '<td>' + escHtml(i.dispatched_to || '—') + '</td>' +
+          '<td class="pr-date">' + shortTime(i.archivedAt) + '</td>' +
+        '</tr>';
+      }).join('') + '</tbody></table></div>';
+  } catch (e) { el.innerHTML = '<p class="empty">Failed to load archive.</p>'; }
+}
+
 function wiPrev() { if (wiPage > 0) { wiPage--; renderWorkItems(allWorkItems); } }
 function wiNext() { const tp = Math.ceil(allWorkItems.length / WI_PER_PAGE); if (wiPage < tp-1) { wiPage++; renderWorkItems(allWorkItems); } }
 
@@ -1323,6 +1379,7 @@ function showToast(id, msg, ok) {
 function detectWorkItemType(text) {
   const t = text.toLowerCase();
   const patterns = [
+    { type: 'ask',      words: ['explain', 'why does', 'why is', 'what does', 'how do i', 'how do you', 'what\'s the', 'tell me', 'can you explain', 'walk me through'] },
     { type: 'explore',  words: ['explore', 'investigate', 'understand', 'analyze', 'audit', 'document', 'architecture', 'how does', 'what is', 'look into', 'research', 'survey', 'map out', 'codebase'] },
     { type: 'fix',      words: ['fix', 'bug', 'broken', 'crash', 'error', 'issue', 'patch', 'repair', 'resolve', 'regression', 'failing', 'doesn\'t work', 'not working'] },
     { type: 'review',   words: ['review', 'code review', 'check pr', 'look at pr', 'audit code', 'inspect'] },
@@ -1342,7 +1399,8 @@ function cmdParseInput(raw) {
     agents: [],           // assigned agent IDs
     fanout: false,
     priority: 'medium',
-    project: '',
+    project: '',          // primary project (for work items, plans)
+    projects: [],          // multi-project list (for PRD items)
     title: '',
     description: '',
     type: '',             // work item type (auto-detected)
@@ -1352,6 +1410,19 @@ function cmdParseInput(raw) {
   if (/^\/decide\b/i.test(text) || /^\/note\b/i.test(text)) {
     result.intent = 'note';
     text = text.replace(/^\/decide\s*/i, '');
+  } else if (/^\/plan\b/i.test(text)) {
+    result.intent = 'plan';
+    text = text.replace(/^\/plan\s*/i, '');
+    // Extract branch strategy flag
+    if (/--parallel\b/i.test(text)) {
+      result.branchStrategy = 'parallel';
+      text = text.replace(/--parallel\b/i, '').trim();
+    } else if (/--shared\b/i.test(text)) {
+      result.branchStrategy = 'shared-branch';
+      text = text.replace(/--shared\b/i, '').trim();
+    } else {
+      result.branchStrategy = 'shared-branch'; // default
+    }
   } else if (/^\/prd\b/i.test(text)) {
     result.intent = 'prd';
     text = text.replace(/^\/prd\s*/i, '');
@@ -1377,12 +1448,15 @@ function cmdParseInput(raw) {
   else if (/!low\b/i.test(text)) { result.priority = 'low'; text = text.replace(/!low\b/i, '').trim(); }
   else if (/!urgent\b/i.test(text)) { result.priority = 'high'; text = text.replace(/!urgent\b/i, '').trim(); }
 
-  // Extract #project
+  // Extract #project(s)
   const projRe = /#(\S+)/g;
   while ((m = projRe.exec(text)) !== null) {
     const pname = m[1];
     const proj = cmdProjects.find(p => p.name.toLowerCase() === pname.toLowerCase());
-    if (proj) result.project = proj.name;
+    if (proj) {
+      result.project = proj.name; // last match for backward compat (work items, plans)
+      if (!result.projects.includes(proj.name)) result.projects.push(proj.name);
+    }
   }
   text = text.replace(/#\S+/g, '').trim();
 
@@ -1410,13 +1484,19 @@ function cmdRenderMeta() {
   let chips = [];
 
   // Intent chip
-  const intentLabels = { 'work-item': 'Work Item', 'note': 'Note', 'prd': 'PRD Item' };
+  const intentLabels = { 'work-item': 'Work Item', 'note': 'Note', 'prd': 'PRD Item', 'plan': 'Plan → PRD → Dispatch' };
   chips.push('<span class="cmd-chip intent">' + intentLabels[parsed.intent] + '</span>');
 
   // Type chip (only for work items)
   if (parsed.intent === 'work-item') {
     chips.push('<span class="cmd-chip">' + parsed.type + '</span>');
   }
+  // Pipeline chip for /plan
+  if (parsed.intent === 'plan') {
+    const strategy = parsed.branchStrategy || 'shared-branch';
+    const stratLabel = strategy === 'parallel' ? 'parallel branches' : 'shared branch';
+    chips.push('<span class="cmd-chip" style="background:var(--purple,#a855f7);color:#fff">plan → prd → agents (' + stratLabel + ')</span>');
+  }
 
   // Priority chip
   chips.push('<span class="cmd-chip priority-' + parsed.priority + '">' + parsed.priority + ' priority</span>');
@@ -1432,8 +1512,10 @@ function cmdRenderMeta() {
     }
   }
 
-  // Project chip
-  if (parsed.project) {
+  // Project chip(s)
+  if (parsed.projects.length > 0) {
+    parsed.projects.forEach(p => chips.push('<span class="cmd-chip project-chip">#' + escHtml(p) + '</span>'));
+  } else if (parsed.project) {
     chips.push('<span class="cmd-chip project-chip">#' + escHtml(parsed.project) + '</span>');
   }
 
@@ -1600,6 +1682,8 @@ async function cmdSubmit() {
   try {
     if (parsed.intent === 'note') {
       await cmdSubmitNote(parsed);
+    } else if (parsed.intent === 'plan') {
+      await cmdSubmitPlan(parsed);
     } else if (parsed.intent === 'prd') {
       await cmdSubmitPrd(parsed);
     } else {
@@ -1657,6 +1741,26 @@ async function cmdSubmitNote(parsed) {
   showToast('cmd-toast', 'Note added', true);
 }
 
+async function cmdSubmitPlan(parsed) {
+  const body = {
+    title: parsed.title,
+    description: parsed.description || '',
+    priority: parsed.priority,
+    branch_strategy: parsed.branchStrategy || 'shared-branch',
+  };
+  if (parsed.project) body.project = parsed.project;
+  if (parsed.agents.length === 1) body.agent = parsed.agents[0];
+
+  const res = await fetch('/api/plan', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error || 'Failed to create plan');
+  const agentLabel = data.agent ? ' → ' + data.agent : '';
+  showToast('cmd-toast', 'Plan ' + data.id + ' dispatched' + agentLabel + ' (will chain → PRD → dispatch)', true);
+}
+
 async function cmdSubmitPrd(parsed) {
   // Auto-generate PRD ID
   const id = 'M' + String(Date.now()).slice(-4);
@@ -1668,12 +1772,14 @@ async function cmdSubmitPrd(parsed) {
       description: parsed.description || parsed.title,
       priority: parsed.priority,
       estimated_complexity: 'medium',
+      projects: parsed.projects || [],
       rationale: '',
     }),
   });
   const data = await res.json();
   if (!res.ok) throw new Error(data.error || 'Failed to add');
-  showToast('cmd-toast', 'PRD item ' + (data.id || id) + ' added', true);
+  const projLabel = (parsed.projects || []).length > 0 ? ' (' + parsed.projects.join(', ') + ')' : '';
+  showToast('cmd-toast', 'PRD item ' + (data.id || id) + ' added' + projLabel, true);
 }
 </script>
 </body>

package/dashboard.js

@@ -107,11 +107,8 @@ function getAgents() {
 }
 
 function getPrdInfo() {
-  // Aggregate PRD across all projects
-  const firstProject = PROJECTS[0];
-  const root = path.resolve(firstProject.localPath || path.resolve(SQUAD_DIR, '..'));
-  const prdSrc = firstProject.workSources?.prd || CONFIG.workSources?.prd || {};
-  const prdPath = path.resolve(root, prdSrc.path || 'docs/prd-gaps.json');
+  // Squad-level PRD — single file at ~/.squad/prd.json
+  const prdPath = path.join(SQUAD_DIR, 'prd.json');
   if (!fs.existsSync(prdPath)) return { progress: null, status: null };
 
   try {
@@ -149,6 +146,7 @@ function getPrdInfo() {
       items: items.map(i => ({
         id: i.id, name: i.name || i.title, priority: i.priority,
         complexity: i.estimated_complexity || i.size, status: i.status || 'missing',
+        projects: i.projects || [],
         prs: prdToPr[i.id] || []
       })),
     };
@@ -580,6 +578,66 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
+  // POST /api/work-items/archive — move a completed/failed work item to archive
+  if (req.method === 'POST' && req.url === '/api/work-items/archive') {
+    try {
+      const body = await readBody(req);
+      const { id, source } = body;
+      if (!id) return jsonReply(res, 400, { error: 'id required' });
+
+      let wiPath;
+      if (!source || source === 'central') {
+        wiPath = path.join(SQUAD_DIR, 'work-items.json');
+      } else {
+        const proj = PROJECTS.find(p => p.name === source);
+        if (proj) {
+          const root = path.resolve(proj.localPath || path.resolve(SQUAD_DIR, '..'));
+          const wiSrc = proj.workSources?.workItems || CONFIG.workSources?.workItems || {};
+          wiPath = path.resolve(root, wiSrc.path || '.squad/work-items.json');
+        }
+      }
+      if (!wiPath) return jsonReply(res, 404, { error: 'source not found' });
+
+      const items = JSON.parse(safeRead(wiPath) || '[]');
+      const idx = items.findIndex(i => i.id === id);
+      if (idx === -1) return jsonReply(res, 404, { error: 'item not found' });
+
+      const item = items.splice(idx, 1)[0];
+      item.archivedAt = new Date().toISOString();
+
+      // Append to archive file
+      const archivePath = wiPath.replace('.json', '-archive.json');
+      let archive = [];
+      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));
+
+      return jsonReply(res, 200, { ok: true, id });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // GET /api/work-items/archive — list archived work items
+  if (req.method === 'GET' && req.url === '/api/work-items/archive') {
+    try {
+      let allArchived = [];
+      // Central archive
+      const centralPath = path.join(SQUAD_DIR, 'work-items-archive.json');
+      const central = safeRead(centralPath);
+      if (central) { try { allArchived.push(...JSON.parse(central).map(i => ({ ...i, _source: 'central' }))); } catch {} }
+      // Project archives
+      for (const project of PROJECTS) {
+        const root = path.resolve(project.localPath || path.resolve(SQUAD_DIR, '..'));
+        const wiSrc = project.workSources?.workItems || CONFIG.workSources?.workItems || {};
+        const archPath = path.resolve(root, (wiSrc.path || '.squad/work-items.json').replace('.json', '-archive.json'));
+        const content = safeRead(archPath);
+        if (content) { try { allArchived.push(...JSON.parse(content).map(i => ({ ...i, _source: project.name }))); } catch {} }
+      }
+      return jsonReply(res, 200, allArchived);
+    } catch (e) { return jsonReply(res, 200, []); }
+  }
+
   // POST /api/work-items
   if (req.method === 'POST' && req.url === '/api/work-items') {
     try {
@@ -641,14 +699,40 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
-  // POST /api/prd-items
+  // POST /api/plan — create a plan work item that chains to PRD on completion
+  if (req.method === 'POST' && req.url === '/api/plan') {
+    try {
+      const body = await readBody(req);
+      // Write as a work item with type 'plan' — engine handles the chaining
+      const wiPath = path.join(SQUAD_DIR, 'work-items.json');
+      let items = [];
+      const existing = safeRead(wiPath);
+      if (existing) { try { items = JSON.parse(existing); } catch {} }
+      const maxNum = items.reduce(function(max, i) {
+        const m = (i.id || '').match(/(\d+)$/);
+        return m ? Math.max(max, parseInt(m[1])) : max;
+      }, 0);
+      const id = 'W' + String(maxNum + 1).padStart(3, '0');
+      const item = {
+        id, title: body.title, type: 'plan',
+        priority: body.priority || 'high', description: body.description || '',
+        status: 'pending', created: new Date().toISOString(), createdBy: 'dashboard',
+        chain: 'plan-to-prd',
+        branchStrategy: body.branch_strategy || 'shared-branch',
+      };
+      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));
+      return jsonReply(res, 200, { ok: true, id, agent: body.agent || '' });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
+  // POST /api/prd-items — squad-level PRD
   if (req.method === 'POST' && req.url === '/api/prd-items') {
     try {
       const body = await readBody(req);
-      const firstProject = PROJECTS[0];
-      const root = path.resolve(firstProject.localPath || path.resolve(SQUAD_DIR, '..'));
-      const prdSrc = firstProject.workSources?.prd || CONFIG.workSources?.prd || {};
-      const prdPath = path.resolve(root, prdSrc.path || 'docs/prd-gaps.json');
+      const prdPath = path.join(SQUAD_DIR, 'prd.json');
       let data = { missing_features: [], existing_features: [], open_questions: [] };
       const existing = safeRead(prdPath);
       if (existing) { try { data = JSON.parse(existing); } catch {} }
@@ -657,6 +741,7 @@ const server = http.createServer(async (req, res) => {
         id: body.id, name: body.name, description: body.description || '',
         priority: body.priority || 'medium', estimated_complexity: body.estimated_complexity || 'medium',
         rationale: body.rationale || '', status: 'missing', affected_areas: [],
+        projects: body.projects || [],
       });
       fs.writeFileSync(prdPath, JSON.stringify(data, null, 2));
       return jsonReply(res, 200, { ok: true, id: body.id });

package/docs/distribution.md

@@ -0,0 +1,95 @@
+# Distribution & Publishing
+
+Squad is distributed as an npm package (`@yemi33/squad`) from a sanitized copy of the main repo.
+
+## Two-Repo Architecture
+
+| Repo | Purpose | What's included |
+|------|---------|----------------|
+| **origin** (`yemishin_microsoft/squad`) | Full working repo with all session state | Everything — history, notes, decisions, work items, CLAUDE.md |
+| **personal** (`yemi33/squad`) | Clean distribution for others | Engine, dashboard, playbooks, charters, skills, docs, npm package files |
+
+## What Gets Stripped
+
+These files are removed during sync to personal:
+
+| Category | Pattern | Reason |
+|----------|---------|--------|
+| Agent history | `agents/*/history.md` | Session-specific task logs |
+| Notes archive | `notes/archive/*` | Historical agent findings |
+| Notes inbox | `notes/inbox/*` | Pending agent findings |
+| Notes summary | `notes.md` | Consolidated knowledge (runtime) |
+| Work items | `work-items.json` | Runtime dispatch tracking |
+| Project instructions | `CLAUDE.md` | Org-specific context |
+
+## npm Package
+
+**Package:** `@yemi33/squad`
+**Registry:** https://www.npmjs.com/package/@yemi33/squad
+
+### What's in the package
+
+Controlled by the `files` field in `package.json`:
+- `bin/squad.js` — CLI entry point
+- `engine.js`, `dashboard.js`, `dashboard.html`, `squad.js` — core scripts
+- `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
+- `agents/*/charter.md` — agent role definitions
+- `playbooks/*.md` — task templates
+- `config.template.json` — starter config
+- `routing.md`, `team.md` — editable team config
+- `skills/`, `docs/` — documentation and workflows
+
+### How `squad init` works
+
+1. Copies all package files from `node_modules/@yemi33/squad/` to `~/.squad/`
+2. Creates `config.json` from `config.template.json` if it doesn't exist
+3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
+4. Runs `squad.js init` to populate config with default agents
+5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files
+
+### How updates work
+
+- Users run `npm update -g @yemi33/squad` then `squad init --force` to update engine code
+- `npx @yemi33/squad` always fetches the latest version
+
+## Auto-Publishing
+
+A GitHub Action on the personal repo auto-publishes to npm on every push to master.
+
+### How it works
+
+1. Push to `yemi33/squad` master triggers `.github/workflows/publish.yml`
+2. Action queries npm for the current published version
+3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
+4. Publishes to npm with the new version
+5. Commits the version bump back to the repo with `[skip ci]` to prevent loops
+
+### Why version comes from npm, not the repo
+
+The sync-to-personal workflow force-pushes, which overwrites any version bump commits from previous action runs. So the action reads the latest version from the npm registry and bumps from there.
+
+### Setup requirements
+
+- `NPM_TOKEN` secret on `yemi33/squad` — a granular access token with publish permissions and 2FA bypass enabled
+- The workflow file (`.github/workflows/publish.yml`) is gitignored on the org repo and force-added during sync
+
+## Sync Workflow
+
+Run `/sync-to-personal` or manually:
+
+```bash
+# 1. Create dist branch, strip files, add workflow, force-push
+git checkout -b dist-clean
+git rm --cached agents/*/history.md notes.md work-items.json CLAUDE.md
+git rm -r --cached notes/archive/ notes/inbox/ notes/
+# ... add .gitkeep files, .gitignore entries, workflow file
+git add -f .github/workflows/publish.yml
+git commit -m "Strip for distribution"
+git push personal dist-clean:master --force
+
+# 2. Return to master
+git checkout master
+git branch -D dist-clean
+```
+
+The full workflow is documented in `.claude/skills/sync-to-personal/SKILL.md`.

package/docs/self-improvement.md

@@ -117,7 +117,31 @@ in the future, avoid the patterns flagged here.
 
 Without this, review findings only exist in the inbox file under the reviewer's name. The author never explicitly sees them unless they happen to read the consolidated notes.md. The feedback loop ensures the author gets a direct, targeted learning from every review.
 
-## 4. Quality Metrics
+## 4. Human Feedback on PRs
+
+Humans can leave comments on ADO PRs containing `@squad` to trigger fix tasks. The engine polls PR threads every ~6 minutes and dispatches fixes to the PR's author agent.
+
+### Flow
+
+```
+Human comments on PR with "@squad fix the error handling here"
+  → pollPrHumanComments() detects new @squad comment
+  → sets pr.humanFeedback.pendingFix = true with comment text
+  → discoverFromPrs() sees pendingFix flag
+  → dispatches fix task to PR author agent
+  → author agent fixes and pushes
+  → PR goes back into normal review cycle
+```
+
+### How it works
+
+- **Trigger:** If you're the only human commenter, **any** comment triggers a fix. If multiple humans are commenting, `@squad` keyword is required to avoid noise
+- **Agent detection:** Comments matching `/\bSquad\s*\(/i` are skipped (agent signature pattern)
+- **Dedup:** Only comments newer than `pr.humanFeedback.lastProcessedCommentDate` are processed
+- **Multiple comments:** All new `@squad` comments are concatenated into a single fix task
+- **After fix:** `pendingFix` is cleared; PR re-enters normal review cycle
+
+## 5. Quality Metrics
 
 The engine tracks per-agent performance metrics in `engine/metrics.json`. Updated after every task completion and PR review.