xtrm-tools 2.0.0

package/skills/orchestrating-agents/references/agent-context-integration.md

@@ -0,0 +1,37 @@
+# AgentContext Integration
+
+To ensure the response from another agent is correctly ingested by the primary agent, use the `AgentContext` pattern.
+
+## Using `AgentContext`
+
+The `AgentContext` class (located in `hooks/agent_context.py`) provides a unified way to inject `additionalContext` into the agent's reasoning.
+
+### Workflow
+
+1. **Capture Output:** Run the target agent's command and capture stdout to a temporary file.
+   ```bash
+   gemini -p "Analyze this code..." > agent_review.log
+   ```
+
+2. **Inject via Hook:** A hook script can then use `AgentContext` to read this log and provide it back to the primary agent.
+
+### Python Example
+
+```python
+from hooks.agent_context import AgentContext
+
+ctx = AgentContext()
+with open("agent_review.log", "r") as f:
+    review_content = f.read()
+
+ctx.allow(
+    system_message="Review from Gemini agent ingested.",
+    additional_context=f"The other agent provided the following review:
+
+{review_content}"
+)
+```
+
+## Progressive Disclosure
+
+Do not load this entire reference unless the agent is actively setting up a hook or needs detailed implementation specifics for `AgentContext`.

package/skills/orchestrating-agents/references/examples.md

@@ -0,0 +1,45 @@
+# Handshake Examples
+
+These examples demonstrate the correct syntax and flow for orchestrating handshakes between agents.
+
+## Example 1: Code Review Handshake (Qwen)
+
+**Phase 1: Initial Proposal**
+```bash
+qwen "Review the security of this session handling logic: $(cat lib/auth.js)" > review_proposal.txt
+```
+
+**Phase 2: Refinement (Handshake)**
+```bash
+qwen -c "The previous review mentioned a potential race condition. Can you provide a specific code fix for that?" > review_fix.txt
+```
+
+## Example 2: Architecture Discussion (Gemini)
+
+**Phase 1: Initial Proposal**
+```bash
+gemini -p "Analyze the dependency graph for our new 'orchestrating-agents' skill." > arch_proposal.txt
+```
+
+**Phase 2: Refinement (Handshake)**
+```bash
+gemini --resume latest -p "Now, suggest how we could integrate this with the 'delegating' skill without creating a circular dependency." > arch_refinement.txt
+```
+
+## Example 3: Integration via AgentContext
+
+**Ingestion Workflow**
+```python
+from hooks.agent_context import AgentContext
+
+ctx = AgentContext()
+with open("review_fix.txt", "r") as f:
+    content = f.read()
+
+ctx.allow(
+    system_message="Qwen's suggested fix ingested.",
+    additional_context=f"Qwen provided this specific fix:
+
+{content}"
+)
+```

package/skills/orchestrating-agents/references/handover-protocol.md

@@ -0,0 +1,31 @@
+# Handover Protocol
+
+This protocol defines how to "hand off" a task to another agent for a second opinion or specialized review.
+
+## Headless Execution
+
+To interact with other agents without blocking the current session, use headless commands.
+
+### Gemini
+- **Initial Query:** `gemini -p "Your prompt here"`
+- **Follow-up (Resume):** `gemini -r latest -p "Your follow-up here"`
+  - `-r latest` resumes the most recent session
+  - `-r 5` resumes session index 5 (use `gemini --list-sessions` to see available sessions)
+
+### Qwen
+- **Initial Query:** `qwen "Your prompt here"`
+- **Follow-up (Continue):** `qwen -c "Your follow-up here"`
+- **Note:** Qwen uses positional prompts. The `-c` flag automatically resumes the most recent session for the current project.
+
+## Handshaking Strategies
+
+### 1. Standard (2-Phase)
+1. **Proposal**: Send initial context and question to the target agent.
+2. **Refinement**: Use `-r latest` (Gemini) or `-c` (Qwen) to ask for specific corrections or clarifications.
+
+### 2. Deep (Multi-Turn)
+Used for "Design," "Bug Hunt," and "Troubleshoot" workflows.
+1. **Agent A (Draft)**: Request an initial solution or hypothesis.
+2. **Agent B (Audit)**: Pass Agent A's output to Agent B for critique.
+3. **Agent A (Iterate)**: Resume Agent A's session with Agent B's critique using `-r latest` or `-c`.
+4. **Final Synthesis**: Ingest the final result using `AgentContext`.

