xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/delegating/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: delegating
+description: >-
+  Proactively delegates tasks to cost-optimized agents before working in main session.
+  MUST suggest for: tests, typos, formatting, docs, refactors, code reviews, feature
+  implementation, debugging, commit validation. Skips main session token usage by routing
+  to GLM (simple/deterministic), Gemini (reasoning/analysis), Qwen (quality/patterns),
+  or multi-agent orchestration (review, feature dev, bug hunt). Never suggest for:
+  architecture decisions, security-critical code, unknown-cause bugs, performance optimization.
+allowed-tools: Bash
+---
+
+# Delegating Tasks
+
+Delegate tasks to cost-optimized models (CCS) or multi-agent orchestration workflows (Gemini/Qwen).
+
+## When to Suggest
+
+**Task Pattern → Backend Mapping** (auto-selection logic):
+
+| Task Pattern                  | Backend     | Cost   | Reason                         |
+|-------------------------------|-------------|--------|--------------------------------|
+| `typo\|test\|doc\|format`     | CCS (GLM)   | LOW    | Simple deterministic           |
+| `think\|analyze\|reason`      | CCS (Gemini)| MEDIUM | Requires reasoning             |
+| `review.*(code\|security)`    | Orchestration| HIGH   | Multi-agent code review        |
+| `implement.*feature`          | Orchestration| HIGH   | Full development workflow      |
+| `validate.*commit`            | Orchestration| MEDIUM | Security+Quality validation    |
+| `debug\|bug.*unknown`         | Orchestration| HIGH   | Root cause investigation       |
+
+**Never Suggest For:**
+- Architecture decisions requiring human judgment
+- Security-critical without review
+- Performance optimization (needs profiling first)
+
+---
+
+## Interactive Menu
+
+### Step 1: Delegation Choice
+
+Use AskUserQuestion with:
+- question: "This task can be delegated. How would you like to proceed?"
+- header: "Execution"
+- options:
+  - "Delegate (Recommended)" — Execute via optimal backend. Saves main session tokens and uses cost-efficient models.
+  - "Work in main session" — Execute in current Claude session. Better for tasks requiring discussion or complex context.
+
+**If user selects "Delegate"** → Continue to Step 2
+**If user selects "Work in main session"** → Execute task normally (don't delegate)
+
+### Step 2: Backend Selection
+
+Use AskUserQuestion with:
+- question: "Which backend should handle this task?"
+- header: "Backend"
+- options:
+  - "Auto-select (Recommended)" — Analyzes task keywords and selects optimal backend/profile automatically.
+  - "GLM - Cost-optimized" — Fast model for tests, typos, formatting [LOW COST]
+  - "Gemini - Reasoning" — Analysis, thinking, architecture tasks [MEDIUM COST]
+  - "Qwen - Quality" — Code quality, pattern detection [MEDIUM COST]
+  - "Multi-Agent Orchestration" — Direct Gemini/Qwen collaboration for complex tasks (review, feature dev, debugging) [HIGH COST]
+
+---
+
+## Auto-Selection Logic
+
+**Configuration-Driven:** All pattern matching is defined in [config.yaml](config.yaml), not hardcoded.
+
+### Configuration Structure
+
+The skill reads `config.yaml` to determine:
+1. **Available backends** (CCS profiles + Orchestration workflows)
+2. **Pattern mappings** (task keywords → backend selection)
+3. **Priority order** (Orchestration workflows checked before CCS)
+4. **Default fallback** (when no pattern matches)
+
+---
+
+## Orchestration Workflow Selection (Autonomous)
+
+When `backend: 'orchestration'` is selected, **Claude autonomously** chooses the appropriate workflow and orchestrates between `gemini` and `qwen` CLI tools.
+
+### Selection Process
+
+1. **Load config** - Read workflow definitions from `config.yaml`
+2. **Match patterns** - Determine which orchestration pattern (collaborative, handshake, troubleshoot) applies.
+3. **Execute turn protocol** - Use CLI commands sequentially:
+   - `gemini -p "..."`
+   - `qwen "..."`
+   - `gemini -r latest -p "..."` (to refine)
+
+### Turn Protocols
+
+| Workflow | Protocol |
+| :--- | :--- |
+| **handshake** | 1 turn: Agent A (Gemini) proposes -> Agent B (Qwen) validates. |
+| **collaborative** | 3 turns: Gemini designs -> Qwen critiques -> Gemini refines. |
+| **troubleshoot** | 4 turns: Gemini hypothesis -> Qwen verification -> Gemini root cause -> Final synthesis. |
+
+---
+
+## Execution Flow
+
+### For Direct Invocation (`/delegation [task]` or `/delegate [task]`)
+
+1. **Parse override flag** (if present: `--glm`, `--gemini`, `--orchestrate`, etc.)
+2. **Auto-select backend** using keyword-based logic.
+3. **Route to appropriate backend** (see sections below).
+4. **Report results**: Backend, Workflow (if Orchestration), Cost indicator, Duration.
+
+---
+
+### CCS / GLM Execution
+
+CCS wraps the `claude` CLI and **only works with GLM**. It requires a PTY for output and is blocked by the `CLAUDECODE` nested-session guard — always run via tmux:
+
+```bash
+tmux new-session -d -s ccs_task "env -u CLAUDECODE ccs glm -p '{task}' > /tmp/ccs_out.txt 2>&1"
+sleep 30  # or poll until session exits
+cat /tmp/ccs_out.txt
+```
+
+**If the task requires file modifications**, add `--dangerously-skip-permissions`:
+
+```bash
+tmux new-session -d -s ccs_task "env -u CLAUDECODE ccs glm --dangerously-skip-permissions -p '{task}' > /tmp/ccs_out.txt 2>&1"
+```
+
+---
+
+### Gemini CLI Execution
+
+Gemini is a **direct CLI** — no tmux workaround needed:
+
+```bash
+gemini -p "task description"
+```
+
+**If the task requires file modifications**, add `-y` to auto-approve all tool calls:
+
+```bash
+gemini -y -p "task description"
+```
+
+---
+
+### Qwen CLI Execution
+
+Qwen is a **direct CLI** — no tmux workaround needed:
+
+```bash
+qwen "task description"
+```
+
+**If the task requires file modifications**, add `-y` to auto-approve all tool calls:
+
+```bash
+qwen -y "task description"
+```
+
+---
+
+### Orchestration Execution
+
+Multi-turn sequences use Gemini and Qwen **direct CLIs**. Add `-y` to all turns when modifications are expected:
+
+```bash
+gemini -y -p "..."            # Turn 1
+qwen -y "..."                 # Turn 2
+gemini -y -r latest -p "..."  # Turn 3 (refine)
+```
+
+---
+
+## Examples
+
+### Auto-Selection Examples
+
+**CCS Simple:**
+- `/delegate add unit tests for UserService` → CCS (GLM)
+- `/delegate think about the best database schema` → CCS (Gemini)
+
+**Orchestration Workflows:**
+- `/delegate review this code for security issues` → Orchestration (parallel-review)
+- `/delegate implement OAuth authentication feature` → Orchestration (feature-design)
+- `/delegate debug crash on startup` → Orchestration (bug-hunt)
+
+---
+
+## Notes
+
+### Version 7.0.0 - Direct Orchestration
+- **Independent of unitAI**: Now uses direct `gemini` and `qwen` CLI calls.
+- **Unified backends**: CCS (cost-optimized) + Direct Orchestration.
+- **Config-driven**: All behavior defined in `config.yaml`.
+- **Reference**: Uses patterns from [orchestrating-agents](../orchestrating-agents/SKILL.md).

package/.xtrm/skills/default/delegating/config.yaml

@@ -0,0 +1,210 @@
+# Delegation Configuration
+# Version: 6.0.0
+# This config defines all available delegation backends and their pattern mappings.
+
+version: 1
+
+# ----------------------------------------------------------------------------
+# CCS Profiles: Cost-optimized delegation via CCS wrapper (GLM only)
+# CCS wraps the claude CLI — only GLM is supported here.
+# Execute via: tmux new-session -d ... "env -u CLAUDECODE ccs glm -p '{task}' > /tmp/out.txt 2>&1"
+# For file modifications: add --dangerously-skip-permissions flag
+# ----------------------------------------------------------------------------
+ccs_profiles:
+  glm:
+    patterns:
+      - "typo|spelling|fix.*typo"
+      - "test|unit.*test|add.*test"
+      - "doc|docstring|comment"
+      - "format|lint|prettier"
+      - "add.*type|type.*hint"
+    cost: low
+    description: "GLM-4-Flash - Fast model for tests, typos, formatting (via CCS, requires tmux)"
+
+# ----------------------------------------------------------------------------
+# Direct CLI: Gemini and Qwen are called directly — no CCS, no tmux workaround.
+# Execute via: gemini -p "{task}"  |  qwen "{task}"
+# For file modifications: add -y flag to auto-approve tool calls
+# ----------------------------------------------------------------------------
+direct_cli:
+  gemini:
+    patterns:
+      - "think|analyze|reason|evaluate"
+      - "architecture|entire|codebase"
+      - "explain|describe|how.*work"
+    cost: medium
+    description: "Gemini CLI - Reasoning and long-context analysis (gemini -p)"
+    allow_modifications_flag: "-y"
+
+  qwen:
+    patterns:
+      - "quality|pattern|convention"
+      - "refactor(?!.*sprint)|improve|optimize"
+    cost: medium
+    description: "Qwen CLI - Code quality and pattern detection (qwen)"
+    allow_modifications_flag: "-y"
+
+# ----------------------------------------------------------------------------
+# Orchestration Workflows: Direct multi-agent orchestration (Gemini + Qwen)
+# Execute via: gemini -p "{prompt}" | qwen "{prompt}"
+# ----------------------------------------------------------------------------
+orchestration_workflows:
+  parallel-review:
+    patterns:
+      - "review.*(code|security|quality)"
+      - "code.*(review|audit|quality)"
+      - "security.*(audit|review|scan)"
+      - "analyze.*code|code.*analysis"
+    cost: high
+    description: "Multi-agent code review (Gemini proposal -> Qwen critique -> Gemini refinement)"
+    pattern: collaborative  # Map to orchestration-agents patterns
+
+  feature-design:
+    patterns:
+      - "implement.*(feature|endpoint|api)"
+      - "create.*(feature|endpoint|api)"
+      - "design.*implement"
+      - "build.*feature"
+    cost: high
+    description: "Full development workflow (Gemini design -> Qwen implementation -> Gemini verification)"
+    pattern: collaborative
+
+  pre-commit-validate:
+    patterns:
+      - "validate.*(commit|staged|change)"
+      - "pre.*commit|before.*commit"
+      - "check.*staged"
+    cost: medium
+    description: "Validate staged changes (Gemini secrets check -> Qwen quality check)"
+    pattern: handshake
+
+  bug-hunt:
+    patterns:
+      - "debug|investigate.*bug"
+      - "bug|crash|error"
+      - "fix.*unknown|unknown.*error"
+      - "root.*cause"
+    cost: high
+    description: "Root cause analysis (Gemini hypothesis -> Qwen verification -> Gemini remediation)"
+    pattern: troubleshoot
+
+  refactor-sprint:
+    patterns:
+      - "refactor.*sprint"
+      - "major.*refactor"
+      - "migrate|migration"
+      - "technical.*debt"
+    cost: high
+    description: "Large-scale refactoring coordination (Gemini plan -> Qwen execution)"
+    pattern: collaborative
+
+  validate-last-commit:
+    patterns:
+      - "validate.*commit(?!.*staged)"
+      - "check.*last.*commit"
+      - "review.*commit"
+    cost: medium
+    description: "Post-commit validation (Gemini quality check -> Qwen security check)"
+    pattern: handshake
+
+# ----------------------------------------------------------------------------
+# Pattern Priority: Higher priority checked first
+# ----------------------------------------------------------------------------
+priority:
+  - orchestration_workflows  # Complex multi-agent tasks first
+  - direct_cli               # Gemini/Qwen direct CLIs second
+  - ccs_profiles             # GLM via CCS last (lowest cost)
+
+# ----------------------------------------------------------------------------
+# Default Backend: Used when no pattern matches
+# ----------------------------------------------------------------------------
+default:
+  backend: ccs
+  profile: glm
+  reason: "Default cost-optimized execution"
+
+# ----------------------------------------------------------------------------
+# Exclusions: Never auto-suggest delegation for these patterns
+# User can still manually invoke /delegation, but no auto-suggestion
+# ----------------------------------------------------------------------------
+exclusions:
+  - "architecture.*decision|design.*decision"
+  - "security.*critical|auth.*implementation"
+  - "performance.*optimize|optimize.*performance"
+  - "breaking.*change|migrate.*breaking"
+
+# ----------------------------------------------------------------------------
+# Auto-Focus Detection: Map keywords to workflow focus parameters
+# Used for workflows with "focus: auto" parameter
+# ----------------------------------------------------------------------------
+auto_focus:
+  security:
+    keywords: ["security", "vulnerability", "xss", "sql", "injection", "auth"]
+    workflow_params:
+      parallel-review:
+        focus: security
+
+  performance:
+    keywords: ["performance", "slow", "optimize", "speed", "memory", "leak"]
+    workflow_params:
+      parallel-review:
+        focus: performance
+      feature-design:
+        architecturalFocus: performance
+
+  quality:
+    keywords: ["quality", "maintainability", "readability", "clean"]
+    workflow_params:
+      parallel-review:
+        focus: quality
+      feature-design:
+        architecturalFocus: maintainability
+
+# ----------------------------------------------------------------------------
+# Override Flags: Command-line overrides
+# Example: /delegation --glm [task] → Force CCS GLM profile
+# Example: /delegation --unitai [task] → Force unitAI (auto-select workflow)
+# ----------------------------------------------------------------------------
+override_flags:
+  # CCS profile override (GLM only)
+  - flag: "--glm"
+    backend: ccs
+    profile: glm
+
+  # Direct CLI overrides
+  - flag: "--gemini"
+    backend: direct_cli
+    profile: gemini
+
+  - flag: "--qwen"
+    backend: direct_cli
+    profile: qwen
+
+  # unitAI workflow overrides
+  - flag: "--unitai"
+    backend: unitai
+    workflow: auto  # Claude selects appropriate workflow
+
+  - flag: "--review"
+    backend: unitai
+    workflow: parallel-review
+
+  - flag: "--feature"
+    backend: unitai
+    workflow: feature-design
+
+  - flag: "--validate"
+    backend: unitai
+    workflow: pre-commit-validate
+
+  - flag: "--debug"
+    backend: unitai
+    workflow: bug-hunt
+
+# ----------------------------------------------------------------------------
+# Notes
+# - Patterns are evaluated as regex (case-insensitive)
+# - First matching pattern wins (respects priority order)
+# - If no pattern matches, uses default backend
+# - Override flags take precedence over auto-selection
+# ----------------------------------------------------------------------------

package/.xtrm/skills/default/delegating/references/orchestration-protocols.md

@@ -0,0 +1,41 @@
+# Multi-Agent Orchestration Protocols
+
+This reference defines how the `delegating` skill orchestrates between Gemini and Qwen agents for complex tasks.
+
+## Protocol 1: Single Handshake (`handshake`)
+**Use Case**: Quick validation, code review, or security check.
+
+1. **Step 1 (Gemini)**: `gemini -p "Analyze this code for security vulnerabilities: [CODE]"`
+2. **Step 2 (Qwen)**: `qwen "Review the vulnerabilities identified by Gemini and suggest specific fixes: [GEMINI_OUTPUT]"`
+3. **Synthesis**: Present Qwen's final review to the user.
+
+## Protocol 2: Collaborative Design (`collaborative`)
+**Use Case**: Feature implementation, architecture planning, or major refactoring.
+
+1. **Step 1 (Gemini - Design)**: `gemini -p "Design a new [FEATURE] based on these requirements: [REQ]"`
+2. **Step 2 (Qwen - Implementation)**: `qwen "Implement the design provided by Gemini: [GEMINI_OUTPUT]"`
+3. **Step 3 (Gemini - Verification)**: `gemini -r latest -p "Verify that the implementation from Qwen meets all original requirements: [QWEN_OUTPUT]"`
+4. **Final Result**: Present the implementation and verification to the user.
+
+## Protocol 3: Troubleshoot Session (`troubleshoot`)
+**Use Case**: Complex debugging, root cause analysis, or emergency production errors.
+
+1. **Step 1 (Gemini - Hypothesis)**: `gemini -p "Analyze these logs and provide 3 hypotheses for the crash: [LOGS]"`
+2. **Step 2 (Qwen - Verification)**: `qwen "Verify Hypothesis #1 using the provided source code: [HYPOTHESIS_1] [CODE]"`
+3. **Step 3 (Gemini - Root Cause)**: `gemini -r latest -p "Based on Qwen's verification, provide the final root cause and a remediation plan."`
+4. **Remediation**: Present the final fix to the user.
+
+## CLI Command Reference
+
+### Gemini
+- **Initial**: `gemini -p "PROMPT"`
+- **Resume**: `gemini -r latest -p "FOLLOW_UP"`
+
+### Qwen
+- **Initial**: `qwen "PROMPT"`
+- **Continue**: `qwen -c "FOLLOW_UP"`
+
+## Best Practices
+- **Minimal Context**: Only send the necessary snippets to avoid hitting token limits in the handoff.
+- **Structured Prompts**: Use clear, instruction-heavy prompts for the second agent.
+- **Final Review**: Always synthesize the final multi-agent output before presenting it to the user.

package/.xtrm/skills/default/documenting/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- CHANGELOG.md management scripts (init, add_entry, bump_release, validate)
+- Documentation orchestrator for coordinated updates
+- Keep a Changelog 1.0.0 strict validation
+- Integration test suite
+
+
+### Changed
+- Extended SKILL.md with new workflows
+- Updated README with comprehensive guide
+## [2.0.0] - 2026-02-01
+
+### Added
+- Initial release

package/.xtrm/skills/default/documenting/README.md

@@ -0,0 +1,148 @@
+# Documenting Skill
+
+Comprehensive documentation management for projects using:
+- **Serena SSOT** (.serena/memories/)
+- **CHANGELOG.md** (Keep a Changelog format)
+- **README.md**
+- **CLAUDE.md / AGENT.md**
+
+## Quick Start
+
+### Initialize Project Documentation
+
+```bash
+# Create CHANGELOG.md
+python3 scripts/changelog/init_changelog.py ./CHANGELOG.md
+
+# Create .serena/memories directory
+mkdir -p .serena/memories
+```
+
+### Document a Change
+
+**Using Orchestrator (Recommended)**:
+
+```bash
+python3 scripts/orchestrator.py . feature "Add new search feature" \
+  --scope=search \
+  --category=backend
+```
+
+**Manual Workflow**:
+
+1. Update CHANGELOG:
+   ```bash
+   python3 scripts/changelog/add_entry.py CHANGELOG.md Added "New feature"
+   ```
+
+2. Create SSOT (if needed):
+   ```bash
+   python3 scripts/generate_template.py ssot .serena/memories/ssot_search_engine_2026-02-01.md \
+     title="Search Engine SSOT" \
+     scope="search-engine" \
+     domain="backend"
+   ```
+
+3. Update README.md and CLAUDE.md manually
+
+4. Validate:
+   ```bash
+   python3 scripts/changelog/validate_changelog.py CHANGELOG.md
+   python3 scripts/validate_metadata.py .serena/memories/ssot_*.md
+   ```
+
+### Release a Version
+
+```bash
+# Bump CHANGELOG
+python3 scripts/changelog/bump_release.py CHANGELOG.md 1.2.0
+
+# Validate
+python3 scripts/changelog/validate_changelog.py CHANGELOG.md
+
+# Commit and tag
+git add CHANGELOG.md
+git commit -m "chore: release v1.2.0"
+git tag -a v1.2.0 -m "Release 1.2.0"
+```
+
+## Scripts Reference
+
+### CHANGELOG Management
+
+| Script | Purpose | Example |
+|--------|---------|---------|
+| `init_changelog.py` | Create new CHANGELOG.md | `init_changelog.py ./CHANGELOG.md` |
+| `add_entry.py` | Add entry to [Unreleased] | `add_entry.py CHANGELOG.md Added "Feature X"` |
+| `bump_release.py` | Release new version | `bump_release.py CHANGELOG.md 1.2.0` |
+| `validate_changelog.py` | Validate format | `validate_changelog.py CHANGELOG.md` |
+
+### SSOT Management
+
+| Script | Purpose | Example |
+|--------|---------|---------|
+| `generate_template.py` | Create new SSOT | `generate_template.py ssot file.md title="X"` |
+| `validate_metadata.py` | Validate SSOT metadata | `validate_metadata.py file.md` |
+| `bump_version.sh` | Calculate next version | `bump_version.sh 1.0.0 patch` |
+
+### Orchestration
+
+| Script | Purpose | Example |
+|--------|---------|---------|
+| `orchestrator.py` | Coordinate all docs | `orchestrator.py . feature "X"` |
+
+## File Structure
+
+```
+~/.claude/skills/documenting/
+├── SKILL.md                      # Skill definition
+├── README.md                     # This file
+├── scripts/
+│   ├── changelog/
+│   │   ├── init_changelog.py    # Create CHANGELOG
+│   │   ├── add_entry.py         # Add entries
+│   │   ├── bump_release.py      # Release versions
+│   │   └── validate_changelog.py # Validate format
+│   ├── orchestrator.py          # Coordination
+│   ├── generate_template.py     # SSOT templates
+│   ├── validate_metadata.py     # SSOT validation
+│   └── bump_version.sh          # Version bumping
+├── templates/
+│   └── CHANGELOG.md.template    # CHANGELOG template
+├── references/
+│   ├── metadata-schema.md       # SSOT schema
+│   ├── changelog-format.md      # Keep a Changelog guide
+│   └── taxonomy.md              # SSOT taxonomy
+└── tests/
+    ├── test_changelog.py        # CHANGELOG tests
+    └── test_orchestrator.py     # Orchestrator tests
+```
+
+## Change Type Guide
+
+- **feature**: New functionality → CHANGELOG: Added
+- **bugfix**: Bug fixes → CHANGELOG: Fixed
+- **refactor**: Code restructuring → CHANGELOG: Changed
+- **breaking**: Breaking changes → CHANGELOG: Changed (with **BREAKING** prefix)
+- **docs**: Documentation → CHANGELOG: Changed
+- **chore**: Maintenance → CHANGELOG: Changed
+
+## Validation
+
+All scripts validate before modifying files:
+- CHANGELOG: Keep a Changelog 1.0.0 format
+- SSOT: Serena metadata schema
+- Versions: Semantic Versioning 2.0.0
+
+## Testing
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Test specific module
+python -m pytest tests/test_changelog.py -v
+
+# Integration test
+bash tests/integration_test.sh
+```