@hasna/terminal 2.3.0 → 2.3.1

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

@@ -1,355 +0,0 @@
----
-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

@@ -1,352 +0,0 @@
----
-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
-```