@softspark/ai-toolkit 1.0.0

package/app/skills/rag-patterns/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: rag-patterns
+description: "Loaded when user asks about RAG systems, embeddings, or vector search"
+effort: medium
+user-invocable: false
+---
+
+# RAG Patterns Skill
+
+## Core Patterns
+
+### 1. Hybrid Search
+Combine dense (vector) and sparse (BM25) retrieval with RRF fusion:
+
+```python
+# RAG-MCP hybrid search
+result = await hybrid_search_kb(
+    query="rate limiting configuration",
+    service="nginx",
+    limit=10
+)
+```
+
+### 2. Corrective RAG (CRAG)
+Self-correcting retrieval with relevance validation:
+
+```python
+result = await crag_search(
+    query="fuzzy query",
+    relevance_threshold=0.4,
+    max_retries=2
+)
+
+# Or via smart_query
+result = await smart_query(query="...", use_crag=True)
+```
+
+### 3. HyDE (Hypothetical Document Embeddings)
+Generate hypothetical answers for better retrieval on conceptual queries:
+
+```python
+result = await smart_query(
+    query="conceptual question about design patterns",
+    use_hyde=True
+)
+```
+
+### 4. Multi-hop Retrieval
+Complex queries requiring multiple retrieval steps:
+
+```python
+result = await multi_hop_search(
+    query="Compare nginx with varnish for Magento cache",
+    max_hops=3
+)
+
+# Or via smart_query
+result = await smart_query(query="compare A vs B", use_multi_hop=True)
+```
+
+---
+
+## Indexing Best Practices
+
+| Aspect | Recommendation |
+|--------|----------------|
+| Chunk size | 512-1024 tokens |
+| Overlap | 10-20% of chunk |
+| Structure | Preserve headers, sections |
+| Metadata | Include title, path, date, category, tags |
+| Frontmatter | YAML with standardized fields |
+
+### Frontmatter Template
+```yaml
+---
+title: "Document Title"
+service: {project-name}
+category: reference|howto|procedures|troubleshooting|decisions|best-practices
+tags: [tag1, tag2, tag3]
+last_updated: "YYYY-MM-DD"
+---
+```
+
+---
+
+## MCP Tools Reference (v5.5.0)
+
+| Tool | Use Case | Speed |
+|------|----------|-------|
+| `smart_query` ⭐ | Default for 90% of queries | 2-4s |
+| `hybrid_search_kb` | Raw vector + text search | <1s |
+| `get_document` | Full document content | <1s |
+| `crag_search` | Vague/fuzzy queries | 1-3s |
+| `multi_hop_search` | Complex reasoning | 20-30s |
+
+### Tool Selection Guide
+
+```python
+# Default - auto-routing
+smart_query("specific technical question")
+
+# Vague query - self-correcting
+crag_search("jak to skonfigurować")
+
+# Complex comparison
+multi_hop_search("nginx vs varnish performance comparison")
+
+# Known document
+get_document(path="kb/reference/architecture.md")
+```
+
+---
+
+## Quality Metrics
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| Faithfulness | Answer based on context | >70% |
+| Relevancy | Answer addresses question | >70% |
+| Context Precision | Found context is accurate | >60% |
+| Latency (p95) | Response time | <2s |
+| Precision@k | Relevant results in top-k | >80% |
+
+---
+
+## Retrieval Optimization
+
+### Reranking
+```python
+# Retrieve more, rerank to top-k
+initial_results = await hybrid_search_kb(query, limit=20)
+reranked = rerank_results(initial_results, query)
+final_results = reranked[:5]
+```
+
+### Context Window Management
+- Place critical info at start/end (serial position effect)
+- Summarize long documents before insertion
+- Use tiered context: critical → supporting → background
+
+### Query Enhancement
+- Query expansion with synonyms
+- Query decomposition for complex questions
+- Entity extraction for filtering
+
+---
+
+## Anti-Patterns
+
+❌ **Don't**:
+- Skip reranking for final results
+- Use very large chunks (>2000 tokens)
+- Ignore metadata in retrieval
+- Trust LLM output without citation
+- Use `latest` for model versions
+
+✅ **Do**:
+- Use top-k=20 → rerank → top-5
+- Chunk semantically (by section)
+- Enrich metadata at indexing time
+- Require source attribution in answers
+- Pin model versions for reproducibility
+
+---
+
+## RAG System Implementation
+
+### Key Files (Typical Structure)
+```
+scripts/
+├── search_core.py           # Core search
+├── query_enhancements.py    # HyDE, query expansion
+├── corrective_rag.py        # CRAG
+├── multi_hop.py             # Multi-hop
+├── unified_indexer.py       # Indexing
+└── rag_evaluator.py         # Evaluation
+```
+
+### Running RAG Commands
+
+**Direct execution:**
+```bash
+# Index KB
+make index
+
+# Evaluate RAG
+python scripts/evaluate_rag.py
+
+# Detect gaps
+python scripts/knowledge_gaps.py --detect
+```
+
+**Docker execution (if containerized):**
+```bash
+# Index KB
+docker exec {app-container} make index
+
+# Evaluate RAG
+docker exec {api-container} python3 scripts/evaluate_rag.py
+
+# Detect gaps
+docker exec {api-container} python3 scripts/knowledge_gaps.py --detect
+```

