@jaggerxtrm/specialists 3.2.0 → 3.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.2.0",
-  "description": "OmniSpecialist \u2014 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
+  "version": "3.2.1",
+  "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",
   "files": [

package/specialists/codebase-explorer.specialist.yaml

@@ -9,7 +9,7 @@ specialist:
 
   execution:
     mode: tool
-    model: google-gemini-cli/gemini-3-flash-preview
+    model: anthropic/claude-haiku-4-5
     fallback_model: anthropic/claude-sonnet-4-6
     timeout_ms: 180000
     response_format: markdown

package/specialists/planner.specialist.yaml

@@ -0,0 +1,87 @@
+specialist:
+  metadata:
+    name: planner
+    version: 1.0.0
+    description: "Structured planning specialist for xtrm projects. Explores the
+      codebase (GitNexus + Serena), creates a phased bd issue board with rich
+      descriptions, and applies test-planning per layer. Outputs a ready-to-implement
+      epic: child issues created, dependencies wired, test issues generated. Fully
+      autonomous — give it a task description and get back an epic ID and first
+      task to claim."
+    category: workflow
+    tags: [planning, bd, issues, epic, gitnexus, test-planning]
+    updated: "2026-03-22"
+
+  execution:
+    mode: tool
+    model: anthropic/claude-sonnet-4-6
+    fallback_model: google-gemini-cli/gemini-3.1-pro-preview
+    timeout_ms: 600000
+    response_format: markdown
+    permission_required: HIGH
+
+  prompt:
+    system: |
+      You are the Planner specialist for xtrm projects.
+
+      Read the planning skill and follow its 6-phase workflow:
+
+        cat $skill_path
+
+      If $skill_path is not readable, fall back to this condensed workflow:
+        Phase 2  Explore codebase — GitNexus + Serena, read-only
+        Phase 3  Structure plan — phases, dependencies, CoT reasoning
+        Phase 4  Create bd issues — epic + child tasks, rich descriptions
+        Phase 5  Apply test-planning — test issues per layer (core/boundary/shell)
+        Phase 6  Output result — epic ID, all issue IDs, first task to claim
+
+      ## Background execution overrides
+
+      These replace the interactive behaviors in the skill:
+
+      - **Skip Phase 1 (clarification)**: the task prompt is fully specified —
+        proceed directly to Phase 2
+      - **Phase 4**: use `bd` CLI directly to create real issues — no approval step
+      - **Phase 5**: apply test-planning logic inline; do NOT invoke /test-planning
+        as a slash command
+      - **Phase 6**: do NOT claim any issue — output the structured result and stop
+
+      ## Required output format
+
+      End your response with this block (fill in real IDs):
+
+      ```
+      ## Planner result
+
+      Epic: <epic-id> — <epic title>
+      Children: <id1>, <id2>, <id3>, ...
+      Test issues: <test-id1>, <test-id2>, ...
+      First task: <id> — <title>
+
+      To start:  bd update <first-task-id> --claim
+      ```
+
+    task_template: |
+      Plan the following task and create a bd issue board:
+
+      Task: $prompt
+
+      Working directory: $cwd
+      Planning skill: ~/.agents/skills/planning/SKILL.md
+
+      Follow the planning skill workflow (Phases 2–6). Explore the codebase with
+      GitNexus and Serena before creating any issues. Create real bd issues via
+      the bd CLI. Apply test-planning logic to add test issues per layer.
+      End with the structured "## Planner result" block.
+
+
+  capabilities:
+    required_tools: [bash, read, grep, glob]
+    external_commands: [bd, git]
+    diagnostic_scripts:
+      - "bd ready"
+      - "bd stats"
+
+  communication:
+    publishes: [epic_id, issue_ids, first_task, plan_summary]
+    subscribes: []

package/specialists/specialist-author.specialist.yaml

@@ -0,0 +1,56 @@
+specialist:
+  metadata:
+    name: specialist-author
+    version: 1.0.0
+    description: "Guides an agent through writing a valid .specialist.yaml file using the schema reference and common error fixes."
+    category: authoring
+    updated: "2026-03-22"
+    tags: [authoring, yaml, specialist, schema, guide]
+
+  execution:
+    mode: tool
+    model: anthropic/claude-sonnet-4-6
+    timeout_ms: 180000
+    response_format: markdown
+    permission_required: LOW
+
+  prompt:
+    system: |
+      You are a specialist authoring assistant. Your job is to help agents and developers
+      write valid .specialist.yaml files that pass schema validation on the first attempt.
+
+      You have deep knowledge of the SpecialistSchema (Zod) and the runtime behavior of
+      SpecialistRunner. You know every required field, every valid enum value, and every
+      common pitfall.
+
+      When asked to create a specialist, you:
+      1. Ask for (or infer from context): name, purpose, model, permission level
+      2. Output a complete, annotated YAML
+      3. Show the bundled schema validator command to verify it
+      4. Highlight any fields the user should customize
+
+      When asked to fix a specialist, you:
+      1. Identify the exact Zod error and map it to the fix table
+      2. Output the corrected YAML section
+      3. Explain why the original was invalid
+
+    task_template: |
+      $prompt
+
+      Working directory: $cwd
+
+      Use the specialist authoring guide (injected below) to produce or fix a
+      .specialist.yaml. Output the complete YAML and the validation command.
+
+  skills:
+    paths:
+      - skills/specialist-author/SKILL.md
+
+  capabilities:
+    diagnostic_scripts:
+      - bun skills/specialist-author/scripts/validate-specialist.ts specialists/<name>.specialist.yaml
+
+  communication:
+    publishes: [specialist_yaml, validation_command]
+
+  beads_integration: auto

package/specialists/sync-docs.specialist.yaml

@@ -0,0 +1,53 @@
+specialist:
+  metadata:
+    name: sync-docs
+    version: 1.0.0
+    description: "Audits and syncs project documentation: detects drift, extracts bloated README sections, updates CHANGELOG, and validates docs/ frontmatter."
+    category: documentation
+    updated: "2026-03-22"
+    tags: [docs, readme, changelog, drift, audit, sync]
+
+  execution:
+    mode: tool
+    model: anthropic/claude-sonnet-4-6
+    fallback_model: google-gemini-cli/gemini-3-flash-preview
+    timeout_ms: 300000
+    response_format: markdown
+    permission_required: LOW
+
+  prompt:
+    system: |
+      You are a documentation sync specialist. You audit and fix project documentation
+      to keep it in sync with code reality.
+
+      Follow the sync-docs 5-phase workflow injected in your skill context:
+        Phase 1: Gather context (recent changes, bd issues, git log)
+        Phase 2: Detect docs/ drift (drift_detector.py)
+        Phase 3: Analyze structure (doc_structure_analyzer.py)
+        Phase 4: Execute fixes (extract, scaffold, update, changelog)
+        Phase 5: Validate (validate_doc.py, final drift scan)
+
+      **Audit vs Execute:**
+      - If the prompt says "audit", "check", "report", or "what's stale" — stop after Phase 3.
+      - Only run Phase 4 fixes when the prompt explicitly asks for changes.
+
+      **Script paths:** Use `~/.agents/skills/sync-docs/scripts/` for global install.
+
+    task_template: |
+      $prompt
+
+      Working directory: $cwd
+
+      Follow the sync-docs workflow from your injected skill. Start with Phase 1 context
+      gathering, then drift detection, then structure analysis. Report findings before
+      making any changes unless the task explicitly asks for fixes.
+
+  skills:
+    paths:
+      - ~/.agents/skills/sync-docs/SKILL.md
+
+  communication:
+    output_to: .specialists/sync-docs-report.md
+    publishes: [docs_audit, drift_report, changelog_update]
+
+  beads_integration: auto

package/specialists/xt-merge.specialist.yaml

@@ -0,0 +1,78 @@
+specialist:
+  metadata:
+    name: xt-merge
+    version: 1.0.0
+    description: "Drains the xt worktree PR queue in FIFO order: lists open xt/ PRs sorted by creation time, checks CI status on the oldest, merges it with --rebase --delete-branch, then rebases all remaining branches onto the new default branch and force-pushes them. Handles rebase conflicts, CI re-triggering, and reports final queue state."
+    category: workflow
+    tags: [git, pr, merge, worktree, xt, rebase, ci]
+    updated: "2026-03-22"
+
+  execution:
+    mode: tool
+    model: anthropic/claude-sonnet-4-6
+    fallback_model: google-gemini-cli/gemini-3-flash-preview
+    timeout_ms: 300000
+    response_format: markdown
+    permission_required: MEDIUM
+
+  prompt:
+    system: |
+      You are a PR merge specialist for xt worktree workflows.
+
+      Your job is to drain the queue of open PRs from xt worktree sessions. These PRs
+      were created by `xt end` — each branch was rebased onto origin/main at the time
+      it was pushed, so they form an ordered queue that must be merged FIFO.
+
+      ## FIFO ordering
+
+      Merge the oldest-created PR first. After each merge, main advances and all
+      remaining branches must be rebased onto the new main before their CI results
+      are meaningful. Merging out of order increases conflict surface unnecessarily.
+
+      ## Your workflow
+
+      1. List open PRs: `gh pr list --state open --json number,title,headRefName,createdAt,isDraft`
+         Filter for branches starting with "xt/", sort by createdAt ascending.
+         Skip draft PRs.
+
+      2. Check CI on the head PR: `gh pr checks <number>`
+         Do NOT merge if checks are pending or failing. Report status and stop.
+
+      3. Merge the head PR:
+         `gh pr merge <number> --rebase --delete-branch`
+         Always use --rebase for linear history. Always --delete-branch to clean up remote.
+
+      4. Rebase all remaining xt/ branches onto the new main:
+         ```
+         git fetch origin main
+         git checkout xt/<branch>
+         git rebase origin/main
+         git push origin xt/<branch> --force-with-lease
+         ```
+         Repeat in queue order. If a rebase produces conflicts, stop and report the
+         conflicted files with enough context for the user to resolve them.
+
+      5. Repeat from step 2 until the queue is empty.
+
+      ## Constraints
+
+      - Never merge a PR with failing or pending CI.
+      - Never use --squash or --merge; always --rebase.
+      - Never force-push without --force-with-lease.
+      - If you hit a rebase conflict you cannot safely resolve, stop and show the
+        conflicted files. Do not guess at conflict resolution.
+      - Report the queue state (PR number, branch, CI status) before each merge action.
+
+    task_template: |
+      Drain the xt worktree PR merge queue.
+
+      $prompt
+
+      Working directory: $cwd
+
+      List all open PRs from xt/ branches, sort oldest-first, check CI on the oldest,
+      merge it if green, rebase the remaining branches onto the new main, and repeat
+      until the queue is empty. Report final state when done.
+
+  communication:
+    output_to: .specialists/merge-prs-result.md

package/hooks/beads-close-memory-prompt.mjs

@@ -1,47 +0,0 @@
-#!/usr/bin/env node
-// beads-close-memory-prompt — Claude Code PostToolUse hook
-// After `bd close`: injects a short reminder into Claude's context to capture
-// knowledge and consider underused beads features.
-// Output to stdout is shown to Claude as additional context.
-//
-// Installed by: specialists install
-
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-// Only fire on Bash tool
-if (input.tool_name !== 'Bash') process.exit(0);
-
-const cmd = (input.tool_input?.command ?? '').trim();
-
-// Only fire when the command is `bd close ...`
-if (!/\bbd\s+close\b/.test(cmd)) process.exit(0);
-
-// Only fire in projects that use beads
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-// Inject reminder into Claude's context
-process.stdout.write(
-  '\n[beads] Issue(s) closed. Before moving on:\n\n' +
-  '  Knowledge worth keeping?\n' +
-  '    bd remember "key insight from this work"\n' +
-  '    bd memories <keyword>   -- search what is already stored\n\n' +
-  '  Discovered related work while implementing?\n' +
-  '    bd create --title="..." --deps=discovered-from:<id>\n\n' +
-  '  Underused features to consider:\n' +
-  '    bd dep add <a> <b>   -- link blocking relationships between issues\n' +
-  '    bd graph             -- visualize issue dependency graph\n' +
-  '    bd orphans           -- issues referenced in commits but still open\n' +
-  '    bd preflight         -- PR readiness checklist before gh pr create\n' +
-  '    bd stale             -- issues not touched recently\n'
-);
-
-process.exit(0);

package/hooks/beads-commit-gate.mjs

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-// beads-commit-gate — Claude Code PreToolUse hook
-// Blocks `git commit` when in_progress beads issues still exist.
-// Forces: close issues first, THEN commit.
-// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
-//
-// Installed by: specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const tool = input.tool_name ?? '';
-if (tool !== 'Bash') process.exit(0);
-
-const cmd = input.tool_input?.command ?? '';
-if (!/\bgit\s+commit\b/.test(cmd)) process.exit(0);
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-let summary = '';
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-  summary = output.trim();
-} catch {
-  process.exit(0);
-}
-
-if (inProgress > 0) {
-  process.stderr.write(
-    '🚫 BEADS GATE: Close open issues before committing.\n\n' +
-    `Open issues:\n${summary}\n\n` +
-    'Next steps:\n' +
-    '  3. bd close <id1> <id2> ...             ← you are here\n' +
-    '  4. git add <files> && git commit -m "..."\n' +
-    '  5. git push -u origin <feature-branch>\n' +
-    '  6. gh pr create --fill && gh pr merge --squash\n' +
-    '  7. git checkout master && git reset --hard origin/master\n'
-  );
-  process.exit(2);
-}
-
-process.exit(0);

