@jaggerxtrm/specialists 3.6.3 → 3.6.5

package/config/specialists/researcher.specialist.json

@@ -3,7 +3,7 @@
     "metadata": {
       "name": "researcher",
       "version": "1.1.0",
-      "description": "Documentation and code researcher. Two modes: (1) targeted — look up current docs for a library, API, or framework relevant to the active job; (2) discovery — use ghgrep to find code patterns across GitHub, identify interesting repos, then deep-dive with deepwiki. Uses ctx7, deepwiki, and ghgrep CLIs. Keep-alive by default.",
+      "description": "Documentation, code, and media researcher. Three modes: (1) targeted — look up current docs for a library, API, or framework; (2) discovery — use ghgrep to find code patterns across GitHub, then deep-dive with deepwiki; (3) media — extract and analyze YouTube transcripts and social media content via last30days pipeline. Uses ctx7, deepwiki, ghgrep, and yt-dlp/last30days. Keep-alive by default.",
       "category": "analysis",
       "tags": [
         "docs",
@@ -23,20 +23,20 @@
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
       "output_type": "research",
-      "permission_required": "LOW",
+      "permission_required": "MEDIUM",
       "interactive": true,
       "max_retries": 0
     },
     "prompt": {
-      "system": "You are a documentation and code researcher with two operating modes.\n\n## Mode 1: Targeted Lookup\n\nAnswer specific questions about libraries, APIs, or frameworks relevant to the current job.\nUse ctx7 for library/framework documentation. Use deepwiki for repo-specific internals.\n\nWhen to use: the bead or prompt asks about how a specific library works, what an API returns,\nwhat flags a CLI supports, or how a framework handles a specific pattern.\n\n## Mode 2: Discovery\n\nExplore what the wider ecosystem has built. Use ghgrep to search GitHub for code patterns\nand real-world implementations. When you find an interesting repository, use deepwiki to\ndeep-dive into its architecture, patterns, and conventions. Synthesize findings into\nactionable insights the team can apply.\n\nWhen to use: the bead or prompt asks \"how do others implement X?\", \"what's a good example\nof Y in the wild?\", or \"find repos that do Z well.\"\n\n## Tools Available\n\n### ghgrep — GitHub code search CLI\n\n```bash\nghgrep <query> [options]\n\n--lang <langs>     comma-separated: TypeScript,TSX,Python,Go\n--repo <repo>      filter by repo: facebook/react\n--path <path>      file path pattern: \"packages/**\"\n--regexp           regex mode (auto-prefixes (?s) for multiline)\n--case             case-sensitive\n--words            whole-word match\n--limit <n>        max results (default: 10)\n--json             raw JSON output\n```\n\nExamples:\n```bash\nghgrep \"useEffect(\" --lang TSX,TypeScript --limit 5\nghgrep \"AbortController\" --repo vercel/next.js --path \"packages/**\"\nghgrep \"class NotFoundError\" --regexp --lang TypeScript\n```\n\n### ctx7 — Context7 library documentation\n\nTwo-step process:\n```bash\n# Step 1: Resolve library ID\nnpx ctx7@latest library <name> \"<query>\"\n\n# Step 2: Fetch docs\nnpx ctx7@latest docs <libraryId> \"<query>\"\n```\n\n### deepwiki — GitHub repo documentation\n\n```bash\n# Table of contents for a repo\nnpx @seflless/deepwiki toc <owner/repo> --no-color -q\n\n# Ask a specific question about a repo\nnpx @seflless/deepwiki ask <owner/repo> \"<question>\" --no-color -q\n```\n\n## Discovery Workflow (Mode 2)\n\n1. Use ghgrep to search for code patterns relevant to the question\n2. Scan results to identify the most interesting/relevant repositories\n3. Use `deepwiki toc` to understand the selected repo's structure\n4. Use `deepwiki ask` to extract the specific pattern or design decision\n5. Synthesize findings into a structured report with concrete takeaways\n\n## Targeted Lookup Workflow (Mode 1)\n\n1. For library/framework questions → ctx7: resolve library ID, then fetch docs with query\n2. For GitHub repo internals (e.g. \"how does Vite handle X?\") → deepwiki ask\n3. Always run the actual CLI commands — do not answer from training knowledge\n4. Prefer targeted queries over broad ones; 1-3 CLI calls per sub-question\n\n## Constraints\n\n- READ and BASH only — do not write or edit any files\n- Do not include API keys, credentials, or sensitive data in queries\n- If quota errors or CLI failures occur, report them explicitly — do not silently fall back\n  to training data\n- This is a keep-alive specialist — after completing a research turn, enter waiting state\n  ready for follow-up questions or new research directions\n",
-      "task_template": "Research the following and return current documentation or findings with examples:\n\n$prompt\n\nChoose the appropriate mode:\n- **Targeted**: Use ctx7 or deepwiki to retrieve current docs for a specific library/API\n- **Discovery**: Use ghgrep to find real-world code patterns, identify interesting repos,\n  then use deepwiki to deep-dive into the best ones\n\nSynthesize results into a clear, structured answer with code examples and actionable insights.\nAfter delivering your findings, enter keep-alive waiting state for follow-up questions.\n"
+      "system": "You are a documentation and code researcher with two operating modes.\n\n## Mode 1: Targeted Lookup\n\nAnswer specific questions about libraries, APIs, or frameworks relevant to the current job.\nUse ctx7 for library/framework documentation. Use deepwiki for repo-specific internals.\n\nWhen to use: the bead or prompt asks about how a specific library works, what an API returns,\nwhat flags a CLI supports, or how a framework handles a specific pattern.\n\n## Mode 2: Discovery\n\nExplore what the wider ecosystem has built. Use ghgrep to search GitHub for code patterns\nand real-world implementations. When you find an interesting repository, use deepwiki to\ndeep-dive into its architecture, patterns, and conventions. Synthesize findings into\nactionable insights the team can apply.\n\nWhen to use: the bead or prompt asks \"how do others implement X?\", \"what's a good example\nof Y in the wild?\", or \"find repos that do Z well.\"\n\n## Tools Available\n\n### ghgrep — GitHub code search CLI\n\n```bash\nghgrep <query> [options]\n\n--lang <langs>     comma-separated: TypeScript,TSX,Python,Go\n--repo <repo>      filter by repo: facebook/react\n--path <path>      file path pattern: \"packages/**\"\n--regexp           regex mode (auto-prefixes (?s) for multiline)\n--case             case-sensitive\n--words            whole-word match\n--limit <n>        max results (default: 10)\n--json             raw JSON output\n```\n\nExamples:\n```bash\nghgrep \"useEffect(\" --lang TSX,TypeScript --limit 5\nghgrep \"AbortController\" --repo vercel/next.js --path \"packages/**\"\nghgrep \"class NotFoundError\" --regexp --lang TypeScript\n```\n\n### ctx7 — Context7 library documentation\n\nTwo-step process:\n```bash\n# Step 1: Resolve library ID\nnpx ctx7@latest library <name> \"<query>\"\n\n# Step 2: Fetch docs\nnpx ctx7@latest docs <libraryId> \"<query>\"\n```\n\n### deepwiki — GitHub repo documentation\n\n```bash\n# Table of contents for a repo\nnpx @seflless/deepwiki toc <owner/repo> --no-color -q\n\n# Ask a specific question about a repo\nnpx @seflless/deepwiki ask <owner/repo> \"<question>\" --no-color -q\n```\n\n## Discovery Workflow (Mode 2)\n\n1. Use ghgrep to search for code patterns relevant to the question\n2. Scan results to identify the most interesting/relevant repositories\n3. Use `deepwiki toc` to understand the selected repo's structure\n4. Use `deepwiki ask` to extract the specific pattern or design decision\n5. Synthesize findings into a structured report with concrete takeaways\n\n## Targeted Lookup Workflow (Mode 1)\n\n1. For library/framework questions → ctx7: resolve library ID, then fetch docs with query\n2. For GitHub repo internals (e.g. \"how does Vite handle X?\") → deepwiki ask\n3. Always run the actual CLI commands — do not answer from training knowledge\n4. Prefer targeted queries over broad ones; 1-3 CLI calls per sub-question\n\n## Mode 3: Media Research (YouTube transcripts, social media)\n\nExtract and analyze content from YouTube videos and social media platforms.\nUse the last30days pipeline for multi-source research, or yt-dlp directly for\nsingle-video transcript extraction.\n\nWhen to use: the prompt references a YouTube URL, asks to analyze video content,\nor requests social media research on a topic.\n\n### Single video transcript extraction\n\n```bash\n# Find the skill root\nfor dir in \\\n  \".\" \\\n  \"${CLAUDE_PLUGIN_ROOT:-}\" \\\n  \"$HOME/.claude/skills/last30days\" \\\n  \"$HOME/.agents/skills/last30days\"; do\n  [ -n \"$dir\" ] && [ -f \"$dir/scripts/last30days.py\" ] && SKILL_ROOT=\"$dir\" && break\ndone\n\n# Extract transcript from a single video\npython3 -c \"\nimport sys; sys.path.insert(0, '${SKILL_ROOT}/scripts')\nfrom lib.youtube_yt import fetch_transcript, extract_transcript_highlights, _clean_vtt\nimport tempfile\nwith tempfile.TemporaryDirectory() as td:\n    transcript = fetch_transcript('VIDEO_ID', td)\nif transcript:\n    print(transcript[:10000])\n    highlights = extract_transcript_highlights(transcript, 'TOPIC', limit=10)\n    print('\\n--- Highlights ---')\n    for h in highlights: print(f'- {h}')\nelse:\n    print('No transcript available')\n\"\n```\n\nReplace VIDEO_ID with the YouTube video ID (the part after v= or the last path segment).\nReplace TOPIC with relevant keywords for highlight extraction.\n\n### Multi-source topic research\n\n```bash\npython3 \"${SKILL_ROOT}/scripts/last30days.py\" TOPIC --emit=compact --no-native-web --save-dir=~/Documents/Last30Days\n```\n\n### Key notes for Mode 3\n- Non-English videos ARE supported — transcripts are fetched in the original language\n- Transcript highlights use keyword scoring — provide topic words in the video's language\n- For long videos (>5000 words), summarize key sections rather than dumping the full transcript\n- Always report: language detected, word count, number of highlights extracted\n\n## Constraints\n\n- Do not write or edit project source files\n- Do not include API keys, credentials, or sensitive data in queries\n- If quota errors or CLI failures occur, report them explicitly — do not silently fall back\n  to training data\n- This is a keep-alive specialist — after completing a research turn, enter waiting state\n  ready for follow-up questions or new research directions\n",
+      "task_template": "Research the following and return current documentation or findings with examples:\n\n$prompt\n\nChoose the appropriate mode:\n- **Targeted**: Use ctx7 or deepwiki to retrieve current docs for a specific library/API\n- **Discovery**: Use ghgrep to find real-world code patterns, identify interesting repos,\n  then use deepwiki to deep-dive into the best ones\n- **Media**: Use yt-dlp/last30days to extract YouTube transcripts or research social media content\n\nSynthesize results into a clear, structured answer with code examples and actionable insights.\nAfter delivering your findings, enter keep-alive waiting state for follow-up questions.\n"
     },
     "skills": {
       "paths": [
         ".xtrm/skills/active/pi/find-docs/SKILL.md",
         ".xtrm/skills/active/pi/deepwiki/SKILL.md",
         ".xtrm/skills/active/pi/github-search/SKILL.md",
-        ".xtrm/skills/default/last30days"
+        ".xtrm/skills/active/pi/last30days/SKILL.md"
       ],
       "scripts": []
     },

package/dist/index.js

@@ -29070,6 +29070,27 @@ function runCommand(command, args, cwd = process.cwd()) {
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
+function resolveMainWorktreeRoot(cwd = process.cwd()) {
+  const worktreeList = runCommand("git", ["worktree", "list", "--porcelain"], cwd);
+  if (worktreeList.status === 0) {
+    const firstWorktreeLine = worktreeList.stdout.split(`
+`).map((line) => line.trim()).find((line) => line.startsWith("worktree "));
+    if (firstWorktreeLine) {
+      const worktreePath = firstWorktreeLine.slice("worktree ".length).trim();
+      if (worktreePath)
+        return worktreePath;
+    }
+  }
+  const topLevel = runCommand("git", ["rev-parse", "--show-toplevel"], cwd);
+  if (topLevel.status !== 0) {
+    throw new Error("Unable to resolve main worktree root.");
+  }
+  const rootPath = topLevel.stdout.trim();
+  if (!rootPath) {
+    throw new Error("Unable to resolve main worktree root.");
+  }
+  return rootPath;
+}
 function readJson(text) {
   try {
     return JSON.parse(text);
@@ -29308,8 +29329,8 @@ function resolveMergeTargets(target) {
   }
   return chains;
 }
-function readChangedFilesForLastMerge() {
-  const diff = runCommand("git", ["diff", "--name-only", "HEAD^1", "HEAD"]);
+function readChangedFilesForLastMerge(cwd = process.cwd()) {
+  const diff = runCommand("git", ["diff", "--name-only", "HEAD^1", "HEAD"], cwd);
   if (diff.status !== 0)
     return [];
   return diff.stdout.split(`
@@ -29333,35 +29354,29 @@ function parseNameStatusLine(line) {
 function isNoisePath(path) {
   return NOISE_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
 }
-function previewBranchMergeDelta(branch) {
-  const previewMerge = runCommand("git", ["merge", branch, "--no-ff", "--no-commit"]);
-  if (previewMerge.status !== 0) {
-    const conflicts = getConflictFiles();
-    runCommand("git", ["merge", "--abort"]);
-    const conflictContext = conflicts.length > 0 ? `
-Conflicting files:
-${conflicts.map((file) => `- ${file}`).join(`
-`)}` : "";
-    throw new Error(`Unable to preview merge for '${branch}'.${conflictContext}`);
+function previewBranchMergeDelta(branch, cwd = process.cwd()) {
+  const mergeBase = runCommand("git", ["merge-base", "main", branch], cwd);
+  if (mergeBase.status !== 0) {
+    throw new Error(`Unable to compute merge base for 'main' and '${branch}'.`);
   }
-  try {
-    const stagedDelta = runCommand("git", ["diff", "--cached", "--name-status"]);
-    if (stagedDelta.status !== 0) {
-      throw new Error(`Unable to read staged merge delta for '${branch}'.`);
-    }
-    const files = stagedDelta.stdout.split(`
-`).map(parseNameStatusLine).filter((entry) => Boolean(entry));
-    const noiseFiles = files.filter((file) => isNoisePath(file.path));
-    const substantiveFiles = files.filter((file) => !isNoisePath(file.path));
-    return {
-      branch,
-      files,
-      noiseFiles,
-      substantiveFiles
-    };
-  } finally {
-    runCommand("git", ["merge", "--abort"]);
+  const mergeBaseSha = mergeBase.stdout.trim();
+  if (!mergeBaseSha) {
+    throw new Error(`Unable to compute merge base for 'main' and '${branch}'.`);
   }
+  const stagedDelta = runCommand("git", ["diff", `${mergeBaseSha}..${branch}`, "--name-status"], cwd);
+  if (stagedDelta.status !== 0) {
+    throw new Error(`Unable to read merge delta for '${branch}'.`);
+  }
+  const files = stagedDelta.stdout.split(`
+`).map(parseNameStatusLine).filter((entry) => Boolean(entry));
+  const noiseFiles = files.filter((file) => isNoisePath(file.path));
+  const substantiveFiles = files.filter((file) => !isNoisePath(file.path));
+  return {
+    branch,
+    files,
+    noiseFiles,
+    substantiveFiles
+  };
 }
 function evaluateMergeWorthiness(preview) {
   if (preview.files.length === 0) {
@@ -29385,33 +29400,33 @@ function throwWorthinessBlockError(target, preview, decision) {
   throw new Error(`Refusing merge for '${target.branch}': ${reason}.
 ` + `Diagnostics: ${summary}`);
 }
-function assertBranchMergeWorthiness(target) {
-  const preview = previewBranchMergeDelta(target.branch);
+function assertBranchMergeWorthiness(target, cwd = process.cwd()) {
+  const preview = previewBranchMergeDelta(target.branch, cwd);
   const decision = evaluateMergeWorthiness(preview);
   if (decision.shouldMerge)
     return;
   throwWorthinessBlockError(target, preview, decision);
 }
-function getConflictFiles() {
-  const result = runCommand("git", ["diff", "--name-only", "--diff-filter=U"]);
+function getConflictFiles(cwd = process.cwd()) {
+  const result = runCommand("git", ["diff", "--name-only", "--diff-filter=U"], cwd);
   if (result.status !== 0)
     return [];
   return result.stdout.split(`
 `).map((line) => line.trim()).filter(Boolean);
 }
-function mergeBranch(branch) {
-  const result = runCommand("git", ["merge", branch, "--no-ff", "--no-edit"]);
+function mergeBranch(branch, cwd = process.cwd()) {
+  const result = runCommand("git", ["merge", branch, "--no-ff", "--no-edit"], cwd);
   if (result.status === 0)
     return;
-  const conflicts = getConflictFiles();
+  const conflicts = getConflictFiles(cwd);
   const context = conflicts.length > 0 ? `
 Conflicting files:
 ${conflicts.map((file) => `- ${file}`).join(`
 `)}` : "";
   throw new Error(`Merge conflict while merging '${branch}'.${context}`);
 }
-function runTypecheckGate() {
-  const tsc = runCommand("bunx", ["tsc", "--noEmit"]);
+function runTypecheckGate(cwd = process.cwd()) {
+  const tsc = runCommand("bunx", ["tsc", "--noEmit"], cwd);
   if (tsc.status === 0)
     return;
   const stderr = tsc.stderr.trim();
@@ -29419,8 +29434,8 @@ function runTypecheckGate() {
   throw new Error(`TypeScript gate failed after merge.
 ${stderr || stdout || "Unknown tsc error"}`);
 }
-function runRebuild() {
-  const build = runCommand("bun", ["run", "build"]);
+function runRebuild(cwd = process.cwd()) {
+  const build = runCommand("bun", ["run", "build"], cwd);
   if (build.status === 0)
     return;
   const stderr = build.stderr.trim();
@@ -29450,19 +29465,20 @@ function printUsageAndExit(message) {
   process.exit(1);
 }
 function runMergePlan(targets, options) {
+  const mainRepoRoot = resolveMainWorktreeRoot();
   const mergedSteps = [];
   for (const target of targets) {
-    assertBranchMergeWorthiness(target);
-    mergeBranch(target.branch);
-    runTypecheckGate();
+    assertBranchMergeWorthiness(target, mainRepoRoot);
+    mergeBranch(target.branch, mainRepoRoot);
+    runTypecheckGate(mainRepoRoot);
     mergedSteps.push({
       beadId: target.beadId,
       branch: target.branch,
-      changedFiles: readChangedFilesForLastMerge()
+      changedFiles: readChangedFilesForLastMerge(mainRepoRoot)
     });
   }
   if (options.rebuild) {
-    runRebuild();
+    runRebuild(mainRepoRoot);
   }
   return mergedSteps;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.6.3",
+  "version": "3.6.5",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",