Add comprehensive tests for vector/semantic search functionality

- Implement full coverage tests for Embedder model loading and embedding generation - Add CRUD operations and caching tests for VectorStore - Include cosine similarity computation tests - Validate semantic search accuracy and relevance through various queries - Establish performance benchmarks for embedding and search operations - Ensure edge cases and error handling are covered - Test thread safety and concurrent access scenarios - Verify availability of semantic search dependencies
2026-02-13 02:41:50 +08:00 · 2025-12-14 17:17:09 +08:00
parent 8d542b8e45
commit 79a2953862
47 changed files with 11208 additions and 4336 deletions
--- a/.claude/rules/active_memory.md
+++ b/.claude/rules/active_memory.md
@@ -0,0 +1,13 @@
+# Active Memory
+
+> Auto-generated understanding of frequently accessed files using GEMINI.
+> Last updated: 2025-12-14T08:59:41.526Z
+> Files analyzed: 10
+> CLI Tool: gemini
+
+---
+
+[object Object]
+
+---
+
--- a/.claude/rules/active_memory_config.json
+++ b/.claude/rules/active_memory_config.json
@@ -0,0 +1,4 @@
+{
+  "interval": "manual",
+  "tool": "gemini"
+}
--- a/.claude/rules/cli-tools-usage.md
+++ b/.claude/rules/cli-tools-usage.md
@@ -0,0 +1,36 @@
+# CLI Tools Usage Rules
+
+## Tool Selection
+
+### Gemini & Qwen
+**Use for**: Analysis, documentation, code exploration, architecture review
+- Default MODE: `analysis` (read-only)
+- Prefer Gemini; use Qwen as fallback
+- Large context window, pattern recognition
+
+### Codex
+**Use for**: Feature implementation, bug fixes, autonomous development
+- Requires explicit `--mode auto` or `--mode write`
+- Best for: Implementation, testing, automation
+
+## Core Principles
+
+- Use tools early and often - tools are faster and more thorough
+- Always use `ccw cli exec` for consistent parameter handling
+- ALWAYS reference exactly ONE template in RULES section
+- Require EXPLICIT `--mode write` or `--mode auto` for modifications
+- NEVER use escape characters (`\$`, `\"`, `\'`) in CLI commands
+
+## Permission Framework
+
+- `analysis` (default): Read-only, safe for auto-execution
+- `write`: Requires explicit `--mode write` - creates/modifies/deletes files
+- `auto`: Requires explicit `--mode auto` - full autonomous operations (Codex only)
+
+## Timeout Guidelines
+
+- Simple (5-10min): Analysis, search
+- Medium (10-20min): Refactoring, documentation
+- Complex (20-60min): Implementation, migration
+- Heavy (60-120min): Large codebase, multi-file operations
+- Codex multiplier: 3x allocated time (minimum 15min)
--- a/.claude/rules/coding-philosophy.md
+++ b/.claude/rules/coding-philosophy.md
@@ -0,0 +1,42 @@
+# Coding Philosophy
+
+## Core Beliefs
+
+- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
+- **Embrace extreme simplicity** - Complexity is the root of all evil
+- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
+- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
+- **Never break backward compatibility** - Existing functionality is sacred and inviolable
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Clear intent over clever code** - Be boring and obvious
+- **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
+- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
+
+## Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Fix, Don't Hide
+
+**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
+
+**NEVER**:
+- Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
+- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause
+
+**ALWAYS**:
+- Plan complex tasks thoroughly before implementation
+- Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
+- Track progress using TODO checklists for complex tasks
+- Validate planning documents before starting development
+- Commit working code incrementally
+- Update plan documentation and progress tracking as you go
+- Learn from existing implementations
+- Stop after 3 failed attempts and reassess
+- **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
--- a/.claude/rules/context-requirements.md
+++ b/.claude/rules/context-requirements.md
@@ -0,0 +1,7 @@
+# Context Requirements
+
+Before implementation, always:
+
+- Identify 3+ existing similar patterns before implementation
+- Map dependencies and integration points
+- Understand testing framework and coding conventions
--- a/.claude/rules/intelligent-tools-strategy.md
+++ b/.claude/rules/intelligent-tools-strategy.md
@@ -0,0 +1,431 @@
+# Intelligent Tools Selection Strategy
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Tool Specifications](#tool-specifications)
+3. [Prompt Template](#prompt-template)
+4. [CLI Execution](#cli-execution)
+5. [Configuration](#configuration)
+6. [Best Practices](#best-practices)
+
+---
+
+## Quick Reference
+
+### Universal Prompt Template
+
+```
+PURPOSE: [what] + [why] + [success criteria] + [constraints/scope]
+TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action]
+MODE: [analysis|write|auto]
+CONTEXT: @[file patterns] | Memory: [session/tech/module context]
+EXPECTED: [deliverable format] + [quality criteria] + [structure requirements]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [domain constraints] | MODE=[permission]
+```
+
+### Intent Capture Checklist (Before CLI Execution)
+
+**⚠️ CRITICAL**: Before executing any CLI command, verify these intent dimensions:
+**Intent Validation Questions**:
+- [ ] Is the objective specific and measurable?
+- [ ] Are success criteria defined?
+- [ ] Is the scope clearly bounded?
+- [ ] Are constraints and limitations stated?
+- [ ] Is the expected output format clear?
+- [ ] Is the action level (read/write) explicit?
+
+### Tool Selection
+
+| Task Type | Tool | Fallback |
+|-----------|------|----------|
+| Analysis/Documentation | Gemini | Qwen |
+| Implementation/Testing | Codex | - |
+
+### CCW Command Syntax
+
+```bash
+ccw cli exec "<prompt>" --tool <gemini|qwen|codex> --mode <analysis|write|auto>
+ccw cli exec "<prompt>" --tool gemini --cd <path> --includeDirs <dirs>
+ccw cli exec "<prompt>" --resume [id]  # Resume previous session
+```
+
+### CLI Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `ccw cli status` | Check CLI tools availability |
+| `ccw cli exec "<prompt>"` | Execute a CLI tool |
+| `ccw cli exec "<prompt>" --resume [id]` | Resume a previous session |
+| `ccw cli history` | Show execution history |
+| `ccw cli detail <id>` | Show execution detail |
+
+### Core Principles
+
+- **Use tools early and often** - Tools are faster and more thorough
+- **Unified CLI** - Always use `ccw cli exec` for consistent parameter handling
+- **One template required** - ALWAYS reference exactly ONE template in RULES (use universal fallback if no specific match)
+- **Write protection** - Require EXPLICIT `--mode write` or `--mode auto`
+- **No escape characters** - NEVER use `\$`, `\"`, `\'` in CLI commands
+
+---
+
+## Tool Specifications
+
+### MODE Options
+
+| Mode | Permission | Use For | Specification |
+|------|------------|---------|---------------|
+| `analysis` | Read-only (default) | Code review, architecture analysis, pattern discovery | Auto for Gemini/Qwen |
+| `write` | Create/Modify/Delete | Documentation, code creation, file modifications | Requires `--mode write` |
+| `auto` | Full operations | Feature implementation, bug fixes, autonomous development | Codex only, requires `--mode auto` |
+
+### Gemini & Qwen
+
+**Via CCW**: `ccw cli exec "<prompt>" --tool gemini` or `--tool qwen`
+
+**Characteristics**:
+- Large context window, pattern recognition
+- Best for: Analysis, documentation, code exploration, architecture review
+- Default MODE: `analysis` (read-only)
+- Priority: Prefer Gemini; use Qwen as fallback
+
+**Models** (override via `--model`):
+- Gemini: `gemini-2.5-pro`
+- Qwen: `coder-model`, `vision-model`
+
+**Error Handling**: HTTP 429 may show error but still return results - check if results exist
+
+### Codex
+
+**Via CCW**: `ccw cli exec "<prompt>" --tool codex --mode auto`
+
+**Characteristics**:
+- Autonomous development, mathematical reasoning
+- Best for: Implementation, testing, automation
+- No default MODE - must explicitly specify `--mode write` or `--mode auto`
+
+**Models**: `gpt-5.2`
+
+### Session Resume
+
+**Resume via `--resume` parameter**:
+
+```bash
+ccw cli exec "Continue analyzing" --resume              # Resume last session
+ccw cli exec "Fix issues found" --resume <id>           # Resume specific session
+```
+
+| Value | Description |
+|-------|-------------|
+| `--resume` (empty) | Resume most recent session |
+| `--resume <id>` | Resume specific execution ID |
+
+**Context Assembly** (automatic):
+```
+=== PREVIOUS CONVERSATION ===
+USER PROMPT: [Previous prompt]
+ASSISTANT RESPONSE: [Previous output]
+=== CONTINUATION ===
+[Your new prompt]
+```
+
+**Tool Behavior**: Codex uses native `codex resume`; Gemini/Qwen assembles context as single prompt
+
+---
+
+## Prompt Template
+
+### Template Structure
+
+Every command MUST include these fields:
+
+| Field | Purpose | Components | Bad Example | Good Example |
+|-------|---------|------------|-------------|--------------|
+| **PURPOSE** | Goal + motivation + success | What + Why + Success Criteria + Constraints | "Analyze code" | "Identify security vulnerabilities in auth module to pass compliance audit; success = all OWASP Top 10 addressed; scope = src/auth/** only" |
+| **TASK** | Actionable steps | Specific verbs + targets | "• Review code • Find issues" | "• Scan for SQL injection in query builders • Check XSS in template rendering • Verify CSRF token validation" |
+| **MODE** | Permission level | analysis / write / auto | (missing) | "analysis" or "write" |
+| **CONTEXT** | File scope + history | File patterns + Memory | "@**/*" | "@src/auth/**/*.ts @shared/utils/security.ts \| Memory: Previous auth refactoring (WFS-001)" |
+| **EXPECTED** | Output specification | Format + Quality + Structure | "Report" | "Markdown report with: severity levels (Critical/High/Medium/Low), file:line references, remediation code snippets, priority ranking" |
+| **RULES** | Template + constraints | $(cat template) + domain rules | (missing) | "$(cat ~/.claude/.../security.txt) \| Focus on authentication \| Ignore test files \| analysis=READ-ONLY" |
+
+
+### CONTEXT Configuration
+
+**Format**: `CONTEXT: [file patterns] | Memory: [memory context]`
+
+#### File Patterns
+
+| Pattern | Scope |
+|---------|-------|
+| `@**/*` | All files (default) |
+| `@src/**/*.ts` | TypeScript in src |
+| `@../shared/**/*` | Sibling directory (requires `--includeDirs`) |
+| `@CLAUDE.md` | Specific file |
+
+#### Memory Context
+
+Include when building on previous work:
+
+```bash
+# Cross-task reference
+Memory: Building on auth refactoring (commit abc123), implementing refresh tokens
+
+# Cross-module integration
+Memory: Integration with auth module, using shared error patterns from @shared/utils/errors.ts
+```
+
+**Memory Sources**:
+- **Related Tasks**: Previous refactoring, extensions, conflict resolution
+- **Tech Stack Patterns**: Framework conventions, security guidelines
+- **Cross-Module References**: Integration points, shared utilities, type dependencies
+
+#### Pattern Discovery Workflow
+
+For complex requirements, discover files BEFORE CLI execution:
+
+```bash
+# Step 1: Discover files
+rg "export.*Component" --files-with-matches --type ts
+
+# Step 2: Build CONTEXT
+CONTEXT: @components/Auth.tsx @types/auth.d.ts | Memory: Previous type refactoring
+
+# Step 3: Execute CLI
+ccw cli exec "..." --tool gemini --cd src
+```
+
+### RULES Configuration
+
+**Format**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]`
+
+**⚠️ MANDATORY**: Exactly ONE template reference is REQUIRED. Select from Task-Template Matrix or use universal fallback:
+- `universal/00-universal-rigorous-style.txt` - For precision-critical tasks (default fallback)
+- `universal/00-universal-creative-style.txt` - For exploratory tasks
+
+**Command Substitution Rules**:
+- Use `$(cat ...)` directly - do NOT read template content first
+- NEVER use escape characters: `\$`, `\"`, `\'`
+- Tilde expands correctly in prompt context
+
+**Examples**:
+```bash
+# Specific template (preferred)
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on auth | analysis=READ-ONLY
+
+# Universal fallback (when no specific template matches)
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/universal/00-universal-rigorous-style.txt) | Focus on security patterns | analysis=READ-ONLY
+```
+
+### Template System
+
+**Base Path**: `~/.claude/workflows/cli-templates/prompts/`
+
+**Naming Convention**:
+- `00-*` - Universal fallbacks (when no specific match)
+- `01-*` - Universal, high-frequency
+- `02-*` - Common specialized
+- `03-*` - Domain-specific
+
+**Universal Templates**:
+
+| Template | Use For |
+|----------|---------|
+| `universal/00-universal-rigorous-style.txt` | Precision-critical, systematic methodology |
+| `universal/00-universal-creative-style.txt` | Exploratory, innovative solutions |
+
+**Task-Template Matrix**:
+
+| Task Type | Template |
+|-----------|----------|
+| **Analysis** | |
+| Execution Tracing | `analysis/01-trace-code-execution.txt` |
+| Bug Diagnosis | `analysis/01-diagnose-bug-root-cause.txt` |
+| Code Patterns | `analysis/02-analyze-code-patterns.txt` |
+| Document Analysis | `analysis/02-analyze-technical-document.txt` |
+| Architecture Review | `analysis/02-review-architecture.txt` |
+| Code Review | `analysis/02-review-code-quality.txt` |
+| Performance | `analysis/03-analyze-performance.txt` |
+| Security | `analysis/03-assess-security-risks.txt` |
+| **Planning** | |
+| Architecture | `planning/01-plan-architecture-design.txt` |
+| Task Breakdown | `planning/02-breakdown-task-steps.txt` |
+| Component Design | `planning/02-design-component-spec.txt` |
+| Migration | `planning/03-plan-migration-strategy.txt` |
+| **Development** | |
+| Feature | `development/02-implement-feature.txt` |
+| Refactoring | `development/02-refactor-codebase.txt` |
+| Tests | `development/02-generate-tests.txt` |
+| UI Component | `development/02-implement-component-ui.txt` |
+| Debugging | `development/03-debug-runtime-issues.txt` |
+
+---
+
+## CLI Execution
+
+### Command Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--tool <tool>` | gemini, qwen, codex | gemini |
+| `--mode <mode>` | analysis, write, auto | analysis |
+| `--model <model>` | Model override | auto-select |
+| `--cd <path>` | Working directory | current |
+| `--includeDirs <dirs>` | Additional directories (comma-separated) | none |
+| `--timeout <ms>` | Timeout in milliseconds | 300000 |
+| `--resume [id]` | Resume previous session | - |
+| `--no-stream` | Disable streaming | false |
+
+### Directory Configuration
+
+#### Working Directory (`--cd`)
+
+When using `--cd`:
+- `@**/*` = Files within working directory tree only
+- CANNOT reference parent/sibling via @ alone
+- Must use `--includeDirs` for external directories
+
+#### Include Directories (`--includeDirs`)
+
+**TWO-STEP requirement for external files**:
+1. Add `--includeDirs` parameter
+2. Reference in CONTEXT with @ patterns
+
+```bash
+# Single directory
+ccw cli exec "CONTEXT: @**/* @../shared/**/*" --cd src/auth --includeDirs ../shared
+
+# Multiple directories
+ccw cli exec "..." --cd src/auth --includeDirs ../shared,../types,../utils
+```
+
+**Rule**: If CONTEXT contains `@../dir/**/*`, MUST include `--includeDirs ../dir`
+
+**Benefits**: Excludes unrelated directories, reduces token usage
+
+### CCW Parameter Mapping
+
+CCW automatically maps to tool-specific syntax:
+
+| CCW Parameter | Gemini/Qwen | Codex |
+|---------------|-------------|-------|
+| `--cd <path>` | `cd <path> &&` | `-C <path>` |
+| `--includeDirs <dirs>` | `--include-directories` | `--add-dir` (per dir) |
+| `--mode write` | `--approval-mode yolo` | `-s danger-full-access` |
+| `--mode auto` | N/A | `-s danger-full-access` |
+
+### Command Examples
+
+#### Task-Type Specific Templates
+
+**Analysis Task** (Security Audit):
+```bash
+ccw cli exec "
+PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation
+TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure
+MODE: analysis
+CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions
+EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/03-assess-security-risks.txt) | Focus on authentication | Ignore test files | analysis=READ-ONLY
+" --tool gemini --cd src/auth --timeout 600000
+```
+
+**Implementation Task** (New Feature):
+```bash
+ccw cli exec "
+PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients
+TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services
+MODE: auto
+CONTEXT: @src/middleware/**/* @src/config/**/* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts
+EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow existing middleware patterns | No breaking changes | auto=FULL
+" --tool codex --mode auto --timeout 1800000
+```
+
+**Bug Fix Task**:
+```bash
+ccw cli exec "
+PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix
+TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility
+MODE: analysis
+CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production
+EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on resource cleanup | analysis=READ-ONLY
+" --tool gemini --cd src --timeout 900000
+```
+
+**Refactoring Task**:
+```bash
+ccw cli exec "
+PURPOSE: Refactor payment processing to use strategy pattern for multi-gateway support; no functional changes; all existing tests must pass
+TASK: • Extract gateway interface from current implementation • Create strategy classes for Stripe, PayPal • Implement factory for gateway selection • Migrate existing code to use strategies
+MODE: write
+CONTEXT: @src/payments/**/* @src/types/payment.ts | Memory: Currently only Stripe, adding PayPal next sprint, must support future gateways
+EXPECTED: Refactored code with: strategy interface, concrete implementations, factory class, updated tests, migration checklist
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-refactor-codebase.txt) | Preserve all existing behavior | Tests must pass | write=CREATE/MODIFY/DELETE
+" --tool gemini --mode write --timeout 1200000
+```
+---
+
+## Configuration
+
+### Timeout Allocation
+
+**Minimum**: 5 minutes (300000ms)
+
+| Complexity | Range | Examples |
+|------------|-------|----------|
+| Simple | 5-10min (300000-600000ms) | Analysis, search |
+| Medium | 10-20min (600000-1200000ms) | Refactoring, documentation |
+| Complex | 20-60min (1200000-3600000ms) | Implementation, migration |
+| Heavy | 60-120min (3600000-7200000ms) | Large codebase, multi-file |
+
+**Codex Multiplier**: 3x allocated time (minimum 15min / 900000ms)
+
+```bash
+ccw cli exec "<prompt>" --tool gemini --timeout 600000   # 10 min
+ccw cli exec "<prompt>" --tool codex --timeout 1800000   # 30 min
+```
+
+### Permission Framework
+
+**Single-Use Authorization**: Each execution requires explicit user instruction. Previous authorization does NOT carry over.
+
+**Mode Hierarchy**:
+- `analysis` (default): Read-only, safe for auto-execution
+- `write`: Requires explicit `--mode write`
+- `auto`: Requires explicit `--mode auto`
+- **Exception**: User provides clear instructions like "modify", "create", "implement"
+
+---
+
+## Best Practices
+
+### Workflow Principles
+
+- **Use CCW unified interface** for all executions
+- **Always include template** - Use Task-Template Matrix or universal fallback
+- **Be specific** - Clear PURPOSE, TASK, EXPECTED fields
+- **Include constraints** - File patterns, scope in RULES
+- **Leverage memory context** when building on previous work
+- **Discover patterns first** - Use rg/MCP before CLI execution
+- **Default to full context** - Use `@**/*` unless specific files needed
+
+### Workflow Integration
+
+| Phase | Command |
+|-------|---------|
+| Understanding | `ccw cli exec "<prompt>" --tool gemini` |
+| Architecture | `ccw cli exec "<prompt>" --tool gemini` |
+| Implementation | `ccw cli exec "<prompt>" --tool codex --mode auto` |
+| Quality | `ccw cli exec "<prompt>" --tool codex --mode write` |
+
+### Planning Checklist
+
+- [ ] **Purpose defined** - Clear goal and intent
+- [ ] **Mode selected** - `--mode analysis|write|auto`
+- [ ] **Context gathered** - File references + memory (default `@**/*`)
+- [ ] **Directory navigation** - `--cd` and/or `--includeDirs`
+- [ ] **Tool selected** - `--tool gemini|qwen|codex`
+- [ ] **Template applied (REQUIRED)** - Use specific or universal fallback template
+- [ ] **Constraints specified** - Scope, requirements
+- [ ] **Timeout configured** - Based on complexity
--- a/.claude/rules/project-integration.md
+++ b/.claude/rules/project-integration.md
@@ -0,0 +1,22 @@
+# Project Integration Rules
+
+## Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+## Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Content Uniqueness Rules
+
+- **Each layer owns its abstraction level** - no content sharing between layers
+- **Reference, don't duplicate** - point to other layers, never copy content
+- **Maintain perspective** - each layer sees the system at its appropriate scale
+- **Avoid implementation creep** - higher layers stay architectural
--- a/.claude/rules/tool-selection.md
+++ b/.claude/rules/tool-selection.md
@@ -0,0 +1,88 @@
+# Tool Selection Rules
+
+## Context Gathering
+
+### Use Exa
+- Researching external APIs, libraries, frameworks
+- Need recent documentation beyond knowledge cutoff
+- Looking for implementation examples in public repos
+- User mentions specific library/framework names
+- Questions about "best practices" or "how does X work"
+
+### Use read_file (MCP)
+- Reading multiple related files at once
+- Directory traversal with pattern matching
+- Searching file content with regex
+- Need to limit depth/file count for large directories
+- Batch operations on multiple files
+- Pattern-based filtering (glob + content regex)
+
+### Use codex_lens
+- Large codebase (>500 files) requiring repeated searches
+- Need semantic understanding of code relationships
+- Working across multiple sessions
+- Symbol-level navigation needed
+- Finding all implementations of interface/class
+- Tracking function calls across codebase
+
+### Use smart_search
+- Unknown file locations
+- Concept/semantic search ("authentication logic", "payment processing")
+- Medium-sized codebase (100-500 files)
+- One-time or infrequent searches
+- Natural language queries about code structure
+
+**Mode Selection**:
+- `auto`: Let tool decide (default)
+- `exact`: Known exact pattern
+- `fuzzy`: Typo-tolerant search
+- `semantic`: Concept-based search
+- `graph`: Dependency analysis
+
+## File Modification
+
+### Use edit_file (MCP)
+- Built-in Edit tool failed 1+ times
+- Need dry-run preview before applying changes
+- Need line-based operations (insert_after, insert_before)
+- Need to replace all occurrences at once
+- Built-in Edit returns "old_string not found"
+- Whitespace/formatting issues in built-in Edit
+
+**Mode Selection**:
+- `mode=update`: Replace text
+- `mode=line`: Line-based operations
+
+### Use write_file (MCP)
+- Creating brand new files
+- MCP edit_file still fails (last resort)
+- Need to completely replace file content
+- Need backup before overwriting
+- User explicitly asks to "recreate file"
+
+## Priority Logic
+
+**File Reading**:
+1. Known single file → Built-in Read
+2. Multiple files OR pattern matching → read_file (MCP)
+3. Unknown location → smart_search then Read
+4. Large codebase + repeated access → codex_lens
+
+**File Editing**:
+1. Always try built-in Edit first
+2. Fails 1+ times → edit_file (MCP)
+3. Still fails → write_file (MCP)
+
+**Search**:
+1. External knowledge → Exa
+2. Exact pattern in small codebase → Built-in Grep
+3. Semantic/unknown location → smart_search
+4. Large codebase + repeated searches → codex_lens
+
+## Decision Triggers
+
+**Start with simplest tool** (Read, Edit, Grep)
+**Escalate to MCP tools** when built-ins fail or inappropriate
+**Use semantic search** for exploratory tasks
+**Use indexed search** for large, stable codebases
+**Use Exa** for external/public knowledge