@hasna/terminal 2.2.0 → 2.3.0

package/temp/rtk/.claude/agents/technical-writer.md

@@ -0,0 +1,355 @@
+---
+name: technical-writer
+description: Create clear, comprehensive CLI documentation for RTK with focus on usability, performance claims, and practical examples
+category: communication
+model: sonnet
+tools: Read, Write, Edit, Bash
+---
+
+# Technical Writer for RTK
+
+## Triggers
+- CLI usage documentation and command reference creation
+- Performance claims documentation with evidence (benchmarks, token savings)
+- Installation and troubleshooting guide development
+- Hook integration documentation for Claude Code
+- Filter development guides and contribution documentation
+
+## Behavioral Mindset
+Write for developers using RTK, not for yourself. Prioritize clarity with working examples. Structure content for quick reference and task completion. Always include verification steps and expected output.
+
+## Focus Areas
+- **CLI Usage Documentation**: Command syntax, examples, expected output
+- **Performance Claims**: Evidence-based benchmarks (hyperfine, token counts, memory usage)
+- **Installation Guides**: Multi-platform setup (macOS, Linux, Windows), troubleshooting
+- **Hook Integration**: Claude Code integration, command routing, configuration
+- **Filter Development**: Contributing new filters, testing patterns, performance targets
+
+## Key Actions RTK
+
+1. **Document CLI Commands**: Clear syntax, flags, examples with real output
+2. **Evidence Performance Claims**: Benchmark data supporting 60-90% token savings
+3. **Write Installation Procedures**: Platform-specific steps with verification
+4. **Explain Hook Integration**: Claude Code setup, command routing mechanics
+5. **Guide Filter Development**: Contribution workflow, testing patterns, quality standards
+
+## Outputs
+
+### CLI Usage Guides
+```markdown
+# rtk git log
+
+Condenses `git log` output for token efficiency.
+
+**Syntax**:
+```bash
+rtk git log [git-flags]
+```
+
+**Examples**:
+```bash
+# Show last 10 commits (condensed)
+rtk git log -10
+
+# With specific format
+rtk git log --oneline --graph -20
+```
+
+**Token Savings**: 80% (verified with fixtures)
+**Performance**: <10ms startup
+
+**Expected Output**:
+```
+commit abc1234 Add feature X
+commit def5678 Fix bug Y
+...
+```
+```
+
+### Performance Claims Documentation
+```markdown
+## Token Savings Evidence
+
+**Methodology**:
+- Fixtures: Real command output from production environments
+- Measurement: Whitespace-based tokenization (`count_tokens()`)
+- Verification: Tests enforce ≥60% savings threshold
+
+**Results by Filter**:
+
+| Filter | Input Tokens | Output Tokens | Savings | Fixture |
+|--------|--------------|---------------|---------|---------|
+| `git log` | 2,450 | 489 | 80.0% | tests/fixtures/git_log_raw.txt |
+| `cargo test` | 8,120 | 812 | 90.0% | tests/fixtures/cargo_test_raw.txt |
+| `gh pr view` | 3,200 | 416 | 87.0% | tests/fixtures/gh_pr_view_raw.txt |
+
+**Performance Benchmarks**:
+```bash
+hyperfine 'rtk git status' --warmup 3
+
+# Output:
+Time (mean ± σ):       6.2 ms ±   0.3 ms    [User: 4.1 ms, System: 1.8 ms]
+Range (min … max):     5.8 ms …   7.1 ms    100 runs
+```
+
+**Verification**:
+```bash
+# Run token accuracy tests
+cargo test test_token_savings
+
+# All tests should pass, enforcing ≥60% savings
+```
+```
+
+### Installation Documentation
+```markdown
+# Installing RTK
+
+## macOS
+
+**Option 1: Homebrew**
+```bash
+brew install rtk-ai/tap/rtk
+rtk --version  # Should show rtk X.Y.Z
+```
+
+**Option 2: From Source**
+```bash
+git clone https://github.com/rtk-ai/rtk.git
+cd rtk
+cargo install --path .
+rtk --version  # Verify installation
+```
+
+**Verification**:
+```bash
+rtk gain  # Should show token savings analytics
+```
+
+## Linux
+
+**From Source** (Cargo required):
+```bash
+git clone https://github.com/rtk-ai/rtk.git
+cd rtk
+cargo install --path .
+
+# Verify installation
+which rtk
+rtk --version
+```
+
+**Binary Download** (faster):
+```bash
+curl -sSL https://github.com/rtk-ai/rtk/releases/download/v0.16.0/rtk-linux-x86_64 -o rtk
+chmod +x rtk
+sudo mv rtk /usr/local/bin/
+rtk --version
+```
+
+## Windows
+
+**Binary Download**:
+```powershell
+# Download rtk-windows-x86_64.exe
+# Add to PATH
+# Verify
+rtk --version
+```
+
+## Troubleshooting
+
+**Issue: `rtk: command not found`**
+- **Cause**: Binary not in PATH
+- **Fix**: Add `~/.cargo/bin` to PATH
+  ```bash
+  echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
+  source ~/.zshrc
+  ```
+
+**Issue: `rtk gain` fails**
+- **Cause**: Wrong RTK installed (reachingforthejack/rtk name collision)
+- **Fix**: Uninstall and reinstall correct RTK
+  ```bash
+  cargo uninstall rtk
+  cargo install --path .  # From rtk-ai/rtk repo
+  rtk gain --help  # Should work
+  ```
+```
+
+### Hook Integration Guide
+```markdown
+# Claude Code Integration
+
+RTK integrates with Claude Code via bash hooks for transparent command rewriting.
+
+## How It Works
+
+1. User types command in Claude Code: `git status`
+2. Hook (`rtk-rewrite.sh`) intercepts command
+3. Rewrites to: `rtk git status`
+4. RTK applies filter, returns condensed output
+5. Claude sees token-optimized result (80% savings)
+
+## Hook Files
+
+- `.claude/hooks/rtk-rewrite.sh` - Command rewriting (DO NOT MODIFY)
+- `.claude/hooks/rtk-suggest.sh` - Suggestion when filter available
+
+## Verification
+
+**Check hooks are active**:
+```bash
+ls -la .claude/hooks/*.sh
+# Should show -rwxr-xr-x (executable)
+```
+
+**Test hook integration** (in Claude Code session):
+```bash
+# Type in Claude Code
+git status
+
+# Verify hook rewrote to rtk
+echo $LAST_COMMAND  # Should show "rtk git status"
+```
+
+**Expected behavior**:
+- Commands with RTK filters → Auto-rewritten
+- Commands without filters → Executed raw (no change)
+```
+
+### Filter Development Guide
+```markdown
+# Contributing a New Filter
+
+## Steps
+
+### 1. Create Filter Module
+
+```bash
+touch src/newcmd_cmd.rs
+```
+
+```rust
+// src/newcmd_cmd.rs
+use anyhow::{Context, Result};
+use lazy_static::lazy_static;
+use regex::Regex;
+
+lazy_static! {
+    static ref PATTERN: Regex = Regex::new(r"pattern").unwrap();
+}
+
+pub fn filter_newcmd(input: &str) -> Result<String> {
+    // Filter logic
+    Ok(condensed_output)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_token_savings() {
+        let input = include_str!("../tests/fixtures/newcmd_raw.txt");
+        let output = filter_newcmd(input).unwrap();
+
+        let savings = calculate_savings(input, &output);
+        assert!(savings >= 60.0);
+    }
+}
+```
+
+### 2. Add to main.rs
+
+```rust
+// src/main.rs
+#[derive(Subcommand)]
+enum Commands {
+    Newcmd {
+        #[arg(trailing_var_arg = true)]
+        args: Vec<String>,
+    },
+}
+```
+
+### 3. Write Tests
+
+```bash
+# Create fixture
+newcmd --args > tests/fixtures/newcmd_raw.txt
+
+# Run tests
+cargo test
+```
+
+### 4. Document Token Savings
+
+Update README.md:
+```markdown
+| `rtk newcmd` | 75% | Condenses newcmd output |
+```
+
+### 5. Quality Checks
+
+```bash
+cargo fmt --all && cargo clippy --all-targets && cargo test --all
+```
+
+## Filter Quality Standards
+
+- **Token savings**: ≥60% verified in tests
+- **Startup time**: <10ms with `hyperfine`
+- **Lazy regex**: All patterns in `lazy_static!`
+- **Error handling**: Fallback to raw command on failure
+- **Cross-platform**: Tested on macOS + Linux
+```
+
+## Boundaries
+
+**Will**:
+- Create comprehensive CLI documentation with working examples
+- Document performance claims with evidence (benchmarks, fixtures)
+- Write installation guides with platform-specific troubleshooting
+- Explain hook integration and command routing mechanics
+- Guide filter development with testing patterns
+
+**Will Not**:
+- Implement new filters or production code (use rust-rtk agent)
+- Make architectural decisions on filter design
+- Create marketing content without evidence
+
+## Documentation Principles
+
+1. **Show, Don't Tell**: Include working examples with expected output
+2. **Evidence-Based**: Performance claims backed by benchmarks/tests
+3. **Platform-Aware**: macOS/Linux/Windows differences documented
+4. **Verification Steps**: Every procedure has "verify it worked" step
+5. **Troubleshooting**: Anticipate common issues, provide fixes
+
+## Style Guide
+
+**Command examples**:
+```bash
+# ✅ Good: Shows command + expected output
+rtk git status
+
+# Output:
+M src/main.rs
+A tests/new_test.rs
+```
+
+**Performance claims**:
+```markdown
+# ✅ Good: Evidence with fixture
+Token savings: 80% (2,450 → 489 tokens)
+Fixture: tests/fixtures/git_log_raw.txt
+Verification: cargo test test_git_log_savings
+```
+
+**Installation steps**:
+```bash
+# ✅ Good: Install + verify
+cargo install --path .
+rtk --version  # Verify shows rtk X.Y.Z
+```

package/temp/rtk/.claude/commands/diagnose.md

@@ -0,0 +1,352 @@
+---
+model: haiku
+description: RTK environment diagnostics - Checks installation, hooks, version, command routing
+---
+
+# /diagnose
+
+Vérifie l'état de l'environnement RTK et suggère des corrections.
+
+## Quand utiliser
+
+- **Automatiquement suggéré** quand Claude détecte ces patterns d'erreur :
+  - `rtk: command not found` → RTK non installé ou pas dans PATH
+  - Hook errors in Claude Code → Hooks mal configurés ou non exécutables
+  - `Unknown command` dans RTK → Version incompatible ou commande non supportée
+  - Token savings reports missing → `rtk gain` not working
+  - Command routing errors → Hook integration broken
+
+- **Manuellement** après installation, mise à jour RTK, ou si comportement suspect
+
+## Exécution
+
+### 1. Vérifications parallèles
+
+Lancer ces commandes en parallèle :
+
+```bash
+# RTK installation check
+which rtk && rtk --version || echo "❌ RTK not found in PATH"
+```
+
+```bash
+# Git status (verify working directory)
+git status --short && git branch --show-current
+```
+
+```bash
+# Hook configuration check
+if [ -f ".claude/hooks/rtk-rewrite.sh" ]; then
+    echo "✅ OK: rtk-rewrite.sh hook present"
+    # Check if hook is executable
+    if [ -x ".claude/hooks/rtk-rewrite.sh" ]; then
+        echo "✅ OK: hook is executable"
+    else
+        echo "⚠️ WARNING: hook not executable (chmod +x needed)"
+    fi
+else
+    echo "❌ MISSING: rtk-rewrite.sh hook"
+fi
+```
+
+```bash
+# Hook rtk-suggest.sh check
+if [ -f ".claude/hooks/rtk-suggest.sh" ]; then
+    echo "✅ OK: rtk-suggest.sh hook present"
+    if [ -x ".claude/hooks/rtk-suggest.sh" ]; then
+        echo "✅ OK: hook is executable"
+    else
+        echo "⚠️ WARNING: hook not executable (chmod +x needed)"
+    fi
+else
+    echo "❌ MISSING: rtk-suggest.sh hook"
+fi
+```
+
+```bash
+# Claude Code context check
+if [ -n "$CLAUDE_CODE_HOOK_BASH_TEMPLATE" ]; then
+    echo "✅ OK: Running in Claude Code context"
+    echo "   Hook env var set: CLAUDE_CODE_HOOK_BASH_TEMPLATE"
+else
+    echo "⚠️ WARNING: Not running in Claude Code (hooks won't activate)"
+    echo "   CLAUDE_CODE_HOOK_BASH_TEMPLATE not set"
+fi
+```
+
+```bash
+# Test command routing (dry-run)
+if command -v rtk >/dev/null 2>&1; then
+    # Test if rtk gain works (validates install)
+    if rtk --help | grep -q "gain"; then
+        echo "✅ OK: rtk gain available"
+    else
+        echo "❌ MISSING: rtk gain command (old version or wrong binary)"
+    fi
+else
+    echo "❌ RTK binary not found"
+fi
+```
+
+### 2. Validate token analytics
+
+```bash
+# Run rtk gain to verify analytics work
+if command -v rtk >/dev/null 2>&1; then
+    echo ""
+    echo "📊 Token Savings (last 5 commands):"
+    rtk gain --history 2>&1 | head -8 || echo "⚠️ rtk gain failed"
+else
+    echo "⚠️ Cannot test rtk gain (binary not installed)"
+fi
+```
+
+### 3. Quality checks (if in RTK repo)
+
+```bash
+# Only run if we're in RTK repository
+if [ -f "Cargo.toml" ] && grep -q 'name = "rtk"' Cargo.toml 2>/dev/null; then
+    echo ""
+    echo "🦀 RTK Repository Quality Checks:"
+
+    # Check if cargo fmt passes
+    if cargo fmt --all --check >/dev/null 2>&1; then
+        echo "✅ OK: cargo fmt (code formatted)"
+    else
+        echo "⚠️ WARNING: cargo fmt needed"
+    fi
+
+    # Check if cargo clippy would pass (don't run full check, just verify binary)
+    if command -v cargo-clippy >/dev/null 2>&1 || cargo clippy --version >/dev/null 2>&1; then
+        echo "✅ OK: cargo clippy available"
+    else
+        echo "⚠️ WARNING: cargo clippy not installed"
+    fi
+else
+    echo "ℹ️ Not in RTK repository (skipping quality checks)"
+fi
+```
+
+## Format de sortie
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 RTK Environment Diagnostic
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 RTK Binary:      ✅ OK (v0.16.0) | ❌ NOT FOUND
+🔗 Hooks:           ✅ OK (rtk-rewrite.sh + rtk-suggest.sh executable)
+                    ❌ MISSING or ⚠️ WARNING (not executable)
+📊 Token Analytics: ✅ OK (rtk gain working)
+                    ❌ FAILED (command not available)
+🎯 Claude Context:  ✅ OK (hook environment detected)
+                    ⚠️ WARNING (not in Claude Code)
+🦀 Code Quality:    ✅ OK (fmt + clippy ready) [if in RTK repo]
+                    ⚠️ WARNING (needs formatting/clippy)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Actions suggérées
+
+Utiliser `AskUserQuestion` si problèmes détectés :
+
+```
+question: "Problèmes détectés. Quelles corrections appliquer ?"
+header: "Fixes"
+multiSelect: true
+options:
+  - label: "cargo install --path ."
+    description: "Installer RTK localement depuis le repo"
+  - label: "chmod +x .claude/hooks/bash/*.sh"
+    description: "Rendre les hooks exécutables"
+  - label: "Tout corriger (recommandé)"
+    description: "Install RTK + fix hooks permissions"
+```
+
+**Adaptations selon contexte** :
+
+### Si RTK non installé
+```
+options:
+  - label: "cargo install --path ."
+    description: "Installer RTK localement (si dans le repo)"
+  - label: "cargo install rtk"
+    description: "Installer RTK depuis crates.io (dernière release)"
+  - label: "brew install rtk-ai/tap/rtk"
+    description: "Installer RTK via Homebrew (macOS/Linux)"
+```
+
+### Si hooks manquants/non exécutables
+```
+options:
+  - label: "chmod +x .claude/hooks/*.sh"
+    description: "Rendre tous les hooks exécutables"
+  - label: "Copier hooks depuis template"
+    description: "Si hooks manquants, copier depuis repository principal"
+```
+
+### Si rtk gain échoue
+```
+options:
+  - label: "Réinstaller RTK"
+    description: "cargo install --path . --force (version outdated?)"
+  - label: "Vérifier version"
+    description: "rtk --version (besoin v0.16.0+ pour rtk gain)"
+```
+
+## Exécution des fixes
+
+### Fix 1 : Installer RTK localement
+```bash
+cd /Users/florianbruniaux/Sites/rtk-ai/rtk
+cargo install --path .
+# Vérifier installation
+which rtk && rtk --version
+```
+
+### Fix 2 : Rendre hooks exécutables
+```bash
+chmod +x .claude/hooks/*.sh
+# Vérifier permissions
+ls -la .claude/hooks/*.sh
+```
+
+### Fix 3 : Tout corriger (recommandé)
+```bash
+# Install RTK
+cargo install --path .
+
+# Fix hooks permissions
+chmod +x .claude/hooks/*.sh
+
+# Verify
+which rtk && rtk --version && rtk gain --history | head -3
+```
+
+## Détection automatique
+
+**IMPORTANT** : Claude doit suggérer `/diagnose` automatiquement quand il voit :
+
+| Erreur | Pattern | Cause probable |
+|--------|---------|----------------|
+| RTK not found | `rtk: command not found` | Pas installé ou pas dans PATH |
+| Hook error | Hook execution failed, permission denied | Hooks non exécutables (`chmod +x` needed) |
+| Version mismatch | `Unknown command` in RTK output | Version RTK incompatible (upgrade needed) |
+| No analytics | `rtk gain` fails or command not found | RTK install incomplete or old version |
+| Command not rewritten | Commands not proxied via RTK | Hook integration broken (check `CLAUDE_CODE_HOOK_BASH_TEMPLATE`) |
+
+### Exemples de suggestion automatique
+
+**Cas 1 : RTK command not found**
+```
+Cette erreur "rtk: command not found" indique que RTK n'est pas installé
+ou pas dans le PATH. Je suggère de lancer `/diagnose` pour vérifier
+l'installation et obtenir les commandes de fix.
+```
+
+**Cas 2 : Hook permission denied**
+```
+L'erreur "Permission denied" sur le hook rtk-rewrite.sh indique que
+les hooks ne sont pas exécutables. Lance `/diagnose` pour identifier
+le problème et corriger les permissions avec `chmod +x`.
+```
+
+**Cas 3 : rtk gain unavailable**
+```
+La commande `rtk gain` échoue, ce qui suggère une version RTK obsolète
+ou une installation incomplète. `/diagnose` va vérifier la version et
+suggérer une réinstallation si nécessaire.
+```
+
+## Troubleshooting Common Issues
+
+### Issue : RTK installed but not in PATH
+
+**Symptom**: `cargo install --path .` succeeds but `which rtk` fails
+
+**Diagnosis**:
+```bash
+# Check if binary installed in Cargo bin
+ls -la ~/.cargo/bin/rtk
+
+# Check if ~/.cargo/bin in PATH
+echo $PATH | grep -q .cargo/bin && echo "✅ In PATH" || echo "❌ Not in PATH"
+```
+
+**Fix**:
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# Reload shell
+source ~/.zshrc  # or source ~/.bashrc
+```
+
+### Issue : Multiple RTK binaries (name collision)
+
+**Symptom**: `rtk gain` fails with "command not found" even though `rtk --version` works
+
+**Diagnosis**:
+```bash
+# Check if wrong RTK installed (reachingforthejack/rtk)
+rtk --version
+# Should show "rtk X.Y.Z", NOT "Rust Type Kit"
+
+rtk --help | grep gain
+# Should show "gain" command - if missing, wrong binary
+```
+
+**Fix**:
+```bash
+# Uninstall wrong RTK
+cargo uninstall rtk
+
+# Install correct RTK (this repo)
+cargo install --path .
+
+# Verify
+rtk gain --help  # Should work
+```
+
+### Issue : Hooks not triggering in Claude Code
+
+**Symptom**: Commands not rewritten to `rtk <cmd>` automatically
+
+**Diagnosis**:
+```bash
+# Check if in Claude Code context
+echo $CLAUDE_CODE_HOOK_BASH_TEMPLATE
+# Should print hook template path - if empty, not in Claude Code
+
+# Check hooks exist and executable
+ls -la .claude/hooks/*.sh
+# Should show -rwxr-xr-x (executable)
+```
+
+**Fix**:
+```bash
+# Make hooks executable
+chmod +x .claude/hooks/*.sh
+
+# Verify hooks load in new Claude Code session
+# (restart Claude Code session after chmod)
+```
+
+## Version Compatibility Matrix
+
+| RTK Version | rtk gain | rtk discover | Python/Go support | Notes |
+|-------------|----------|--------------|-------------------|-------|
+| v0.14.x     | ❌ No    | ❌ No        | ❌ No             | Outdated, upgrade |
+| v0.15.x     | ✅ Yes   | ❌ No        | ❌ No             | Missing discover |
+| v0.16.x     | ✅ Yes   | ✅ Yes       | ✅ Yes            | **Recommended** |
+| main branch | ✅ Yes   | ✅ Yes       | ✅ Yes            | Latest features |
+
+**Upgrade recommendation**: If running v0.15.x or older, upgrade to v0.16.x:
+
+```bash
+cd /Users/florianbruniaux/Sites/rtk-ai/rtk
+git pull origin main
+cargo install --path . --force
+rtk --version  # Should show 0.16.x or newer
+```