Skill: garylooop/wheelspotter (version 1.0.0)

--- name: WheelSpotter version: 1.0.0 description: A wheel-spotting scout that finds reusable solutions before you build from scratch. Cost-controlled intelligent search with complexity-aware filtering, intent-based platform selection, and form consistency checks. author: YourName license: MIT dependency: python: - requests>=2.31.0 - pydantic>=2.0.0 triggers: - "is there an existing" - "looking for library" - "any existing solution" - "before implementing" - "avoid reinventing" - "is there a library for" - "find a tool that" - "need a package for" - "spot a wheel" - "find wheels" --- # WheelSpotter (v1.0) > 🎯 **WheelSpotter** — Your wheel-spotting scout. Spots reusable solutions before you build from scratch. **Core principle**: Solutions must be directly integrable—not flashy but unusable toys. --- ## When to Use ### ✅ Trigger Scenarios Load this skill when the user expresses these intents: | Pattern | Example | |---------|---------| | Looking for existing solutions | "Is there an existing PDF parsing library?" | | Avoiding duplicate work | "I don't want to reinvent the wheel..." | | Tech stack consultation | "What's a good Python data visualization library?" | | Quick integration needs | "I need an OCR API I can use right away" | | Pre-implementation research | "Implementing JWT auth—any existing solutions?" | | Wheel spotting | "Spot any wheels for image processing?" | **Keyword matches**: `is there`, `existing`, `wheel`, `library`, `framework`, `API`, `tool`, `solution`, `spot` ### ❌ Do NOT Trigger | Scenario | Reason | Suggestion | |----------|--------|------------| | User wants to build themselves | "I want to write my own..." | Assist with coding directly | | Highly customized requirements | "I need something that does X, Y, Z all at once..." | Suggest breaking down and searching separately | | Learning purposes | "I want to learn how to implement..." | Provide tutorials instead | | Tech stack already decided | "I'm using React to build..." | Move to development guidance | --- ## Design Principles | Principle | Description | Implementation | |-----------|-------------|----------------| | **Problem-Oriented** | Precisely solve "finding integrable wheels" | Sources classified by output form, exclude chatbots | | **Closed-Loop Delivery** | Clear "usable/unusable" conclusion with action | Results include `pip install` commands or self-build recommendation | | **High Adaptability** | Dynamic strategy based on complexity and intent | Complexity grading + intent-adaptive source selection | | **Progressive Improvement** | System gets smarter with each use | Feedback loops, result caching, vector memory | | **Transferable Leverage** | Core capabilities reusable elsewhere | Funnel engine, cost monitor as independent modules | | **Cost Red Line** | Search cost must be lower than self-build cost | Budget caps, tiered abandonment, early termination | --- ## Prerequisites ```bash pip install -r requirements.txt ``` **Environment**: - Python 3.8+ - Internet access for API calls - GitHub Token (optional, increases API limit to 5000 req/hour) --- ## Input/Output Specification ### Input Format ```python # Method 1: Natural language (parsed by agent) user_input = "I need a Python library to process Excel files" # Method 2: Structured input (optional) { "requirement": "process Excel files", "tech_stack": ["Python"], "intent": "library", "constraints": { "license": "MIT", "min_stars": 100, "last_updated": "12m" } } ``` ### Output Format ```json { "status": "found", "recommendations": [ { "name": "openpyxl", "source": "pypi", "url": "https://openpyxl.readthedocs.io/", "match_score": 0.92, "integration_score": 0.95, "action": "pip install openpyxl", "license": "MIT", "stars": 1200, "last_updated": "2 months ago", "warnings": [], "advice": "Recommended, mature and stable" } ], "fallback": null, "cost": { "tokens_used": 420, "time_seconds": 3.2, "estimated_time_saved": "~4 hours" } } ``` **Status values**: - `found`: Suitable solutions found - `not_found`: Recommend self-build - `needs_clarification`: Requirement unclear, need follow-up - `error`: Search failed, return error info --- ## Core Workflow ``` User Input ↓ [M0] Complexity Grading (~30 tokens) ↓ [M1] Intent Classification (~60 tokens) ↓ [Optional] Clarification (1-2 rounds if needed) ↓ [M2] Extract Keywords + Tech Entities (~150 tokens) ↓ [Search] Activate platforms by intent, parallel API calls ↓ [Hard Filter] Deprecated/activity/form matching ↓ [LLM Refinement] Multi-dimensional eval for ≤5 candidates (~300 tokens) ↓ Output recommendations + action commands + cost report ``` --- ## Implementation Details ### Step 1: Complexity Grading (M0) **Prompt Template**: ``` You are a development complexity assessment expert. Evaluate the requirement: - L1: Simple function/tool, solvable with dozens of lines - L2: Medium module, requires interface design - L3: Complex system, involves multiple components Requirement: {requirement} Output JSON only: { "complexity": "L2", "reason": "..." } ``` **Impact on Search Strategy**: | Complexity | Token Cap | Time Cap | Sources | Star Threshold | |------------|-----------|----------|---------|----------------| | L1 Simple | 300 | 8s | 2-3 | ≥10 | | L2 Medium | 600 | 12s | 3-5 | ≥50 | | L3 Complex | 800 | 15s | Full | ≥100 | ### Step 2: Intent Classification (M1) **Prompt Template**: ``` Analyze the requirement, determine desired output form (multiple allowed): - library: Library/framework integrable into code - service: Callable external API/service - tool: Standalone executable tool/CLI - reference: Code template/example/architecture reference - assistant: Conversational assistant (usually not a wheel, use cautiously) Requirement: {requirement} Output JSON only: { "intent": [...], "reason": "..." } ``` **Important**: If intent only contains `assistant`, return guidance without triggering search. ### Step 3: Platform Selection Matrix | Intent | Activate Sources | Do NOT Search | |--------|------------------|---------------| | library | GitHub, npm, PyPI, Maven, Crates.io | Conversational skill marketplaces | | service | MCP Hubs, HuggingFace API, RapidAPI | Pure code repos | | tool | GitHub Releases, Docker Hub, npm -g | Pure library platforms | | reference | Stack Overflow, GitHub Gist, Official docs | Distribution platforms | ### Step 4: Hard Filtering Rules ```python def hard_filter(candidate, complexity, intent): """Adaptive hard filtering""" # 1. Archived/Deprecated check if candidate.archived or candidate.deprecated: return False, "Archived or deprecated" # 2. Dynamic star threshold thresholds = {"L1": 10, "L2": 50, "L3": 100} if candidate.stars < thresholds[complexity]: return False, f"Insufficient stars ({candidate.stars} < {thresholds[complexity]})" # 3. Update time check if months_since_update > 24: return False, "Not updated in 24+ months" # 4. Form consistency check if intent == "library" and not has_package_indicator(candidate): return False, "Form mismatch: no library indicators" return True, "Passed" ``` ### Step 5: LLM Refinement **Multi-dimensional Scoring**: ``` Final Score = Semantic Similarity × 0.5 + Integration Feasibility × 0.3 + Activity Normalization × 0.2 ``` **Refinement Prompt**: ``` You are a technical solution evaluator. Assess this candidate: Requirement: {requirement} Candidate: {candidate} Evaluation dimensions: 1. Semantic match (0-1): Does it truly solve the need? 2. Integration feasibility (0-1): Can user try within 1 hour? 3. Activity score (0-1): Based on stars, update frequency 4. License compatibility: Common open source license? 5. Known issues: Major bugs or security vulnerabilities? Output JSON: { "semantic_score": 0.9, "integration_score": 0.85, "activity_score": 0.7, "final_score": 0.83, "license_ok": true, "warnings": [], "advice": "Recommended, but note..." } ``` --- ## Search Script See [scripts/search.py](scripts/search.py) for the standalone implementation. **Usage**: ```bash # Basic usage python scripts/search.py --query "python pdf parser" --complexity L2 --intent library # Multiple platforms python scripts/search.py -q "python excel read write" -c L2 -i library -p github,pypi # With GitHub token (recommended) python scripts/search.py -q "react charting library" -c L3 --token $GITHUB_TOKEN ``` **Parameters**: | Parameter | Short | Description | Default | |-----------|-------|-------------|---------| | `--query` | `-q` | Search keywords (required) | - | | `--complexity` | `-c` | L1/L2/L3 | L2 | | `--intent` | `-i` | library/service/tool/reference | library | | `--platforms` | `-p` | Comma-separated platforms | github | | `--limit` | `-l` | Max results per platform | 20 | | `--token` | `-t` | GitHub token (optional) | - | | `--output` | `-o` | Output file (optional) | stdout | --- ## Error Handling | Error Condition | Strategy | User Message | |-----------------|----------|--------------| | GitHub API rate limit (403) | Fallback to web search or prompt for token | "GitHub API limit reached. Please retry later or configure a GitHub token." | | Network timeout (>10s) | Retry once, return partial results on failure | "Some platforms timed out. Returning available results." | | No matching intent | Don't trigger search, guide user to clarify | "Your requirement may need custom development. Continue searching?" | | JSON parse failure | Log error, return raw response | "Failed to parse search results. Please check raw data." | | All platforms failed | Return graceful degradation | "Search service temporarily unavailable. Please retry later or research manually." | --- ## Cost Control ### Three-Tier Budget System | Level | Token Cap | Time Cap | Strategy | |-------|-----------|----------|----------| | L1 Simple | 300 | 8s | Quick abandonment, recommend self-build if not found | | L2 Medium | 600 | 12s | Moderate resources | | L3 Complex | 800 | 15s | Full resources by intent matrix | ### Early Termination Conditions - Hard filter yields 0 candidates → Immediately output "not found, recommend self-build" - Intent is only `assistant` → Don't trigger search - High-match result found (score > 0.9) → Early termination ### Graceful Degradation ``` ⚠️ Search cost approaching or exceeding self-build cost (estimated self-build: X hours). Found partial matches: - [Project Name] (match score: 0.65) Suggestion: Try the above first. If requirements not met, direct implementation may be faster. ``` --- ## Usage Examples ### Example 1: Library Search (L2) **Input**: ``` I need a Python library to read and write Excel files ``` **Agent Analysis**: - Complexity: L2 (medium module) - Intent: library - Keywords: python, excel, read, write **Script Call**: ```bash python scripts/search.py -q "python excel read write" -c L2 -i library -p github,pypi ``` **Output**: ```json { "status": "found", "recommendations": [ { "name": "openpyxl/openpyxl", "action": "pip install openpyxl", "match_score": 0.92, "advice": "Recommended, comprehensive features" }, { "name": "pandas-dev/pandas", "action": "pip install pandas", "match_score": 0.88, "advice": "Use pandas for data analysis needs" } ] } ``` ### Example 2: Simple Requirement (L1 - Quick Abandonment) **Input**: ``` I need to validate email format ``` **Agent Judgment**: - Complexity: L1 (~10 lines of regex) - Recommendation: Direct implementation is faster than searching **Output**: ```json { "status": "not_found", "message": "This is an L1 simple requirement. Recommend direct implementation.", "code_snippet": "import re\nre.match(r'^[\\w.-]+@[\\w.-]+\\.\\w+$', email)" } ``` ### Example 3: Service Discovery (L3) **Input**: ``` I need an OCR service that can batch process PDFs via API, supporting Chinese and English ``` **Agent Analysis**: - Complexity: L3 (complex system) - Intent: service - Keywords: ocr, api, pdf, batch, chinese, english **Output**: ```json { "status": "found", "recommendations": [ { "name": "Tesseract OCR", "type": "library + CLI", "action": "pip install pytesseract or docker run tesseract", "match_score": 0.85, "warnings": ["Requires self-hosting"] }, { "name": "Google Cloud Vision API", "type": "cloud service", "action": "Apply for API key then call", "match_score": 0.90, "warnings": ["Paid service"] } ] } ``` --- ## Implementation Roadmap | Phase | Features | Status | Value | |-------|----------|--------|-------| | **M1** | Complexity + Intent + Search + Hard Filter | ✅ Complete | Core functionality | | **M2** | Multi-turn clarification + Quick/Deep mode | ⏳ Planned | Reduce ineffective searches | | **M3** | Result caching + Adaptive thresholds | ⏳ Planned | Lower cost | | **M4** | Security scanning (OSV API) | ⏳ Planned | Production safety | | **M5** | Vector pre-filtering (bge-small) | ⏳ Planned | Improve precision | **Recommendation**: M1 is production-ready. M2-M5 are optional enhancements. --- ## Limitations | Limitation | Description | Mitigation | |------------|-------------|------------| | GitHub API limits | 60 req/hour unauthenticated | Configure GitHub token | | PyPI search | Exact package names only | Combine with GitHub search | | No vector pre-filter | Not implemented in current version | Planned for M5 | | No vulnerability scan | OSV not integrated | Planned for M4 | --- ## Resource Index | Resource | Location | Description | |----------|----------|-------------| | Search script | `scripts/search.py` | Standalone multi-platform search | | Dependencies | `requirements.txt` | Python package requirements | | License | `LICENSE` | MIT License | --- ## Best Practices 1. **Extract specific keywords** before calling the script 2. **Classify complexity and intent accurately** - determines search strategy 3. **Check license compatibility** before final recommendation 4. **Provide context** when requirements are ambiguous 5. **Respect early termination** - L1 requirements should self-build if not found --- ## Why WheelSpotter Works WheelSpotter isn't a "comprehensive search engine" — it's your **wheel-spotting scout**: - 🎯 **First determines if search is worthwhile** - Complexity grading - 📍 **Then determines where to search most accurately** - Intent-driven platform selection - 💰 **Gets decision evidence at lowest cost** - Budget control - ✅ **Always provides next action** - Closed-loop delivery --- ## Changelog | Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-04-28 | Renamed to WheelSpotter, added triggers, error handling, standalone script, I/O spec |

