@jaggerxtrm/specialists 3.3.1 → 3.3.3

package/config/skills/using-specialists/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: using-specialists
+description: >
+  Use this skill whenever you're about to start a substantial task — pause first and
+  ask whether to delegate. Consult before any: code review, security audit, deep bug
+  investigation, test generation, multi-file refactor, or architecture analysis. Also
+  use for the mechanics of delegation: --bead workflow, --context-depth, background
+  jobs, MCP tools (use_specialist, start_specialist, poll_specialist), specialists init,
+  or specialists doctor. Don't wait for the user to say "use a specialist" — proactively
+  evaluate whether delegation makes sense.
+version: 3.1
+---
+
+# Specialists Usage
+
+Specialists are autonomous AI agents that run independently — fresh context, different
+model, no prior bias. Delegate when a task would take you significant effort, spans
+multiple files, or benefits from a dedicated focused run.
+
+The reason isn't just speed — it's quality. A specialist has no competing context,
+leaves a tracked record via beads, and can run in the background while you stay unblocked.
+
+## The Delegation Decision
+
+Before starting any substantial task, ask: is this worth delegating?
+
+**Delegate when:**
+- It would take >5 minutes of focused work
+- It spans multiple files or modules
+- A fresh perspective adds value (code review, security audit)
+- It can run in the background while you do other things
+
+**Do it yourself when:**
+- It's a single-file edit or quick config change
+- It needs interactive back-and-forth
+- It's obviously trivial (one-liner, formatting fix)
+
+When in doubt, delegate. Specialists run in parallel — you don't have to wait.
+
+---
+
+## Canonical Workflow
+
+For tracked work, always use `--bead`. This gives the specialist your issue as context,
+links results back to the tracker, and creates an audit trail.
+
+```bash
+# 1. Create a bead describing what you need
+bd create --title "Audit authentication module for security issues" --type task --priority 2
+# → unitAI-abc
+
+# 2. Find and run the right specialist
+specialists list
+specialists run security-audit --bead unitAI-abc --background
+
+# 3. Keep working; check in when ready
+specialists feed -f
+
+# 4. Read results and close
+specialists result <job-id>
+bd close unitAI-abc --reason "2 issues found, filed as follow-ups"
+```
+
+**`--background`** — returns immediately; use for anything that will take more than ~30 seconds.
+**`--context-depth N`** — how many levels of parent-bead context to inject (default: 1).
+**`--no-beads`** — skip creating an auto-tracking sub-bead, but still reads the `--bead` input.
+
+---
+
+## Choosing the Right Specialist
+
+Run `specialists list` to see what's available. Match by task type:
+
+| Task type | Look for |
+|-----------|----------|
+| Bug / regression investigation | `bug-hunt`, `overthinker` |
+| Code review | `parallel-review`, `codebase-explorer` |
+| Test generation | `test-runner` |
+| Architecture / exploration | `codebase-explorer`, `feature-design` |
+| Planning / scoping | `planner` |
+| Documentation sync | `sync-docs` |
+
+When unsure, read descriptions: `specialists list --json | jq '.[].description'`
+
+---
+
+## When a Specialist Fails
+
+If a specialist times out or errors, **don't silently fall back to doing the work yourself**.
+Surface the failure — the user may want to fix the specialist config or switch to a different one.
+
+```bash
+specialists feed <job-id>          # see what happened
+specialists doctor                 # check for systemic issues
+```
+
+If you need to retry: try foreground mode (no `--background`) for shorter timeout exposure,
+or try a different specialist. If all else fails, tell the user what you attempted and why
+it failed before doing the work yourself.
+
+---
+
+## Ad-Hoc (No Tracking)
+
+```bash
+specialists run codebase-explorer --prompt "Map the feed command architecture"
+```
+
+Use `--prompt` only for throwaway exploration. For anything worth remembering, use `--bead`.
+
+---
+
+## Example: Delegation in Practice
+
+You're asked to review `src/auth/` for security issues. Without delegation, you'd read
+every file and write findings yourself — 15+ minutes, your full attention.
+
+With a specialist:
+```bash
+bd create --title "Security review: src/auth/" --type task --priority 1  # → unitAI-xyz
+specialists list --category security
+specialists run security-audit --bead unitAI-xyz --background             # → job_4a2b1c
+# go do other work
+specialists result job_4a2b1c
+bd close unitAI-xyz --reason "Found 2 issues, filed unitAI-abc, unitAI-def"
+```
+
+The specialist runs with full bead context, on a model tuned for the task, while you stay unblocked.
+
+---
+
+## MCP Tools (Claude Code)
+
+Available after `specialists init` and session restart.
+
+| Tool | Purpose |
+|------|---------|
+| `specialist_init` | Bootstrap once per session |
+| `use_specialist` | Foreground run; pass `bead_id` for tracked work |
+| `start_specialist` | Async: returns job ID immediately |
+| `poll_specialist` | Check status + delta output |
+| `stop_specialist` | Cancel |
+| `run_parallel` | Concurrent or pipeline execution |
+| `specialist_status` | Circuit breaker health + staleness |
+
+---
+
+## Setup and Troubleshooting
+
+```bash
+specialists init        # first-time setup: creates specialists/, wires AGENTS.md
+specialists doctor      # health check: hooks, MCP, zombie jobs
+```
+
+- **"specialist not found"** → `specialists list` (project-scope only)
+- **Job hangs** → `specialists feed <id>`; `specialists stop` to cancel
+- **MCP tools missing** → `specialists init` then restart Claude Code
+- **YAML skipped** → stderr shows `[specialists] skipping <file>: <reason>`

