xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/find-docs/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: find-docs
+description: >-
+  Retrieves up-to-date documentation, API references, and code examples for any
+  developer technology. Use this skill whenever the user asks about a specific
+  library, framework, SDK, CLI tool, or cloud service -- even for well-known ones
+  like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. Your
+  training data may not reflect recent API changes or version updates.
+
+  Always use for: API syntax questions, configuration options, version migration
+  issues, "how do I" questions mentioning a library name, debugging that involves
+  library-specific behavior, setup instructions, and CLI tool usage.
+
+  Use even when you think you know the answer -- do not rely on training data
+  for API details, signatures, or configuration options as they are frequently
+  outdated. Always verify against current docs. Prefer this over web search for
+  library documentation and API details.
+---
+
+# Documentation Lookup
+
+Retrieve current documentation and code examples for any library using the Context7 CLI.
+
+Make sure the CLI is up to date before running commands:
+
+```bash
+npm install -g ctx7@latest
+```
+
+Or run directly without installing:
+
+```bash
+npx ctx7@latest <command>
+```
+
+## Workflow
+
+Two-step process: resolve the library name to an ID, then query docs with that ID.
+
+```bash
+# Step 1: Resolve library ID
+ctx7 library <name> <query>
+
+# Step 2: Query documentation
+ctx7 docs <libraryId> <query>
+```
+
+You MUST call `ctx7 library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
+
+IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have.
+
+## Step 1: Resolve a Library
+
+Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
+
+```bash
+ctx7 library react "How to clean up useEffect with async operations"
+ctx7 library nextjs "How to set up app router with middleware"
+ctx7 library prisma "How to define one-to-many relations with cascade delete"
+```
+
+Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+### Result fields
+
+Each result includes:
+
+- **Library ID** — Context7-compatible identifier (format: `/org/project`)
+- **Name** — Library or package name
+- **Description** — Short summary
+- **Code Snippets** — Number of available code examples
+- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
+- **Benchmark Score** — Quality indicator (100 is the highest score)
+- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
+
+### Selection process
+
+1. Analyze the query to understand what library/package the user is looking for
+2. Select the most relevant match based on:
+   - Name similarity to the query (exact matches prioritized)
+   - Description relevance to the query's intent
+   - Documentation coverage (prioritize libraries with higher Code Snippet counts)
+   - Source reputation (consider libraries with High or Medium reputation more authoritative)
+   - Benchmark score (higher is better, 100 is the maximum)
+3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
+4. If no good matches exist, clearly state this and suggest query refinements
+5. For ambiguous queries, request clarification before proceeding with a best-guess match
+
+### Version-specific IDs
+
+If the user mentions a specific version, use a version-specific library ID:
+
+```bash
+# General (latest indexed)
+ctx7 docs /vercel/next.js "How to set up app router"
+
+# Version-specific
+ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
+```
+
+The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
+
+## Step 2: Query Documentation
+
+Retrieves up-to-date documentation and code examples for the resolved library.
+
+```bash
+ctx7 docs /facebook/react "How to clean up useEffect with async operations"
+ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
+ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
+```
+
+### Writing good queries
+
+The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
+
+| Quality | Example |
+|---------|---------|
+| Good | `"How to set up authentication with JWT in Express.js"` |
+| Good | `"React useEffect cleanup function with async operations"` |
+| Bad | `"auth"` |
+| Bad | `"hooks"` |
+
+Use the user's full question as the query when possible, vague one-word queries return generic results.
+
+The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
+
+## Authentication
+
+Works without authentication. For higher rate limits:
+
+```bash
+# Option A: environment variable
+export CONTEXT7_API_KEY=your_key
+
+# Option B: OAuth login
+ctx7 login
+```
+
+## Error Handling
+
+If a command fails with a quota error ("Monthly quota reached" or "quota exceeded"):
+1. Inform the user their Context7 quota is exhausted
+2. Suggest they authenticate for higher limits: `ctx7 login`
+3. If they cannot or choose not to authenticate, answer from training knowledge and clearly note it may be outdated
+
+Do not silently fall back to training data — always tell the user why Context7 was not used.
+
+## Common Mistakes
+
+- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
+- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
+- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"`
+- Do not include sensitive information (API keys, passwords, credentials) in queries
+
+## Related Skills
+
+**last30days** — For recent trends, community sentiment, and what people are saying _right now_:
+
+| Use `find-docs` | Use `last30days` |
+|-----------------|------------------|
+| "How do I use React useEffect?" | "What are people saying about React 19 beta?" |
+| "Next.js middleware API syntax" | "Best Next.js auth patterns 2026" |
+| "Prisma cascade delete syntax" | "Prisma vs Drizzle community opinions" |
+| API reference, stable documentation | Recent discussions, trends, real-world experiences |
+
+**When to use last30days:**
+- Researching trends, comparisons, or "best of" questions
+- Finding real-world experiences and community recommendations
+- Topics where recency matters (new releases, beta features, emerging tools)
+- "What are people using for X?" questions
+
+**Invocation:** `/last30days <topic>` (e.g., `/last30days AI video tools`)
+
+See: `.xtrm/skills/default/last30days/SKILL.md`

package/.xtrm/skills/default/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/.xtrm/skills/default/github-search/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: github-search
+description: >-
+  Search real-world GitHub code examples from bash using the ghgrep CLI wrapper
+  for the github-grep MCP server. Use when you need implementation patterns,
+  API usage examples, or production snippets from public repositories.
+---
+
+# GitHub Code Search (ghgrep)
+
+Use `ghgrep` to query `mcp.grep.app` without requiring MCP tool access.
+
+## Usage
+
+```bash
+ghgrep <query> [options]
+```
+
+## Options
+
+```bash
+--lang <langs>       Comma-separated languages (TypeScript,TSX,Python)
+--repo <repo>        Repository filter (facebook/react)
+--path <path>        File path filter
+--regexp             Regex mode (auto-prefixes (?s) for multiline)
+--case               Case-sensitive match
+--words              Whole-word match
+--limit <n>          Max formatted results (default: 10)
+--json               Raw MCP JSON payload
+```
+
+## Recommended workflow
+
+1. Start with a literal code pattern (`useEffect(`, `createServer(`, `router.get(`).
+2. Add `--lang` and `--repo` filters to reduce noise.
+3. Use `--regexp` for multi-line patterns.
+4. Re-run with narrower `--path` once you identify likely file locations.
+
+## Examples
+
+```bash
+ghgrep "useEffect(" --lang TSX,TypeScript --limit 5
+
+ghgrep "createMiddleware" --repo vercel/next.js --lang TypeScript
+
+ghgrep "try {.*await" --regexp --lang TypeScript --path src/
+
+ghgrep "z\.object\(" --regexp --lang TypeScript --json
+```

package/.xtrm/skills/default/gitnexus-debugging/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

package/.xtrm/skills/default/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```