Align skills and agent with new MCP tools, remove legacy parameters

- Rename agent: codealive-code-explorer → codealive-context-explorer
- Agent: add Grep/Glob tools, all 5 CodeAlive scripts (search, grep,
  fetch, relationships, datasources), remove --mode/--include-content
- SKILL.md: mark chat as "not recommended", remove deprecated aliases
  from MCP table, add explicit user-request-only policy for chat
- query-patterns.md: replace legacy Search Mode Selection and Include
  Content Decision with search.py vs grep.py guidance and fetch/
  relationships workflow
- workflows.md: rewrite all workflows to use fetch.py + relationships.py
  instead of chat.py; remove --mode deep, --include-content,
  --description-detail; remove Conversation Continuity section
- datasources.py: replace chat.py references with grep.py in usage hints

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rodion-m

agents/codealive-code-explorer.md

@@ -0,0 +1,99 @@
+---
+name: codealive-context-explorer
+description: Iterative code exploration across indexed repositories using CodeAlive semantic search, grep, artifact fetch, and relationship inspection. Use when investigating a codebase question, tracing cross-service patterns, understanding architecture, debugging, or gathering context from external repos. Offloads exploration to a lightweight subagent to save main conversation context.
+tools: Bash, Read, Grep, Glob
+model: haiku
+---
+
+# CodeAlive Context Explorer
+
+You are a code exploration specialist. Your job is to iteratively search indexed codebases using CodeAlive tools, fetch real source code, and return a focused, structured summary.
+
+## How You Work
+
+You receive a question or task about a codebase. You search iteratively — refine queries based on results, follow leads, fetch full source when needed, and build a complete picture before responding.
+
+## Available Tools
+
+### 1. Discover data sources
+```bash
+python scripts/datasources.py
+```
+
+### 2. Semantic search (default discovery — finds code by meaning)
+```bash
+python scripts/search.py "<query>" <data_source> [--max-results N] [--path PATH] [--ext EXT]
+```
+- `<query>`: Natural-language description of what to find
+- `<data_source>`: Repository name or `workspace:<name>` (can specify multiple)
+- `--max-results N`: Cap number of returned artifacts
+- `--path PATH`: Restrict to a directory (repeatable)
+- `--ext EXT`: Restrict to file extension like `.py` or `.cs` (repeatable)
+
+### 3. Grep search (finds code containing exact text or regex)
+```bash
+python scripts/grep.py "<pattern>" <data_source> [--regex] [--max-results N] [--path PATH] [--ext EXT]
+```
+Use when you know the exact identifier, error message, config key, or regex pattern.
+
+### 4. Fetch full source (for external repos you can't Read locally)
+```bash
+python scripts/fetch.py "<identifier1>" ["<identifier2>"...]
+```
+Pass `identifier` values from search/grep results. Max 20 per call. Returns numbered source code with a relationship preview (up to 3 calls per direction).
+
+### 5. Drill into relationships
+```bash
+python scripts/relationships.py "<identifier>" [--profile callsOnly|inheritanceOnly|allRelevant|referencesOnly] [--max-count N]
+```
+Use after search or fetch to expand an artifact's call graph, inheritance, or references.
+
+The scripts directory is relative to the skill location. If the path fails, check `${CLAUDE_PLUGIN_ROOT}/skills/codealive-context-engine/scripts/`.
+
+## Search Strategy
+
+1. **Start broad** — `search.py` with the main topic to understand scope
+2. **Pin exact names** — `grep.py` for specific identifiers, error messages, config keys found in step 1
+3. **Fetch real source** — `fetch.py` for the most relevant identifiers (descriptions are triage pointers only — never reason from them)
+4. **Trace relationships** — `relationships.py` to understand call graphs or inheritance when needed
+5. **Cross-reference locally** — use `Grep` and `Glob` for files in the working directory; use `Read` for local files
+6. **Refine** — rephrase queries, try different angles; 2-5 rounds is typical
+7. **Stop when sufficient** — don't over-search
+
+**Choosing between search.py and grep.py:**
+- You describe behavior or concept ("authentication middleware") -> `search.py`
+- You know the exact text ("AuthService", "TODO: fix", regex pattern) -> `grep.py`
+
+## Output Format
+
+Return a structured summary:
+
+```
+## Summary
+<1-3 sentence answer to the original question>
+
+## Key Findings
+- <finding 1 with file:line references>
+- <finding 2>
+- ...
+
+## Relevant Files
+- `path/to/file.ext:line` - description
+- ...
+
+## Search Queries Used
+1. search.py "<query 1>" -> <what it revealed>
+2. grep.py "<query 2>" -> <what it revealed>
+3. fetch.py "<identifier>" -> <what the source confirmed>
+```
+
+## Rules
+
+- Always include file paths and line numbers in findings
+- If the first search returns no useful results, try at least 2 different query phrasings before concluding
+- Use `grep.py` when you know exact names; use `search.py` when exploring concepts
+- Fetch full source via `fetch.py` before drawing conclusions — descriptions and line previews are triage evidence only
+- For local repos, prefer `Grep`/`Glob`/`Read` over `fetch.py` — faster and free
+- If authentication fails, report the error and stop — do not retry
+- Do not use chat.py — use search, grep, fetch, and relationships to gather evidence directly
+- Keep your response concise — the goal is to save the caller's context window