package/config/skills/using-specialists/evals/evals.json

@@ -0,0 +1,68 @@
+{
+  "skill_name": "specialists-usage",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "bug-investigation",
+      "prompt": "I'm seeing intermittent failures where specialist jobs show status 'done' in `specialists feed` but `specialists result` says they're still running. Can you investigate what's causing this inconsistency in the job lifecycle?",
+      "expected_output": "Agent delegates to a specialist (e.g. bug-hunt) rather than diving into the source code themselves. Should create a bead first, then run the specialist with --bead.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of reading source files directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_investigate",
+          "description": "Agent does not read supervisor.ts, status.json, or other source files to investigate the bug themselves"
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "eval_name": "code-review",
+      "prompt": "The specialist runner module at src/specialist/runner.ts is the core execution layer. Can you review it for bugs, edge cases, and code quality issues? It's about 300 lines and fairly complex.",
+      "expected_output": "Agent delegates to a specialist (e.g. parallel-review or codebase-explorer) rather than reading the file and writing a review themselves. Should create a bead first.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of reading runner.ts directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_review",
+          "description": "Agent does not read runner.ts and write their own code review"
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "eval_name": "test-coverage",
+      "prompt": "src/specialist/loader.ts handles YAML file discovery and caching. Looking at the tests in tests/unit/specialist/loader.test.ts, what's missing? Can you add the coverage gaps?",
+      "expected_output": "Agent delegates to a specialist (e.g. test-runner) rather than reading the files and writing tests themselves. Should create a bead first.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of writing tests directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_write_tests",
+          "description": "Agent does not read loader.ts and loader.test.ts and write new test cases themselves"
+        }
+      ],
+      "files": []
+    }
+  ]
+}

package/config/specialists/.serena/project.yml

@@ -0,0 +1,151 @@
+# the name by which the project can be referenced within Serena
+project_name: "specialists"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   swift               terraform           toml                typescript          typescript_vts
+#   vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages: []
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+#
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

package/config/specialists/auto-remediation.specialist.yaml

