@yemi33/minions 0.1.1038 → 0.1.1040

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.1.1040 (2026-04-16)
+
+### Other
+- Harden CC stream resilience
+
+## 0.1.1039 (2026-04-16)
+
+### Features
+-  Doc-chat performance — debounced persistence, session TTL, smart disk reads (#1164)
+- split getStatus() into fast/slow state tiers with separate TTLs (#1170)
+-  Cache _countWorktrees() with 30s TTL (#1166)
+- Pre-cache gzipped status buffer alongside JSON cache (#1171)
+- parallelize ADO and GitHub PR polling with Promise.allSettled (#1172)
+- route implement items to dedicated implement playbook (#1115)
+
+### Fixes
+- allow test tasks to create PRs when files are modified
+-  sidecar oversized dispatch prompts to prevent dashboard OOM (closes #1167) (#1183)
+-  use locked write for failed-with-PR reconciliation in cleanup.js (#1169)
+-  prevent test from corrupting live meeting state
+- scheduler enabled field falsy check treats undefined as disabled (#1160)
+-  update branch-dedup tests to use canonical PR IDs after merge with master (#1146)
+-  auto-review not firing for manually-linked PRs with autoObserve=true
+-  mark PR abandoned on 404 instead of silently retrying each tick
+- replace undefined PROJECTS with config.projects in checkWatches (#1108)
+- write permission for publish workflow
+-  run tests inline and post check runs for publish PRs
+- add maxBuffer to all GitHub CLI spawns + paginate PR list (#1130)
+-  add required CI checks for PRs + update publish for auto-merge
+-  revert to PR merge now that stale status check is removed
+- guard live review check against undefined vote/state values (#1132)
+-  push version bump directly to master instead of via PR
+-  add push-triggered CI for chore/publish branches
+-  publish workflow chore PRs failing to merge
+-  harden KB ordering
+-  harden audited state transitions
+
+### Other
+- Tighten playbook guidance
+- Fix audit cleanup and test isolation
+- docs(sched-weekly-docs-cleanup-1776355200664): weekly documentation cleanup (#1181)
+- [E2E] Dashboard & engine perf: gzip cache, tiered status, lock backoff, polling parallelization (#1174)
+- Fix doc chat session isolation
+- test(pipeline): add unit tests for CRUD, stage execution, run lifecycle (#1162)
+- chore: test publish after removing stale status check
+- chore: trigger publish test
+- chore: test publish workflow fix
+- chore: trigger publish workflow test
+
 ## 0.1.1038 (2026-04-16)
 
 ### Features

package/dashboard/js/command-center.js

@@ -54,6 +54,26 @@ function _ccActiveTab() {
   return _ccTabs.find(function(t) { return t.id === _ccActiveTabId; }) || null;
 }
 
+async function _ccDashboardHealth() {
+  var controller = new AbortController();
+  var timer = setTimeout(function() { controller.abort(); }, 3000);
+  try {
+    var res = await fetch('/api/status', { signal: controller.signal, cache: 'no-store' });
+    if (!(res && res.ok)) return { reachable: false, restarted: false };
+    var data = await res.json().catch(function() { return null; });
+    var currentDashId = data && data.version ? data.version.dashboardStartedAt : null;
+    var knownDashId = window._lastStatus && window._lastStatus.version ? window._lastStatus.version.dashboardStartedAt : null;
+    return {
+      reachable: true,
+      restarted: !!(currentDashId && knownDashId && currentDashId !== knownDashId)
+    };
+  } catch {
+    return { reachable: false, restarted: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 function _ccFindPinTarget(query) {
   for (var i = 0; i < (inboxData || []).length; i++) {
     if (inboxData[i].name.toLowerCase().includes(query)) {
@@ -532,6 +552,16 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
       if (activeTab._queue && activeTab._queue.length > 0) _renderQueueIndicator();
       if (msgs.scrollHeight - msgs.scrollTop - msgs.clientHeight < 150) msgs.scrollTop = msgs.scrollHeight;
     }
+    function _ccElapsedFooter(label) {
+      var seconds = Math.round((Date.now() - ccStartTime) / 1000);
+      return '<div style="font-size:9px;color:var(--muted);margin-top:6px;display:flex;justify-content:flex-end;padding-right:30px">' + label.replace('{seconds}', seconds) + '</div>';
+    }
+    function _ccRetryControls(extraHtml, showReload) {
+      return (extraHtml || '') +
+        '<button onclick="ccRetryLast()" style="margin-top:6px;padding:4px 12px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;color:var(--blue);cursor:pointer;font-size:11px">Retry</button>' +
+        (showReload ? ' <button onclick="location.reload()" style="margin-top:6px;padding:4px 12px;background:var(--orange);color:#fff;border:none;border-radius:4px;cursor:pointer;font-size:11px">Reload Page</button>' : '') +
+        ' <button onclick="ccNewTab()" style="margin-top:6px;padding:4px 12px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;color:var(--muted);cursor:pointer;font-size:11px">New Session</button>';
+    }
     // Start phase timer immediately so thinking text updates while waiting for SSE
     var phaseTimer = setInterval(updateStreamDiv, 1000);
     updateStreamDiv(); // render proper layout immediately (not raw "Thinking..." text)
@@ -563,6 +593,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
     var reader = res.body.getReader();
     var decoder = new TextDecoder();
     var buf = '';
+    var terminalEventSeen = false;
 
     while (true) {
       var readResult = await reader.read();
@@ -579,21 +610,23 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
             streamedText = evt.text;
             if (activeTab) activeTab._streamedText = streamedText;
             updateStreamDiv();
+          } else if (evt.type === 'heartbeat') {
+            continue;
           } else if (evt.type === 'tool') {
             toolsUsed.push({ name: evt.name, input: evt.input || {} });
             if (activeTab) activeTab._toolsUsed = toolsUsed.slice();
             updateStreamDiv();
             if (msgs.scrollHeight - msgs.scrollTop - msgs.clientHeight < 150) msgs.scrollTop = msgs.scrollHeight;
           } else if (evt.type === 'done') {
+            terminalEventSeen = true;
             _cleanupStreamDiv();
             // If system prompt changed, show a notice before the response
             if (evt.sessionReset) {
               addMsg('system', '<div style="text-align:center;padding:6px 12px;font-size:11px;color:var(--muted);background:var(--surface2);border-radius:6px;margin:4px 0">Minions was updated — started a fresh session with latest context.</div>', false, activeTabId);
             }
             // placeholder was added with skipSave=true — nothing to pop
-            var ccElapsed = Math.round((Date.now() - ccStartTime) / 1000);
             var rendered = renderMd(evt.text || streamedText || '');
-            addMsg('assistant', rendered + '<div style="font-size:9px;color:var(--muted);margin-top:6px;display:flex;justify-content:flex-end;padding-right:30px">' + ccElapsed + 's</div>');
+            addMsg('assistant', rendered + _ccElapsedFooter('{seconds}s'));
             if (evt.sessionId !== undefined) {
               // Save session to the originating tab, not whichever tab is active now
               var originTab = _ccTabs.find(function(t) { return t.id === activeTabId; });
@@ -605,6 +638,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
               for (var ai = 0; ai < evt.actions.length; ai++) { await ccExecuteAction(evt.actions[ai], activeTabId); }
             }
           } else if (evt.type === 'error') {
+            terminalEventSeen = true;
             _cleanupStreamDiv();
             // placeholder was skipSave — no pop needed
             addMsg('assistant', '<span style="color:var(--red)">' + escHtml(evt.error) + '</span>');
@@ -621,11 +655,11 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
         try {
           var revt = JSON.parse(rline.slice(6));
           if (revt.type === 'done') {
+            terminalEventSeen = true;
             _cleanupStreamDiv();
             // placeholder was skipSave — no pop needed
-            var ccElapsed2 = Math.round((Date.now() - ccStartTime) / 1000);
             var rendered2 = renderMd(revt.text || streamedText || '');
-            addMsg('assistant', rendered2 + '<div style="font-size:9px;color:var(--muted);margin-top:6px;display:flex;justify-content:flex-end;padding-right:30px">' + ccElapsed2 + 's</div>');
+            addMsg('assistant', rendered2 + _ccElapsedFooter('{seconds}s'));
             if (revt.sessionId !== undefined) {
               var originTab2 = _ccTabs.find(function(t) { return t.id === activeTabId; });
               if (originTab2) { originTab2.sessionId = revt.sessionId || null; }
@@ -635,6 +669,12 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
               _tagServerExecuted(revt.actions, revt.actionResults);
               for (var ai2 = 0; ai2 < revt.actions.length; ai2++) { await ccExecuteAction(revt.actions[ai2], activeTabId); }
             }
+          } else if (revt.type === 'heartbeat') {
+            continue;
+          } else if (revt.type === 'error') {
+            terminalEventSeen = true;
+            _cleanupStreamDiv();
+            addMsg('assistant', '<span style="color:var(--red)">' + escHtml(revt.error) + '</span>');
           } else if (revt.type === 'chunk') {
             streamedText = revt.text;
             updateStreamDiv();
@@ -643,11 +683,13 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
       }
     }
     // If stream ended without a 'done' event, finalize with whatever we have
-    if (streamDiv.parentNode || document.getElementById('cc-restore-thinking') || document.querySelector('[data-stream-tab="' + activeTabId + '"]')) {
+    if (!terminalEventSeen && (streamDiv.parentNode || document.getElementById('cc-restore-thinking') || document.querySelector('[data-stream-tab="' + activeTabId + '"]'))) {
       _cleanupStreamDiv();
+      var streamEndedHint = '<div style="font-size:10px;color:var(--muted);margin-top:4px">The response stream ended before completion. Retry to continue from the last user message.</div>';
       if (streamedText) {
-        var ccElapsed3 = Math.round((Date.now() - ccStartTime) / 1000);
-        addMsg('assistant', renderMd(streamedText) + '<div style="font-size:9px;color:var(--muted);margin-top:6px;display:flex;justify-content:flex-end;padding-right:30px">' + ccElapsed3 + 's</div>');
+        addMsg('assistant', renderMd(streamedText) + _ccElapsedFooter('Stream interrupted after {seconds}s') + _ccRetryControls(streamEndedHint, false));
+      } else {
+        addMsg('assistant', '<span style="color:var(--red)">The response stream ended before completion.</span>' + _ccRetryControls(streamEndedHint, false));
       }
     }
   } catch (e) {
@@ -655,19 +697,24 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
     if (e.name === 'AbortError') {
       _wasAborted = true;
       if (streamedText) {
-        var ccElapsed4 = Math.round((Date.now() - ccStartTime) / 1000);
-        addMsg('assistant', renderMd(streamedText) + '<div style="font-size:9px;color:var(--muted);margin-top:6px;display:flex;justify-content:flex-end;padding-right:30px">Stopped after ' + ccElapsed4 + 's</div>');
+        addMsg('assistant', renderMd(streamedText) + _ccElapsedFooter('Stopped after {seconds}s'));
       } else {
         addMsg('assistant', '<span style="color:var(--red);font-size:11px">Stopped</span>');
       }
     } else {
-      var retryId = 'cc-retry-' + Date.now();
       var isNetworkError = e.message === 'Failed to fetch' || e.message.includes('NetworkError');
-      addMsg('assistant', '<span style="color:var(--red)">Error: ' + escHtml(e.message) + '</span>' +
-        (isNetworkError ? '<div style="font-size:10px;color:var(--muted);margin-top:4px">Dashboard connection lost. Reload the page to reconnect.</div>' : '') +
-        '<button id="' + retryId + '" onclick="ccRetryLast()" style="margin-top:6px;padding:4px 12px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;color:var(--blue);cursor:pointer;font-size:11px">Retry</button>' +
-        (isNetworkError ? ' <button onclick="location.reload()" style="margin-top:6px;padding:4px 12px;background:var(--orange);color:#fff;border:none;border-radius:4px;cursor:pointer;font-size:11px">Reload Page</button>' : '') +
-        ' <button onclick="ccNewTab()" style="margin-top:6px;padding:4px 12px;background:var(--surface2);border:1px solid var(--border);border-radius:4px;color:var(--muted);cursor:pointer;font-size:11px">New Session</button>');
+      var dashboardHealth = isNetworkError ? await _ccDashboardHealth() : { reachable: false, restarted: false };
+      var connectionHint = '';
+      if (isNetworkError) {
+        connectionHint = dashboardHealth.restarted
+          ? '<div style="font-size:10px;color:var(--muted);margin-top:4px">Dashboard restarted while this response was streaming. Reload the page to reconnect to the new instance.</div>'
+          : dashboardHealth.reachable
+            ? '<div style="font-size:10px;color:var(--muted);margin-top:4px">The request stream was interrupted, but the dashboard is still reachable. Retry or start a new session.</div>'
+            : '<div style="font-size:10px;color:var(--muted);margin-top:4px">Dashboard connection lost. Reload the page to reconnect.</div>';
+      }
+      addMsg('assistant', (streamedText ? renderMd(streamedText) + _ccElapsedFooter('Stream interrupted after {seconds}s') : '') +
+        '<span style="color:var(--red)">Error: ' + escHtml(e.message) + '</span>' +
+        _ccRetryControls(connectionHint, isNetworkError && (!dashboardHealth.reachable || dashboardHealth.restarted)));
     }
   } finally {
     if (activeTab) { activeTab._sending = false; activeTab._abortController = null; activeTab._429retries = 0; delete activeTab._streamedText; delete activeTab._toolsUsed; delete activeTab._sendStartedAt; }

package/dashboard.js

@@ -541,6 +541,7 @@ const ccInFlightTabs = new Map(); // tabId → timestamp — per-tab in-flight t
 const ccInFlightAborts = new Map(); // tabId → abortFn — lets a new request kill the stale LLM
 const CC_INFLIGHT_TIMEOUT_MS = 2 * 60 * 1000; // 2 minutes — auto-release if request hangs
 const CC_LOCK_WAIT_MS = 200; // grace period for previous handler's finally to release lock
+const CC_STREAM_HEARTBEAT_MS = 15000; // keep streaming responses alive across proxies/restart races
 function _releaseCCTab(tabId) { ccInFlightTabs.delete(tabId); ccInFlightAborts.delete(tabId); }
 function _ccTabIsInFlight(tabId) {
   if (!ccInFlightTabs.has(tabId)) return false;
@@ -3791,6 +3792,23 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   async function handleCommandCenterStream(req, res) {
     if (checkRateLimit('command-center', 10)) { res.statusCode = 429; res.end('Rate limited'); return; }
     let tabId;
+    let _ccStreamAbort = null;
+    let _ccStreamEnded = false;
+    let _ccHeartbeatTimer = null;
+    const writeCcEvent = (payload) => {
+      try {
+        res.write('data: ' + JSON.stringify(payload) + '\n\n');
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const stopCcHeartbeat = () => {
+      if (_ccHeartbeatTimer) {
+        clearInterval(_ccHeartbeatTimer);
+        _ccHeartbeatTimer = null;
+      }
+    };
     try {
       const body = await readBody(req);
       if (!body.message) { res.statusCode = 400; res.end('message required'); return; }
@@ -3807,13 +3825,20 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       ccInFlightTabs.set(tabId, Date.now());
 
       res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
-      let _ccStreamAbort = null;
-      let _ccStreamEnded = false;
+      writeCcEvent({ type: 'heartbeat' }); // flush headers quickly and keep intermediaries from idling out
+      _ccHeartbeatTimer = setInterval(() => {
+        if (_ccStreamEnded) {
+          stopCcHeartbeat();
+          return;
+        }
+        if (!writeCcEvent({ type: 'heartbeat' })) stopCcHeartbeat();
+      }, CC_STREAM_HEARTBEAT_MS);
       // Kill LLM process immediately if client disconnects mid-stream.
       // Guard with !_ccStreamEnded: when the stream ends normally, finally already released the lock;
       // without the guard, this close event (which fires after res.end) could wipe a new request's lock.
       req.on('close', () => {
         if (!_ccStreamEnded) {
+          stopCcHeartbeat();
           _releaseCCTab(tabId);
           if (_ccStreamAbort) {
             console.log(`[CC-stream] Client disconnected for tab ${tabId} — aborting LLM`);
@@ -3851,10 +3876,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           onChunk: (text) => {
             const actIdx = findCCActionsDelimiter(text);
             const display = actIdx >= 0 ? text.slice(0, actIdx).trim() : text;
-            try { res.write('data: ' + JSON.stringify({ type: 'chunk', text: display }) + '\n\n'); } catch {}
+            writeCcEvent({ type: 'chunk', text: display });
           },
           onToolUse: (name, input) => {
-            try { res.write('data: ' + JSON.stringify({ type: 'tool', name, input: _lightToolInput(input) }) + '\n\n'); } catch {}
+            writeCcEvent({ type: 'tool', name, input: _lightToolInput(input) });
           }
         });
         _ccStreamAbort = llmPromise.abort;
@@ -3875,10 +3900,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             onChunk: (text) => {
               const actIdx = findCCActionsDelimiter(text);
               const display = actIdx >= 0 ? text.slice(0, actIdx).trim() : text;
-              try { res.write('data: ' + JSON.stringify({ type: 'chunk', text: display }) + '\n\n'); } catch {}
+              writeCcEvent({ type: 'chunk', text: display });
             },
             onToolUse: (name, input) => {
-              try { res.write('data: ' + JSON.stringify({ type: 'tool', name, input: _lightToolInput(input) }) + '\n\n'); } catch {}
+              writeCcEvent({ type: 'tool', name, input: _lightToolInput(input) });
             }
           });
           _ccStreamAbort = retryPromise.abort;
@@ -3896,7 +3921,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           const stderrTail = (result.stderr || '').trim().split('\n').filter(Boolean).slice(-3).join(' | ');
           console.error(`[CC-stream] Failed: code=${result.code}, stderr=${(result.stderr || '').slice(0, 500)}, stdout_tail=${(result.raw || '').slice(-500)}`);
           const retryHint = 'Send your message again to retry.';
-          res.write('data: ' + JSON.stringify({ type: 'done', text: `I had trouble processing that ${debugInfo}. ${stderrTail ? 'Detail: ' + stderrTail : ''}\n\n${retryHint}`, actions: [], sessionId: null }) + '\n\n');
+          writeCcEvent({ type: 'done', text: `I had trouble processing that ${debugInfo}. ${stderrTail ? 'Detail: ' + stderrTail : ''}\n\n${retryHint}`, actions: [], sessionId: null });
           _ccStreamEnded = true; res.end();
           return;
         }
@@ -3939,7 +3964,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
         const donePayload = { type: 'done', text: displayText, actions, actionResults, sessionId: responseSessionId, newSession: !wasResume };
         if (sessionReset) donePayload.sessionReset = true;
-        res.write('data: ' + JSON.stringify(donePayload) + '\n\n');
+        writeCcEvent(donePayload);
 
         // Mirror CC response to Teams (non-blocking, skip Teams-originated)
         const _streamTabId = body.tabId || 'default';
@@ -3949,11 +3974,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
         _ccStreamEnded = true; res.end();
       } finally {
+        stopCcHeartbeat();
         _releaseCCTab(tabId);
       }
     } catch (e) {
+      stopCcHeartbeat();
       _releaseCCTab(tabId);
-      try { res.write('data: ' + JSON.stringify({ type: 'error', error: e.message }) + '\n\n'); } catch {}
+      writeCcEvent({ type: 'error', error: e.message });
       _ccStreamEnded = true; try { res.end(); } catch {}
     }
   }

package/package.json

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

package/playbooks/implement-shared.md

@@ -33,11 +33,11 @@ git log --oneline {{main_branch}}..HEAD
 
 Do ALL work in the worktree.
 
-**Do NOT:**
+**Shared branch workflow — do NOT:**
 - Create a new branch — use `{{branch_name}}`
-- Create a PR — one will be created automatically when all plan items complete
-- Remove the worktree — the next plan item needs it
 - Create a new worktree — one already exists at `{{worktree_path}}`
+- Remove the worktree — the engine cleans it up after all plan items complete
+- Create a PR — one will be created automatically when all plan items complete
 
 ## Health Check
 

package/playbooks/implement.md

@@ -51,19 +51,13 @@ Do NOT remove the worktree — the engine handles cleanup automatically.
 
 ## Build & Test (MANDATORY before pushing)
 
-After implementation, verify everything works before pushing:
-
-1. **Build** the project using its build system (check CLAUDE.md, package.json, README, Makefile). If the build fails:
-   - Read the error, fix the issue, re-build
-   - If it fails 3 times, report the errors in your findings and stop
-2. **Run the full test suite** using whatever command the project specifies (check CLAUDE.md, agent.md, README, or package.json scripts).
-3. If any tests fail:
-   - Determine if YOUR changes caused the failure
-   - Fix any regressions you introduced
-   - Re-run tests until all pass
-4. If tests were already failing before your changes (pre-existing), note them in the PR description but do NOT block on them
-5. **Run any other checks** the repo defines (linting, type checking, formatting) — read project docs for the full list
-6. Do NOT push code with failing tests or a broken build that you introduced
+Build and test before pushing:
+
+1. **Build** the project using its build system (check CLAUDE.md, package.json, README, or Makefile). Retry up to 3 times; if it still fails, report the errors and stop.
+2. **Run the full test suite** using the command the project defines. Fix regressions you introduced and re-run until your changes are green.
+3. If tests were already failing before your changes, note that in the PR description but do not block on pre-existing failures.
+4. **Run any other checks** the repo defines (linting, type checking, formatting).
+5. Do NOT push code with a broken build or failing tests that you introduced.
 
 ## Push & Create PR
 
@@ -83,4 +77,4 @@ Include build/test status and run instructions in the PR description. If the pro
 
 Your task is complete once you have: (1) confirmed build and tests pass, (2) pushed your branch, and (3) created the PR. Your final message MUST include the PR URL so the engine can track it. Stop immediately after.
 
-**NEVER run `gh pr merge` or any merge command on your own PR.** The engine reviews and merges PRs through a separate review cycle. Self-merging bypasses code review entirely and is prohibited regardless of circumstances.
+Do NOT run `gh pr merge` or any other merge command on your own PR. The engine reviews and merges PRs through a separate review cycle. Self-merging is prohibited.

package/playbooks/plan-to-prd.md

@@ -16,7 +16,7 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 1. **Read the plan carefully** — understand the goals, scope, and requirements
 2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
 3. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — status is determined only by existing PRD items (step 2), not codebase state
-4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work
+4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work, with enough detail for another agent to implement it directly
 5. **Estimate complexity** — `small` (< 1 file), `medium` (2-5 files), `large` (6+ files or cross-cutting)
 6. **Order by dependency** — items that others depend on come first
 7. **Use unique item IDs** — generate a short uuid for each item (e.g. `P-a3f9b2c1`). Do not use sequential `P001`/`P002` — IDs must be globally unique across all PRDs to avoid collisions. **If reusing an existing PRD, keep all existing IDs — only generate new UUIDs for genuinely new items.**
@@ -88,7 +88,7 @@ Rules for items:
 - **Do NOT include a "verify" or "test" or "integration test" item** — the engine automatically creates a verify task when all PRD items are done. Adding one manually creates a duplicate that blocks plan completion.
 - **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
 - `depends_on` lists IDs of items that must be done first
-- Keep descriptions actionable — an implementing agent should know exactly what to build
+- Keep descriptions actionable — name the files, functions, patterns, or integration points the implementing agent should touch whenever the plan makes them clear
 - Include `acceptance_criteria` so reviewers know when it's done
 - Aim for 5-25 items depending on plan scope. If more than 25, group related work
 

package/playbooks/verify.md

@@ -13,7 +13,7 @@ Repo: {{repo_name}} | Org: {{ado_org}} | ADO Project: {{ado_project}}
 
 ## Your Task
 
-Verify that a set of related changes work correctly together. You must **figure out** how to build, test, and run this specific project — do not assume any particular language, framework, or tooling. Your job is to:
+Verify that a set of related changes work correctly together. You must **figure out** how to build, test, and run this specific project — do not assume any particular language, framework, or tooling. Follow this process:
 
 1. **Set up worktrees** with all PR branches merged
 2. **Understand the project** — read its docs to learn how to build, test, and run it
@@ -43,15 +43,17 @@ For each project worktree, **read its documentation** to understand:
 
 Check these files: `CLAUDE.md`, `README.md`, `package.json`, `Makefile`, `Cargo.toml`, `pyproject.toml`, `build.gradle`, `CMakeLists.txt`, `docker-compose.yml`, `Podfile`, `build.gradle.kts`, `*.xcodeproj`, `*.xcworkspace`, or whatever build system the project uses.
 
+Treat the repository's own docs, scripts, and config as the source of truth for build, test, and run commands. If the repo provides multiple options, choose the standard local verification path it recommends.
+
 **Do not assume any specific platform.** The project could be a web app, mobile app (Android/iOS/React Native/Flutter), backend service, CLI tool, library, monorepo, or anything else. Adapt your verification approach to what the project actually is.
 
 ## Step 3: Build and Test
 
 For each project worktree:
 1. `cd` into the worktree path
-2. Install dependencies using whatever the project requires
-3. Run the build using the project's build system
-4. Run the test suite
+2. Install dependencies using the command or workflow the repo specifies
+3. Run the build using the repo's documented build command
+4. Run the test suite the repo defines for full verification
 5. Record: PASS or FAIL with error output, test counts (passed/failed/skipped)
 
 If a build or test fails, **do NOT fix it** — report the exact error and continue with other projects.
@@ -61,18 +63,13 @@ If a build or test fails, **do NOT fix it** — report the exact error and conti
 Determine if the project has a **runnable application** (web server, API, desktop app, mobile emulator, etc.) by reading its documentation and build config. For mobile apps, check if an emulator/simulator can be launched or if building an APK/IPA is the appropriate verification step.
 
 If found:
-1. Start it **detached from your process** so it survives after you exit. Use the platform-appropriate method:
-   ```bash
-   cd <worktree-path>
-   nohup <start-command> > app-server.log 2>&1 &
-   echo $! > app-server.pid
-   ```
-   On Windows, use `spawn` with `detached: true` and `child.unref()`.
-
-2. Wait a few seconds, then verify it's responding (e.g. `curl -s -o /dev/null -w "%{http_code}" http://localhost:<PORT>`)
-3. Note the URL, port, and PID
+1. Start it **detached from your process** so it survives after you exit.
+   - If the repo docs provide a local run or background-start command, use that.
+   - Otherwise, use the detached-process mechanism that fits the current environment. Do not assume Bash, PowerShell, or any specific shell unless the repo or runtime clearly provides it.
+2. Wait a few seconds, then verify it using the repo's documented smoke test, health check, startup output, or the lightest project-appropriate manual check.
+3. Note the URL, port, process identifier, or equivalent runtime details the repo exposes
 4. Output the exact restart command with **absolute worktree paths**
-5. Include the stop command (e.g. `kill <PID>` or `taskkill /PID <PID> /F` on Windows)
+5. Include the stop command or shutdown procedure that matches how you started it
 
 If the project has no runnable application, skip this step and note that in the guide.
 
@@ -144,11 +141,12 @@ For each project worktree:
 
 ## Working Style
 
-Use subagents only for genuinely parallel, independent tasks (e.g., building separate project worktrees simultaneously). For sequential steps like reading docs, running tests, and writing the report, work directly — do not spawn subagents.
+Use subagents only for genuinely parallel, independent build/test tasks on separate project worktrees. For sequential work (docs → build → test → report), and for starting detached servers, work directly — do not spawn subagents.
 
 ## Rules
 
 - **Read the project docs first** — never assume a build system, language, or framework
+- Treat repo-provided docs, scripts, and config as the source of truth for build/test/run commands
 - Base testing steps on the **acceptance criteria** from each plan item
 - Include **concrete steps** — URLs, buttons to click, inputs to type, expected results
 - Be **transparent** — clearly separate what you verified vs what needs human review

package/playbooks/work-item.md

@@ -59,4 +59,4 @@ If you encounter merge conflicts during push or PR creation:
 
 Your task is complete once you have: (1) confirmed build and tests pass, (2) pushed your branch, and (3) created the PR. Do NOT continue beyond the task description. Stop immediately.
 
-**NEVER run `gh pr merge` or any merge command on your own PR.** The engine reviews and merges PRs through a separate review cycle. Self-merging bypasses code review entirely and is prohibited regardless of circumstances.
+Do NOT run `gh pr merge` or any other merge command on your own PR. The engine reviews and merges PRs through a separate review cycle. Self-merging is prohibited.