claude-agent-framework 1.0.0

package/framework/skills/core/code-review.md

@@ -0,0 +1,341 @@
+# Skill: Code Review
+
+## Purpose
+Systematically review code for quality, security, performance, and maintainability.
+
+## Review Checklist
+
+### 1. Functionality
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases are handled
+- [ ] Error handling is appropriate
+- [ ] No obvious bugs
+
+### 2. Security
+- [ ] No SQL injection vulnerabilities
+- [ ] No XSS vulnerabilities
+- [ ] Authentication/authorization checked
+- [ ] Sensitive data not logged
+- [ ] CSRF protection in place
+- [ ] Strong parameters used
+- [ ] No hardcoded secrets
+
+### 3. Performance
+- [ ] No N+1 queries
+- [ ] Proper indexes exist
+- [ ] No unnecessary database calls
+- [ ] Efficient algorithms used
+- [ ] Caching where appropriate
+
+### 4. Code Quality
+- [ ] Follows Rails conventions
+- [ ] DRY - no unnecessary duplication
+- [ ] Single responsibility principle
+- [ ] Clear naming
+- [ ] Appropriate comments (not excessive)
+
+### 5. Testing
+- [ ] Tests exist for new code
+- [ ] Tests cover edge cases
+- [ ] Tests are meaningful (not just coverage)
+- [ ] All tests pass
+
+### 6. Accessibility
+- [ ] Semantic HTML used
+- [ ] Form labels present
+- [ ] ARIA attributes where needed
+- [ ] Color contrast sufficient
+
+## Security Review
+
+### SQL Injection
+```ruby
+# BAD - SQL injection vulnerable
+User.where("name = '#{params[:name]}'")
+
+# GOOD - Parameterized
+User.where(name: params[:name])
+User.where("name = ?", params[:name])
+```
+
+### XSS Prevention
+```erb
+<%# BAD - Raw HTML output %>
+<%= raw @article.body %>
+<%= @article.body.html_safe %>
+
+<%# GOOD - Escaped by default %>
+<%= @article.body %>
+
+<%# GOOD - Sanitized HTML %>
+<%= sanitize @article.body, tags: %w[p br strong em] %>
+```
+
+### Mass Assignment
+```ruby
+# BAD - Permits everything
+params.require(:user).permit!
+
+# GOOD - Explicit whitelist
+params.require(:user).permit(:name, :email)
+
+# GOOD - Conditional permits
+def user_params
+  permitted = [:name, :email]
+  permitted << :role if current_user.admin?
+  params.require(:user).permit(permitted)
+end
+```
+
+### Authorization
+```ruby
+# BAD - No authorization check
+def update
+  @article = Article.find(params[:id])
+  @article.update(article_params)
+end
+
+# GOOD - Ownership check
+def update
+  @article = current_user.articles.find(params[:id])
+  @article.update(article_params)
+end
+
+# GOOD - Policy check
+def update
+  @article = Article.find(params[:id])
+  authorize @article
+  @article.update(article_params)
+end
+```
+
+## Performance Review
+
+### N+1 Queries
+```ruby
+# BAD - N+1 query
+@articles = Article.all
+@articles.each { |a| puts a.user.name }
+
+# GOOD - Eager loading
+@articles = Article.includes(:user)
+@articles.each { |a| puts a.user.name }
+```
+
+### Efficient Queries
+```ruby
+# BAD - Loads all records
+User.all.count
+User.all.any?
+
+# GOOD - Database operations
+User.count
+User.exists?
+```
+
+### Avoid Memory Bloat
+```ruby
+# BAD - Loads all into memory
+User.all.each { |u| process(u) }
+
+# GOOD - Batch processing
+User.find_each { |u| process(u) }
+```
+
+## Code Quality Review
+
+### Single Responsibility
+```ruby
+# BAD - Controller doing too much
+def create
+  @user = User.new(user_params)
+  @user.generate_token
+  @user.save
+  UserMailer.welcome(@user).deliver_now
+  Analytics.track("signup", @user.id)
+  redirect_to dashboard_path
+end
+
+# GOOD - Delegated to service/job
+def create
+  @user = User.new(user_params)
+  if @user.save
+    UserRegistrationJob.perform_later(@user.id)
+    redirect_to dashboard_path
+  else
+    render :new
+  end
+end
+```
+
+### Clear Naming
+```ruby
+# BAD - Unclear names
+def process(d)
+  d.map { |x| x * 2 }
+end
+
+# GOOD - Descriptive names
+def double_quantities(order_items)
+  order_items.map { |item| item.quantity * 2 }
+end
+```
+
+### Avoid Deep Nesting
+```ruby
+# BAD - Too nested
+if user
+  if user.active?
+    if user.verified?
+      do_something
+    end
+  end
+end
+
+# GOOD - Early returns
+return unless user
+return unless user.active?
+return unless user.verified?
+do_something
+```
+
+## Rails Conventions Review
+
+### RESTful Actions
+```ruby
+# BAD - Non-RESTful action names
+def fetch_articles
+def do_publish
+
+# GOOD - RESTful
+def index
+def show
+def publish  # Custom action on member
+```
+
+### Callbacks vs Explicit Calls
+```ruby
+# QUESTIONABLE - Hidden behavior
+class Article < ApplicationRecord
+  after_save :notify_subscribers
+  after_save :update_search_index
+  after_save :clear_cache
+end
+
+# BETTER - Explicit service object
+class ArticlePublisher
+  def call(article)
+    article.save!
+    notify_subscribers(article)
+    update_search_index(article)
+    clear_cache(article)
+  end
+end
+```
+
+### Fat Models, Skinny Controllers
+```ruby
+# BAD - Logic in controller
+def create
+  @order = Order.new(order_params)
+  @order.total = @order.items.sum(&:price) * 1.1  # Tax
+  @order.status = "pending"
+  @order.save
+end
+
+# GOOD - Logic in model
+def create
+  @order = Order.new(order_params)
+  @order.save
+end
+
+class Order < ApplicationRecord
+  before_save :calculate_total
+
+  def calculate_total
+    self.total = items.sum(&:price) * tax_rate
+  end
+end
+```
+
+## Review Report Format
+
+```markdown
+# Code Review: [PR/Feature Name]
+Reviewer: [Name]
+Date: [Date]
+
+## Summary
+[Brief description of what was reviewed]
+
+## Findings
+
+### Critical Issues
+1. **[Issue Title]**
+   - File: `path/to/file.rb:123`
+   - Problem: [Description]
+   - Suggestion: [How to fix]
+
+### Warnings
+1. **[Issue Title]**
+   - File: `path/to/file.rb:456`
+   - Problem: [Description]
+   - Suggestion: [How to fix]
+
+### Suggestions
+1. **[Improvement]**
+   - File: `path/to/file.rb:789`
+   - Current: [Current approach]
+   - Suggested: [Better approach]
+
+## Positive Notes
+- [What was done well]
+- [Good patterns used]
+
+## Tests
+- [ ] Tests exist and pass
+- [ ] Coverage adequate
+
+## Verdict
+- [ ] Approved
+- [ ] Approved with minor changes
+- [ ] Changes requested
+```
+
+## Automated Checks
+
+### Linting (RuboCop)
+```yaml
+# .rubocop.yml
+require:
+  - rubocop-rails
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+
+Rails:
+  Enabled: true
+```
+
+### Security Scanning (Brakeman)
+```bash
+# Run security scan
+brakeman -o brakeman-report.html
+```
+
+### Dependency Audit
+```bash
+# Check for vulnerable gems
+bundle audit check --update
+```
+
+## Best Practices
+
+1. **Review small PRs** - Easier to catch issues
+2. **Use automated tools first** - Let robots catch obvious issues
+3. **Focus on logic** - Don't nitpick style (let linters handle it)
+4. **Ask questions** - Don't assume, clarify intent
+5. **Be constructive** - Suggest solutions, not just problems
+6. **Prioritize security** - Always check auth and data handling