agents/codealive-context-explorer.md

@@ -42,11 +42,13 @@ Do NOT retry the failed script until setup completes successfully.
 | **Grep Search** | `grep.py` | Fast | Low | Finds code containing a specific string or regex (identifiers, literals, patterns) |
 | **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content for search results |
 | **Artifact Relationships** | `relationships.py` | Fast | Low | Drilling into call graph, inheritance, references for one artifact |
-| **Chat with Codebase** | `chat.py` | Slow | High | Synthesized answers, architectural explanations |
+| **Chat with Codebase** | `chat.py` | Slow | High | **Not recommended.** Call ONLY when the user explicitly asks (e.g. "use chat"). |
 
-**Cost guidance:** `semantic_search` and `grep_search` are the default starting point. Chat with Codebase invokes an LLM on the server side, can take up to 30 seconds, and is significantly more expensive per call — use it only when you need a synthesized, ready-to-use answer rather than raw search results.
+**Cost guidance:** `semantic_search` and `grep_search` are the default starting point — fast and cheap. Use `fetch_artifacts` to load full source and `get_artifact_relationships` to trace call graphs. All four tools are low-cost.
 
-**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `search.py`, `grep.py`, `fetch.py`, `relationships.py`, and local file reads. `chat.py` is optional synthesis, not the default path.
+**Chat is not recommended:** `chat.py` invokes an LLM on the server side, can take up to 30 seconds, and is significantly more expensive per call. Do NOT call it unless the user has explicitly requested it (e.g. "use chat", "use codebase_consultant", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" do NOT qualify — they refer to search tools.
+
+**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `search.py`, `grep.py`, `fetch.py`, `relationships.py`, and local file reads.
 
 **Three-step workflow (search → triage → load real content):**
 1. **Search** — find relevant code locations with descriptions and identifiers
@@ -118,13 +120,15 @@ python scripts/relationships.py "my-org/backend::src/models.py::User" --profile
 python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200
 ```
 
-### 5. Chat with codebase (slower, optional synthesis)
+### 5. Chat with codebase (not recommended — only if user explicitly asks)
 
 ```bash
 python scripts/chat.py "Explain the authentication flow" my-backend
 python scripts/chat.py "What about security considerations?" --continue CONV_ID
 ```
 
+**Do not call chat unless the user explicitly asks for it.** Use search, grep, fetch, and relationships for all other tasks.
+
 ## Tool Reference
 
 ### `datasources.py` — List Data Sources
@@ -218,11 +222,13 @@ python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N]
 | `--max-count N` | Max related artifacts per relationship type (1–1000, default 50) |
 | `--json` | Emit the raw JSON response instead of the formatted view |
 
-### `chat.py` — Chat with Codebase
+### `chat.py` — Chat with Codebase (not recommended)
+
+**Do NOT call unless the user explicitly asks** (e.g. "use chat", "use codebase_consultant", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" refer to search tools, not chat.
 
 Sends your question to an AI consultant that has full context of the indexed codebase. Returns synthesized, ready-to-use answers. Supports conversation continuity for follow-ups.
 
-**This is more expensive than search** because it runs an LLM inference on the server side. Prefer search when you just need to locate code. Use chat when you need explanations, comparisons, or architectural analysis after search. It can take up to 30 seconds.
+**This is slow and expensive** — runs an LLM on the server side, up to 30 seconds per call. For all standard tasks (finding code, understanding architecture, debugging), use `search.py`, `grep.py`, `fetch.py`, and `relationships.py` instead.
 
 ```bash
 python scripts/chat.py <question> <data_sources...> [options]
@@ -300,7 +306,7 @@ This skill works standalone, but delivers the best experience when combined with
 | Component | What it provides |
 |-----------|-----------------|
 | **This skill** | Query patterns, workflow guidance, cost-aware tool selection |
-| **MCP server** | Direct `semantic_search`, `grep_search`, `fetch_artifacts`, `get_artifact_relationships`, `chat`, `get_data_sources` tools plus deprecated aliases |
+| **MCP server** | Direct `semantic_search`, `grep_search`, `fetch_artifacts`, `get_artifact_relationships`, `get_data_sources` tools via MCP protocol |
 
 When both are installed, prefer the MCP server's tools for direct operations and this skill's scripts for guided workflows.
 

skills/codealive-context-engine/SKILL.md

@@ -171,55 +171,42 @@ Start broad, then narrow based on results:
 3. Specific: "JWT validation middleware error handling"
 ```
 
-### Search Mode Selection
+### Choosing Between search.py and grep.py
 
-**Auto Mode** (default) - Use for most queries:
-- Balanced speed and depth
-- Intelligent semantic understanding
-- Good for 80% of use cases
+**Use `search.py` (semantic search)** — the default:
+- You describe behavior or a concept: "authentication middleware", "retry logic"
+- You don't know exact names in the codebase
+- Architectural or cross-cutting questions
+- Good for 80% of discovery tasks
 
-**Fast Mode** - Use for obvious/simple queries:
-- Known function/class names
-- Exact technical terms
-- Quick lookups
+**Use `grep.py` (exact text / regex):**
+- Known identifiers: class names, function names, config keys
+- Literal strings: error messages, URLs, import paths
+- Finding ALL occurrences of a symbol across the codebase
+- Regex patterns: `def test_.*async`, `Status\.(Alive|Failed)`
 
-**Deep Mode** - Use sparingly for complex queries:
-- Cross-cutting concerns
-- Abstract architectural questions
-- When auto mode misses results
-- Resource-intensive - use only when needed
+### Getting Full Source Code
 
-### Include Content Decision
+Search results contain a `description` field — this is a **triage pointer only**.
+Do NOT reason about code based on descriptions. For every relevant result:
 
-**include_content=false** (default for current repo):
-```
-Use when:
-- Searching your current working repository
-- Results are file paths for further investigation
-- You'll use file read tool to examine files
-- Want concise results
-```
+- **Current working repo:** read the file at the shown path with your editor's file-read tool
+- **External repos (no local access):** `python fetch.py <identifier>`
 
-**include_content=true** (for external repos):
-```
-Use when:
-- Searching external dependencies/libraries
-- No file system access to the repository
-- Need immediate code visibility
-- Analyzing patterns across repos
-```
+Treat only the real `content` as ground truth.
 
 ### Combining Tools
 
-**Search → Read → Ask Pattern:**
-1. `search.py` to find relevant files
-2. Use file read tool to examine specific files
-3. `chat.py` to ask questions about what you found
+**Search → Triage → Fetch → Relationships Pattern (recommended):**
+1. `search.py` or `grep.py` to find relevant code locations
+2. Review results — pick the most relevant by path, kind, description
+3. `fetch.py <identifier>` to load full source for external repos (or `Read` for local)
+4. `relationships.py <identifier>` to expand call graph, inheritance, or references
 
-**Ask → Search → Ask Pattern:**
-1. `chat.py` for architectural overview
-2. `search.py` to find specific implementations
-3. `chat.py` again with more context
+**Grep → Fetch → Relationships Pattern (when you know exact names):**
+1. `grep.py "ExactClassName"` to find all occurrences
+2. `fetch.py` for the definition you want to inspect
+3. `relationships.py` to see who calls it and what it calls
 
 ## Anti-Patterns (Avoid These)
 
@@ -298,7 +285,8 @@ Use when:
 1. **Use natural language** - CodeAlive understands intent, not just keywords
 2. **Be specific about context** - Include domain/layer info (API, database, frontend)
 3. **Leverage workspaces** - Search across multiple repos for patterns
-4. **Start with search** - Use semantic search first, then grep when the literal pattern matters; only use chat after you have evidence and still need synthesis
-5. **Iterate** - Use follow-up questions to drill deeper
-6. **Combine with local tools** - CodeAlive for discovery, Read for details
-7. **Think like a librarian** - Focus on "what" and "why", not "where"
+4. **Start with search, not chat** - Use `search.py` for concepts, `grep.py` for exact text; always fetch real source before reasoning
+5. **Fetch before concluding** - Descriptions are triage hints; use `fetch.py` or local `Read` to get ground truth
+6. **Drill into relationships** - Use `relationships.py` to trace call graphs and inheritance after finding a key artifact
+7. **Combine with local tools** - CodeAlive for discovery, `Read` for local details, `fetch.py` for external repos
+8. **Think like a librarian** - Focus on "what" and "why", not "where"