@yemi33/minions 0.1.1680 → 0.1.1682

package/engine/lifecycle.js

@@ -69,6 +69,12 @@ function checkPlanCompletion(meta, config) {
 
   const doneItems = planItems.filter(w => DONE_STATUSES.has(w.status));
   const failedItems = planItems.filter(w => w.status === WI_STATUS.FAILED || w.status === WI_STATUS.CANCELLED);
+  const isActiveVerify = (wi) => wi && (
+    wi.status === WI_STATUS.PENDING ||
+    wi.status === WI_STATUS.QUEUED ||
+    wi.status === WI_STATUS.DISPATCHED
+  );
+  const isReopenableVerify = (wi) => wi && (DONE_STATUSES.has(wi.status) || wi.status === WI_STATUS.FAILED);
 
   if (failedItems.length > 0) {
     const failDetails = failedItems.map(w =>
@@ -166,6 +172,7 @@ function checkPlanCompletion(meta, config) {
       const mainBranch = shared.resolveMainBranch(primaryProject.localPath, primaryProject.mainBranch);
       const itemSummary = doneItems.map(w => '- ' + w.id + ': ' + w.title.replace('Implement: ', '')).join('\n');
       mutateWorkItems(wiPath, workItems => {
+        if (workItems.some(w => w.sourcePlan === planFile && w.itemType === 'pr')) return workItems;
         workItems.push({
           id, title: `Create PR for plan: ${plan.plan_summary || planFile}`,
           type: 'implement', priority: 'high',
@@ -181,9 +188,23 @@ function checkPlanCompletion(meta, config) {
   // 4. Create verification work item (build, test, start webapp, write testing guide)
   // Only one verify per PRD — skip if pending/dispatched, re-open if done/failed (PRD was modified)
   const existingVerify = allWorkItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
-  if (existingVerify && (existingVerify.status === WI_STATUS.PENDING || existingVerify.status === WI_STATUS.DISPATCHED)) {
+  if (isActiveVerify(existingVerify)) {
     log('info', `Plan ${planFile}: verify WI ${existingVerify.id} already ${existingVerify.status} — skipping`);
-  } else if (doneItems.length > 0) {
+  } else if (isReopenableVerify(existingVerify) && doneItems.length > 0) {
+    const verifyProject = existingVerify.project || projectName;
+    const vWiPath = shared.projectWorkItemsPath(
+      projects.find(p => p.name?.toLowerCase() === verifyProject?.toLowerCase()) || primaryProject
+    );
+    let reopenedVerify = false;
+    mutateWorkItems(vWiPath, items => {
+      const v = items.find(w => w.id === existingVerify.id);
+      if (isReopenableVerify(v)) {
+        shared.reopenWorkItem(v);
+        reopenedVerify = true;
+      }
+    });
+    if (reopenedVerify) log('info', `Re-opened verification work item ${existingVerify.id} for modified plan ${planFile}`);
+  } else if (!existingVerify && doneItems.length > 0) {
     const verifyId = 'PL-' + shared.uid();
     const planSlug = planFile.replace('.json', '');
 
@@ -276,7 +297,17 @@ function checkPlanCompletion(meta, config) {
       prSummary,
     ].join('\n');
 
+    let createdVerify = false;
+    let reopenedVerifyId = null;
     mutateWorkItems(wiPath, workItems => {
+      const v = workItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
+      if (v) {
+        if (isReopenableVerify(v)) {
+          shared.reopenWorkItem(v);
+          reopenedVerifyId = v.id;
+        }
+        return workItems;
+      }
       workItems.push({
         id: verifyId,
         title: `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
@@ -290,32 +321,19 @@ function checkPlanCompletion(meta, config) {
         itemType: 'verify',
         project: projectName,
       });
+      createdVerify = true;
     });
-    log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
+    if (createdVerify) {
+      log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
 
-    // Teams notification for verify creation — non-blocking
-    try {
-      const teams = require('./teams');
-      teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
-    } catch {}
-  } else if (existingVerify && DONE_STATUSES.has(existingVerify.status) && doneItems.length > 0) {
-    // PRD was modified and re-completed — re-open the existing verify instead of creating a duplicate
-    const verifyProject = existingVerify.project || projectName;
-    const vWiPath = shared.projectWorkItemsPath(
-      projects.find(p => p.name?.toLowerCase() === verifyProject?.toLowerCase()) || primaryProject
-    );
-    mutateWorkItems(vWiPath, items => {
-      const v = items.find(w => w.id === existingVerify.id);
-      if (v && DONE_STATUSES.has(v.status)) {
-        v.status = WI_STATUS.PENDING;
-        v._reopened = true;
-        delete v.completedAt;
-        delete v.dispatched_to;
-        delete v.dispatched_at;
-        v._retryCount = 0;
-      }
-    });
-    log('info', `Re-opened verification work item ${existingVerify.id} for modified plan ${planFile}`);
+      // Teams notification for verify creation — non-blocking
+      try {
+        const teams = require('./teams');
+        teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
+      } catch {}
+    } else if (reopenedVerifyId) {
+      log('info', `Re-opened verification work item ${reopenedVerifyId} for modified plan ${planFile}`);
+    }
   }
 
   // Archive deferred until verify completes
@@ -350,9 +368,9 @@ function archivePlan(planFile, plan, projects, config) {
     // plan completion and spawning duplicate verify tasks for already-archived plans.
     // On Windows, the unlink can fail due to file locking; overwrite with archived status
     // as a fallback so a restored backup is inert even if deletion fails.
-    const backupPath = planPath + '.backup';
-    try { fs.unlinkSync(backupPath); } catch {
-      try { fs.writeFileSync(backupPath, JSON.stringify({ status: 'archived' })); } catch { }
+    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
+    if (!backupCleanup.ok) {
+      log('warn', `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`);
     }
   } catch (err) {
     log('warn', `Failed to archive PRD ${planFile}: ${err.message}`);
@@ -440,95 +458,6 @@ function cleanupPlanWorktrees(planFile, plan, projects, config) {
   } catch (err) { log('warn', `Plan worktree cleanup: ${err.message}`); }
 }
 
-// ─── Plan → PRD Chaining ─────────────────────────────────────────────────────
-function chainPlanToPrd(dispatchItem, meta, config) {
-
-  const planDir = path.join(MINIONS_DIR, 'plans');
-  if (!fs.existsSync(planDir)) fs.mkdirSync(planDir, { recursive: true });
-
-  let planFileName = meta?.planFileName || meta?.item?._planFileName;
-  if (planFileName && fs.existsSync(path.join(planDir, planFileName))) {
-    // Exact match from meta
-  } else {
-    const planFiles = fs.readdirSync(planDir)
-      .filter(f => f.endsWith('.md') || f.endsWith('.json'))
-      .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 plan files found in plans/ after task ${dispatchItem.id}`);
-      return;
-    }
-    log('info', `Plan chaining: using mtime fallback — found ${planFileName}`);
-  }
-
-  if (planFileName.endsWith('.json')) {
-    const mdName = planFileName.replace(/\.json$/, '.md');
-    // Check plans/ first, then prd/ for .json files
-    const jsonPath = fs.existsSync(path.join(planDir, planFileName))
-      ? path.join(planDir, planFileName)
-      : path.join(MINIONS_DIR, 'prd', planFileName);
-    const mdPath = path.join(planDir, mdName);
-    try {
-      const content = fs.readFileSync(jsonPath, 'utf8');
-      const parsed = JSON.parse(content);
-      if (!parsed.missing_features) {
-        fs.renameSync(jsonPath, mdPath);
-        planFileName = mdName;
-        log('info', `Plan chaining: renamed ${planFileName} → ${mdName} (plans must be .md)`);
-      }
-    } catch {
-      try {
-        if (fs.existsSync(jsonPath)) fs.renameSync(jsonPath, path.join(planDir, mdName));
-        planFileName = mdName;
-        log('info', `Plan chaining: renamed to .md (not valid JSON)`);
-      } catch (err) { log('warn', `Plan rename fallback: ${err.message}`); }
-    }
-  }
-
-  const planFile = { name: planFileName };
-  const planPath = path.join(planDir, planFileName);
-  let planContent;
-  try { planContent = fs.readFileSync(planPath, 'utf8'); } catch (err) {
-    log('error', `Plan chaining: failed to read plan file ${planFile.name}: ${err.message}`);
-    return;
-  }
-
-  const projectName = meta?.item?.project || meta?.project?.name;
-  const projects = shared.getProjects(config);
-  if (projects.length === 0) {
-    log('error', 'Plan chaining: no projects configured');
-    return;
-  }
-  const targetProject = projectName
-    ? projects.find(p => p.name === projectName) || projects[0]
-    : projects[0];
-
-  if (!targetProject) {
-    log('error', 'Plan chaining: no target project available');
-    return;
-  }
-
-  log('info', `Plan chaining: queuing plan-to-prd for next tick (chained from ${dispatchItem.id})`);
-  const wiPath = path.join(MINIONS_DIR, 'work-items.json');
-  shared.mutateJsonFileLocked(wiPath, (items) => {
-    if (!Array.isArray(items)) items = [];
-    items.push({
-      id: 'W-' + shared.uid(),
-      title: `Convert plan to PRD: ${meta?.item?.title || planFile.name}`,
-      type: 'plan-to-prd',
-      priority: meta?.item?.priority || 'high',
-      description: `Plan file: plans/${planFile.name}\nChained from plan task ${dispatchItem.id}`,
-      status: WI_STATUS.PENDING,
-      created: ts(),
-      createdBy: 'engine:chain',
-      project: targetProject.name,
-      planFile: planFile.name,
-    });
-    return items;
-  }, { defaultValue: [] });
-}
-
 // ─── Work Item Path Resolution ───────────────────────────────────────────────
 
 /** Resolve the work-items.json path from dispatch meta. Reused by retry paths. */
@@ -642,15 +571,14 @@ function syncPrdItemStatus(itemId, status, sourcePlan) {
       const feature = plan?.missing_features?.find(f => f.id === itemId);
       if (!feature || feature.status === status) continue;
       let updated = false;
-      shared.withFileLock(`${fpath}.lock`, () => {
-        const fresh = safeJson(fpath);
+      mutateJsonFileLocked(fpath, (fresh) => {
         const f = fresh?.missing_features?.find(x => x.id === itemId);
         if (f && f.status !== status) {
           f.status = status;
-          safeWrite(fpath, fresh);
           updated = true;
         }
-      });
+        return fresh;
+      }, { skipWriteIfUnchanged: true });
       if (updated) return;
     }
   } catch (err) { log('warn', `PRD status sync: ${err.message}`); }
@@ -682,31 +610,28 @@ function reconcilePrdStatuses(config) {
   for (const file of prdFiles) {
     try {
       const fpath = path.join(PRD_DIR, file);
-      const plan = safeJson(fpath);
-      if (!plan?.missing_features) continue;
-      // Skip completed/archived PRDs — no reconciliation needed
-      if (plan.status === PLAN_STATUS.COMPLETED) continue;
-
-      let modified = false;
-      for (const feature of plan.missing_features) {
-        if (feature.status === PRD_ITEM_STATUS.MISSING && doneWiById.has(feature.id)) {
-          feature.status = PRD_ITEM_STATUS.UPDATED;
-          modified = true;
-          log('info', `PRD backward-scan: promoted ${feature.id} from missing→updated in ${file} (done work item exists)`);
-        }
-        // (#984) Stale status: PRD item stuck at dispatched/failed/pending while WI is done —
-        // happens when fix work items complete with a different ID than the original PRD feature
-        else if (_STALE_PRD_STATUSES.has(feature.status) && doneWiById.has(feature.id)) {
-          const prev = feature.status;
-          feature.status = WI_STATUS.DONE;
-          modified = true;
-          log('info', `PRD backward-scan: promoted ${feature.id} from ${prev}→done in ${file} (done work item exists)`);
-        }
-      }
+      const logMessages = [];
+      mutateJsonFileLocked(fpath, (plan) => {
+        if (!plan?.missing_features) return plan;
+        // Skip completed/archived PRDs — no reconciliation needed
+        if (plan.status === PLAN_STATUS.COMPLETED) return plan;
 
-      if (modified) {
-        safeWrite(fpath, plan);
-      }
+        for (const feature of plan.missing_features) {
+          if (feature.status === PRD_ITEM_STATUS.MISSING && doneWiById.has(feature.id)) {
+            feature.status = PRD_ITEM_STATUS.UPDATED;
+            logMessages.push(`PRD backward-scan: promoted ${feature.id} from missing→updated in ${file} (done work item exists)`);
+          }
+          // (#984) Stale status: PRD item stuck at dispatched/failed/pending while WI is done —
+          // happens when fix work items complete with a different ID than the original PRD feature
+          else if (_STALE_PRD_STATUSES.has(feature.status) && doneWiById.has(feature.id)) {
+            const prev = feature.status;
+            feature.status = WI_STATUS.DONE;
+            logMessages.push(`PRD backward-scan: promoted ${feature.id} from ${prev}→done in ${file} (done work item exists)`);
+          }
+        }
+        return plan;
+      }, { skipWriteIfUnchanged: true });
+      for (const message of logMessages) log('info', message);
     } catch (err) { log('warn', `PRD backward-scan for ${file}: ${err.message}`); }
   }
 }
@@ -1608,19 +1533,17 @@ async function handlePostMerge(pr, project, config, newStatus) {
       const planFiles = fs.readdirSync(prdDir).filter(f => f.endsWith('.json'));
       let updated = 0;
       for (const pf of planFiles) {
-        const plan = safeJson(path.join(prdDir, pf));
-        if (!plan?.missing_features) continue;
-        let changed = false;
-        for (const feature of plan.missing_features) {
-          if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
-            feature.status = WI_STATUS.DONE;
-            changed = true;
-            updated++;
+        const planPath = path.join(prdDir, pf);
+        mutateJsonFileLocked(planPath, (plan) => {
+          if (!plan?.missing_features) return plan;
+          for (const feature of plan.missing_features) {
+            if (mergedItemSet.has(feature.id) && feature.status !== WI_STATUS.DONE) {
+              feature.status = WI_STATUS.DONE;
+              updated++;
+            }
           }
-        }
-        if (changed) {
-          shared.safeWrite(path.join(prdDir, pf), plan);
-        }
+          return plan;
+        }, { skipWriteIfUnchanged: true });
       }
       if (updated > 0) log('info', `Post-merge: marked ${mergedItemIds.join(', ')} as done for ${pr.id}`);
     } catch (err) { log('warn', `Post-merge PRD update: ${err.message}`); }
@@ -1703,9 +1626,23 @@ function checkForLearnings(agentId, agentInfo, taskDesc) {
   log('warn', `${agentInfo?.name || agentId} didn't write learnings — no follow-up queued`);
 }
 
-function extractSkillsFromOutput(output, agentId, dispatchItem, config) {
+function skillWriteTargets(runtimeName, project = null) {
+  try {
+    const runtime = resolveRuntime(runtimeName || 'claude');
+    if (typeof runtime.getSkillWriteTargets === 'function') {
+      return runtime.getSkillWriteTargets({ homeDir: os.homedir(), project });
+    }
+  } catch { /* fall through to Claude-compatible legacy target */ }
+  return {
+    personal: path.join(os.homedir(), '.claude', 'skills'),
+    project: project?.localPath ? path.resolve(project.localPath, '.claude', 'skills') : null,
+  };
+}
+
+function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeName = null) {
 
   if (!output) return;
+  const effectiveRuntime = runtimeName || dispatchItem?.meta?.runtimeName || dispatchItem?.runtimeName || 'claude';
   let fullText = '';
   for (const line of output.split('\n')) {
     try {
@@ -1743,6 +1680,9 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config) {
     if (scope === 'project' && project) {
       const proj = shared.getProjects(config).find(p => p.name === project);
       if (proj) {
+        const projectSkillRoot = skillWriteTargets(effectiveRuntime, proj).project
+          || path.resolve(proj.localPath, '.claude', 'skills');
+        const projectSkillPath = path.join(projectSkillRoot, skillDirName, 'SKILL.md');
         const centralPath = path.join(MINIONS_DIR, 'work-items.json');
         let skillId = null;
         mutateJsonFileLocked(centralPath, data => {
@@ -1750,7 +1690,7 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config) {
           if (data.some(i => i.title === `Add skill: ${name}` && i.status !== WI_STATUS.FAILED)) return data;
           skillId = `SK${String(data.filter(i => i.id?.startsWith('SK')).length + 1).padStart(3, '0')}`;
           data.push({ id: skillId, type: 'implement', title: `Add skill: ${name}`,
-            description: `Create project-level skill \`${skillDirName}/SKILL.md\` in ${project}.\n\nWrite this file to \`${proj.localPath}/.claude/skills/${skillDirName}/SKILL.md\` via a PR.\n\n## Skill Content\n\n\`\`\`\n${enrichedBlock}\n\`\`\``,
+            description: `Create project-level skill \`${skillDirName}/SKILL.md\` in ${project}.\n\nWrite this file to \`${projectSkillPath}\` via a PR.\n\n## Skill Content\n\n\`\`\`\n${enrichedBlock}\n\`\`\``,
             priority: 'low', status: WI_STATUS.QUEUED, created: ts(), createdBy: `engine:skill-extraction:${agentName}` });
           return data;
         }, { skipWriteIfUnchanged: true });
@@ -1759,18 +1699,18 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config) {
         }
       }
     } else {
-      // Write in Claude Code native format: ~/.claude/skills/<name>/SKILL.md
-      const claudeSkillsDir = path.join(os.homedir(), '.claude', 'skills');
-      const skillDir = path.join(claudeSkillsDir, name.replace(/[^a-z0-9-]/g, '-'));
+      const personalSkillRoot = skillWriteTargets(effectiveRuntime).personal;
+      const skillDir = path.join(personalSkillRoot, name.replace(/[^a-z0-9-]/g, '-'));
       const skillPath = path.join(skillDir, 'SKILL.md');
       if (!fs.existsSync(skillPath)) {
-        // Convert to Claude Code format: only name + description in frontmatter
+        // Native skill format: only name + description in frontmatter.
         const description = m('description') || m('trigger') || `Auto-extracted skill from ${agentName}`;
         const body = fmMatch[2] || '';
         const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${body.trim()}\n`;
         if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
         shared.safeWrite(skillPath, ccContent);
-        log('info', `Extracted skill "${name}" from ${agentName} → ~/.claude/skills/${name.replace(/[^a-z0-9-]/g, '-')}/SKILL.md`);
+        try { require('./queries').invalidateSkillsCache(); } catch {}
+        log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
       } else {
         log('info', `Skill "${name}" already exists, skipping`);
       }

package/engine/meeting.js

@@ -45,7 +45,7 @@ function getStructuredNoteArtifacts(structuredCompletion) {
 
 function isPathInside(parent, child) {
   const rel = path.relative(parent, child);
-  return rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+  return Boolean(rel && !rel.startsWith('..') && !path.isAbsolute(rel));
 }
 
 function resolveMeetingNoteArtifactPath(artifactPath) {
@@ -114,27 +114,34 @@ function formatMeetingContributions(entries, agents, emptyText, label, maxBytes)
   return truncateMeetingContext(combined, maxBytes, label);
 }
 
-function cleanMeetingSummaryText(text) {
+function stripMeetingSummaryMarkdown(text) {
   return String(text || '')
     .replace(/\r/g, '')
-    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/```[\s\S]*?```/g, '\n')
     .replace(/`([^`]+)`/g, '$1')
     .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-    .replace(/^[#>*-]+\s*/gm, '')
+    .replace(/^\s*(?:[#>*-]+|\d+[.)])\s*/gm, '');
+}
+
+function cleanMeetingSummaryText(text) {
+  return stripMeetingSummaryMarkdown(text)
     .replace(/\s+/g, ' ')
     .trim();
 }
 
 function splitMeetingSummaryFragments(text) {
-  return cleanMeetingSummaryText(text)
-    .split(/\n+|(?:[.!?])\s+|;\s+/)
-    .map(s => s.trim())
+  return stripMeetingSummaryMarkdown(text)
+    .split(/\n+|[.!?]+\s*|;\s*/)
+    .map(s => s.replace(/\s+/g, ' ').trim())
     .filter(Boolean);
 }
 
 function truncateMeetingSummary(text, maxLen) {
-  if (text.length <= maxLen) return text;
-  return text.slice(0, Math.max(0, maxLen - 1)).trimEnd() + '…';
+  const value = String(text || '');
+  if (!value) return '';
+  if (!Number.isFinite(maxLen) || maxLen <= 0) return '';
+  if (value.length < maxLen) return value;
+  return value.slice(0, Math.max(0, maxLen - 1)) + '…';
 }
 
 function formatMeetingSummaryBullets(entries, agents, emptyText, maxLen) {
@@ -148,13 +155,14 @@ function formatMeetingSummaryBullets(entries, agents, emptyText, maxLen) {
 }
 
 function scoreMeetingTakeaway(fragment) {
-  const lower = fragment.toLowerCase();
+  const value = String(fragment || '');
+  const lower = value.toLowerCase();
   let score = 0;
   if (/(should|must|need to|needs to|recommend|recommended|action|next step|follow up|fix|mitigat|investigat|verify|test|block)/.test(lower)) score += 4;
   if (/(agree|aligned|consensus|support|prefer)/.test(lower)) score += 3;
   if (/(disagree|however|but|risk|risky|concern|trade-off|question|uncertain|worry)/.test(lower)) score += 3;
-  if (fragment.length >= 40 && fragment.length <= 180) score += 2;
-  if (fragment.length > 220) score -= 1;
+  if (value.length >= 40 && value.length <= 180) score += 2;
+  if (value.length > 220) score -= 1;
   return score;
 }
 
@@ -195,7 +203,9 @@ function collectMeetingNextSteps(meeting) {
       }
     }
   }
-  return ['- Review the findings and debate, then add a human-written conclusion if more nuance is needed.'];
+  return steps.length
+    ? steps
+    : ['- Review the findings and debate, then add a human-written conclusion if more nuance is needed.'];
 }
 
 function buildTimedOutMeetingConclusion(meeting, agents) {
@@ -615,4 +625,17 @@ module.exports = {
   discoverMeetingWork, collectMeetingFindings, checkMeetingTimeouts,
   addMeetingNote, advanceMeetingRound, endMeeting, archiveMeeting, unarchiveMeeting, deleteMeeting,
   EMPTY_OUTPUT_PATTERNS,
+  // exported for testing — engine code MUST go through
+  // getMeetings/discoverMeetingWork/collectMeetingFindings/checkMeetingTimeouts,
+  // never these helpers directly.
+  isPathInside,
+  resolveMeetingNoteArtifactPath,
+  cleanMeetingSummaryText,
+  splitMeetingSummaryFragments,
+  truncateMeetingSummary,
+  formatMeetingSummaryBullets,
+  scoreMeetingTakeaway,
+  collectMeetingTakeaways,
+  collectMeetingNextSteps,
+  buildTimedOutMeetingConclusion,
 };

package/engine/playbook.js

@@ -5,12 +5,13 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
 const { safeJson, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT } = shared;
-const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, AGENTS_DIR } = queries;
+const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
 const PLAYBOOKS_DIR = path.join(MINIONS_DIR, 'playbooks');
@@ -394,8 +395,8 @@ function renderPlaybook(type, vars) {
   content += '````\n```skill\n';
   content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
   content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to ~/.claude/skills/ so they are available in normal Claude windows too\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to <project>/.claude/skills/\n`;
+  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to the selected runtime's native personal skills directory\n`;
+  content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to the selected runtime's native project skills directory\n`;
   content += `- Emit at most one skill block per task unless you uncovered two clearly distinct reusable workflows\n`;
   content += `- Do NOT create a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs/playbooks/skills\n`;
 
@@ -503,7 +504,7 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
   prompt += `4. Write learnings to the path specified in the task prompt (format: \`notes/inbox/{agent}-{work-item-id}-{date}-{time}.md\`)\n`;
   prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n`;
-  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — minions-scoped skills are auto-extracted to ~/.claude/skills/ so they are available in normal Claude windows too\n\n`;
+  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — minions-scoped skills are auto-extracted to the selected runtime's native personal skills directory\n\n`;
 
   return prompt;
 }
@@ -514,6 +515,26 @@ function buildAgentContext(agentId, config, project) {
   project = project || getProjects(config)[0] || {};
   let context = '';
 
+  function appendContextFile(heading, filePath, maxBytes, extra = '') {
+    if (!filePath) return;
+    const content = safeRead(filePath);
+    if (!content || !content.trim()) return;
+    const truncated = Buffer.byteLength(content, 'utf8') > maxBytes
+      ? truncateTextBytes(content, maxBytes, '\n\n_...truncated; read the full file if needed_')
+      : content;
+    context += `## ${heading}\n\n`;
+    if (extra) context += `${extra}\n\n`;
+    context += `${truncated}\n\n`;
+  }
+
+  function appendIndex(heading, body, maxBytes) {
+    if (!body || !String(body).trim()) return;
+    const truncated = Buffer.byteLength(body, 'utf8') > maxBytes
+      ? truncateTextBytes(body, maxBytes, '\n\n_...index truncated; use Glob/Read for the full list_')
+      : body;
+    context += `## ${heading}\n\n${truncated.replace(/^## .+\n\n/, '')}\n`;
+  }
+
 
   // Agent history — last 5 tasks only (keeps it relevant, avoids 37KB dumps)
   const history = safeRead(path.join(AGENTS_DIR, agentId, 'history.md'));
@@ -527,16 +548,19 @@ function buildAgentContext(agentId, config, project) {
 
   // Project conventions (from CLAUDE.md) — always relevant for code quality
   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`;
-    }
+    appendContextFile('Project Conventions (from CLAUDE.md)', path.join(project.localPath, 'CLAUDE.md'), 8192);
+    appendContextFile('Project Agent Instructions (from AGENTS.md)', path.join(project.localPath, 'AGENTS.md'), 8192,
+      'These instructions are explicitly injected because some runtimes suppress automatic AGENTS.md loading. Follow them unless they conflict with the Minions task contract or playbook.');
+    appendContextFile('Project Copilot Instructions (from .github/copilot-instructions.md)', path.join(project.localPath, '.github', 'copilot-instructions.md'), 8192,
+      'Follow these repository instructions unless they conflict with the Minions task contract or playbook.');
   }
 
-  // KB and skills: NOT injected — agents can Glob/Read when needed
-  // This saves ~27KB per dispatch. Reference note so agents know they exist:
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. User-level Minions skills live in \`~/.claude/skills/\`, and project-specific skills live in \`<project>/.claude/skills/\`. Use Glob/Read when relevant.\n\n`;
+  appendContextFile('User Claude Instructions (from ~/.claude/CLAUDE.md)', path.join(os.homedir(), '.claude', 'CLAUDE.md'), 8192,
+    'These are the user-level Claude Code instructions available in regular Claude usage. Follow them unless they conflict with the Minions task contract or playbook.');
+
+  appendIndex('Knowledge Base Reference', getKnowledgeBaseIndex(), 8192);
+
+  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`, and project-local playbooks live in \`projects/<project>/playbooks/\`. Runtime-native skills and commands are left to the selected CLI runtime; Minions does not inject their contents into the task prompt.\n\n`;
 
   // Minions awareness: what's in flight, who's doing what
   const dispatch = getDispatch();