path: README.md
content: # WheelSpotter

> 🎯 Your wheel-spotting scout. Finds reusable solutions before you build from scratch.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## What It Does

**WheelSpotter** spots reusable "wheels" before you write code. The core principle: **solutions must be directly integrable—not flashy but unusable toys.**

## Key Features

- 🎯 **Complexity-aware filtering** - Different search strategies for L1 (simple), L2 (medium), L3 (complex) requirements
- 🔍 **Intent-based platform selection** - Automatically activates relevant platforms (GitHub, PyPI, npm, Maven, Crates.io)
- 💰 **Cost control** - Token/time budgets with early termination when search cost exceeds self-build cost
- ✅ **Closed-loop delivery** - Returns actionable commands (`pip install X`) or clear "self-build" recommendation

## Quick Start

```bash
# Clone the repository
git clone https://github.com/yourusername/wheelspotter.git
cd wheelspotter

# Install dependencies
pip install -r requirements.txt

# Basic usage
python scripts/search.py -q "python pdf parser" -c L2 -i library

# Multiple platforms
python scripts/search.py -q "react charting" -c L3 -p github,npm

# With GitHub token (recommended for higher rate limits)
python scripts/search.py -q "rust web framework" --token $GITHUB_TOKEN
```

## Usage Examples

### Find a Python library (L2 complexity)
```bash
python scripts/search.py -q "python excel read write" -c L2 -i library -p github,pypi
```

