@jaggerxtrm/specialists 3.0.2 → 3.2.1

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);