package/framework/skills/core/controllers.md

@@ -0,0 +1,290 @@
+# Skill: Controllers
+
+## Purpose
+Create RESTful controllers with proper authentication, authorization, parameter handling, and responses.
+
+## Controller Structure
+
+```ruby
+class ArticlesController < ApplicationController
+  # 1. Callbacks
+  before_action :authenticate_user!
+  before_action :set_article, only: %i[show edit update destroy]
+
+  # 2. RESTful actions
+  def index
+    @articles = Article.includes(:user).recent.page(params[:page])
+  end
+
+  def show
+  end
+
+  def new
+    @article = current_user.articles.build
+  end
+
+  def create
+    @article = current_user.articles.build(article_params)
+
+    if @article.save
+      redirect_to @article, notice: "Article created successfully."
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def edit
+  end
+
+  def update
+    if @article.update(article_params)
+      redirect_to @article, notice: "Article updated successfully."
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @article.destroy
+    redirect_to articles_path, notice: "Article deleted."
+  end
+
+  private
+
+  def set_article
+    @article = Article.find(params[:id])
+  end
+
+  def article_params
+    params.require(:article).permit(:title, :body, :published)
+  end
+end
+```
+
+## Strong Parameters
+
+```ruby
+# Basic
+def article_params
+  params.require(:article).permit(:title, :body)
+end
+
+# With nested attributes
+def article_params
+  params.require(:article).permit(
+    :title,
+    :body,
+    tags_attributes: [:id, :name, :_destroy],
+    images: []  # Array of files
+  )
+end
+
+# Conditional
+def article_params
+  permitted = [:title, :body]
+  permitted << :published if current_user.admin?
+  params.require(:article).permit(permitted)
+end
+```
+
+## Before Actions
+
+```ruby
+class ArticlesController < ApplicationController
+  # Authentication
+  before_action :authenticate_user!
+  before_action :authenticate_user!, except: [:index, :show]
+
+  # Resource loading
+  before_action :set_article, only: %i[show edit update destroy]
+
+  # Authorization
+  before_action :authorize_article, only: %i[edit update destroy]
+
+  private
+
+  def set_article
+    @article = Article.find(params[:id])
+  end
+
+  def authorize_article
+    redirect_to articles_path, alert: "Not authorized" unless @article.user == current_user
+  end
+end
+```
+
+## Response Formats
+
+### HTML with Turbo
+```ruby
+def create
+  @article = current_user.articles.build(article_params)
+
+  if @article.save
+    respond_to do |format|
+      format.html { redirect_to @article, notice: "Created!" }
+      format.turbo_stream
+    end
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+### JSON API
+```ruby
+def index
+  @articles = Article.all
+
+  respond_to do |format|
+    format.html
+    format.json { render json: @articles }
+  end
+end
+```
+
+## Flash Messages
+
+```ruby
+# Standard messages
+redirect_to @article, notice: "Article created."
+redirect_to articles_path, alert: "Something went wrong."
+
+# Custom flash types
+flash[:success] = "Great job!"
+flash.now[:error] = "Please fix the errors."  # For render
+```
+
+## Turbo Stream Responses
+
+```ruby
+# app/views/articles/create.turbo_stream.erb
+<%= turbo_stream.prepend "articles", @article %>
+<%= turbo_stream.update "flash", partial: "shared/flash" %>
+
+# Or inline in controller
+def create
+  @article = current_user.articles.build(article_params)
+
+  if @article.save
+    render turbo_stream: [
+      turbo_stream.prepend("articles", @article),
+      turbo_stream.update("form", partial: "form", locals: { article: Article.new })
+    ]
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+## Authorization with Pundit
+
+```ruby
+class ArticlesController < ApplicationController
+  include Pundit::Authorization
+
+  def show
+    @article = Article.find(params[:id])
+    authorize @article
+  end
+
+  def create
+    @article = current_user.articles.build(article_params)
+    authorize @article
+
+    if @article.save
+      redirect_to @article
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from ActiveRecord::RecordNotFound, with: :not_found
+  rescue_from Pundit::NotAuthorizedError, with: :forbidden
+
+  private
+
+  def not_found
+    render file: Rails.root.join("public/404.html"), status: :not_found, layout: false
+  end
+
+  def forbidden
+    redirect_to root_path, alert: "You are not authorized to perform this action."
+  end
+end
+```
+
+## RESTful Custom Actions
+
+```ruby
+# routes.rb
+resources :articles do
+  member do
+    patch :publish
+    patch :archive
+  end
+  collection do
+    get :drafts
+    get :search
+  end
+end
+
+# controller
+def publish
+  @article = Article.find(params[:id])
+  @article.update(published: true)
+  redirect_to @article, notice: "Article published."
+end
+
+def drafts
+  @articles = current_user.articles.where(published: false)
+  render :index
+end
+```
+
+## Pagination
+
+```ruby
+# With Pagy (recommended for Rails 8)
+class ArticlesController < ApplicationController
+  include Pagy::Backend
+
+  def index
+    @pagy, @articles = pagy(Article.recent, items: 20)
+  end
+end
+
+# In view
+<%== pagy_nav(@pagy) %>
+```
+
+## Concerns
+
+```ruby
+# app/controllers/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  def search
+    @results = model_class.search(params[:q])
+    render :index
+  end
+
+  private
+
+  def model_class
+    controller_name.classify.constantize
+  end
+end
+
+# Usage
+class ArticlesController < ApplicationController
+  include Searchable
+end
+```