Output:
```json
{
  "status": "found",
  "recommendations": [
    {
      "name": "openpyxl/openpyxl",
      "source": "github",
      "url": "https://github.com/openpyxl/openpyxl",
      "stars": 3200,
      "action": "pip install openpyxl"
    }
  ]
}
```

### Find a Rust crate (L3 complexity)
```bash
python scripts/search.py -q "rust async runtime" -c L3 -p github,crates
```

### Simple function (L1 - recommends self-build)
```bash
python scripts/search.py -q "email validation" -c L1
```
Returns: "No suitable wheels found. Recommend self-build." (because email validation is ~10 lines of regex)

## CLI Parameters

| Parameter | Short | Description | Default |
|-----------|-------|-------------|---------|
| `--query` | `-q` | Search keywords (required) | - |
| `--complexity` | `-c` | L1/L2/L3 | L2 |
| `--intent` | `-i` | library/service/tool/reference | library |
| `--platforms` | `-p` | Comma-separated list | github |
| `--limit` | `-l` | Max results per platform | 20 |
| `--token` | `-t` | GitHub token (optional) | - |
| `--output` | `-o` | Output file | stdout |

## Platform Support

| Platform | Best For | Note |
|----------|----------|------|
| GitHub | All intents | Primary source, star-based ranking |
| PyPI | Python libraries | Exact package name search |
| npm | JavaScript packages | Popularity-based ranking |
| Maven | Java libraries | Central repository search |
| Crates.io | Rust crates | Download-based ranking |

## How It Works

```
User Query
    ↓
[1] Complexity Grading (L1/L2/L3)
    ↓
[2] Intent Classification (library/service/tool/reference)
    ↓
[3] Multi-Platform Search (parallel API calls)
    ↓
[4] Hard Filtering (stars, update time, archived status)
    ↓
[5] Top 5 Recommendations with actionable commands
```

### Cost Control Matrix

| Complexity | Token Budget | Time Budget | Star Threshold |
|------------|--------------|-------------|----------------|
| L1 Simple | 300 | 8s | ≥10 |
| L2 Medium | 600 | 12s | ≥50 |
| L3 Complex | 800 | 15s | ≥100 |

## Project Structure

```
wheelspotter/
├── SKILL.md              # Skill definition (for AI agents)
├── README.md             # This file
├── scripts/
│   └── search.py         # Standalone search script (wheelspot CLI)
├── requirements.txt      # Python dependencies
└── LICENSE              # MIT License
```

## Use as a Skill

This project is designed to work as a WorkBuddy skill. The `SKILL.md` file contains:
- Trigger conditions (when to activate)
- Workflow steps (complexity grading, intent classification, filtering)
- Integration instructions

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

Named "WheelSpotter" because it spots reusable wheels before you build from scratch.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)