@yemi33/minions 0.1.1959 → 0.1.1961

package/docs/skills.md

@@ -0,0 +1,43 @@
+# Skill Block Format
+
+Agents emit a fenced `skill` block when they discover a durable, reusable workflow that future agents are likely to need. See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the eligibility threshold and the "zero skills is the default" rule.
+
+The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills are landed via PR into the matching project's playbook tree.
+
+## Block format
+
+````
+```skill
+---
+name: short-descriptive-name
+description: One-line description of when to trigger this skill
+scope: minions
+---
+
+# Skill Title
+
+## Steps
+1. ...
+2. ...
+
+## Notes
+...
+```
+````
+
+### Frontmatter fields
+
+- `name` (**required**) — kebab-case identifier; becomes the on-disk directory name.
+- `description` (**required**) — one-line "when to use this" hint shown in skill listings.
+- `scope` — `minions` (default; user-level skill, available in any runtime window) or `project` (repo-local skill, landed via PR into that project).
+- `project` — required when `scope: project`; the project name the skill belongs to.
+- `allowed-tools` (optional) — comma-separated tools the skill is permitted to call (e.g. `Bash, Read, Edit`).
+- `trigger` (optional) — natural-language phrase describing when an agent should invoke the skill.
+
+### Body
+
+Plain Markdown. Include the steps, commands, file paths, and notes another agent needs to follow the workflow without reading the original task context. Cite source files and PR numbers where useful — the body is what future agents actually read.
+
+## When not to emit a skill
+
+See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the full threshold. In short: do not emit a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs, playbooks, or skills.

package/engine/lifecycle.js

@@ -2332,6 +2332,38 @@ function checkForLearnings(agentId, agentInfo, taskDesc) {
   log('info', `${agentInfo?.name || agentId} didn't write learnings — no follow-up queued`);
 }
 
