claude-agent-framework 1.0.0

package/framework/skills/core/hotwire.md

@@ -0,0 +1,278 @@
+# Skill: Hotwire
+
+## Purpose
+Implement dynamic, SPA-like interactions using Turbo (Drive, Frames, Streams) and Stimulus without writing custom JavaScript.
+
+## Turbo Drive
+
+### Automatic Enhancement
+Turbo Drive is enabled by default. All links and forms are enhanced automatically.
+
+### Disabling Turbo
+```erb
+<%# Disable for specific link %>
+<%= link_to "External", "https://example.com", data: { turbo: false } %>
+
+<%# Disable for form %>
+<%= form_with model: @article, data: { turbo: false } do |f| %>
+<% end %>
+```
+
+### Progress Bar
+```css
+/* Customize in application.css */
+.turbo-progress-bar {
+  height: 3px;
+  background-color: #3b82f6;
+}
+```
+
+## Turbo Frames
+
+### Basic Frame
+```erb
+<%# index.html.erb %>
+<%= turbo_frame_tag "articles" do %>
+  <%= render @articles %>
+<% end %>
+
+<%# _article.html.erb %>
+<%= turbo_frame_tag dom_id(article) do %>
+  <div class="article-card">
+    <%= article.title %>
+    <%= link_to "Edit", edit_article_path(article) %>
+  </div>
+<% end %>
+
+<%# edit.html.erb %>
+<%= turbo_frame_tag dom_id(@article) do %>
+  <%= render "form", article: @article %>
+<% end %>
+```
+
+### Lazy Loading
+```erb
+<%= turbo_frame_tag "comments",
+    src: article_comments_path(@article),
+    loading: :lazy do %>
+  <p>Loading comments...</p>
+<% end %>
+```
+
+### Breaking Out of Frames
+```erb
+<%# Target entire page %>
+<%= link_to "View All", articles_path, data: { turbo_frame: "_top" } %>
+
+<%# Target specific frame %>
+<%= link_to "Details", article_path(article), data: { turbo_frame: "main_content" } %>
+```
+
+### Frame Targeting
+```erb
+<%# Form targets different frame %>
+<%= form_with model: @comment, data: { turbo_frame: "comments" } do |f| %>
+  <%= f.text_area :body %>
+  <%= f.submit %>
+<% end %>
+```
+
+## Turbo Streams
+
+### Stream Actions
+```erb
+<%# append - Add to end %>
+<%= turbo_stream.append "articles", @article %>
+
+<%# prepend - Add to beginning %>
+<%= turbo_stream.prepend "articles", @article %>
+
+<%# replace - Replace entire element %>
+<%= turbo_stream.replace @article %>
+
+<%# update - Replace contents only %>
+<%= turbo_stream.update "counter", "42" %>
+
+<%# remove - Delete element %>
+<%= turbo_stream.remove @article %>
+
+<%# before/after - Insert adjacent %>
+<%= turbo_stream.before @article, partial: "divider" %>
+```
+
+### Controller Response
+```ruby
+def create
+  @article = current_user.articles.build(article_params)
+
+  if @article.save
+    respond_to do |format|
+      format.html { redirect_to @article }
+      format.turbo_stream
+    end
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+### Stream Template
+```erb
+<%# app/views/articles/create.turbo_stream.erb %>
+<%= turbo_stream.prepend "articles", @article %>
+<%= turbo_stream.update "articles_count", Article.count %>
+<%= turbo_stream.replace "new_article_form" do %>
+  <%= render "form", article: Article.new %>
+<% end %>
+```
+
+### Inline Streams
+```ruby
+def destroy
+  @article.destroy
+
+  render turbo_stream: turbo_stream.remove(@article)
+end
+
+# Multiple streams
+render turbo_stream: [
+  turbo_stream.remove(@article),
+  turbo_stream.update("count", Article.count)
+]
+```
+
+## Stimulus Controllers
+
+### Basic Controller
+```javascript
+// app/javascript/controllers/hello_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["name", "output"]
+  static values = { greeting: { type: String, default: "Hello" } }
+
+  greet() {
+    this.outputTarget.textContent = `${this.greetingValue}, ${this.nameTarget.value}!`
+  }
+}
+```
+
+### HTML Usage
+```erb
+<div data-controller="hello" data-hello-greeting-value="Hi">
+  <input data-hello-target="name" type="text">
+  <button data-action="click->hello#greet">Greet</button>
+  <span data-hello-target="output"></span>
+</div>
+```
+
+### Common Controllers
+
+#### Toggle
+```javascript
+// toggle_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["content"]
+  static classes = ["hidden"]
+
+  toggle() {
+    this.contentTarget.classList.toggle(this.hiddenClass)
+  }
+}
+```
+
+#### Flash Auto-Dismiss
+```javascript
+// flash_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    setTimeout(() => this.dismiss(), 5000)
+  }
+
+  dismiss() {
+    this.element.remove()
+  }
+}
+```
+
+#### Form Validation
+```javascript
+// form_validation_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["submit"]
+
+  validate(event) {
+    const form = event.target.closest("form")
+    this.submitTarget.disabled = !form.checkValidity()
+  }
+}
+```
+
+#### Dropdown
+```javascript
+// dropdown_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["menu"]
+
+  toggle() {
+    this.menuTarget.classList.toggle("hidden")
+  }
+
+  close(event) {
+    if (!this.element.contains(event.target)) {
+      this.menuTarget.classList.add("hidden")
+    }
+  }
+
+  connect() {
+    document.addEventListener("click", this.close.bind(this))
+  }
+
+  disconnect() {
+    document.removeEventListener("click", this.close.bind(this))
+  }
+}
+```
+
+## Real-Time with Turbo Streams
+
+### Broadcast from Model
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :article
+
+  after_create_commit -> {
+    broadcast_prepend_to article, target: "comments"
+  }
+
+  after_destroy_commit -> {
+    broadcast_remove_to article
+  }
+end
+```
+
+### View Subscription
+```erb
+<%= turbo_stream_from @article %>
+
+<div id="comments">
+  <%= render @article.comments %>
+</div>
+```
+
+## Best Practices
+
+1. **Use frames for in-place editing** - Edit forms replace show content
+2. **Use streams for lists** - Append/prepend without full reload
+3. **Keep Stimulus simple** - Small, focused controllers
+4. **Leverage morphing** - For complex updates
+5. **Progressive enhancement** - Works without JS first