package/app/skills/refactor/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: refactor
+description: "Refactor code for quality and maintainability"
+user-invocable: true
+effort: high
+argument-hint: "[target and goal]"
+agent: code-reviewer
+context: fork
+allowed-tools: Read, Edit, Grep, Glob, Bash
+---
+
+# Refactor Code
+
+$ARGUMENTS
+
+Plan and execute code refactoring.
+
+## Usage
+
+```
+/refactor [target] [--pattern=<pattern>]
+```
+
+## What This Command Does
+
+1. **Analyzes** target code
+2. **Identifies** refactoring opportunities
+3. **Plans** refactoring steps
+4. **Executes** with user approval
+
+## Refactoring Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| `extract-function` | Extract code block to function |
+| `extract-component` | Extract UI component |
+| `rename` | Rename symbol across codebase |
+| `move` | Move code to better location |
+| `inline` | Inline unnecessary abstraction |
+| `simplify` | Simplify complex logic |
+
+## Safety Rules
+
+- Run tests before refactoring
+- Make atomic commits
+- Preserve behavior (no feature changes)
+- Run tests after each step
+- Don't mix refactoring with features
+
+## Output Format
+
+```markdown
+## Refactoring Plan: [Target]
+
+### Current State
+- **Location**: [file:line]
+- **Issues**: [what's wrong]
+
+### Proposed Changes
+1. [Change 1]
+2. [Change 2]
+
+### Impact Analysis
+- **Files affected**: [count]
+- **Risk level**: [Low/Medium/High]
+
+### Test Coverage
+- [x] Unit tests exist
+- [ ] Integration tests needed
+
+### Rollback
+```
+git revert [commit]
+```
+```
+
+## Approval Required
+
+Before executing:
+- [ ] Plan reviewed
+- [ ] Tests passing
+- [ ] Backup created
+
+## READ BEFORE WRITE
+
+This command analyzes and plans first.
+Execution requires explicit approval.
+
+## MANDATORY: Documentation Update
+
+After refactoring, update documentation:
+
+### Required Updates
+| Change Type | Update |
+|-------------|--------|
+| API changes | API documentation |
+| Architecture | architecture note if significant |
+| Patterns | Best practices docs |
+| Breaking changes | Migration guide |
+
+### Post-Refactoring Checklist
+- [ ] Tests still pass
+- [ ] No behavior changes
+- [ ] **Documentation updated if interfaces changed**
+- [ ] Code comments updated
+
+## Automated Smell Detection
+
+Run the bundled script to find refactoring opportunities:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/refactor-scan.py src/
+```
+
+## Parallel Refactoring (complex cases)
+
+If the scan reports >5 smells across multiple files, use Agent Teams:
+
+```
+Create an agent team for refactoring:
+- Teammate 1 (code-reviewer): "Plan the refactoring strategy for [identified smells]. Document what to change and why." Use Opus. READ-ONLY.
+- Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
+Teammate 1 completes first, then Teammate 2 acts on the plan.
+```

package/app/skills/refactor/scripts/refactor-scan.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Detect code smells deterministically: long functions, deep nesting, large files."""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+IGNORE_DIRS = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build', '.next', 'vendor', '.cache'}
+
+SOURCE_EXTS = {'.py', '.ts', '.js', '.tsx', '.jsx', '.go', '.php', '.dart'}
+
+THRESHOLDS = {
+    'long_function_lines': 50,
+    'deep_nesting_levels': 4,
+    'large_file_lines': 300,
+    'many_functions': 15,
+}
+
+FUNC_PATTERNS = {
+    '.py': re.compile(r'^(\s*)def\s+(\w+)\s*\('),
+    '.js': re.compile(r'^(\s*)(?:(?:async\s+)?function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()'),
+    '.jsx': re.compile(r'^(\s*)(?:(?:async\s+)?function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()'),
+    '.ts': re.compile(r'^(\s*)(?:(?:async\s+)?function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()'),
+    '.tsx': re.compile(r'^(\s*)(?:(?:async\s+)?function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()'),
+    '.go': re.compile(r'^(\s*)func\s+(?:\([^)]*\)\s+)?(\w+)\s*\('),
+    '.php': re.compile(r'^(\s*)(?:public|private|protected|static|\s)*function\s+(\w+)'),
+    '.dart': re.compile(r'^(\s*)(?:\w+\s+)?(\w+)\s*\([^)]*\)\s*(?:async\s*)?\{'),
+}
+
+
+def find_source_files(root: str) -> list:
+    result = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+        for fn in filenames:
+            if Path(fn).suffix in SOURCE_EXTS:
+                result.append(os.path.join(dirpath, fn))
+    return result
+
+
+def measure_nesting(line: str, ext: str) -> int:
+    """Measure nesting depth from indentation."""
+    if not line.strip():
+        return 0
+    if ext == '.py':
+        # Python: 4 spaces = 1 level
+        spaces = len(line) - len(line.lstrip())
+        return spaces // 4
+    else:
+        # Brace languages: count { minus } up to this point is complex,
+        # so use indentation heuristic (2 or 4 spaces = 1 level)
+        spaces = len(line) - len(line.lstrip())
+        tab_count = line.count('\t')
+        if tab_count > 0:
+            return tab_count
+        indent_size = 2 if spaces % 2 == 0 and spaces % 4 != 0 else 4
+        return spaces // indent_size
+
+
+def analyze_file(filepath: str, project_root: str) -> dict:
+    ext = Path(filepath).suffix
+    rel_path = os.path.relpath(filepath, project_root)
+    smells = []
+
+    try:
+        with open(filepath, 'r', errors='replace') as f:
+            lines = f.readlines()
+    except OSError:
+        return {"file": rel_path, "smells": [], "functions": 0}
+
+    total_lines = len(lines)
+    func_pattern = FUNC_PATTERNS.get(ext)
+    if not func_pattern:
+        return {"file": rel_path, "smells": [], "functions": 0}
+
+    # Find function boundaries
+    functions = []
+    for i, line in enumerate(lines):
+        m = func_pattern.match(line)
+        if m:
+            name = next((g for g in m.groups()[1:] if g is not None), 'anonymous')
+            indent = len(m.group(1).expandtabs(4))
+            functions.append({"name": name, "start": i + 1, "indent": indent})
+
+    # Calculate function lengths
+    for idx, func in enumerate(functions):
+        if idx + 1 < len(functions):
+            end = functions[idx + 1]["start"] - 1
+        else:
+            end = total_lines
+        func["length"] = end - func["start"] + 1
+
+    # Detect max nesting per function
+    for func in functions:
+        start_idx = func["start"] - 1
+        end_idx = start_idx + func["length"]
+        max_depth = 0
+        for i in range(start_idx, min(end_idx, total_lines)):
+            depth = measure_nesting(lines[i], ext)
+            # Relative nesting: subtract function's own indent level
+            relative_depth = depth - (func["indent"] // 4) - 1
+            if relative_depth > max_depth:
+                max_depth = relative_depth
+        func["max_nesting"] = max(max_depth, 0)
+
+    # Flag smells
+    for func in functions:
+        if func["length"] > THRESHOLDS['long_function_lines']:
+            smells.append({
+                "type": "long_function",
+                "severity": "high" if func["length"] > 100 else "medium",
+                "file": rel_path,
+                "function": func["name"],
+                "line": func["start"],
+                "detail": f"{func['length']} lines (threshold: {THRESHOLDS['long_function_lines']})",
+            })
+        if func["max_nesting"] > THRESHOLDS['deep_nesting_levels']:
+            smells.append({
+                "type": "deep_nesting",
+                "severity": "high" if func["max_nesting"] > 6 else "medium",
+                "file": rel_path,
+                "function": func["name"],
+                "line": func["start"],
+                "detail": f"depth {func['max_nesting']} (threshold: {THRESHOLDS['deep_nesting_levels']})",
+            })
+
+    if total_lines > THRESHOLDS['large_file_lines']:
+        smells.append({
+            "type": "large_file",
+            "severity": "high" if total_lines > 600 else "medium",
+            "file": rel_path,
+            "function": None,
+            "line": None,
+            "detail": f"{total_lines} lines (threshold: {THRESHOLDS['large_file_lines']})",
+        })
+
+    if len(functions) > THRESHOLDS['many_functions']:
+        smells.append({
+            "type": "too_many_functions",
+            "severity": "medium",
+            "file": rel_path,
+            "function": None,
+            "line": None,
+            "detail": f"{len(functions)} functions (threshold: {THRESHOLDS['many_functions']}, possible God class)",
+        })
+
+    return {"file": rel_path, "smells": smells, "functions": len(functions)}
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "Usage: refactor-scan.py <file_or_directory>"}))
+        sys.exit(1)
+
+    target = os.path.abspath(sys.argv[1])
+    if not os.path.exists(target):
+        print(json.dumps({"error": f"Path not found: {target}"}))
+        sys.exit(1)
+
+    # Determine project root
+    project_root = target if os.path.isdir(target) else os.path.dirname(target)
+    check = project_root
+    for _ in range(10):
+        if os.path.isdir(os.path.join(check, '.git')):
+            project_root = check
+            break
+        parent = os.path.dirname(check)
+        if parent == check:
+            break
+        check = parent
+
+    files = [target] if os.path.isfile(target) else find_source_files(target)
+
+    all_smells = []
+    files_scanned = 0
+
+    for fp in files:
+        result = analyze_file(fp, project_root)
+        files_scanned += 1
+        all_smells.extend(result["smells"])
+
+    # Sort by severity (high first)
+    severity_order = {"high": 0, "medium": 1, "low": 2}
+    all_smells.sort(key=lambda s: severity_order.get(s["severity"], 99))
+
+    # Generate recommendation
+    if not all_smells:
+        recommendation = "No code smells detected. Codebase looks clean."
+    elif len(all_smells) <= 3:
+        recommendation = "Minor issues found. Address them in your next refactoring pass."
+    elif len(all_smells) <= 10:
+        recommendation = "Several code smells detected. Prioritize high-severity items."
+    else:
+        recommendation = "Significant technical debt detected. Consider a dedicated refactoring sprint."
+
+    output = {
+        "target": os.path.relpath(target, project_root),
+        "smells": all_smells,
+        "files_scanned": files_scanned,
+        "total_smells": len(all_smells),
+        "recommendation": recommendation,
+    }
+
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/app/skills/refactor-plan/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: refactor-plan
+description: "Create a detailed refactor plan with tiny commits via user interview, then file as a GitHub issue RFC. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps."
+user-invocable: true
+effort: high
+argument-hint: "[area or module to refactor]"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Refactor Plan
+
+$ARGUMENTS
+
+Create a detailed refactor plan with tiny commits via user interview, filed as a GitHub issue.
+
+## Usage
+
+```
+/refactor-plan [area or module to refactor]
+```
+
+## What This Command Does
+
+1. **Gathers** detailed problem description from user
+2. **Explores** the codebase to verify assertions
+3. **Presents** alternative approaches (>=3 options)
+4. **Interviews** about implementation details
+5. **Checks** test coverage of affected area
+6. **Breaks** into tiny commits (Martin Fowler: each step keeps codebase working)
+7. **Files** as GitHub issue via `gh issue create`
+
+## Process
+
+### 1. Gather Problem
+
+Ask for detailed description of:
+- The problem they want to solve
+- Potential ideas for solutions
+
+### 2. Explore Codebase
+
+Use Agent (subagent_type=Explore) to verify assertions and understand current state.
+
+### 3. Present Alternatives
+
+Present >=3 alternative approaches. Discuss trade-offs.
+
+### 4. Interview
+
+Detailed interview about chosen approach. Hammer out exact scope — what changes, what doesn't.
+
+### 5. Check Test Coverage
+
+Explore existing test coverage for the affected area. If insufficient, ask about testing plans.
+
+### 6. Break into Tiny Commits
+
+Each commit:
+- Leaves the codebase in a working state
+- Is the smallest possible step
+- Can be reviewed independently
+
+### 7. File GitHub Issue
+
+Use `gh issue create` with template below. Share URL immediately.
+
+## Issue Template
+
+<refactor-plan-template>
+
+## Problem Statement
+
+The problem from the developer's perspective.
+
+## Solution
+
+The solution from the developer's perspective.
+
+## Commits
+
+Detailed plan in plain English, broken into the tiniest commits possible. Each commit leaves the codebase working.
+
+## Decision Document
+
+Implementation decisions made:
+- Modules to build/modify
+- Interface changes
+- Architectural decisions
+- Schema changes
+- API contracts
+
+Do NOT include file paths or code snippets — they go stale.
+
+## Testing Decisions
+
+- What makes a good test (external behavior, not implementation details)
+- Which modules to test
+- Prior art for tests in the codebase
+
+## Out of Scope
+
+What is explicitly NOT part of this refactor.
+
+</refactor-plan-template>
+
+## Rules
+
+- Present >=3 alternatives before committing to an approach
+- Tiny commits — each step keeps codebase working
+- No file paths or code snippets in the issue (durability)
+- File immediately via `gh issue create` — don't ask for review
+- Interview thoroughly before planning