package/skills/orchestrating-agents/references/workflows.md

@@ -0,0 +1,42 @@
+# Multi-Turn Orchestration Workflows
+
+These workflows define deep, multi-turn interactions between agents for complex scenarios.
+
+## 1. Collaborative Design (`collaborative-design`)
+**Scenario**: Building a new feature or architecting a component.
+
+| Turn | Agent | Action |
+| :--- | :--- | :--- |
+| **1** | **Primary** | Send requirements and initial constraints to Agent A. |
+| **2** | **Agent A** | Propose a high-level design. |
+| **3** | **Primary** | Pipe Agent A's proposal to Agent B. |
+| **4** | **Agent B** | Critique the design for edge cases and complexity. |
+| **5** | **Primary** | Return Agent B's critique to Agent A via `-r latest` (Gemini) or `-c` (Qwen). |
+| **6** | **Agent A** | Refine the design to address critiques. |
+
+## 2. Adversarial Review (`adversarial-review`)
+**Scenario**: Security audits, "red teaming," or finding hidden flaws.
+
+| Turn | Agent | Action |
+| :--- | :--- | :--- |
+| **1** | **Primary** | Send the code/logic to Agent A for a "safe" review. |
+| **2** | **Agent B** | Act as a "Skeptic/Attacker": "Find 3 ways to break this logic." |
+| **3** | **Primary** | Pipe "attacks" to Agent A via `-r latest` (Gemini) or `-c` (Qwen). |
+| **4** | **Agent A** | Defend the logic or provide patches for the identified flaws. |
+
+## 3. Troubleshoot Session (`troubleshoot-session`)
+**Scenario**: "Getting out of trouble," emergency production errors, or ghost bugs.
+
+| Turn | Agent | Action |
+| :--- | :--- | :--- |
+| **1** | **Primary** | Provide symptoms to Agent A and ask for 3 hypotheses. |
+| **2** | **Agent A** | Propose hypotheses and verification steps. |
+| **3** | **Primary** | Ask Agent B to verify Hypothesis #1 using current logs/code. |
+| **4** | **Agent B** | Provide verification result (Confirmed/Refuted). |
+| **5** | **Primary** | Update Agent A with the findings and ask for the final root cause. |
+
+## Automatic Triggering
+The primary agent should suggest these workflows when:
+- **Complexity is high**: Changes affecting >3 files or core infrastructure.
+- **Risk is high**: Security, authentication, or payment logic.
+- **Agent is "stuck"**: When a single-agent approach fails to find a bug.

package/skills/orchestrating-agents/scripts/detect_neighbors.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+import shutil
+import json
+import sys
+
+def check_command(cmd):
+    return shutil.which(cmd) is not None
+
+def main():
+    agents = ["gemini", "qwen"]
+    found = {agent: check_command(agent) for agent in agents}
+    
+    if any(found.values()):
+        print("Available Agents:")
+        for agent, is_available in found.items():
+            status = "AVAILABLE" if is_available else "NOT FOUND"
+            print(f"- {agent}: {status}")
+    else:
+        print("No neighboring agents (gemini, qwen) found in PATH.")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/skills/prompt-improving/README.md

