@jaggerxtrm/specialists 3.9.0 → 3.10.0

package/config/mandatory-rules/README.md

@@ -3,6 +3,10 @@
 Rule sets injected at the end of every specialist prompt at spawn time. Enforces
 behaviors the model must follow regardless of the specific task.
 
+> **Quick introspection:** `sp list-rules` prints the rule × specialist matrix.
+> Filter with `sp list-rules --rule <id>` or `sp list-rules --specialist <name>`,
+> machine output via `--json`.
+
 ## Layout (three tiers)
 
 The loader reads and unions indexes from three paths, in this precedence:

package/config/mandatory-rules/gitnexus-required.md

@@ -2,4 +2,15 @@
 name: gitnexus-required
 kind: mandatory-rule
 ---
-Use GitNexus for symbol changes. Run impact before edit and detect_changes before finish.
+Use GitNexus before editing any function/class/method.
+
+Tools (prefer MCP; fall back to CLI if MCP unavailable):
+- Blast radius before edit: `gitnexus_impact({target, direction:"upstream"})` or `npx gitnexus impact <target>`. STOP and warn if HIGH/CRITICAL.
+- Symbol callers/callees: `gitnexus_context({name})` or `npx gitnexus context <name>`.
+- Concept search: `gitnexus_query({query})` or `npx gitnexus query "<text>"`.
+- Pre-commit scope check: `gitnexus_detect_changes()` (MCP only — fallback: `git diff --stat`).
+
+Rules:
+- Run impact for every symbol you modify; never edit without it.
+- Never rename via find-replace — use `gitnexus_rename({symbol_name, new_name, dry_run:true})` first.
+- If index is stale, ask the user to run `npx gitnexus analyze`.

package/config/mandatory-rules/serena-cheatsheet.md

@@ -0,0 +1,41 @@
+---
+name: serena-cheatsheet
+kind: mandatory-rule
+rules:
+  - id: prefer-serena
+    level: required
+    text: "Prefer Serena tools over read/grep/find/ls for source code (.ts .py .go .rs .js etc.). Native tools fine for .md .json .yaml configs."
+  - id: get_symbols_overview
+    level: required
+    text: "get_symbols_overview <path> — symbol skeleton of a file or dir (~300 tokens vs reading the whole file). Use first to pick what you actually need."
+  - id: find_symbol
+    level: required
+    text: "find_symbol <name_path> — fetch one symbol's body (or just signature). Drop-in replacement for read-then-scan-for-function workflows."
+  - id: find_referencing_symbols
+    level: required
+    text: "find_referencing_symbols <name_path> — who calls or uses this symbol across the codebase."
+  - id: search_for_pattern
+    level: required
+    text: "search_for_pattern <regex> — replaces grep. Returns matches with file:line context."
+  - id: find_file
+    level: required
+    text: "find_file <glob> and list_dir <path> — replace native find and ls."
+  - id: read_file
+    level: required
+    text: "read_file <path> — full or sliced read. Use only when navigation tools are not enough; check get_symbols_overview first."
+  - id: replace_symbol_body
+    level: required
+    text: "replace_symbol_body <name_path> — swap a function or class body in place. Use instead of Edit string-match for symbol-scoped changes (MEDIUM+ permission)."
+  - id: insert_around_symbol
+    level: required
+    text: "insert_before_symbol / insert_after_symbol <name_path> — add adjacent code such as imports or helpers (MEDIUM+ permission)."
+  - id: rename_symbol
+    level: required
+    text: "rename_symbol <name_path> <new_name> — refactor-safe across all references. Use instead of find-and-replace (MEDIUM+ permission)."
+  - id: replace_content
+    level: required
+    text: "replace_content <path> <pattern> <replacement> — line-range or regex edits when no symbol target fits (MEDIUM+ permission)."
+  - id: cost-rule
+    level: info
+    text: "Rule of thumb: read of a 500-line source file ~5000 tokens; find_symbol on one function ~200 tokens (~25x cheaper). Use get_symbols_overview before deciding."
+---

package/config/specialists/debugger.specialist.json

@@ -35,7 +35,8 @@
     "mandatory_rules": {
       "template_sets": [
         "debugger-trace-first",
-        "gitnexus-required"
+        "gitnexus-required",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/executor.specialist.json

@@ -31,7 +31,8 @@
       "template_sets": [
         "executor-delivery",
         "git-workflow-safe",
-        "gitnexus-required"
+        "gitnexus-required",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/explorer.specialist.json

@@ -28,7 +28,8 @@
     "mandatory_rules": {
       "template_sets": [
         "explorer-readonly",
-        "gitnexus-required"
+        "gitnexus-required",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/memory-processor.specialist.json

@@ -54,6 +54,11 @@
     },
     "stall_detection": {},
     "beads_integration": "auto",
-    "beads_write_notes": true
+    "beads_write_notes": true,
+    "mandatory_rules": {
+      "template_sets": [
+        "serena-cheatsheet"
+      ]
+    }
   }
 }

package/config/specialists/overthinker.specialist.json

@@ -28,7 +28,8 @@
     },
     "mandatory_rules": {
       "template_sets": [
-        "overthinker-4phase"
+        "overthinker-4phase",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/planner.specialist.json

@@ -83,6 +83,11 @@
     },
     "beads_integration": "auto",
     "stall_detection": {},
-    "beads_write_notes": true
+    "beads_write_notes": true,
+    "mandatory_rules": {
+      "template_sets": [
+        "serena-cheatsheet"
+      ]
+    }
   }
 }

package/config/specialists/researcher.specialist.json

@@ -29,7 +29,8 @@
     },
     "mandatory_rules": {
       "template_sets": [
-        "researcher-source-discipline"
+        "researcher-source-discipline",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/reviewer.specialist.json

@@ -29,7 +29,8 @@
     "mandatory_rules": {
       "template_sets": [
         "reviewer-verdict-format",
-        "gitnexus-required"
+        "gitnexus-required",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/specialists-creator.specialist.json

@@ -17,6 +17,7 @@
     "execution": {
       "mode": "tool",
       "model": "anthropic/claude-sonnet-4-6",
+      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
@@ -62,6 +63,11 @@
     },
     "beads_integration": "auto",
     "stall_detection": {},
-    "beads_write_notes": true
+    "beads_write_notes": true,
+    "mandatory_rules": {
+      "template_sets": [
+        "serena-cheatsheet"
+      ]
+    }
   }
 }

package/config/specialists/sync-docs.specialist.json

@@ -29,7 +29,8 @@
     },
     "mandatory_rules": {
       "template_sets": [
-        "researcher-source-discipline"
+        "researcher-source-discipline",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {

package/config/specialists/test-runner.specialist.json

@@ -27,7 +27,8 @@
     },
     "mandatory_rules": {
       "template_sets": [
-        "test-runner-execution-scope"
+        "test-runner-execution-scope",
+        "serena-cheatsheet"
       ]
     },
     "prompt": {