Initial commit

2025-11-30 08:42:29 +08:00
commit bece5178ef
31 changed files with 9410 additions and 0 deletions
--- a/skills/rails-pattern-finder/SKILL.md
+++ b/skills/rails-pattern-finder/SKILL.md
@@ -0,0 +1,374 @@
+# Rails Pattern Finder
+
+---
+name: rails-pattern-finder
+description: Finds Rails code patterns and best practices using Ref (primary), Grep, and reference patterns with WebFetch fallback
+version: 1.2.0
+author: Rails Workflow Team
+tags: [rails, patterns, best-practices, code-examples, ref]
+priority: 3
+---
+
+## Purpose
+
+Searches the current Rails codebase for existing patterns and provides best-practice code examples. Helps agents write code consistent with project conventions.
+
+**Replaces**: Manual codebase exploration and pattern recognition
+
+## Usage
+
+**Auto-invoked** when agents need code examples:
+```
+Agent: "How is authentication implemented in this project?"
+*invokes rails-pattern-finder pattern="authentication"*
+```
+
+**Manual invocation**:
+```
+@rails-pattern-finder pattern="service_objects"
+@rails-pattern-finder pattern="api_serialization"
+@rails-pattern-finder pattern="background_jobs"
+```
+
+## Supported Patterns
+
+See `reference.md` for complete pattern list. Common patterns:
+
+### Architectural Patterns
+- `service_objects` - Service layer implementation
+- `form_objects` - Form object pattern
+- `query_objects` - Complex query encapsulation
+- `decorators` - Decorator/presenter pattern
+- `policies` - Authorization policies (Pundit)
+
+### API Patterns
+- `api_versioning` - API version management
+- `api_serialization` - JSON response formatting
+- `api_authentication` - Token/JWT authentication
+- `api_error_handling` - Error response patterns
+
+### Database Patterns
+- `scopes` - Named scope usage
+- `concerns` - Model concern organization
+- `polymorphic_associations` - Polymorphic pattern
+- `sti` - Single Table Inheritance
+- `database_views` - Database view usage
+
+### Testing Patterns
+- `factory_usage` - FactoryBot patterns
+- `request_specs` - API request testing
+- `system_specs` - System/feature testing
+- `shared_examples` - RSpec shared examples
+
+## Search Process
+
+### Step 1: Pattern Lookup
+```
+Input: pattern="service_objects"
+Lookup: reference.md → search_paths, file_patterns, code_patterns
+```
+
+### Step 2: Codebase Search
+```
+Tool: Grep
+Pattern: "class.*Service$"
+Glob: "app/services/**/*.rb"
+Output: List of matching files
+```
+
+### Step 3: Example Extraction
+```
+Tool: Read
+Files: [top 3 matches by relevance]
+Extract: Class structure, method signatures, usage patterns
+```
+
+### Step 4: Response Formatting
+```ruby
+## Pattern: Service Objects
+
+### Found in Project (3 examples):
+
+**1. UserRegistrationService** (app/services/user_registration_service.rb)
+```ruby
+class UserRegistrationService
+  def initialize(params)
+    @params = params
+  end
+
+  def call
+    user = User.create!(@params)
+    send_welcome_email(user)
+    user
+  end
+
+  private
+
+  def send_welcome_email(user)
+    UserMailer.welcome(user).deliver_later
+  end
+end
+```
+
+**2. PaymentProcessingService** (app/services/payment_processing_service.rb)
+[Example code...]
+
+### Best Practice from Rails Community:
+[Fetch from reference.md or WebSearch]
+
+**Source**: Project codebase + Rails best practices
+```
+
+## Reference Lookup
+
+**Pattern → Search Strategy mapping** in `reference.md`:
+
+```yaml
+service_objects:
+  title: "Service Objects"
+  search_paths: ["app/services/**/*.rb"]
+  file_patterns: ["*_service.rb"]
+  code_patterns:
+    - "class \\w+Service"
+    - "def call"
+  best_practice_url: "https://example.com/rails-service-objects"
+  keywords: [service, business logic, call method]
+
+api_serialization:
+  title: "API Serialization"
+  search_paths: ["app/serializers/**/*.rb", "app/blueprints/**/*.rb"]
+  file_patterns: ["*_serializer.rb", "*_blueprint.rb"]
+  code_patterns:
+    - "class \\w+Serializer"
+    - "ActiveModel::Serializer"
+    - "Blueprinter::Base"
+  keywords: [json, serializer, blueprint, jbuilder]
+```
+
+## Output Format
+
+### Pattern Found in Project
+```markdown
+## Pattern: [Pattern Name]
+
+### Found in Project ([N] examples):
+
+**File**: [path/to/file.rb]
+**Purpose**: [What this implementation does]
+
+```ruby
+[Code example from project]
+```
+
+**Key characteristics**:
+- [Feature 1]
+- [Feature 2]
+
+**Usage in project**:
+[How this pattern is used - grep for usage examples]
+```
+
+### Pattern Not Found
+```markdown
+## Pattern: [Pattern Name] - Not found in project
+
+**Searched**:
+- app/services/**/*.rb
+- app/lib/**/*.rb
+
+**Best Practice Implementation**:
+
+```ruby
+[Example from reference.md or external source]
+```
+
+**To implement in this project**:
+1. Create: app/services/[name]_service.rb
+2. Follow structure above
+3. Test in: spec/services/[name]_service_spec.rb
+
+**Similar patterns in project**:
+- [Alternative pattern found]
+```
+
+### Multiple Variants Found
+```markdown
+## Pattern: [Pattern Name] - Multiple variants found
+
+This project uses [N] different approaches:
+
+### Variant 1: [Approach Name] ([N] files)
+[Example code...]
+
+### Variant 2: [Approach Name] ([N] files)
+[Example code...]
+
+**Recommendation**: [Which variant to use for consistency]
+```
+
+## Implementation Details
+
+**Tools used** (in order of preference):
+1. **Read** - Load `reference.md` pattern definitions
+2. **context7_fetch** (primary) - Fetch curated patterns via Context7 MCP
+3. **ref_search_documentation** (secondary) - Search Rails pattern docs via Ref MCP
+4. **ref_read_url** (secondary) - Fetch specific pattern guides via Ref MCP
+5. **tavily_search** (tertiary) - Optimized search via Tavily MCP
+6. **Grep** - Search codebase for pattern matches
+7. **Read** - Extract code examples from matching files
+8. **WebFetch** (fallback) - Fetch pattern docs if MCPs not available
+9. **WebSearch** (optional) - Fetch external best practices
+10. **Glob** - Find files matching pattern
+
+**Optional dependencies**:
+- **context7-mcp**: Fastest pattern documentation
+- **ref-tools-mcp**: Token-efficient pattern search
+- **tavily-mcp**: Optimized search for LLMs
+- If neither installed: Falls back to WebFetch and local searches (still works!)
+
+**Search strategies**:
+
+**File-based search**:
+```bash
+# Find files matching naming convention
+glob: "app/services/*_service.rb"
+```
+
+**Content-based search**:
+```bash
+# Find class definitions
+grep: "class \\w+Service$"
+path: "app/services"
+```
+
+**Usage search**:
+```bash
+# Find where pattern is used
+grep: "UserRegistrationService\\.new"
+path: "app/controllers"
+```
+
+**Relevance ranking**:
+1. Most recently modified files (likely current patterns)
+2. Files with most references (commonly used)
+3. Files with comprehensive examples (best for learning)
+
+## Error Handling
+
+**Pattern not found**:
+```markdown
+⚠️ Pattern "[pattern]" not found in project
+
+**Searched**:
+- [paths searched]
+
+**Options**:
+1. View best practice example (from reference.md)
+2. Search for similar pattern: [suggestions]
+3. Implement from scratch using best practices
+```
+
+**Invalid pattern name**:
+```markdown
+❌ Unknown pattern: "[pattern]"
+
+Available patterns:
+- service_objects
+- form_objects
+- query_objects
+[...from reference.md...]
+
+Try: @rails-pattern-finder pattern="[one of above]"
+```
+
+**Ambiguous results**:
+```markdown
+⚠️ Multiple pattern variants found for "[pattern]"
+
+Please review all variants and choose one for consistency.
+
+[List all variants found...]
+```
+
+## Integration
+
+**Auto-invoked by**:
+- All 7 Rails agents when generating new code
+- @rails-architect for architectural decisions
+- Agents adapting to project conventions
+
+**Workflow**:
+1. Agent needs to generate code (e.g., new service)
+2. Invokes @rails-pattern-finder pattern="service_objects"
+3. Receives project-specific examples
+4. Generates code matching project style
+
+## Special Features
+
+### Pattern comparison
+```
+@rails-pattern-finder pattern="service_objects" compare_with="form_objects"
+→ Shows differences and use cases for each
+```
+
+### Project convention detection
+```
+@rails-pattern-finder detect_conventions
+→ Analyzes codebase and reports common patterns
+```
+
+### Anti-pattern detection
+```
+@rails-pattern-finder anti_patterns
+→ Searches for common Rails anti-patterns in codebase
+```
+
+### Test pattern search
+```
+@rails-pattern-finder pattern="service_objects" include_tests=true
+→ Shows both implementation and test examples
+```
+
+## Pattern Categories
+
+### Creation Patterns
+- `service_objects` - Business logic encapsulation
+- `form_objects` - Form handling
+- `query_objects` - Query encapsulation
+- `builder_pattern` - Object construction
+
+### Structural Patterns
+- `concerns` - Module organization
+- `decorators` - Presentation logic
+- `adapters` - External API integration
+- `repositories` - Data access layer
+
+### Behavioral Patterns
+- `observers` - Event handling
+- `state_machines` - State management
+- `strategies` - Algorithm selection
+- `commands` - Action encapsulation
+
+### Rails-Specific
+- `sti` - Single Table Inheritance
+- `polymorphic_associations` - Flexible relationships
+- `custom_validators` - Validation logic
+- `background_jobs` - Async processing
+
+## Testing
+
+**Test cases**:
+1. Pattern exists in project → Returns project examples
+2. Pattern doesn't exist → Returns best practice example
+3. Multiple variants → Lists all with recommendation
+4. Invalid pattern → Error with suggestions
+5. Empty project → All patterns return best practices
+
+## Notes
+
+- This skill searches **current project codebase**, not external repos
+- Pattern definitions in `reference.md` include search strategies
+- Results prioritize recent, commonly-used code
+- Helps maintain consistency across large teams
+- Adapts to project-specific conventions automatically
+- Use with @rails-docs-search (theory) and @rails-api-lookup (APIs)