package/framework/skills/core/i18n.md

@@ -0,0 +1,334 @@
+# Skill: Internationalization (i18n)
+
+## Purpose
+Implement multi-language support using Rails built-in i18n framework.
+
+## Configuration
+
+### Available Locales
+```ruby
+# config/application.rb
+config.i18n.available_locales = [:en, :es, :fr]
+config.i18n.default_locale = :en
+config.i18n.fallbacks = true
+```
+
+### Load Path
+```ruby
+# config/application.rb
+config.i18n.load_path += Dir[Rails.root.join("config/locales/**/*.{rb,yml}")]
+```
+
+## Locale Files Structure
+
+```
+config/locales/
+├── en.yml                    # Default English
+├── es.yml                    # Spanish
+├── models/
+│   ├── user.en.yml
+│   └── user.es.yml
+├── views/
+│   ├── articles.en.yml
+│   └── articles.es.yml
+└── defaults/
+    ├── en.yml
+    └── es.yml
+```
+
+## Basic Translations
+
+### Simple Strings
+```yaml
+# config/locales/en.yml
+en:
+  hello: "Hello"
+  welcome: "Welcome to our app"
+
+# config/locales/es.yml
+es:
+  hello: "Hola"
+  welcome: "Bienvenido a nuestra app"
+```
+
+### Nested Structure
+```yaml
+# config/locales/en.yml
+en:
+  navigation:
+    home: "Home"
+    about: "About"
+    contact: "Contact"
+
+  footer:
+    copyright: "All rights reserved"
+    privacy: "Privacy Policy"
+```
+
+### With Variables
+```yaml
+en:
+  greeting: "Hello, %{name}!"
+  items_count: "You have %{count} items"
+```
+
+```ruby
+t("greeting", name: "John")  # => "Hello, John!"
+```
+
+## Pluralization
+
+```yaml
+en:
+  articles:
+    count:
+      zero: "No articles"
+      one: "1 article"
+      other: "%{count} articles"
+```
+
+```ruby
+t("articles.count", count: 0)  # => "No articles"
+t("articles.count", count: 1)  # => "1 article"
+t("articles.count", count: 5)  # => "5 articles"
+```
+
+## Model Translations
+
+### Active Record Attributes
+```yaml
+# config/locales/models/article.en.yml
+en:
+  activerecord:
+    models:
+      article:
+        one: "Article"
+        other: "Articles"
+    attributes:
+      article:
+        title: "Title"
+        body: "Content"
+        published: "Published"
+        created_at: "Created"
+    errors:
+      models:
+        article:
+          attributes:
+            title:
+              blank: "Please provide a title"
+              too_short: "Title must be at least %{count} characters"
+```
+
+### Usage in Views
+```erb
+<%= Article.model_name.human %>
+<%= Article.human_attribute_name(:title) %>
+```
+
+## View Translations
+
+### Lazy Lookup
+```yaml
+# config/locales/views/articles.en.yml
+en:
+  articles:
+    index:
+      title: "All Articles"
+      new_article: "New Article"
+      no_articles: "No articles yet"
+    show:
+      edit: "Edit"
+      delete: "Delete"
+      confirm_delete: "Are you sure?"
+    form:
+      submit_create: "Create Article"
+      submit_update: "Update Article"
+```
+
+```erb
+<%# app/views/articles/index.html.erb %>
+<h1><%= t(".title") %></h1>
+<%= link_to t(".new_article"), new_article_path %>
+
+<% if @articles.empty? %>
+  <p><%= t(".no_articles") %></p>
+<% end %>
+```
+
+### With HTML
+```yaml
+en:
+  welcome_html: "Welcome to <strong>Our App</strong>"
+  terms_html: "By signing up, you agree to our %{link}"
+```
+
+```erb
+<%= t("welcome_html") %>
+<%= t("terms_html", link: link_to(t("terms"), terms_path)) %>
+```
+
+## Date and Time
+
+### Formats
+```yaml
+en:
+  date:
+    formats:
+      default: "%Y-%m-%d"
+      short: "%b %d"
+      long: "%B %d, %Y"
+  time:
+    formats:
+      default: "%Y-%m-%d %H:%M"
+      short: "%d %b %H:%M"
+      long: "%B %d, %Y at %H:%M"
+```
+
+### Usage
+```erb
+<%= l(article.created_at) %>
+<%= l(article.created_at, format: :short) %>
+<%= l(article.created_at, format: :long) %>
+```
+
+## Controller Setup
+
+### Set Locale
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  around_action :switch_locale
+
+  private
+
+  def switch_locale(&action)
+    locale = extract_locale || I18n.default_locale
+    I18n.with_locale(locale, &action)
+  end
+
+  def extract_locale
+    # From URL param
+    locale = params[:locale]
+    # From user preference
+    locale ||= current_user&.locale
+    # From Accept-Language header
+    locale ||= extract_locale_from_header
+
+    locale if I18n.available_locales.include?(locale&.to_sym)
+  end
+
+  def extract_locale_from_header
+    request.env["HTTP_ACCEPT_LANGUAGE"]&.scan(/^[a-z]{2}/)&.first
+  end
+
+  def default_url_options
+    { locale: I18n.locale }
+  end
+end
+```
+
+### URL-Based Locale
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  scope "(:locale)", locale: /en|es|fr/ do
+    resources :articles
+    root "pages#home"
+  end
+end
+```
+
+## JavaScript Translations
+
+### Export to JS
+```ruby
+# config/initializers/i18n_js.rb
+# Using i18n-js gem
+I18nJS.configure do |config|
+  config.translations do |t|
+    t.file = "app/javascript/translations.json"
+    t.patterns << "*"
+  end
+end
+```
+
+### Stimulus Controller
+```javascript
+// app/javascript/controllers/i18n_controller.js
+import { Controller } from "@hotwired/stimulus"
+import translations from "../translations.json"
+
+export default class extends Controller {
+  static values = { locale: String }
+
+  t(key, options = {}) {
+    let translation = translations[this.localeValue][key]
+
+    Object.keys(options).forEach(k => {
+      translation = translation.replace(`%{${k}}`, options[k])
+    })
+
+    return translation
+  }
+}
+```
+
+## Form Errors
+
+```yaml
+en:
+  errors:
+    format: "%{attribute} %{message}"
+    messages:
+      blank: "can't be blank"
+      invalid: "is invalid"
+      too_short: "is too short (minimum is %{count} characters)"
+      too_long: "is too long (maximum is %{count} characters)"
+      taken: "has already been taken"
+```
+
+## Flash Messages
+
+```yaml
+en:
+  flash:
+    actions:
+      create:
+        success: "%{model} was successfully created."
+        error: "Could not create %{model}."
+      update:
+        success: "%{model} was successfully updated."
+        error: "Could not update %{model}."
+      destroy:
+        success: "%{model} was successfully deleted."
+```
+
+```ruby
+# Controller
+redirect_to @article, notice: t("flash.actions.create.success", model: Article.model_name.human)
+```
+
+## Testing
+
+```ruby
+# spec/support/i18n.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    I18n.locale = :en
+  end
+end
+
+# Test missing translations
+I18n.exception_handler = ->(exception, locale, key, options) {
+  raise exception.to_exception
+}
+```
+
+## Best Practices
+
+1. **Use lazy lookup** - `.title` instead of full path
+2. **Organize by feature** - Separate files per domain
+3. **Use YAML anchors** - Reduce duplication
+4. **Test all locales** - Ensure no missing keys
+5. **Use variables** - Don't concatenate strings
+6. **Keep defaults in en.yml** - Fallback always works