@@ -0,0 +1,162 @@
+# prompt-improving
+
+Automatically improves user prompts using Claude's XML best practices before execution.
+
+## Purpose
+
+Transforms raw, unstructured prompts into well-formatted requests that leverage Claude's capabilities more effectively. Applies semantic XML tags, multishot examples, chain-of-thought reasoning, and contextual structure based on task type.
+
+## Invocation
+
+```
+/prompt-improving "raw prompt text"
+```
+
+The skill analyzes the input prompt and enhances it with:
+- Semantic XML structure
+- Relevant examples from reference library
+- Chain-of-thought scaffolding
+- Context-appropriate formatting
+
+## Associated Hooks
+
+**skill-suggestion.sh**
+
+Proactively suggests using `/prompt-improving` when detecting:
+- Very short prompts (less than 35 characters)
+- Generic requests without specificity
+- Analysis or explanation tasks
+- Prompts in Italian or English
+
+Configuration in `~/.claude/settings.json`:
+```json
+{
+  "skillSuggestions": {
+    "enabled": true
+  }
+}
+```
+
+## Execution Flow
+
+1. **Detect Context**: Analyze prompt for task type (analysis, development, refactoring)
+2. **Apply Core XML**: Structure prompt with semantic tags from reference library
+3. **Add Examples**: Include multishot examples when beneficial
+4. **Handle Ambiguity**: If prompt is very vague, use AskUserQuestion dialog to clarify intent
+5. **Execute Improved**: Run the enhanced prompt through Claude
+
+## Reference Files
+
+The skill uses these reference documents to inform improvements:
+
+- `xml_core.md` - Semantic XML tags and prefill patterns
+- `multishot.md` - Example-based learning patterns
+- `chain_of_thought.md` - Reasoning scaffolds
+- `mcp_definitions.md` - MCP-specific structures
+- `analysis_commands.md` - Analysis task patterns
+
+## Configuration
+
+No additional configuration required beyond hook setup.
+
+## Examples
+
+### Example 1: Short Analysis Prompt
+
+**Before:**
+```
+analyze logs
+```
+
+**After:**
+```xml
+<log_analysis>
+  <thinking>
+    To analyze the logs effectively, I should:
+    1. Identify error patterns
+    2. Check timestamps for incident correlation
+    3. Look for system warnings
+    4. Summarize critical issues
+  </thinking>
+  <description>Analyze application logs for errors and issues</description>
+  <constraints>
+    - Focus on ERROR and WARN level entries
+    - Provide actionable recommendations
+  </constraints>
+</log_analysis>
+```
+
+### Example 2: Development Task
+
+**Before:**
+```
+implement oauth
+```
+
+**After:**
+```xml
+<implementation>
+  <description>Implement OAuth 2.0 authentication</description>
+  <parameters>
+    <param name="flow">Authorization Code flow with PKCE</param>
+    <param name="provider">To be specified</param>
+  </parameters>
+  <examples>
+    <example>Standard OAuth flow with JWT tokens</example>
+  </examples>
+  <instructions>
+    1. Setup OAuth client configuration
+    2. Implement authorization endpoint
+    3. Handle token exchange
+    4. Validate and refresh tokens
+  </instructions>
+  <constraints>
+    - Follow OAuth 2.0 security best practices
+    - Use HTTPS for all endpoints
+    - Implement proper CSRF protection
+  </constraints>
+</implementation>
+```
+
+## Ambiguity Handling
+
+When the prompt is too vague (less than 8 words, no specifics), the skill presents an interactive dialog:
+
+```
+Clarify: The prompt is ambiguous. What would you like me to focus on?
+
+Options:
+1. Add more detail - I'll provide more context
+2. Execute as-is - Apply basic XML structure and proceed
+3. Cancel - Skip prompt improvement
+```
+
+## Version History
+
+- **v5.1.0** (2026-01-30): Renamed from `p` to `prompt-improving` following Claude naming conventions
+- **v5.0.0** (2026-01-30): Simplified from 118 to 64 lines, removed complex quality metrics
+- **v4.2.0** (Pre-2026): Original feature-rich version with detailed scoring
+
+## Related Documentation
+
+- [Main README](../../README.md)
+- [CHANGELOG](../../CHANGELOG.md)
+- [ROADMAP](../../ROADMAP.md) - See Programmatic Tool Calling integration plans
+- [Hook Documentation](../../hooks/README.md)
+
+## Troubleshooting
+
+**Skill not triggering**
+- Verify skill directory is in `~/.claude/skills/`
+- Check SKILL.md frontmatter has correct name
+- Restart Claude Code if recently installed
+
+**No suggestions from hook**
+- Check `settings.json` has `skillSuggestions.enabled: true`
+- Verify `skill-suggestion.sh` is executable
+- Check hook timeout is sufficient (default: 1s)
+
+**Prompts not being improved**
+- Try explicit invocation: `/prompt-improving "your prompt"`
+- Check reference files exist in `references/` directory
+- Verify no errors in Claude Code console