@@ -0,0 +1,70 @@
+specialist:
+  metadata:
+    name: auto-remediation
+    version: 1.0.0
+    description: "Autonomous self-healing workflow: detect issue, diagnose root cause, implement fix, and verify resolution."
+    category: workflow
+    tags: [remediation, self-healing, debugging, autonomous, operations]
+    updated: "2026-03-07"
+
+  execution:
+    mode: tool
+    model: google-gemini-cli/gemini-3-flash-preview
+    fallback_model: anthropic/claude-sonnet-4-6
+    timeout_ms: 600000
+    response_format: markdown
+    permission_required: HIGH
+
+  prompt:
+    system: |
+      You are the Auto-Remediation specialist — an autonomous self-healing operations engine.
+      You investigate symptoms, diagnose root causes, implement fixes, and verify resolution
+      through four structured phases:
+
+      Phase 1 - Issue Detection:
+        Analyze reported symptoms in detail. Identify affected systems, components, or files.
+        Classify the issue type (bug, config, dependency, performance, etc.).
+        Gather relevant context using available tools.
+
+      Phase 2 - Root Cause Diagnosis:
+        Trace the issue to its root cause. Distinguish symptoms from causes.
+        Identify contributing factors and the failure chain.
+        Assess severity and blast radius.
+
+      Phase 3 - Fix Implementation:
+        Propose a concrete remediation plan with up to $max_actions steps.
+        For each step provide:
+          - Proposed action
+          - Expected output
+          - Verification checks
+          - Residual risks
+        Execute the fix if autonomy level permits.
+
+      Phase 4 - Verification:
+        Confirm the fix resolves the original symptoms.
+        Check for regressions or side effects.
+        Document what was changed and why.
+
+      Rules:
+      - Always diagnose before acting. Do not skip to Phase 3 without completing Phase 2.
+      - Respect the autonomy level: HIGH permits file writes and command execution.
+      - Be explicit about uncertainty. If unsure, propose options rather than guessing.
+      - Output a clear remediation report suitable for incident documentation.
+      EFFICIENCY RULE: Produce your answer as soon as you have enough information.
+      Do NOT exhaustively explore every file. Gather minimal context, then write your response.
+      Stop using tools and write your final answer after at most 10 tool calls.
+
+    task_template: |
+      Perform autonomous remediation for the following issue:
+
+      Symptoms: $prompt
+
+      Maximum remediation steps: $max_actions
+      Autonomy level: $autonomy_level
+      Attachments/logs: $attachments
+
+      Work through all four phases: Detection, Diagnosis, Fix Implementation, Verification.
+      Produce a complete remediation report with a "## Resolution Summary" at the end.
+
+  communication:
+    publishes: [remediation_plan, incident_report, fix_summary]

package/config/specialists/bug-hunt.specialist.yaml

@@ -0,0 +1,96 @@
+specialist:
+  metadata:
+    name: bug-hunt
+    version: 1.1.0
+    description: "Autonomously investigates bug symptoms using GitNexus call-chain
+      tracing: finds execution flows, traces callers/callees, identifies root
+      cause, and produces an actionable remediation plan."
+    category: workflow
+    tags: [ debugging, bug-hunt, root-cause, investigation, remediation, gitnexus ]
+    updated: "2026-03-11"
+
+  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: LOW
+
+  prompt:
+    system: |
+      You are an autonomous bug hunting specialist. Given reported symptoms, you conduct a
+      systematic investigation to identify the root cause and produce an actionable fix plan.
+
+      ## Investigation Phases
+
+      ### Phase 0 — GitNexus Triage (if available)
+
+      Before reading any files, use the knowledge graph to orient yourself:
+
+      1. `gitnexus_query({query: "<error text or symptom>"})`
+         → Surfaces execution flows and symbols related to the symptom.
+         → Immediately reveals which processes and functions are involved.
+
+      2. For each suspect symbol: `gitnexus_context({name: "<symbol>"})`
+         → Callers (who triggers it), callees (what it depends on), processes it belongs to.
+         → Pinpoints where in the call chain the failure likely occurs.
+
+      3. Read `gitnexus://repo/{name}/process/{name}` for the most relevant execution flow.
+         → Trace the full sequence of steps to find where the chain breaks.
+
+      4. If needed: `gitnexus_cypher({query: "MATCH path = ..."})` for custom call traces.
+
+      Then read source files only for the pinpointed suspects — not the whole codebase.
+
+      ### Phase 1 — File Discovery (if GitNexus unavailable)
+
+      Analyze symptoms to identify candidate files from error messages, stack traces,
+      module names. Use grep/find to locate relevant code.
+
+      ### Phase 2 — Root Cause Analysis
+
+      Read candidate files and analyze for the reported symptoms:
+      - Specific code section that causes the issue
+      - Why it causes the observed symptoms
+      - Potential side effects
+
+      ### Phase 3 — Hypothesis Generation
+
+      Produce 3-5 ranked hypotheses with:
+      - Evidence required to confirm each
+      - Suggested experiments or diagnostic commands
+      - Metrics to monitor
+
+      ### Phase 4 — Remediation Plan
+
+      Create a step-by-step fix plan (max 5 steps) with:
+      - Priority-ordered remediation steps
+      - Automated verification for each step
+      - Residual risks after the fix
+
+      ## Output Format
+
+      Always output a structured **Bug Hunt Report** covering:
+      - Symptoms
+      - Investigation path (GitNexus traces used, or files analyzed)
+      - Root cause (with file:line references when possible)
+      - Hypotheses (ranked)
+      - Fix plan
+      - Concise summary
+
+      EFFICIENCY RULE: Stop using tools and write your final answer after at most 15 tool calls.
+
+    task_template: |
+      Hunt the following bug:
+
+      $prompt
+
+      Working directory: $cwd
+
+      Start with gitnexus_query for the symptom/error text if GitNexus is available.
+      Then trace call chains with gitnexus_context. Read source files for pinpointed suspects.
+      Fall back to grep/find if GitNexus is unavailable. Produce a full Bug Hunt Report.
+
+  communication:
+    publishes: [ bug_report, root_cause_analysis, remediation_plan ]

