unix-goto-development — Skillopedia

unix-goto Development Expert Comprehensive development expertise for the unix-goto shell navigation system - a high-performance Unix navigation tool with natural language support, sub-100ms cached navigation, and 100% test coverage. When to Use This Skill Use this skill when: - Developing new features for unix-goto shell navigation system - Implementing cache-based navigation optimizations - Adding bookmarks, history, or navigation commands - Following the standard 9-step feature addition workflow - Integrating with Linear project management - Writing comprehensive test suites (100% coverage…

\\n' sorted=($(sort -n \u003c\u003c\u003c\"${values[*]}\"))\n\n # Min/Max\n local min=${sorted[0]}\n local max=${sorted[$((count-1))]}\n\n # Mean\n local sum=0\n for val in \"${values[@]}\"; do\n sum=$((sum + val))\n done\n local mean=$((sum / count))\n\n # Median\n local mid=$((count / 2))\n local median=${sorted[$mid]}\n\n # Standard deviation\n local variance=0\n for val in \"${values[@]}\"; do\n local diff=$((val - mean))\n variance=$((variance + diff * diff))\n done\n variance=$((variance / count))\n local stddev=$(echo \"sqrt($variance)\" | bc)\n\n echo \"$min,$max,$mean,$median,$stddev\"\n}\n\n# Print header\nbench_header() {\n local title=\"$1\"\n echo \"╔══════════════════════════════════════════════════════════════════╗\"\n printf \"║ %-62s ║\\n\" \"$title\"\n echo \"╚══════════════════════════════════════════════════════════════════╝\"\n echo \"\"\n}\n\n# Print section\nbench_section() {\n local title=\"$1\"\n echo \"$title\"\n echo \"─────────────────────────────────────────────────────────────────\"\n}\n\n# Print statistics block\nbench_print_stats() {\n local stats=\"$1\"\n local label=\"$2\"\n\n IFS=',' read -r min max mean median stddev \u003c\u003c\u003c \"$stats\"\n\n echo \"\"\n echo \"$label:\"\n printf \" Min: %dms\\n\" \"$min\"\n printf \" Max: %dms\\n\" \"$max\"\n printf \" Mean: %dms\\n\" \"$mean\"\n printf \" Median: %dms\\n\" \"$median\"\n printf \" Std Dev: %.2fms\\n\" \"$stddev\"\n}\n\n# Assert performance target\nbench_assert_target() {\n local actual=\"$1\"\n local target=\"$2\"\n local label=\"$3\"\n\n if [ \"$actual\" -lt \"$target\" ]; then\n echo \"✓ $label meets target: ${actual}ms (target: \u003c${target}ms)\"\n else\n echo \"✗ $label exceeds target: ${actual}ms (target: \u003c${target}ms)\"\n fi\n}\n\n# Initialize results directory\nbench_init() {\n mkdir -p \"$BENCH_RESULTS_DIR\"\n}\n\n# Save benchmark result\nbench_save_result() {\n bench_init\n\n local name=\"$1\"\n local stats=\"$2\"\n local metadata=\"${3:-}\"\n\n local timestamp=$(date +%s)\n local results_file=\"$BENCH_RESULTS_DIR/results.csv\"\n\n # Create header if file doesn't exist\n if [ ! -f \"$results_file\" ]; then\n echo \"timestamp,benchmark_name,operation,min_ms,max_ms,mean_ms,median_ms,stddev,metadata\" > \"$results_file\"\n fi\n\n # Append result\n echo \"$timestamp,$name,$metadata,$stats\" >> \"$results_file\"\n}\n\n# Create test workspace\nbench_create_workspace() {\n local size=\"${1:-medium}\"\n local workspace=$(mktemp -d)\n\n case \"$size\" in\n small)\n # 10 folders\n for i in {1..10}; do\n mkdir -p \"$workspace/folder-$i\"\n done\n ;;\n medium)\n # 50 folders\n for i in {1..50}; do\n mkdir -p \"$workspace/folder-$i\"\n done\n ;;\n large)\n # 500 folders\n for i in {1..500}; do\n mkdir -p \"$workspace/folder-$i\"\n done\n ;;\n esac\n\n echo \"$workspace\"\n}\n\n# Cleanup workspace\nbench_cleanup_workspace() {\n local workspace=\"$1\"\n rm -rf \"$workspace\"\n}\n\n# Run benchmark iterations\nbench_run() {\n local name=\"$1\"\n local cmd=\"$2\"\n local iterations=\"${3:-10}\"\n\n local times=()\n\n for i in $(seq 1 $iterations); do\n local time=$(bench_time_ms \"$cmd\")\n times+=(\"$time\")\n printf \" Run %2d: %dms\\n\" \"$i\" \"$time\"\n done\n\n bench_calculate_stats \"${times[@]}\"\n}\n\n# Warmup iterations\nbench_warmup() {\n local cmd=\"$1\"\n local iterations=\"${2:-3}\"\n\n for i in $(seq 1 $iterations); do\n eval \"$cmd\" > /dev/null 2>&1\n done\n}\n\n# Compare performance\nbench_compare() {\n local baseline=\"$1\"\n local optimized=\"$2\"\n\n local speedup=$(echo \"scale=2; $baseline / $optimized\" | bc)\n echo \"$speedup\"\n}\n```\n\n## Best Practices\n\n### Code Style Standards\n\n**Function Structure:**\n```bash\nfunction_name() {\n local param1=\"$1\"\n local param2=\"${2:-default}\"\n\n # Validate inputs\n if [ -z \"$param1\" ]; then\n echo \"Error: param1 required\"\n return 1\n fi\n\n # Main logic\n local result=$(process \"$param1\")\n\n # Return value\n echo \"$result\"\n return 0\n}\n```\n\n**Error Handling:**\n```bash\n# Always check command success\nif ! goto index rebuild; then\n echo \"Failed to rebuild cache\"\n return 1\nfi\n\n# Use meaningful error messages\nif [ ! -d \"$target_dir\" ]; then\n echo \"❌ Directory not found: $target_dir\"\n return 1\nfi\n```\n\n**Comments:**\n```bash\n# Good: Explain why, not what\n# Cache lookup is O(1) because we use grep on indexed file\n\n# Bad: Explain what (obvious from code)\n# Set folder_name to first parameter\nfolder_name=\"$1\"\n```\n\n### Data File Format Pattern\n\n**Standard format:** Pipe-delimited with metadata header\n\n```bash\n# Module data file\n# Version: 1.0\n# Built: [timestamp]\n# Format: field1|field2|field3\n#---\nvalue1|value2|value3\nvalue1|value2|value3\n```\n\n### Performance Optimization Tips\n\n**Cache System:**\n- Use cache for all lookups\n- Limit recursive search depth\n- Avoid redundant filesystem operations\n- Use `grep` for fast text matching\n\n**Memory:**\n- Cache file: \u003c100KB for 500 folders\n- Memory usage: Minimal (shell functions only)\n- No persistent processes\n\n### Debugging Tips\n\n**Enable Bash Tracing:**\n```bash\nset -x\nsource goto.sh\ngoto test\nset +x\n```\n\n**Check Function Existence:**\n```bash\nif declare -f __goto_cache_lookup > /dev/null; then\n echo \"Function loaded\"\nfi\n```\n\n**Debug Cache Issues:**\n```bash\n# View cache file\ncat ~/.goto_index\n\n# Check cache age\nstat -f %m ~/.goto_index\n\n# Rebuild and observe\ngoto index rebuild\n```\n\n### Linear Workflow Integration\n\n**Linear Project Details:**\n- Team: Ceti-luxor\n- Project: unix-goto - Shell Navigation Tool\n- Project ID: 7232cafe-cb71-4310-856a-0d584e6f3df0\n\n**Issue Lifecycle:**\n```\nBacklog → In Progress → Complete\n```\n\n**Standard Workflow:**\n\n1. Pick an issue from Phase 3 backlog\n2. Move to \"In Progress\" in Linear\n3. Create feature branch: `feature/CET-XX-feature-name`\n4. Implement following 9-step workflow\n5. Test thoroughly (100% coverage)\n6. Commit with proper format\n7. Update Linear issue with results\n8. Move to \"Complete\"\n\n**Linear Issue Template:**\n```markdown\n## Problem\nWhat problem does this solve?\n\n## Solution\nHow will we solve it?\n\n## Acceptance Criteria\n- [ ] Criterion 1\n- [ ] Criterion 2\n- [ ] Tests pass\n- [ ] Performance targets met\n\n## Performance Targets\n- Metric 1: \u003ctarget>\n- Metric 2: \u003ctarget>\n\n## Dependencies\n- Issue CET-XX (if applicable)\n```\n\n## Quick Reference\n\n### Essential Commands\n\n```bash\n# Development\nsource goto.sh # Load all modules\ngoto index rebuild # Rebuild cache\nbash test-cache.sh # Run cache tests\nbash test-benchmark.sh # Run benchmark tests\ngoto benchmark all # Run all benchmarks\n\n# Debugging\nset -x; goto project; set +x # Trace execution\ndeclare -F | grep goto # List functions\ncat ~/.goto_index # View cache\n\n# Git workflow\ngit checkout -b feature/CET-XX # Create branch\ngit commit -m \"feat: ...\" # Commit with proper format\ngit push origin feature/CET-XX # Push to remote\n\n# Performance\ntime goto project # Measure navigation\ngoto benchmark navigation # Benchmark navigation\ngoto index status # Check cache health\n```\n\n### File Locations\n\n```\n~/.goto_index - Cache file\n~/.goto_bookmarks - Bookmarks file\n~/.goto_history - History file\n~/.goto_stack - Navigation stack\n~/.goto_benchmarks/ - Benchmark results directory\n```\n\n### Performance Targets Summary\n\n| Metric | Target | Current |\n|--------|--------|---------|\n| Cached navigation | \u003c100ms | 26ms ✓ |\n| Cache build | \u003c5s | 3-5s ✓ |\n| Cache hit rate | >90% | 92-95% ✓ |\n| Speedup ratio | 20-50x | 8x ⚠ |\n| Test coverage | 100% | 100% ✓ |\n\n---\n\n**Skill Version:** 1.0\n**Last Updated:** October 2025\n**Maintained By:** Manu Tej + Claude Code\n**Source Repository:** https://github.com/manutej/unix-goto\n---","attachment_filenames":["README.md"],"attachments":[{"filename":"README.md","content":"# unix-goto Development Skill\n\nExpert guidance for developing features in the unix-goto shell navigation tool.\n\n## Overview\n\nThis skill provides comprehensive expertise for unix-goto development, including:\n\n- **Architecture Knowledge**: Cache system (O(1) lookup), bookmarks, history tracking, module dependencies\n- **9-Step Feature Workflow**: Standard process for adding any new feature\n- **Testing Requirements**: 100% test coverage for all core features\n- **Performance Standards**: \u003c100ms cached navigation, >90% cache hit rate\n- **Linear Integration**: Complete workflow for issue tracking and project management\n- **API Documentation**: Patterns for documenting shell modules\n- **Best Practices**: Code style, commit standards, debugging tips\n\n## When to Use\n\nUse this skill when:\n- Developing new features for unix-goto\n- Implementing cache-based navigation optimizations\n- Adding bookmarks, history, or navigation commands\n- Following the standard development workflow\n- Writing comprehensive test suites\n- Optimizing performance to meet targets\n- Creating API documentation\n- Integrating with Linear project management\n\n## Key Features\n\n### Architecture Patterns\n- Cache system: O(1) lookup with auto-refresh\n- Bookmarks: Fast access to frequent locations\n- History tracking: Stack-based navigation\n- Module dependencies: Critical load order\n\n### 9-Step Development Workflow\n1. Plan your feature\n2. Create module (if needed)\n3. Add to loader\n4. Integrate with main function\n5. Add tests (100% coverage)\n6. Document API\n7. Update user documentation\n8. Performance validation\n9. Linear issue update & commit\n\n### Performance Targets\n- Cached navigation: \u003c100ms (achieved: 26ms)\n- Cache build: \u003c5s (achieved: 3-5s)\n- Cache hit rate: >90% (achieved: 92-95%)\n- Speedup ratio: >20x (in progress: 8x)\n- Test coverage: 100%\n\n## Installation\n\nThis skill is already installed at:\n```\n~/Library/Application Support/Claude/skills/unix-goto-development/\n```\n\n## Usage\n\nSimply mention unix-goto development tasks in your conversation with Claude:\n\n```\n\"I need to add a recent directories feature to unix-goto\"\n\"Help me implement bookmark navigation with 100% test coverage\"\n\"Create a cache optimization following the 9-step workflow\"\n```\n\nClaude will automatically activate this skill and guide you through the complete development process.\n\n## Examples\n\n### Example 1: Adding a New Feature\n```\n\"I need to add a 'goto recent' command to show recently visited directories.\nFollow the 9-step workflow and ensure 100% test coverage.\"\n```\n\nClaude will:\n1. Help you plan the feature (interface, performance, dependencies)\n2. Generate the module code\n3. Show you how to add it to the loader\n4. Integrate with the main goto function\n5. Create comprehensive tests (unit, integration, edge cases, performance)\n6. Generate API documentation\n7. Update README\n8. Validate performance\n9. Create proper commit message\n\n### Example 2: Optimizing Performance\n```\n\"The cache lookup is taking 150ms. Help me optimize it to meet the \u003c100ms target.\"\n```\n\nClaude will:\n- Analyze the current implementation\n- Identify performance bottlenecks\n- Suggest optimizations\n- Help implement changes\n- Create performance tests\n- Validate against targets\n\n## Skill Contents\n\n- **SKILL.md** (1,269 lines): Complete development expertise\n - Architecture patterns\n - 9-step workflow\n - Testing requirements\n - Performance standards\n - Linear integration\n - Code examples\n - Best practices\n\n## Version\n\n- **Version**: 1.0\n- **Created**: October 2025\n- **Source**: unix-goto project knowledge base\n- **Lines**: 1,269\n\n## Related Skills\n\n- **shell-testing-framework**: Testing expertise for bash scripts\n- **performance-benchmark-specialist**: Performance benchmarking patterns\n- **linear-dev-accelerator**: Linear project management integration\n\n## License\n\nThis skill is created for the unix-goto project by Manu Tej + Claude Code.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3900,"content_sha256":"0cfa6c3e7b47ad659bf208f0225325e7455b03a44b11de851f2b3b92d024970b"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"unix-goto Development Expert","type":"text"}]},{"type":"paragraph","content":[{"text":"Comprehensive development expertise for the unix-goto shell navigation system - a high-performance Unix navigation tool with natural language support, sub-100ms cached navigation, and 100% test coverage.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this skill when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Developing new features for unix-goto shell navigation system","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implementing cache-based navigation optimizations","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Adding bookmarks, history, or navigation commands","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Following the standard 9-step feature addition workflow","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Integrating with Linear project management","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Writing comprehensive test suites (100% coverage required)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optimizing performance to meet \u003c100ms targets","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating API documentation for shell modules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Debugging navigation or cache issues","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do NOT use this skill for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"General bash scripting (use generic bash skills)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Non-navigation shell tools","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Projects without performance requirements","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Simple one-off shell scripts","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Project Overview","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"unix-goto System Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"unix-goto is a high-performance Unix navigation system designed with five core principles:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Simple","type":"text","marks":[{"type":"strong"}]},{"text":" - ONE-line loading (","type":"text"},{"text":"source goto.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":"), minimal configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fast","type":"text","marks":[{"type":"strong"}]},{"text":" - Sub-100ms navigation performance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lean","type":"text","marks":[{"type":"strong"}]},{"text":" - No bloat, no unnecessary dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tested","type":"text","marks":[{"type":"strong"}]},{"text":" - 100% test coverage for core features","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Documented","type":"text","marks":[{"type":"strong"}]},{"text":" - Clear, comprehensive documentation","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Key Performance Metrics","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Metric","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Target","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Achieved","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Status","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cached navigation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003c100ms","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"26ms","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"✅ Exceeded","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cache hit rate","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">90%","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"92-95%","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"✅ Exceeded","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Speedup ratio","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"20-50x","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"8x","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"⏳ On track","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Test coverage","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"100%","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"100%","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"✅ Met","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cache build time","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003c5s","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3-5s","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"✅ Met","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"System Architecture","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"┌─────────────────────────────────────────────────────────────┐\n│ User Interface │\n│ goto, bookmark, recent, back, goto list, goto benchmark │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Core Navigation │\n│ goto-function.sh - Main routing and path resolution │\n└─────────────────────────────────────────────────────────────┘\n │\n ┌─────────────────┼─────────────────┐\n ▼ ▼ ▼\n┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐\n│ Cache System │ │ Bookmarks │ │ History │\n│ cache-index.sh │ │ bookmark- │ │ history- │\n│ │ │ command.sh │ │ tracking.sh │\n│ O(1) lookup │ │ │ │ │\n│ Auto-refresh │ │ Add/Remove │ │ Track visits │\n└──────────────────┘ └──────────────┘ └──────────────────┘","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Module Dependencies","type":"text"}]},{"type":"paragraph","content":[{"text":"Critical Load Order","type":"text","marks":[{"type":"strong"}]},{"text":" (dependencies must load before dependents):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"goto.sh (loader)\n ├── history-tracking.sh (no dependencies)\n ├── back-command.sh (depends on: history-tracking.sh)\n ├── recent-command.sh (depends on: history-tracking.sh)\n ├── bookmark-command.sh (no dependencies)\n ├── cache-index.sh (no dependencies)\n ├── list-command.sh (depends on: bookmark-command.sh)\n ├── benchmark-command.sh (depends on: cache-index.sh)\n ├── benchmark-workspace.sh (no dependencies)\n └── goto-function.sh (depends on: all above)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Knowledge","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The 9-Step Feature Addition Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"This is the STANDARD process for adding any feature to unix-goto. Follow ALL nine steps.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 1: Plan Your Feature","type":"text"}]},{"type":"paragraph","content":[{"text":"Before writing ANY code, answer these questions:","type":"text"}]},{"type":"paragraph","content":[{"text":"Planning Questions:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What problem does this solve?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What's the user interface (commands/flags)?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What's the expected performance?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What dependencies exist?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What tests are needed?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What documentation is required?","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Planning Template:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Feature: [Name]\nProblem: [User pain point]\nInterface: [Commands/flags]\nPerformance: [Target metrics]\nDependencies: [Module dependencies]\nTests: [Test scenarios]\nDocs: [API.md, README.md sections]","type":"text"}]},{"type":"paragraph","content":[{"text":"Example - Recent Directories Feature (CET-77):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Feature: Recent Directories Command\nProblem: Users can't quickly revisit recently navigated directories\nInterface: goto recent [n]\nPerformance: \u003c10ms for history retrieval\nDependencies: history-tracking.sh\nTests:\n - List recent directories\n - Handle empty history\n - Limit to N entries\n - Navigate to recent directory by number\nDocs: Add to API.md and README.md","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 2: Create Module (if needed)","type":"text"}]},{"type":"paragraph","content":[{"text":"Module Template:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# unix-goto - [Module purpose]\n# https://github.com/manutej/unix-goto\n\n# Storage location\nGOTO_MODULE_FILE=\"${GOTO_MODULE_FILE:-$HOME/.goto_module}\"\n\n# Main function\ngoto_module() {\n local subcommand=\"$1\"\n shift\n\n case \"$subcommand\" in\n list)\n # Implementation\n ;;\n add)\n # Implementation\n ;;\n --help|-h|help|\"\")\n echo \"goto module - [Description]\"\n echo \"\"\n echo \"Usage:\"\n echo \" goto module list [Description]\"\n echo \" goto module add [Description]\"\n ;;\n *)\n echo \"Unknown command: $subcommand\"\n return 1\n ;;\n esac\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Key Module Patterns:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Function Naming:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Public functions: no prefix (","type":"text"},{"text":"goto","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"bookmark","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"recent","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Internal functions: double underscore (","type":"text"},{"text":"__goto_navigate_to","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"__goto_cache_lookup","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Variables: UPPERCASE for globals, lowercase for locals","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Environment Variables:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Always provide defaults\nGOTO_INDEX_FILE=\"${GOTO_INDEX_FILE:-$HOME/.goto_index}\"\nGOTO_CACHE_TTL=\"${GOTO_CACHE_TTL:-86400}\"\nGOTO_SEARCH_DEPTH=\"${GOTO_SEARCH_DEPTH:-3}\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Return Codes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"0","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Success","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" - General error (not found, invalid input)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"2","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Multiple matches found (cache lookup only)","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 3: Add to Loader","type":"text"}]},{"type":"paragraph","content":[{"text":"Edit ","type":"text"},{"text":"goto.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" to load your module in the correct dependency order:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Add to load sequence (respect dependencies)\nsource \"$GOTO_LIB_DIR/history-tracking.sh\"\nsource \"$GOTO_LIB_DIR/module.sh\" # NEW - add after dependencies\nsource \"$GOTO_LIB_DIR/back-command.sh\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Dependency Rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Modules with no dependencies load first","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Modules depending on others load AFTER dependencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Main goto-function.sh loads LAST (depends on everything)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 4: Integrate with Main Function","type":"text"}]},{"type":"paragraph","content":[{"text":"Edit ","type":"text"},{"text":"lib/goto-function.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" to route commands to your module:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"goto() {\n case \"$1\" in\n module) # NEW\n if command -v goto_module &> /dev/null; then\n shift\n goto_module \"$@\"\n else\n echo \"⚠️ Module command not loaded\"\n fi\n return\n ;;\n esac\n}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 5: Add Tests (100% Coverage Required)","type":"text"}]},{"type":"paragraph","content":[{"text":"Test File Template:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# Test suite for [feature] functionality\n\nset -e\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\nsource \"$SCRIPT_DIR/lib/module.sh\"\n\n# Test counters\nTESTS_PASSED=0\nTESTS_FAILED=0\n\n# Test helper\npass() {\n echo \"✓ PASS: $1\"\n ((TESTS_PASSED++))\n}\n\nfail() {\n echo \"✗ FAIL: $1\"\n ((TESTS_FAILED++))\n}\n\n# Test 1: [Description]\ntest_feature() {\n # Arrange\n local input=\"test\"\n\n # Act\n local result=$(function_under_test \"$input\")\n\n # Assert\n if [[ \"$result\" == \"expected\" ]]; then\n pass \"Feature works\"\n else\n fail \"Feature failed: got '$result'\"\n fi\n}\n\n# Run tests\ntest_feature\n\n# Summary\necho \"\"\necho \"Tests passed: $TESTS_PASSED\"\necho \"Tests failed: $TESTS_FAILED\"\n\n[ $TESTS_FAILED -eq 0 ] && exit 0 || exit 1","type":"text"}]},{"type":"paragraph","content":[{"text":"Test Categories (ALL Required):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unit Tests","type":"text","marks":[{"type":"strong"}]},{"text":" - Test individual functions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Integration Tests","type":"text","marks":[{"type":"strong"}]},{"text":" - Test module interaction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Edge Cases","type":"text","marks":[{"type":"strong"}]},{"text":" - Test boundary conditions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Performance Tests","type":"text","marks":[{"type":"strong"}]},{"text":" - Validate speed requirements","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example from CET-77 (Recent Directories):","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Unit test\ntest_get_recent_dirs() {\n result=$(__goto_recent_dirs 5)\n [ $? -eq 0 ] && pass \"Get recent dirs\" || fail \"Get recent dirs failed\"\n}\n\n# Integration test\ntest_goto_recent_navigation() {\n goto recent 1\n [ $? -eq 0 ] && pass \"Navigate to recent dir\" || fail \"Navigation failed\"\n}\n\n# Edge case\ntest_empty_history() {\n rm -f ~/.goto_history\n result=$(goto recent)\n [[ \"$result\" == *\"No history\"* ]] && pass \"Empty history\" || fail \"Empty history check\"\n}\n\n# Performance test\ntest_recent_speed() {\n start=$(date +%s%N)\n __goto_recent_dirs 10\n end=$(date +%s%N)\n duration=$(((end - start) / 1000000))\n [ $duration -lt 10 ] && pass \"Recent dirs \u003c10ms\" || fail \"Too slow: ${duration}ms\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 6: Document API","type":"text"}]},{"type":"paragraph","content":[{"text":"Add to ","type":"text"},{"text":"docs/API.md","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Module API\n\n### `goto module`\n\n[Description of what the module does]\n\n**Signature:**\n```bash\ngoto module \u003csubcommand>","type":"text"}]},{"type":"paragraph","content":[{"text":"Subcommands:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"list","type":"text","marks":[{"type":"code_inline"}]},{"text":" - [Description]","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"add","type":"text","marks":[{"type":"code_inline"}]},{"text":" - [Description]","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Performance:","type":"text","marks":[{"type":"strong"}]},{"text":" [Target metrics]","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"goto module list\ngoto module add value","type":"text"}]},{"type":"paragraph","content":[{"text":"Return Codes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"0 - Success","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"1 - Error","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Implementation:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"lib/module.sh","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n**Example from CET-77:**\n```markdown\n## Recent Directories\n\n### `goto recent [n]`\n\nDisplay recently navigated directories in reverse chronological order.\n\n**Signature:**\n```bash\ngoto recent [n]","type":"text"}]},{"type":"paragraph","content":[{"text":"Parameters:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"n","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Optional number of recent directories to display (default: all)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Performance:","type":"text","marks":[{"type":"strong"}]},{"text":" \u003c10ms for history retrieval","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"goto recent # Show all recent directories\ngoto recent 5 # Show 5 most recent","type":"text"}]},{"type":"paragraph","content":[{"text":"Implementation:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"lib/recent-command.sh","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n#### Step 7: Update User Documentation\n\nAdd to `README.md`:\n\n```markdown\n### Module\n\n[User-facing description]\n\n```bash\ngoto module list # [Description]\ngoto module add # [Description]","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n#### Step 8: Performance Validation\n\nValidate performance meets targets:\n\n```bash\n# Add benchmark if performance-critical\ngoto benchmark module 10\n\n# Measure overhead\ntime goto_module list\n\n# Expected: \u003c100ms for navigation, \u003c10ms for lookups","type":"text"}]},{"type":"paragraph","content":[{"text":"Performance Targets:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cached navigation: \u003c100ms","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bookmark lookup: \u003c10ms","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cache speedup: >20x","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cache hit rate: >90%","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cache build: \u003c5s","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 9: Linear Issue Update & Commit","type":"text"}]},{"type":"paragraph","content":[{"text":"Update Linear Issue:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add implementation comment","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include test results","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include performance metrics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Link to commit","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Move to \"Complete\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Commit Format:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git commit -m \"feat: implement module feature (CET-XX)\n\n[Detailed explanation]\n\nFeatures:\n- Feature 1\n- Feature 2\n\nPerformance:\n- Metric: value\n\nTests:\n- X/X tests passing\n- 100% coverage\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \[email protected]>\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Commit Types:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"feat:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - New feature","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fix:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Bug fix","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"perf:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Performance improvement","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"refactor:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Code refactoring","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"test:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Add or update tests","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Documentation only","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"chore:","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Build, dependencies, or tooling","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example Commit from CET-85:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"feat: implement comprehensive benchmark suite (CET-85)\n\nImplement complete benchmark framework with 5 benchmark tests, helpers,\nworkspace generation, and CSV results storage.\n\nFeatures:\n- 5 benchmark tests: cached vs uncached, multi-level paths, max depth,\n cache build performance, parallel navigation\n- Benchmark helpers library with timing, stats, workspace management\n- CSV results storage in ~/.goto_benchmarks/\n- Performance target assertions (\u003c100ms navigation)\n- Comprehensive statistical analysis (min/max/mean/median/stddev)\n\nPerformance:\n- Cached navigation: 26ms (target: \u003c100ms) ✓\n- Cache build: 3-5s (target: \u003c5s) ✓\n- Speedup ratio: 8x (target: >20x, in progress)\n\nTests:\n- 5/5 benchmark tests passing\n- All performance targets met for Phase 1\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \[email protected]>","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Feature Checklist","type":"text"}]},{"type":"paragraph","content":[{"text":"Before submitting ANY feature:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Implementation complete","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Loaded in ","type":"text"},{"text":"goto.sh","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Integrated with main ","type":"text"},{"text":"goto","type":"text","marks":[{"type":"code_inline"}]},{"text":" function","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Tests written and passing (100% coverage)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"API documented in ","type":"text"},{"text":"docs/API.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"User documentation updated in ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Performance validated (if applicable)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Linear issue updated with results","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Committed with proper message format","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cache System Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"Purpose:","type":"text","marks":[{"type":"strong"}]},{"text":" O(1) folder lookup with automatic refresh","type":"text"}]},{"type":"paragraph","content":[{"text":"Implementation:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"lib/cache-index.sh","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Key Components:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_cache_build","type":"text","marks":[{"type":"code_inline"}]},{"text":" - O(n) index building","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_cache_lookup","type":"text","marks":[{"type":"code_inline"}]},{"text":" - O(1) hash table lookup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_cache_is_valid","type":"text","marks":[{"type":"code_inline"}]},{"text":" - TTL-based validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-refresh on stale cache (24-hour TTL)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Cache File Format:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"# unix-goto folder index cache\n# Version: 1.0\n# Built: 1697558122\n# Depth: 3\n# Format: folder_name|full_path|depth|last_modified\n#---\nunix-goto|/Users/manu/Documents/LUXOR/Git_Repos/unix-goto|8|1697558100\nGAI-3101|/Users/manu/Documents/LUXOR/PROJECTS/GAI-3101|6|1697558050","type":"text"}]},{"type":"paragraph","content":[{"text":"Performance:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build time: O(n) - 3-5s for 1200+ folders","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lookup time: O(1) - \u003c100ms target, 26ms actual","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Storage: ~42KB for 487 folders","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Cache Lookup Return Codes:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"__goto_cache_lookup \"folder\"\n# Returns:\n# 0 - Single match found (path to stdout)\n# 1 - Not found in cache\n# 2 - Multiple matches found (all paths to stdout)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Navigation Data Flow","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"User Input → goto \"project\"\n │\n ├─► Check special cases (list, index, benchmark, @bookmark)\n ├─► Check multi-level paths (contains /)\n ├─► Try cache lookup (O(1)) → Cache hit → Navigate\n ├─► Try direct folder match in search paths\n ├─► Recursive search (max depth 3)\n │ ├─► Single match → Navigate\n │ └─► Multiple matches → Show disambiguation\n └─► Natural language AI resolution (if spaces)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Bookmark System Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"Storage:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"~/.goto_bookmarks","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Format:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"work|/Users/manu/work|1697558122\napi|/Users/manu/code/api-server|1697558130","type":"text"}]},{"type":"paragraph","content":[{"text":"Key Functions:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_bookmark_add","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Add with validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_bookmark_remove","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Remove by name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_bookmark_get","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Retrieve path (O(1) grep)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_bookmark_goto","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Navigate to bookmark","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Performance Target:","type":"text","marks":[{"type":"strong"}]},{"text":" \u003c10ms lookup time","type":"text"}]},{"type":"paragraph","content":[{"text":"Usage:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bookmark add work /path/to/work\nbookmark remove work\ngoto @work","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"History Tracking Architecture","type":"text"}]},{"type":"paragraph","content":[{"text":"Storage:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"~/.goto_history","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Format:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"1697558122|/Users/manu/work\n1697558130|/Users/manu/Documents/LUXOR","type":"text"}]},{"type":"paragraph","content":[{"text":"Key Functions:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_track","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Append with auto-trim (max 100 entries)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_get_history","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Retrieve full history","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_recent_dirs","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Get unique directories in reverse chronological order","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"__goto_stack_push/pop","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Stack-based back navigation","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example Usage:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"goto recent # Show all recent directories\ngoto recent 5 # Show 5 most recent\nback # Go back to previous directory","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 1: Adding a Recent Directories Feature (CET-77)","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 1: Plan","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Feature: Recent Directories Command\nProblem: Users can't quickly revisit recently navigated directories\nInterface: goto recent [n]\nPerformance: \u003c10ms for history retrieval\nDependencies: history-tracking.sh\nTests: List recent, empty history, limit entries, navigate by number\nDocs: API.md, README.md","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 2: Create Module","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"lib/recent-command.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# unix-goto - Recent directories command\n# https://github.com/manutej/unix-goto\n\n# Get recent directories\n__goto_recent_dirs() {\n local limit=\"${1:-}\"\n\n if [ ! -f \"$GOTO_HISTORY_FILE\" ]; then\n return 1\n fi\n\n # Extract paths, reverse order, unique, limit\n local dirs=$(awk -F'|' '{print $2}' \"$GOTO_HISTORY_FILE\" | \\\n tac | \\\n awk '!seen[$0]++' | \\\n ${limit:+head -n \"$limit\"})\n\n echo \"$dirs\"\n return 0\n}\n\n# Recent command implementation\ngoto_recent() {\n local limit=\"${1:-}\"\n\n local dirs=$(__goto_recent_dirs \"$limit\")\n\n if [ -z \"$dirs\" ]; then\n echo \"No recent directories\"\n return 1\n fi\n\n echo \"$dirs\"\n return 0\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 3: Add to Loader","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"goto.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"source \"$GOTO_LIB_DIR/history-tracking.sh\"\nsource \"$GOTO_LIB_DIR/recent-command.sh\" # NEW","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 4: Integrate","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"lib/goto-function.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"goto() {\n case \"$1\" in\n recent)\n shift\n goto_recent \"$@\"\n return\n ;;\n esac\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 5: Add Tests","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"test-recent.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\nset -e\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\nsource \"$SCRIPT_DIR/lib/recent-command.sh\"\n\nTESTS_PASSED=0\nTESTS_FAILED=0\n\npass() { echo \"✓ PASS: $1\"; ((TESTS_PASSED++)); }\nfail() { echo \"✗ FAIL: $1\"; ((TESTS_FAILED++)); }\n\n# Test 1: Get recent directories\ntest_get_recent() {\n result=$(__goto_recent_dirs)\n [ $? -eq 0 ] && pass \"Get recent dirs\" || fail \"Failed\"\n}\n\n# Test 2: Empty history\ntest_empty_history() {\n rm -f ~/.goto_history\n result=$(goto_recent)\n [[ \"$result\" == *\"No recent\"* ]] && pass \"Empty history\" || fail \"Empty check\"\n}\n\n# Test 3: Limit results\ntest_limit_results() {\n result=$(__goto_recent_dirs 5)\n count=$(echo \"$result\" | wc -l)\n [ $count -le 5 ] && pass \"Limit to 5\" || fail \"Limit failed\"\n}\n\n# Run tests\ntest_get_recent\ntest_empty_history\ntest_limit_results\n\necho \"\"\necho \"Passed: $TESTS_PASSED, Failed: $TESTS_FAILED\"\n[ $TESTS_FAILED -eq 0 ] && exit 0 || exit 1","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 6: Document API","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"docs/API.md","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Recent Directories\n\n### `goto recent [n]`\n\nDisplay recently navigated directories in reverse chronological order.\n\n**Performance:** \u003c10ms for history retrieval\n\n**Examples:**\n```bash\ngoto recent # Show all recent directories\ngoto recent 5 # Show 5 most recent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n**Step 7: Update README** (`README.md`)\n```markdown\n### Recent Directories\n\nQuickly revisit recently navigated directories:\n\n```bash\ngoto recent # Show all recent directories\ngoto recent 5 # Show 5 most recent","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\n**Step 8: Validate Performance**\n```bash\ntime goto recent\n# Expected: \u003c10ms","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 9: Commit","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git commit -m \"feat: implement recent directories command (CET-77)\n\nAdd goto recent command to display recently navigated directories.\n\nFeatures:\n- List all recent directories\n- Limit to N most recent\n- Unique directories only\n- Reverse chronological order\n\nPerformance:\n- History retrieval: \u003c10ms ✓\n\nTests:\n- 3/3 tests passing\n- 100% coverage\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude \[email protected]>\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example 2: Adding Benchmark Suite (CET-85)","type":"text"}]},{"type":"paragraph","content":[{"text":"Complete benchmark implementation with helpers, workspace, and CSV storage.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Benchmark Structure","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"benchmarks/bench-cached-vs-uncached.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# Benchmark: Cached vs Uncached Navigation Performance\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nREPO_DIR=\"$SCRIPT_DIR/..\"\n\nsource \"$SCRIPT_DIR/bench-helpers.sh\"\nsource \"$REPO_DIR/lib/cache-index.sh\"\n\nmain() {\n bench_header \"Cached vs Uncached Navigation Performance\"\n\n echo \"Configuration:\"\n echo \" Iterations: 10\"\n echo \" Warmup: 3 runs\"\n echo \"\"\n\n benchmark_cached_vs_uncached\n\n generate_summary\n}\n\nbenchmark_cached_vs_uncached() {\n bench_section \"Benchmark: Cached vs Uncached Lookup\"\n\n # Setup workspace\n local workspace=$(bench_create_workspace \"medium\")\n\n # Phase 1: Uncached lookup\n echo \"Phase 1: Uncached lookup (no cache)\"\n echo \"─────────────────────────────────\"\n\n # Warmup\n bench_warmup \"__goto_cache_lookup unix-goto\" 3\n\n # Run benchmark\n local uncached_stats=$(bench_run \"uncached\" \\\n \"__goto_cache_lookup unix-goto\" 10)\n\n IFS=',' read -r uc_min uc_max uc_mean uc_median uc_stddev \u003c\u003c\u003c \"$uncached_stats\"\n\n bench_print_stats \"$uncached_stats\" \"Uncached Results\"\n\n # Phase 2: Cached lookup\n echo \"\"\n echo \"Phase 2: Cached lookup (with cache)\"\n echo \"─────────────────────────────────\"\n\n # Build cache\n __goto_cache_build\n\n # Warmup\n bench_warmup \"__goto_cache_lookup unix-goto\" 3\n\n # Run benchmark\n local cached_stats=$(bench_run \"cached\" \\\n \"__goto_cache_lookup unix-goto\" 10)\n\n IFS=',' read -r c_min c_max c_mean c_median c_stddev \u003c\u003c\u003c \"$cached_stats\"\n\n bench_print_stats \"$cached_stats\" \"Cached Results\"\n\n # Calculate speedup\n local speedup=$(bench_compare \"$uc_mean\" \"$c_mean\")\n\n echo \"\"\n echo \"Speedup Analysis:\"\n echo \" Speedup ratio: ${speedup}x\"\n\n # Assert targets\n bench_assert_target \"$c_mean\" 100 \"Cached navigation time\"\n\n # Save results\n bench_save_result \"cached_vs_uncached\" \"$uncached_stats\" \"uncached\"\n bench_save_result \"cached_vs_uncached\" \"$cached_stats\" \"cached\"\n\n # Cleanup\n bench_cleanup_workspace \"$workspace\"\n}\n\nmain\nexit 0","type":"text"}]},{"type":"paragraph","content":[{"text":"Benchmark Helpers","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"benchmarks/bench-helpers.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# Benchmark helper functions\n\nBENCH_RESULTS_DIR=\"${BENCH_RESULTS_DIR:-$HOME/.goto_benchmarks}\"\n\n# High-precision timing\nbench_time_ms() {\n local cmd=\"$*\"\n local start=$(date +%s%N)\n eval \"$cmd\" > /dev/null 2>&1\n local end=$(date +%s%N)\n echo $(((end - start) / 1000000))\n}\n\n# Calculate statistics\nbench_calculate_stats() {\n local values=(\"$@\")\n local count=${#values[@]}\n\n # Sort values\n IFS=

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.