package/skills/prompt-improving/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: prompt-improving
+description: 'Prompt Improver (Trigger: /prompt-improving "raw prompt"). Applies Claude XML best practices to user prompts before execution. Use when the user specifically invokes /prompt-improving.'
+gemini-command: prompt
+gemini-prompt: |
+  1. Detect context: ANALYSIS (thinking), DEV (examples), or REFACTOR (constraints).
+  2. Apply core XML tags (<description>, <parameters>, <instructions>).
+  3. Add enhancements (Chain of Thought, Multishot examples) based on context.
+  4. Execute ONLY the improved prompt version.
+---
+
+# Prompt Improver ( /prompt-improving )
+
+Automatically improves raw prompts using Claude's XML best practices (semantic tags, multishot examples, chain-of-thought) and then executes the improved version.
+
+## When to Use
+
+**Trigger:** User types `/prompt-improving "raw prompt"` or `/prompt-improving <raw prompt>`
+
+## Execution Flow
+
+1.  **Detect Context:**
+    *   Scan prompt for task type keywords
+    *   **ANALYSIS** (contains: analyze, investigate, research) → needs thinking space
+    *   **DEV** (contains: implement, create, build, add) → needs examples
+    *   **REFACTOR** (contains: refactor, improve, optimize) → needs constraints
+
+2.  **Apply Core XML:**
+    *   Consult [references/xml_core.md](references/xml_core.md)
+    *   Wrap the prompt in a semantic root tag (e.g., `<task_name>`)
+    *   Use tags like `<description>`, `<parameters>`, `<instructions>` by default
+
+3.  **Add Context-Specific Enhancements:**
+    *   **ANALYSIS tasks:**
+        *   Consult [references/chain_of_thought.md](references/chain_of_thought.md)
+        *   Add `<thinking>` section with prefill
+        *   Define structured `<outputs>`
+    *   **DEV tasks:**
+        *   Consult [references/multishot.md](references/multishot.md)
+        *   Add 1-2 `<example>` blocks
+    *   **REFACTOR tasks:**
+        *   Add `<constraints>` section (preserve behavior, tests must pass)
+        *   Add `<current_state>` context if helpful
+
+4.  **Handle Ambiguity:**
+    *   If prompt is very vague (<8 words, no specifics)
+    *   Use **AskUserQuestion** to clarify:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Clarify",
+    question: "The prompt is ambiguous. What would you like me to focus on?",
+    multiSelect: false,
+    options: [
+      { label: "Add more detail", description: "I'll provide more context" },
+      { label: "Execute as-is", description: "Apply basic XML structure and proceed" },
+      { label: "Cancel", description: "Skip prompt improvement" }
+    ]
+  }]
+});
+```
+
+5.  **Execute:**
+    *   **EXECUTE ONLY THE IMPROVED PROMPT.**
+    *   Act as if the user entered the improved XML prompt directly.
+
+## Reference Library
+
+*   **Core XML:** [references/xml_core.md](references/xml_core.md) - Basic XML structure and semantic tags
+*   **Multishot:** [references/multishot.md](references/multishot.md) - Adding concrete examples
+*   **Chain of Thought:** [references/chain_of_thought.md](references/chain_of_thought.md) - Thinking space for analysis
+*   **Tool Definitions:** [references/mcp_definitions.md](references/mcp_definitions.md) - MCP tool structure
+*   **Analysis Frameworks:** [references/analysis_commands.md](references/analysis_commands.md) - Structured analysis

package/skills/prompt-improving/references/analysis_commands.md

@@ -0,0 +1,24 @@
+# Analysis Frameworks
+
+## When to Use
+When the user wants to perform a deep dive analysis (e.g., "analyze employment data", "review logs").
+
+## Structure
+```xml
+<analysis_task>
+  <requirements>
+    <data>Required inputs.</data>
+    <format>Input format.</format>
+  </requirements>
+  <instructions>
+    1. Step 1
+    2. Step 2
+  </instructions>
+  <outputs>
+    <output_1>Executive Summary</output_1>
+    <output_2>Detailed Findings</output_2>
+  </outputs>
+  <!-- Always include CoT for analysis -->
+  <thinking>...</thinking>
+</analysis_task>
+```

package/skills/prompt-improving/references/chain_of_thought.md

@@ -0,0 +1,24 @@
+# Chain of Thought (CoT)
+
+## When to Use
+Use for analysis, research, complex decisions, multi-step tasks, or mathematical calculations.
+
+## Core Principle
+Give the model space to think step-by-step before the final answer.
+
+## Levels
+1. **Basic:** "Think step-by-step."
+2. **Structured:** Use `<thinking>` tags before `<analysis>` or `<answer>`.
+
+## Template
+```xml
+<thinking>
+Step 1: Evaluate inputs.
+Step 2: Identify patterns.
+Step 3: Formulate conclusion.
+</thinking>
+
+<analysis>
+Detailed output based on thinking.
+</analysis>
+```

package/skills/prompt-improving/references/mcp_definitions.md

@@ -0,0 +1,20 @@
+# MCP Tool Definitions
+
+## When to Use
+When the user wants to define a new tool, function, or API capability.
+
+## Structure
+```xml
+<tool_definition>
+  <description>One-line summary.</description>
+  <purpose>Extended explanation.</purpose>
+  <parameters>
+    <param name="arg1">Type, default, description.</param>
+  </parameters>
+  <returns>Structure of return value.</returns>
+  <constraints>Rules and limits.</constraints>
+  <examples>
+    <!-- Multishot examples here -->
+  </examples>
+</tool_definition>
+```

package/skills/prompt-improving/references/multishot.md

@@ -0,0 +1,23 @@
+# Multishot Prompting
+
+## When to Use
+Use for complex tasks, structured outputs, edge cases, or tool definitions.
+
+## Core Principle
+Provide 3-5 diverse, relevant examples to show exactly what is desired.
+
+## Best Practices
+1. **Relevance:** Mirror actual use cases.
+2. **Diversity:** Include basic, complex, and edge cases.
+3. **Structure:** Wrap in `<example>` tags.
+
+## Template
+```xml
+<examples>
+  <example>
+    <input>Scenario description</input>
+    <output>Expected result</output>
+    <explanation>Why this is correct</explanation>
+  </example>
+</examples>
+```

package/skills/prompt-improving/references/xml_core.md

@@ -0,0 +1,60 @@
+# XML Tags for Clarity & Structure
+
+## Core Principle
+Use semantic XML tags to structure information hierarchically. Tags should make sense contextually and improve readability. This is the **default** format for all improved prompts.
+
+## Common Tags
+| Tag                | Purpose                    |
+| ------------------ | -------------------------- |
+| `<description>`    | High-level overview        |
+| `<parameters>`     | Input arguments            |
+| `<examples>`       | Concrete usage             |
+| `<instructions>`   | How to perform task        |
+| `<constraints>`    | Limitations & requirements |
+| `<thinking>`       | Internal reasoning         |
+| `<analysis>`       | Detailed examination       |
+| `<recommendation>` | Suggested action           |
+
+## Structure Template
+```xml
+<root_description>
+  <description>One-line summary.</description>
+  <parameters>
+    <param name="p1">Description.</param>
+  </parameters>
+  <instructions>Step-by-step guidance.</instructions>
+</root_description>
+```
+
+## Common Prefill Patterns
+
+### Analysis Tasks
+```xml
+<analysis>
+  <thinking>Let me break down the problem...</thinking>
+  <examination>Key aspects to consider...</examination>
+  <findings>Based on the analysis...</findings>
+  <recommendation>Suggested approach...</recommendation>
+</analysis>
+```
+
+### Code Generation
+```xml
+<implementation>
+  <approach>High-level strategy...</approach>
+  <code>
+    // Implementation
+  </code>
+  <testing>Verification steps...</testing>
+</implementation>
+```
+
+### Assistant Responses
+```xml
+<response>
+  <summary>Quick answer for context.</summary>
+  <detailed_explanation>In-depth reasoning...</detailed_explanation>
+  <examples>Concrete cases...</examples>
+  <next_steps>What to do next...</next_steps>
+</response>
+```