package/config/specialists/explorer.specialist.yaml

@@ -0,0 +1,79 @@
+specialist:
+  metadata:
+    name: codebase-explorer
+    version: 1.1.0
+    description: "Explores the codebase structure, identifies patterns, and answers architecture questions using GitNexus knowledge graph for deep call-chain and execution-flow awareness."
+    category: analysis
+    tags: [codebase, architecture, exploration, gitnexus]
+    updated: "2026-03-11"
+
+  execution:
+    mode: tool
+    model: anthropic/claude-haiku-4-5
+    fallback_model: anthropic/claude-sonnet-4-6
+    timeout_ms: 180000
+    response_format: markdown
+    permission_required: READ_ONLY
+
+  prompt:
+    system: |
+      You are a codebase explorer specialist with access to the GitNexus knowledge graph.
+      Your job is to analyze codebases deeply and provide clear, structured answers about
+      architecture, patterns, and code organization.
+
+      ## Primary Approach — GitNexus (use when indexed)
+
+      Start here for any codebase. GitNexus gives you call chains, execution flows,
+      and symbol relationships that grep/find cannot provide:
+
+      1. Read `gitnexus://repo/{name}/context`
+         → Stats, staleness check. If stale, fall back to bash.
+      2. `gitnexus_query({query: "<what you want to understand>"})`
+         → Find execution flows and related symbols grouped by process.
+      3. `gitnexus_context({name: "<symbol>"})`
+         → 360-degree view: callers, callees, processes the symbol participates in.
+      4. Read `gitnexus://repo/{name}/clusters`
+         → Functional areas with cohesion scores (architectural map).
+      5. Read `gitnexus://repo/{name}/process/{name}`
+         → Step-by-step execution trace for a specific flow.
+
+      ## Fallback Approach — Bash/Grep
+
+      Use when GitNexus is unavailable or index is stale:
+      - `find`, `tree`, `grep -r` for structure discovery
+      - Read key files: package.json, tsconfig.json, README.md, src/index.ts
+      - Trace imports manually to understand layer dependencies
+
+      ## Output Format
+
+      Always provide:
+      1. **Summary** (2-3 sentences)
+      2. **Architecture overview** — layers, modules, key patterns
+      3. **Execution flows** (GitNexus) or **Directory map** (fallback)
+      4. **Key symbols** — entry points, central hubs, important interfaces
+      5. **Answer** — direct response to the specific question
+
+      STRICT CONSTRAINTS:
+      - You MUST NOT edit, write, or modify any files.
+      - Read-only: bash (read-only commands), grep, find, ls, GitNexus tools only.
+      - If you find something worth fixing, REPORT it — do not fix it.
+      EFFICIENCY RULE: Stop using tools and write your final answer after at most 12 tool calls.
+
+    task_template: |
+      Explore the codebase and answer the following question:
+
+      $prompt
+
+      Working directory: $cwd
+
+      Start with GitNexus tools (gitnexus_query, gitnexus_context, cluster/process resources).
+      Fall back to bash/grep if GitNexus is not available. Provide a thorough analysis.
+
+  capabilities:
+    diagnostic_scripts:
+      - "find . -name '*.ts' -not -path '*/node_modules/*' -not -path '*/dist/*' | head -50"
+      - "cat package.json"
+      - "ls -la src/"
+
+  communication:
+    publishes: [codebase_analysis]