claude-agent-framework 1.0.0

package/framework/skills/core/infrastructure.md

@@ -0,0 +1,337 @@
+# Skill: Infrastructure
+
+## Purpose
+Set up and manage deployment infrastructure for Rails applications.
+
+## Development Environment
+
+### Prerequisites
+```bash
+# Ruby (via rbenv)
+brew install rbenv ruby-build
+rbenv install 3.3.0
+rbenv global 3.3.0
+
+# Node.js (for asset compilation)
+brew install node
+
+# SQLite3
+brew install sqlite3
+```
+
+### Project Setup
+```bash
+# Create new Rails app
+rails new myapp --database=sqlite3 --css=tailwind --skip-jbuilder
+
+# Or with existing project
+cd myapp
+bundle install
+rails db:setup
+```
+
+### Development Server
+```bash
+# Start server with all processes
+bin/dev
+
+# Or manually
+rails server
+```
+
+## Production Configuration
+
+### Database (SQLite3 for Production)
+```yaml
+# config/database.yml
+production:
+  adapter: sqlite3
+  database: storage/production.sqlite3
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+```
+
+### Environment Variables
+```bash
+# .env.production (not committed)
+RAILS_ENV=production
+SECRET_KEY_BASE=your-secret-key-here
+RAILS_MASTER_KEY=your-master-key
+```
+
+### Production Settings
+```ruby
+# config/environments/production.rb
+Rails.application.configure do
+  config.cache_classes = true
+  config.eager_load = true
+  config.consider_all_requests_local = false
+  config.action_controller.perform_caching = true
+
+  # Force SSL
+  config.force_ssl = true
+
+  # Logging
+  config.log_level = :info
+  config.log_tags = [:request_id]
+
+  # Asset serving
+  config.public_file_server.enabled = ENV["RAILS_SERVE_STATIC_FILES"].present?
+
+  # Active Storage
+  config.active_storage.service = :local
+end
+```
+
+## Deployment Options
+
+### Option 1: Render.com (Recommended Free Option)
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: myapp
+    env: ruby
+    buildCommand: bundle install && bundle exec rails assets:precompile
+    startCommand: bundle exec puma -C config/puma.rb
+    envVars:
+      - key: RAILS_MASTER_KEY
+        sync: false
+      - key: SECRET_KEY_BASE
+        generateValue: true
+    disk:
+      name: data
+      mountPath: /app/storage
+      sizeGB: 1
+```
+
+### Option 2: Fly.io
+
+```toml
+# fly.toml
+app = "myapp"
+primary_region = "iad"
+
+[build]
+  builder = "heroku/buildpacks:22"
+
+[env]
+  RAILS_ENV = "production"
+  RAILS_LOG_TO_STDOUT = "true"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[mounts]
+  source = "data"
+  destination = "/app/storage"
+```
+
+```bash
+# Deploy commands
+fly launch
+fly secrets set RAILS_MASTER_KEY=xxx
+fly deploy
+```
+
+### Option 3: Railway
+
+```json
+// railway.json
+{
+  "build": {
+    "builder": "nixpacks"
+  },
+  "deploy": {
+    "startCommand": "bundle exec rails server -b 0.0.0.0 -p $PORT",
+    "healthcheckPath": "/up",
+    "healthcheckTimeout": 100
+  }
+}
+```
+
+### Option 4: VPS (DigitalOcean, Linode, etc.)
+
+```bash
+# Server setup script
+#!/bin/bash
+
+# Install dependencies
+apt update && apt upgrade -y
+apt install -y curl git build-essential libssl-dev zlib1g-dev
+
+# Install Ruby via rbenv
+git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
+echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
+echo 'eval "$(rbenv init -)"' >> ~/.bashrc
+source ~/.bashrc
+
+rbenv install 3.3.0
+rbenv global 3.3.0
+
+# Install bundler
+gem install bundler
+
+# Clone and setup app
+git clone your-repo /var/www/myapp
+cd /var/www/myapp
+bundle install --deployment
+RAILS_ENV=production rails db:migrate
+RAILS_ENV=production rails assets:precompile
+```
+
+## Puma Configuration
+
+```ruby
+# config/puma.rb
+max_threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }
+min_threads_count = ENV.fetch("RAILS_MIN_THREADS") { max_threads_count }
+threads min_threads_count, max_threads_count
+
+port ENV.fetch("PORT") { 3000 }
+
+environment ENV.fetch("RAILS_ENV") { "development" }
+
+# Workers for production
+workers ENV.fetch("WEB_CONCURRENCY") { 2 } if ENV["RAILS_ENV"] == "production"
+
+preload_app!
+
+# Solid Queue integration
+plugin :solid_queue if ENV["RAILS_ENV"] == "production"
+```
+
+## Background Jobs in Production
+
+### Solid Queue Setup
+```bash
+# Procfile
+web: bundle exec puma -C config/puma.rb
+worker: bundle exec rake solid_queue:start
+```
+
+### Or with Puma Plugin
+```ruby
+# config/puma.rb
+plugin :solid_queue
+```
+
+## Health Checks
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  get "up" => "rails/health#show", as: :rails_health_check
+end
+```
+
+## SSL/HTTPS
+
+### Force SSL in Production
+```ruby
+# config/environments/production.rb
+config.force_ssl = true
+```
+
+### Let's Encrypt (VPS)
+```bash
+# Install certbot
+apt install certbot python3-certbot-nginx
+
+# Get certificate
+certbot --nginx -d yourdomain.com
+```
+
+## Monitoring
+
+### Basic Logging
+```ruby
+# config/environments/production.rb
+config.log_level = :info
+config.log_formatter = ::Logger::Formatter.new
+
+# Log to STDOUT for container environments
+if ENV["RAILS_LOG_TO_STDOUT"].present?
+  logger = ActiveSupport::Logger.new(STDOUT)
+  logger.formatter = config.log_formatter
+  config.logger = ActiveSupport::TaggedLogging.new(logger)
+end
+```
+
+### Error Tracking (Optional)
+```ruby
+# Gemfile
+gem "sentry-ruby"
+gem "sentry-rails"
+
+# config/initializers/sentry.rb
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.environment = Rails.env
+end
+```
+
+## Backup Strategy
+
+### Database Backup Script
+```bash
+#!/bin/bash
+# backup.sh
+
+BACKUP_DIR="/backups"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+DB_FILE="/app/storage/production.sqlite3"
+
+# Create backup
+cp $DB_FILE "$BACKUP_DIR/production_$TIMESTAMP.sqlite3"
+
+# Keep only last 7 days
+find $BACKUP_DIR -name "*.sqlite3" -mtime +7 -delete
+```
+
+### Cron Job
+```bash
+# crontab -e
+0 2 * * * /app/backup.sh
+```
+
+## Deployment Checklist
+
+### Pre-deployment
+- [ ] All tests pass
+- [ ] No security vulnerabilities (brakeman)
+- [ ] Environment variables set
+- [ ] Database migrations ready
+- [ ] Assets precompiled
+
+### Deployment
+- [ ] Database backup taken
+- [ ] Deploy code
+- [ ] Run migrations
+- [ ] Restart application
+- [ ] Verify health check
+
+### Post-deployment
+- [ ] Verify application loads
+- [ ] Check error logs
+- [ ] Test critical flows
+- [ ] Monitor performance
+
+## Rollback Plan
+
+```bash
+# If using Git-based deployment
+git revert HEAD
+git push origin main
+
+# Restore database if needed
+cp /backups/latest.sqlite3 /app/storage/production.sqlite3
+
+# Restart application
+systemctl restart myapp
+```