+// E2.a (W-mp7goxe4000p75f7): name-normalised dedup against the personal-scope
+// skill dir. Strips a trailing `-[a-z0-9]{4,8}` random-suffix on the candidate
+// and re-checks against existing stems; also does simple prefix-match.
+// Returns the matched existing stem, or null if no near-duplicate.
+// Read-only — never deletes or renames existing skills.
+function _findNearDuplicateSkill(personalSkillRoot, candidateName) {
+  if (!personalSkillRoot || !candidateName) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(personalSkillRoot, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch { return null; }
+  if (entries.length === 0) return null;
+
+  // 1. Strip trailing `-[a-z0-9]{4,8}` random suffix and re-check.
+  const stripped = candidateName.replace(/-[a-z0-9]{4,8}$/, '');
+  if (stripped !== candidateName && entries.includes(stripped)) {
+    return stripped;
+  }
+
+  // 2. Prefix-match against existing stems. Either direction:
+  //    - candidate `foo-bar-x4y2` vs existing `foo-bar`
+  //    - candidate `foo` vs existing `foo-bar`
+  for (const existing of entries) {
+    if (existing === candidateName) continue;
+    if (candidateName.startsWith(existing + '-')) return existing;
+    if (existing.startsWith(candidateName + '-')) return existing;
+  }
+  return null;
+}
+
 function skillWriteTargets(runtimeName, project = null) {
   try {
     const runtime = resolveRuntime(runtimeName || 'claude');
@@ -2408,22 +2440,42 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
       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)) {
-        // Native skill format: only name + description in frontmatter. The
-        // `Auto-extracted` marker is an HTML comment so the dashboard's
-        // autoGenerated detection picks it up without polluting the body
-        // an agent reads.
-        const description = m('description') || m('trigger') || `Auto-extracted skill from ${agentName}`;
-        const body = fmMatch[2] || '';
-        const marker = `<!-- Auto-extracted by ${agentName} on ${dateStamp()} -->`;
-        const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${marker}\n\n${body.trim()}\n`;
-        if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
-        shared.safeWrite(skillPath, ccContent);
-        try { require('./queries').invalidateSkillsCache(); } catch {}
-        log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
-      } else {
+      if (fs.existsSync(skillPath)) {
         log('info', `Skill "${name}" already exists, skipping`);
+        continue;
+      }
+      // E2.a (W-mp7goxe4000p75f7): catch random-suffix and prefix-match
+      // near-duplicates BEFORE writing. Logs + flags for human review;
+      // no existing skills are deleted or renamed.
+      const nearDup = _findNearDuplicateSkill(personalSkillRoot, name.replace(/[^a-z0-9-]/g, '-'));
+      if (nearDup) {
+        log('warn', `Skill "${name}" appears to be a near-duplicate of "${nearDup}", skipping`);
+        const flaggedPath = path.join(ENGINE_DIR, 'skills-flagged.json');
+        mutateJsonFileLocked(flaggedPath, (data) => {
+          const arr = Array.isArray(data) ? data : [];
+          arr.push({
+            timestamp: ts(),
+            candidate: name,
+            existing: nearDup,
+            agent: agentName,
+            dispatchId: dispatchItem?.id || null,
+          });
+          return arr;
+        });
+        continue;
       }
+      // Native skill format: only name + description in frontmatter. The
+      // `Auto-extracted` marker is an HTML comment so the dashboard's
+      // autoGenerated detection picks it up without polluting the body
+      // an agent reads.
+      const description = m('description') || m('trigger') || `Auto-extracted skill from ${agentName}`;
+      const body = fmMatch[2] || '';
+      const marker = `<!-- Auto-extracted by ${agentName} on ${dateStamp()} -->`;
+      const ccContent = `---\nname: ${name}\ndescription: ${description}\n---\n\n${marker}\n\n${body.trim()}\n`;
+      if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
+      shared.safeWrite(skillPath, ccContent);
+      try { require('./queries').invalidateSkillsCache(); } catch {}
+      log('info', `Extracted skill "${name}" from ${agentName} → ${skillPath}`);
 
     }
   }

package/engine/playbook.js

@@ -488,16 +488,6 @@ function renderPlaybook(type, vars) {
   content += `- Gotchas or warnings for future agents\n`;
   content += `- Conventions to follow\n`;
   content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
-  content += `### Skill Extraction (IMPORTANT)\n\n`;
-  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — only output it as a fenced skill block when **all** of these are true: (1) you had to discover it during this task, (2) it is not already captured in team memory, repo docs, existing playbooks, or existing skills, and (3) another agent is likely to reuse it on future tasks. **Zero skills is the default.** Prefer the inbox findings for one-off notes, repo facts, and task-specific observations.\n\n`;
-  content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
-  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 the selected runtime's native personal skills directory so they are available in normal runtime windows too\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`;
 
   // Inject project-level variables from config
   const config = getConfig();
@@ -604,7 +594,7 @@ function buildSystemPrompt(agentId, config, project) {
   // Agent identity
   prompt += `# You are ${agent.name} (${agent.role})\n\n`;
   prompt += `Agent ID: ${agentId}\n`;
-  prompt += `Skills: ${(agent.skills || []).join(', ')}\n\n`;
+  prompt += `Expertise: ${(agent.skills || []).join(', ')}\n\n`;
 
   // Charter (detailed instructions — typically 1-2KB)
   if (charter) {
@@ -624,12 +614,59 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `2. ${getRepoHostToolRule(project)}\n`;
   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 the selected runtime's native personal skills directory\n\n`;
+  prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n\n`;
 
   return prompt;
 }
 
+// E2.b (W-mp7goxe4000p75f7): build the `## Existing Skills (do not duplicate)`
+// section for buildAgentContext. Lists name + first-line description for every
+// personal-scope/installed-plugin skill discovered by queries.getSkills().
+// Caps at ~2KB by truncating alphabetically with a "_...and N more_" tail.
+// Returns '' when there are no personal-scope skills to advertise.
+const EXISTING_SKILLS_MAX_BYTES = 2048;
+const PERSONAL_SKILL_SCOPES = new Set(['claude-code', 'copilot', 'agent-skill', 'plugin', 'copilot-plugin']);
+
+function _buildExistingSkillsSection(config) {
+  let skills;
+  try {
+    skills = queries.getSkills(config) || [];
+  } catch { return ''; }
+  const personal = skills
+    .filter(s => PERSONAL_SKILL_SCOPES.has(s.scope))
+    .map(s => ({
+      name: String(s.name || '').trim(),
+      description: String(s.description || '').split('\n')[0].trim(),
+    }))
+    .filter(s => s.name)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  if (personal.length === 0) return '';
+
+  const header = `## Existing Skills (do not duplicate)\n\nThese personal-scope skills already exist on disk. Do NOT emit a \`\`\`skill block whose name duplicates or near-duplicates one of these — the engine will flag it for human review and skip the write.\n\n`;
+  const lines = personal.map(s => s.description ? `- ${s.name} — ${s.description}` : `- ${s.name}`);
+
+  let body = lines.join('\n') + '\n\n';
+  if (Buffer.byteLength(header + body, 'utf8') <= EXISTING_SKILLS_MAX_BYTES) {
+    return header + body;
+  }
+
+  // Truncate alphabetically until we fit, leaving room for the tail line.
+  let kept = lines.length;
+  while (kept > 0) {
+    const dropped = lines.length - kept;
+    const tail = `_...and ${dropped} more (alphabetical truncation; full list on disk)_\n\n`;
+    body = lines.slice(0, kept).join('\n') + '\n' + tail;
+    if (Buffer.byteLength(header + body, 'utf8') <= EXISTING_SKILLS_MAX_BYTES) {
+      return header + body;
+    }
+    kept--;
+  }
+  // Pathological: header alone exceeds the cap. Return at least the header
+  // with a tail showing every skill was dropped, so the agent still sees the
+  // section heading.
+  return header + `_...and ${lines.length} more (alphabetical truncation; full list on disk)_\n\n`;
+}
+
 // 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) {
@@ -682,7 +719,12 @@ function buildAgentContext(agentId, config, project) {
 
   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`;
+  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 live in their native indexes (the catalog of names + descriptions is injected below as "Existing Skills"; full skill bodies are not).\n\n`;
+
+  // E2.b (W-mp7goxe4000p75f7): inject existing personal-scope skill catalog
+  // so agents can see what already exists before emitting a near-duplicate
+  // skill block. Caps at ~2KB; truncates alphabetically with a tail count.
+  context += _buildExistingSkillsSection(config);
 
   // Minions awareness: what's in flight, who's doing what
   const dispatch = getDispatch();

package/engine/worktree-pool.js

@@ -148,85 +148,6 @@ function tryBorrow(projectName, dispatchId, opts) {
   return borrowed;
 }
 
-/**
- * Register a brand-new worktree as a borrowed pool member. Used when a fresh
- * worktree is created (no idle slot available) and the pool has room — we
- * track it from creation so the eventual return is a simple state flip.
- *
- * Honors capacity inside the locked mutation: if the project is already at or
- * over `poolSize`, the registration is rejected and the worktree stays
- * untracked (cleanup will reap it normally).
- */
-function registerBorrowed(projectName, wtPath, dispatchId, opts) {
-  opts = opts || {};
-  if (!projectName || !wtPath || !dispatchId) return false;
-  const poolSize = Number.isFinite(opts.poolSize) ? Math.max(0, Math.floor(opts.poolSize)) : 0;
-  if (poolSize <= 0) return false;
-  const branch = opts.branch || '';
-  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
-  let registered = false;
-  mutateWorktreePool((data) => {
-    const entries = data.entries;
-    // Already tracked? Update the borrower fields and keep going.
-    const existingIdx = _findEntryByPath(entries, wtPath);
-    if (existingIdx !== -1) {
-      const e = entries[existingIdx];
-      e.state = POOL_STATE.BORROWED;
-      e.borrowedBy = dispatchId;
-      e.borrowedAt = _nowIso(now);
-      e.idleSince = null;
-      if (branch) e.lastBranch = branch;
-      e.lastUsed = e.borrowedAt;
-      registered = true;
-      return data;
-    }
-    // Capacity gate — count entries (idle + borrowed) for this project.
-    const projectCount = entries.filter(e => e && e.project === projectName).length;
-    if (projectCount >= poolSize) return data;
-    entries.push({
-      project: projectName,
-      path: wtPath,
-      state: POOL_STATE.BORROWED,
-      borrowedBy: dispatchId,
-      borrowedAt: _nowIso(now),
-      idleSince: null,
-      lastBranch: branch,
-      createdAt: _nowIso(now),
-      lastUsed: _nowIso(now),
-    });
-    registered = true;
-    return data;
-  });
-  return registered;
-}
-
-/**
- * Mark a borrowed entry as idle. Caller is responsible for having already run
- * the git reset/clean/checkout-detach/pull dance — this is purely a state
- * flip. If the entry is unknown, no-op (caller can decide to register first).
- */
-function markIdle(wtPath, opts) {
-  opts = opts || {};
-  if (!wtPath) return false;
-  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
-  const branch = opts.branch || '';
-  let flipped = false;
-  mutateWorktreePool((data) => {
-    const idx = _findEntryByPath(data.entries, wtPath);
-    if (idx === -1) return data;
-    const e = data.entries[idx];
-    e.state = POOL_STATE.IDLE;
-    e.borrowedBy = null;
-    e.borrowedAt = null;
-    e.idleSince = _nowIso(now);
-    e.lastUsed = _nowIso(now);
-    if (branch) e.lastBranch = branch;
-    flipped = true;
-    return data;
-  });
-  return flipped;
-}
-
 /**
  * Return a worktree to the pool — flip an existing borrowed entry to idle, or
  * insert a fresh entry as idle when the project is under capacity. Both paths
@@ -353,8 +274,8 @@ function pruneStale(opts) {
 }
 
 /**
- * Count entries (idle + borrowed) belonging to a project. Used to gate
- * `markIdle` registrations from fresh-create paths.
+ * Count entries (idle + borrowed) belonging to a project. Used for capacity
+ * gating diagnostics and pool-size dashboards.
  */
 function countForProject(projectName) {
   if (!projectName) return 0;
@@ -397,8 +318,6 @@ module.exports = {
   isPoolMember,
   getEntry,
   tryBorrow,
-  registerBorrowed,
-  markIdle,
   returnToPool,
   evictEntry,
   pruneStale,

package/engine.js

@@ -990,8 +990,15 @@ async function spawnAgent(dispatchItem, config) {
           if (borrowed && borrowed.path && fs.existsSync(borrowed.path)) {
             try { shared.assertWorktreeOutsideProject(borrowed.path, rootDir); }
             catch (assertErr) {
+              // Always evict before deciding what to do — leaves no BORROWED
+              // orphan tied to a dispatch that won't complete normally.
+              // pruneStale would self-heal in ~10 ticks via orphan-borrow, but
+              // that window is unnecessary.
+              const _evictReason = assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT'
+                ? 'nested-in-project'
+                : 'assert-failed';
+              worktreePool.evictEntry(borrowed.path, _evictReason);
               if (assertErr?.code === 'WORKTREE_NESTED_IN_PROJECT') {
-                worktreePool.evictEntry(borrowed.path, 'nested-in-project');
                 _failWorktreePreflight(assertErr); return null;
               }
               throw assertErr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1959",
+  "version": "0.1.1961",
   "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/explore.md

@@ -60,7 +60,6 @@ Use subagents only for genuinely parallel, independent tasks. For reading files,
 - Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the `az` CLI first and use ADO MCP only as a fallback when `az` is unavailable or insufficient.
 - Do NOT checkout branches in the main working tree — use worktrees.
 - Read `notes.md` for all team rules before starting.
-- Only emit a ```skill block if you uncovered a durable reusable workflow that is not already documented and is likely to help future tasks; zero skills is the default, and one-off findings belong in the inbox notes instead.
 
 ## When to Stop
 

package/playbooks/shared-rules.md

@@ -46,20 +46,7 @@ Bias toward senior-engineer restraint:
   5. Previous agent output in `agents/*/live-output.log` for related tasks
   6. Work item descriptions and `resultSummary` for prior completed work on the same topic
   Only after exhausting team memory should you look outside (web search, codebase exploration, external docs). This avoids duplicating research another agent already completed and ensures team decisions are respected.
-- Only output a fenced skill block when **all** of these are true: (1) you discovered a durable multi-step workflow that was not already documented in team memory, repo docs, existing playbooks, or existing skills, (2) another agent is likely to need it on future tasks, and (3) the workflow is specific enough to be actionable but general enough to stand alone. **Zero skills is the default.** Prefer writing one-off findings, repo facts, or task-specific notes to the inbox findings instead of creating a skill. Emit **at most one skill block per task** unless the task clearly uncovered two unrelated reusable workflows. The engine auto-extracts valid skill blocks to `~/.claude/skills/<name>/SKILL.md`, so `scope: minions` skills become user-level Claude skills available in normal Claude windows too. Required format:
-  ````
-  ```skill
-  ---
-  name: skill-name-here
-  description: One-line description of when to trigger this skill
-  scope: minions
-  ---
-
-  Instructions for the skill go here.
-  ```
-  ````
-  The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: minions` for user-level reusable skills; use `scope: project` + `project: ProjectName` only for repo-specific skills that should land in that project via PR.
-  Do **not** create a skill for one-off bug fixes, isolated command outputs, obvious repo facts, or anything already covered by existing docs/playbooks/skills.
+- Only output a fenced skill block when **all** of these are true: (1) you discovered a durable multi-step workflow that was not already documented in team memory, repo docs, existing playbooks, or existing skills, (2) another agent is likely to need it on future tasks, and (3) the workflow is specific enough to be actionable but general enough to stand alone. **Zero skills is the default.** Prefer writing one-off findings, repo facts, or task-specific notes to the inbox findings instead of creating a skill. Emit at most one skill block per task unless the task clearly uncovered two unrelated reusable workflows. The engine auto-extracts valid skill blocks to the selected runtime's native personal skills directory, so `scope: minions` skills become user-level Claude/Copilot skills available in normal runtime windows too. See [`docs/skills.md`](../docs/skills.md) for the skill block format. 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.
 - Do TDD where it makes sense — write failing tests first, then implement, then verify tests pass. Especially for bug fixes (write a test that reproduces the bug) and new utility functions.
 
 ## Completion Reports