package/hooks/beads-edit-gate.mjs

@@ -1,53 +0,0 @@
-#!/usr/bin/env node
-// beads-edit-gate — Claude Code PreToolUse hook
-// Blocks file edits when no beads issue is in_progress.
-// Only active in projects with a .beads/ directory.
-// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
-//
-// Installed by: specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-} catch {
-  process.exit(0);
-}
-
-if (inProgress === 0) {
-  process.stderr.write(
-    '🚫 BEADS GATE: No active issue — create one before editing files.\n\n' +
-    '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
-    '  bd update <id> --status=in_progress\n\n' +
-    'Full workflow (do this every session):\n' +
-    '  1. bd create + bd update in_progress   ← you are here\n' +
-    '  2. Edit files / write code\n' +
-    '  3. bd close <id>                        close when done\n' +
-    '  4. git add <files> && git commit\n' +
-    '  5. git push -u origin <feature-branch>\n' +
-    '  6. gh pr create --fill && gh pr merge --squash\n' +
-    '  7. git checkout master && git reset --hard origin/master\n'
-  );
-  process.exit(2);
-}
-
-process.exit(0);

package/hooks/beads-stop-gate.mjs

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-// beads-stop-gate — Claude Code Stop hook
-// Blocks the agent from stopping when in_progress beads issues remain.
-// Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
-//
-// Installed by: specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-let summary = '';
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-  summary = output.trim();
-} catch {
-  process.exit(0);
-}
-
-if (inProgress > 0) {
-  process.stderr.write(
-    '🚫 BEADS STOP GATE: Unresolved issues — complete the session close protocol.\n\n' +
-    `Open issues:\n${summary}\n\n` +
-    'Session close protocol:\n' +
-    '  3. bd close <id1> <id2> ...               close all in_progress issues\n' +
-    '  4. git add <files> && git commit -m "..."  commit your changes\n' +
-    '  5. git push -u origin <feature-branch>     push feature branch\n' +
-    '  6. gh pr create --fill                     create PR\n' +
-    '  7. gh pr merge --squash                    merge PR\n' +
-    '  8. git checkout master && git reset --hard origin/master\n'
-  );
-  process.exit(2);
-}
-
-process.exit(0);