package/framework/skills/core/models.md

@@ -0,0 +1,228 @@
+# Skill: Models
+
+## Purpose
+Create and manage Active Record models with validations, associations, scopes, and callbacks.
+
+## Model Structure
+
+```ruby
+class ModelName < ApplicationRecord
+  # 1. Constants
+  STATUSES = %w[draft published archived].freeze
+
+  # 2. Associations
+  belongs_to :user
+  has_many :comments, dependent: :destroy
+  has_one :profile, dependent: :destroy
+  has_many :tags, through: :taggings
+  has_one_attached :avatar
+  has_many_attached :images
+
+  # 3. Validations
+  validates :title, presence: true, length: { maximum: 255 }
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :status, inclusion: { in: STATUSES }
+
+  # 4. Scopes
+  scope :published, -> { where(published: true) }
+  scope :recent, -> { order(created_at: :desc) }
+  scope :by_user, ->(user) { where(user: user) }
+
+  # 5. Callbacks
+  before_validation :normalize_data
+  after_create :send_notification
+
+  # 6. Class methods
+  def self.search(query)
+    where("title LIKE ?", "%#{query}%")
+  end
+
+  # 7. Instance methods
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+
+  private
+
+  def normalize_data
+    self.email = email&.downcase&.strip
+  end
+end
+```
+
+## Associations
+
+### Basic Associations
+```ruby
+# One-to-many
+class User < ApplicationRecord
+  has_many :posts, dependent: :destroy
+end
+
+class Post < ApplicationRecord
+  belongs_to :user
+end
+
+# Many-to-many
+class Article < ApplicationRecord
+  has_many :taggings, dependent: :destroy
+  has_many :tags, through: :taggings
+end
+
+class Tag < ApplicationRecord
+  has_many :taggings, dependent: :destroy
+  has_many :articles, through: :taggings
+end
+
+class Tagging < ApplicationRecord
+  belongs_to :article
+  belongs_to :tag
+end
+```
+
+### Association Options
+```ruby
+has_many :comments, -> { order(created_at: :desc) }, dependent: :destroy
+belongs_to :author, class_name: "User", foreign_key: "user_id"
+has_one :profile, dependent: :destroy, inverse_of: :user
+```
+
+## Validations
+
+### Common Validations
+```ruby
+# Presence
+validates :name, presence: true
+
+# Length
+validates :title, length: { minimum: 5, maximum: 255 }
+validates :password, length: { in: 8..72 }
+
+# Format
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :slug, format: { with: /\A[a-z0-9-]+\z/ }
+
+# Uniqueness
+validates :email, uniqueness: { case_sensitive: false }
+validates :slug, uniqueness: { scope: :user_id }
+
+# Numericality
+validates :price, numericality: { greater_than: 0 }
+validates :quantity, numericality: { only_integer: true }
+
+# Inclusion
+validates :status, inclusion: { in: %w[draft published] }
+
+# Custom
+validate :end_date_after_start_date
+
+def end_date_after_start_date
+  return if end_date.blank? || start_date.blank?
+  if end_date < start_date
+    errors.add(:end_date, "must be after start date")
+  end
+end
+```
+
+## Scopes
+
+```ruby
+# Basic scopes
+scope :active, -> { where(active: true) }
+scope :recent, -> { order(created_at: :desc) }
+scope :limit_recent, ->(n) { recent.limit(n) }
+
+# Composed scopes
+scope :published_recently, -> { published.where("created_at > ?", 1.week.ago) }
+
+# With joins
+scope :with_comments, -> { joins(:comments).distinct }
+
+# Default scope (use sparingly)
+default_scope { order(created_at: :desc) }
+```
+
+## Callbacks
+
+```ruby
+# Available callbacks (in order)
+before_validation
+after_validation
+before_save
+around_save
+after_save
+before_create / before_update
+around_create / around_update
+after_create / after_update
+after_commit / after_rollback
+
+# Example usage
+before_save :generate_slug
+after_create :send_welcome_email
+after_commit :update_search_index, on: [:create, :update]
+
+private
+
+def generate_slug
+  self.slug = title.parameterize if slug.blank?
+end
+```
+
+## Migrations
+
+### Create Table
+```ruby
+class CreateArticles < ActiveRecord::Migration[8.0]
+  def change
+    create_table :articles do |t|
+      t.string :title, null: false
+      t.text :body
+      t.references :user, null: false, foreign_key: true
+      t.boolean :published, default: false
+      t.timestamps
+    end
+
+    add_index :articles, :title
+    add_index :articles, [:user_id, :created_at]
+  end
+end
+```
+
+### Modify Table
+```ruby
+class AddCategoryToArticles < ActiveRecord::Migration[8.0]
+  def change
+    add_column :articles, :category, :string
+    add_index :articles, :category
+  end
+end
+```
+
+## Query Interface
+
+```ruby
+# Find
+User.find(1)
+User.find_by(email: "test@example.com")
+User.find_or_create_by(email: "new@example.com")
+
+# Where
+User.where(active: true)
+User.where("created_at > ?", 1.week.ago)
+User.where(role: ["admin", "moderator"])
+
+# Ordering
+User.order(created_at: :desc)
+User.order(:last_name, :first_name)
+
+# Eager loading (N+1 prevention)
+User.includes(:posts).where(posts: { published: true })
+User.preload(:comments)
+User.eager_load(:profile)
+
+# Aggregations
+User.count
+User.average(:age)
+User.sum(:balance)
+User.group(:status).count
+```