package/hooks/specialists-main-guard.mjs

@@ -1,90 +0,0 @@
-#!/usr/bin/env node
-// Claude Code PreToolUse hook — block writes and direct master pushes
-// Exit 0: allow  |  Exit 2: block (message shown to user)
-//
-// Installed by: specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-
-let branch = '';
-try {
-  branch = execSync('git branch --show-current', {
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }).trim();
-} catch {}
-
-// Not in a git repo or not on a protected branch — allow
-if (!branch || (branch !== 'main' && branch !== 'master')) {
-  process.exit(0);
-}
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const tool = input.tool_name ?? '';
-
-const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
-
-if (WRITE_TOOLS.has(tool)) {
-  process.stderr.write(
-    `⛔ You are on '${branch}' — never edit files directly on master.\n\n` +
-    'Full workflow:\n' +
-    '  1. git checkout -b feature/<name>         ← start here\n' +
-    '  2. bd create + bd update in_progress      track your work\n' +
-    '  3. Edit files / write code\n' +
-    '  4. bd close <id> && git add && git commit\n' +
-    '  5. git push -u origin feature/<name>\n' +
-    '  6. gh pr create --fill && gh pr merge --squash\n' +
-    '  7. git checkout master && git reset --hard origin/master\n'
-  );
-  process.exit(2);
-}
-
-// Block direct commits and pushes to master — use feature branches + gh pr create/merge
-if (tool === 'Bash') {
-  const cmd = (input.tool_input?.command ?? '').trim().replace(/\s+/g, ' ');
-
-  if (/^git commit/.test(cmd)) {
-    process.stderr.write(
-      `⛔ Don't commit directly to '${branch}' — use a feature branch.\n\n` +
-      'Full workflow:\n' +
-      '  1. git checkout -b feature/<name>         ← start here\n' +
-      '  2. bd create + bd update in_progress      track your work\n' +
-      '  3. Edit files / write code\n' +
-      '  4. bd close <id> && git add && git commit\n' +
-      '  5. git push -u origin feature/<name>\n' +
-      '  6. gh pr create --fill && gh pr merge --squash\n' +
-      '  7. git checkout master && git reset --hard origin/master\n'
-    );
-    process.exit(2);
-  }
-
-  if (/^git push/.test(cmd)) {
-    const tokens = cmd.split(' ');
-    const lastToken = tokens[tokens.length - 1];
-    const explicitMaster = /^(master|main)$/.test(lastToken) || /:(master|main)$/.test(lastToken);
-    const impliedMaster = tokens.length <= 3 && (branch === 'main' || branch === 'master');
-    if (explicitMaster || impliedMaster) {
-      process.stderr.write(
-        `⛔ Don't push directly to '${branch}' — use the PR workflow.\n\n` +
-        'Next steps:\n' +
-        '  5. git push -u origin <feature-branch>     ← push your branch\n' +
-        '  6. gh pr create --fill                      create PR\n' +
-        '     gh pr merge --squash                     merge it\n' +
-        '  7. git checkout master                      sync master\n' +
-        '     git reset --hard origin/master\n\n' +
-        'If you\'re not on a feature branch yet:\n' +
-        '  git checkout -b feature/<name>    (then re-commit and push)\n'
-      );
-      process.exit(2);
-    }
-  }
-}
-
-process.exit(0);