@codyswann/lisa 1.37.0 → 1.38.0

package/all/copy-overwrite/CLAUDE.md

@@ -46,6 +46,7 @@ Never delete anything outside of this project's directory
 Never add "BREAKING CHANGE" to a commit message unless there is actually a breaking change
 Never stash changes you can't commit. Either fix whatever is prevening the commit or fail out and let the human know why.
 Never lower thresholds for tests to pass a pre-push hook. You must increase test coverage to make it pass
+Never handle tasks yourself when working in a team of agents. Always delegate to a specialied agent.
 
 ONLY use eslint-disable as a last resort and confirm with human before doing so
 ONLY use eslint-disable for test file max-lines when comprehensive test coverage requires extensive test cases (must include matching eslint-enable)

package/package.json

@@ -89,7 +89,7 @@
     "@isaacs/brace-expansion": "^5.0.1"
   },
   "name": "@codyswann/lisa",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "bin": {

package/rails/copy-overwrite/.claude/rules/lisa.md

@@ -19,6 +19,9 @@ The following files are managed by Lisa and will be overwritten on every `lisa`
 - `spec/spec_helper.rb`
 - `spec/rails_helper.rb`
 - `.github/workflows/quality.yml`
+- `.github/workflows/ci.yml`
+- `.github/workflows/release.yml`
+- `VERSION`
 
 ## Directories with both Lisa-managed and project content
 
@@ -34,7 +37,8 @@ These directories contain files deployed by Lisa **and** files you create. Do no
 - `.claude/rules/coding-philosophy.md`, `.claude/rules/plan.md`, `.claude/rules/verfication.md`
 - `.claude/rules/rails-conventions.md`
 - `CLAUDE.md`, `HUMAN.md`, `.safety-net.json`
-- `.rubocop.yml`, `lefthook.yml`, `Gemfile.lisa`
+- `.rubocop.yml`, `.versionrc`, `lefthook.yml`, `Gemfile.lisa`
+- `config/initializers/version.rb`
 - `.coderabbit.yml`, `commitlint.config.cjs`
 - `.claude/settings.json`
 - `.claude/README.md`, `.claude/REFERENCE.md`

package/rails/copy-overwrite/.claude/skills/action-controller-best-practices/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: action-controller-best-practices
+description: Build or Refactor large Rails controller files into clean, maintainable code. Use when a controller action exceeds ~10 lines, a controller has custom non-RESTful actions, or when the user asks to refactor, slim down, clean up, or organize a Rails controller. Applies patterns: service objects, query objects, form objects, controller concerns, presenters/decorators, and RESTful resource extraction.
+---
+
+# Rails Controller Refactoring
+
+Controllers should be thin traffic cops — they receive input via params, delegate to the appropriate object, and decide what to render or redirect. Each action should be roughly 5-10 lines. If an action is longer, logic needs to be extracted.
+
+## Decision Framework
+
+Read the controller and classify each block of code:
+
+| Code type                                               | Extract to             | Location                               |
+| ------------------------------------------------------- | ---------------------- | -------------------------------------- |
+| Business logic, multi-step operations, side effects     | Service object         | `app/services/`                        |
+| Complex queries, filtering, sorting, search             | Query object           | `app/queries/`                         |
+| Context-specific param validation and persistence       | Form object            | `app/forms/`                           |
+| Shared before_actions, auth, pagination, error handling | Controller concern     | `app/controllers/concerns/`            |
+| Complex view data assembly, formatting, display logic   | Presenter / Decorator  | `app/presenters/` or `app/decorators/` |
+| Non-RESTful custom actions on a different concept       | New RESTful controller | `app/controllers/`                     |
+| Simple CRUD, strong params, render/redirect             | Keep on controller     | —                                      |
+
+## Patterns
+
+### Service Objects
+
+Use for any business logic that goes beyond simple CRUD. A controller action should call one service at most.
+
+Before:
+
+```ruby
+def create
+  @player = Player.new(player_params)
+  @player.team = Team.find(params[:team_id])
+  @player.contract_start = Time.current
+  @player.status = :active
+
+  if @player.save
+    PlayerMailer.welcome(@player).deliver_later
+    Analytics.track("player_signed", player_id: @player.id)
+    NotifyScoutsJob.perform_later(@player.team_id)
+    redirect_to @player, notice: "Player signed"
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+After:
+
+```ruby
+# Controller
+def create
+  result = Players::SignPlayer.new(player_params, team_id: params[:team_id]).call
+
+  if result.success?
+    redirect_to result.player, notice: "Player signed"
+  else
+    @player = result.player
+    render :new, status: :unprocessable_entity
+  end
+end
+
+# app/services/players/sign_player.rb
+module Players
+  class SignPlayer
+    def initialize(params, team_id:)
+      @params = params
+      @team_id = team_id
+    end
+
+    def call
+      player = Player.new(@params)
+      player.team = Team.find(@team_id)
+      player.contract_start = Time.current
+      player.status = :active
+
+      if player.save
+        send_notifications(player)
+        Result.new(success: true, player: player)
+      else
+        Result.new(success: false, player: player)
+      end
+    end
+
+    private
+
+    def send_notifications(player)
+      PlayerMailer.welcome(player).deliver_later
+      Analytics.track("player_signed", player_id: player.id)
+      NotifyScoutsJob.perform_later(player.team_id)
+    end
+
+    Result = Struct.new(:success, :player, keyword_init: true) do
+      alias_method :success?, :success
+    end
+  end
+end
+```
+
+### Query Objects
+
+Use when index actions have complex filtering, sorting, or search logic.
+
+Before:
+
+```ruby
+def index
+  @players = Player.where(team_id: params[:team_id])
+  @players = @players.where(position: params[:position]) if params[:position].present?
+  @players = @players.where("age >= ?", params[:min_age]) if params[:min_age].present?
+  @players = @players.where(status: :active) unless params[:include_inactive]
+  @players = @players.joins(:stats).order("stats.war DESC")
+  @players = @players.page(params[:page]).per(25)
+end
+```
+
+After:
+
+```ruby
+# Controller
+def index
+  @players = Players::FilterQuery.new(params).call
+end
+
+# app/queries/players/filter_query.rb
+module Players
+  class FilterQuery
+    def initialize(params, relation: Player.all)
+      @params = params
+      @relation = relation
+    end
+
+    def call
+      filter_by_team
+      filter_by_position
+      filter_by_age
+      filter_by_status
+      sort_and_paginate
+      @relation
+    end
+
+    private
+
+    def filter_by_team
+      @relation = @relation.where(team_id: @params[:team_id]) if @params[:team_id].present?
+    end
+
+    def filter_by_position
+      @relation = @relation.where(position: @params[:position]) if @params[:position].present?
+    end
+
+    def filter_by_age
+      @relation = @relation.where("age >= ?", @params[:min_age]) if @params[:min_age].present?
+    end
+
+    def filter_by_status
+      @relation = @relation.where(status: :active) unless @params[:include_inactive]
+    end
+
+    def sort_and_paginate
+      @relation = @relation.joins(:stats).order("stats.war DESC").page(@params[:page]).per(25)
+    end
+  end
+end
+```
+
+### Controller Concerns
+
+Use for shared behavior across multiple controllers: authentication, authorization, pagination, error handling, locale setting.
+
+```ruby
+# app/controllers/concerns/paginatable.rb
+module Paginatable
+  extend ActiveSupport::Concern
+
+  private
+
+  def page
+    params[:page] || 1
+  end
+
+  def per_page
+    [params[:per_page].to_i, 100].min.nonzero? || 25
+  end
+end
+
+# app/controllers/concerns/error_handleable.rb
+module ErrorHandleable
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+  end
+
+  private
+
+  def not_found
+    render json: { error: "Not found" }, status: :not_found
+  end
+
+  def bad_request(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+end
+```
+
+Guidelines for controller concerns:
+
+- Each concern should handle one cross-cutting aspect
+- Don't use concerns to just split a large controller into files — that hides complexity
+- Good candidates: auth, error handling, pagination, locale, current tenant scoping
+- Bad candidates: domain-specific business logic
+
+### Presenters / Decorators
+
+Use when an action assembles complex data for the view that isn't a direct model attribute. Keeps view logic out of the controller.
+
+```ruby
+# app/presenters/player_dashboard_presenter.rb
+class PlayerDashboardPresenter
+  def initialize(player)
+    @player = player
+  end
+
+  def career_stats
+    @career_stats ||= @player.stats.group(:season).sum(:war)
+  end
+
+  def contract_status_label
+    return "Free Agent" if @player.contract_end&.past?
+    "Under Contract (#{@player.contract_end&.year})"
+  end
+
+  def trade_value_rating
+    case @player.trade_value
+    when 90.. then "Elite"
+    when 70..89 then "High"
+    when 50..69 then "Average"
+    else "Low"
+    end
+  end
+end
+
+# Controller
+def show
+  @player = Player.find(params[:id])
+  @presenter = PlayerDashboardPresenter.new(@player)
+end
+```
+
+### RESTful Resource Extraction
+
+When a controller has custom non-RESTful actions, it usually means there's a hidden resource. Extract it into its own controller with standard CRUD actions.
+
+Before:
+
+```ruby
+class PlayersController < ApplicationController
+  def trade
+    # ...
+  end
+
+  def release
+    # ...
+  end
+
+  def promote_to_roster
+    # ...
+  end
+end
+```
+
+After:
+
+```ruby
+# config/routes.rb
+resources :players do
+  resource :trade, only: [:new, :create], controller: "players/trades"
+  resource :release, only: [:create], controller: "players/releases"
+  resource :roster_promotion, only: [:create], controller: "players/roster_promotions"
+end
+
+# app/controllers/players/trades_controller.rb
+module Players
+  class TradesController < ApplicationController
+    def new
+      @player = Player.find(params[:player_id])
+    end
+
+    def create
+      result = Players::TradePlayer.new(Player.find(params[:player_id]), trade_params).call
+      # ...
+    end
+  end
+end
+```
+
+Signs you need a new controller:
+
+- Action name is a verb that isn't a CRUD verb (trade, approve, archive, publish)
+- Action operates on a different concept than the controller's resource
+- Controller has more than the 7 RESTful actions
+
+## Refactoring Process
+
+1. **Read the entire controller** and identify every action, before_action, and private method.
+2. **Inline hidden code first.** Copy logic from before_actions, helper methods, and parent classes into each action so you can see the full picture.
+3. **Classify each block** using the decision framework table above.
+4. **Extract in order**: RESTful resource extraction first (new controllers), then service objects, query objects, form objects, presenters, and finally concerns.
+5. **Slim down each action** to: find/build the resource, call a service or query, render or redirect. Each action should be 5-10 lines.
+6. **Clean up strong params.** Each controller should have one `_params` method. If you need different permitted params per action, consider separate controllers or form objects.
+7. **Create or update tests** for each extracted class with its own spec file.
+
+## What the Controller Should Look Like After
+
+```ruby
+class PlayersController < ApplicationController
+  before_action :set_player, only: [:show, :edit, :update, :destroy]
+
+  def index
+    @players = Players::FilterQuery.new(params).call
+  end
+
+  def show
+    @presenter = PlayerDashboardPresenter.new(@player)
+  end
+
+  def create
+    result = Players::SignPlayer.new(player_params, team_id: params[:team_id]).call
+
+    if result.success?
+      redirect_to result.player, notice: "Player signed"
+    else
+      @player = result.player
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    if @player.update(player_params)
+      redirect_to @player, notice: "Player updated"
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    @player.destroy
+    redirect_to players_path, notice: "Player removed"
+  end
+
+  private
+
+  def set_player
+    @player = Player.find(params[:id])
+  end
+
+  def player_params
+    params.require(:player).permit(:name, :position, :age, :team_id)
+  end
+end
+```
+
+## What NOT to Do
+
+- Don't put business logic in before_actions — they obscure the flow of an action.
+- Don't use instance variables to pass data between before_actions and actions in complex ways.
+- Don't rescue broad exceptions in individual actions — use a concern or `rescue_from`.
+- Don't add non-RESTful actions to a controller when a new controller would be clearer.
+- Don't create deeply nested service call chains — one service per action is the goal.
+- Don't move logic to private methods and call it refactored — private methods still live in the controller.

package/rails/copy-overwrite/.claude/skills/action-view-best-practices/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: action-view-best-practices
+description: Build or Refactor Rails views, partials, and templates into clean, maintainable code. Use when views have inline Ruby logic, deeply nested partials, jQuery or legacy JavaScript, helper methods returning HTML, or when the user asks to modernize, refactor, or clean up Rails views. Applies patterns - Turbo Frames, Turbo Streams, Stimulus controllers, ViewComponent, presenters, strict locals, and proper partial extraction.
+---
+
+# Rails View Refactoring
+
+Views should contain markup and minimal display logic. If a view has conditionals, calculations, query calls, or complex Ruby blocks, it needs refactoring. The modern Rails 8+ stack uses Hotwire (Turbo + Stimulus) for interactivity, Propshaft for assets, and Importmap for JavaScript — no build step required.
+
+## Decision Framework
+
+Read the view and classify each block of code:
+
+| Code type                                               | Extract to                      | Location                                   |
+| ------------------------------------------------------- | ------------------------------- | ------------------------------------------ |
+| Reusable UI patterns (buttons, cards, modals, badges)   | ViewComponent                   | `app/components/`                          |
+| Display logic (formatting, conditional CSS, label text) | Presenter or ViewComponent      | `app/presenters/` or `app/components/`     |
+| HTML-returning helper methods                           | ViewComponent                   | `app/components/`                          |
+| Inline `<script>` tags and jQuery                       | Stimulus controller             | `app/javascript/controllers/`              |
+| AJAX calls, remote forms, `$.ajax`                      | Turbo Frame or Turbo Stream     | ERB template + controller response         |
+| Partial page updates via JavaScript                     | Turbo Frame                     | Wrap in `turbo_frame_tag`                  |
+| Real-time broadcasts (chat, notifications)              | Turbo Stream                    | Model `broadcasts_to` or controller stream |
+| One-off page sections that are too long                 | Partial with strict locals      | `app/views/shared/` or alongside view      |
+| Complex data assembly for the view                      | Presenter                       | `app/presenters/`                          |
+| Repeated inline Ruby (loops with logic)                 | Collection partial or component | Partial or component                       |
+| Instance variables used across partials                 | Locals / strict locals          | Pass explicitly                            |
+
+## Modernizing to Hotwire
+
+### Replace jQuery AJAX with Turbo Frames
+
+Turbo Frames update a specific section of the page without a full reload. No JavaScript needed.
+
+```erb
+<%# Before — jQuery AJAX %>
+<div id="player-stats"></div>
+<script>
+  $.get('/players/<%= @player.id %>/stats', function(data) {
+    $('#player-stats').html(data);
+  });
+</script>
+
+<%# After — Turbo Frame %>
+<%= turbo_frame_tag "player_stats" do %>
+  <%= render partial: "players/stats", locals: { player: @player } %>
+<% end %>
+```
+
+The linked page just needs a matching `turbo_frame_tag` with the same ID and Turbo handles the rest.
+
+### Replace Remote Forms with Turbo
+
+Rails UJS `remote: true` forms are deprecated. Turbo handles forms natively.
+
+```erb
+<%# Before — Rails UJS %>
+<%= form_with model: @player, remote: true do |f| %>
+  ...
+<% end %>
+
+<%# After — Turbo (just remove remote: true, Turbo handles it) %>
+<%= form_with model: @player do |f| %>
+  ...
+<% end %>
+```
+
+Turbo intercepts all form submissions by default. For partial updates, wrap the form in a `turbo_frame_tag`. For multi-target updates, respond with a Turbo Stream:
+
+```erb
+<%# app/views/players/update.turbo_stream.erb %>
+<%= turbo_stream.replace "player_header" do %>
+  <%= render partial: "players/header", locals: { player: @player } %>
+<% end %>
+
+<%= turbo_stream.update "flash_messages" do %>
+  <%= render partial: "shared/flash" %>
+<% end %>
+```
+
+### Replace Inline JavaScript with Stimulus
+
+Any behavior attached to DOM elements (toggles, dropdowns, form validation, clipboard, modals) should be a Stimulus controller.
+
+```erb
+<%# Before — inline JS / jQuery %>
+<button onclick="document.getElementById('details').classList.toggle('hidden')">
+  Toggle
+</button>
+<div id="details" class="hidden">...</div>
+
+<%# After — Stimulus %>
+<div data-controller="toggle">
+  <button data-action="click->toggle#switch">Toggle</button>
+  <div data-toggle-target="content" class="hidden">...</div>
+</div>
+```
+
+```javascript
+// app/javascript/controllers/toggle_controller.js
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["content"];
+
+  switch() {
+    this.contentTarget.classList.toggle("hidden");
+  }
+}
+```
+
+Conventions:
+
+- One behavior per controller — keep them small and composable
+- Name controllers after what they do: `toggle`, `clipboard`, `dropdown`, `search-form`
+- Use `targets` for elements, `values` for data, `classes` for CSS class names
+- Never manipulate DOM outside the controller's element scope
+
+### Replace Polling with Turbo Streams
+
+For real-time updates, use Turbo Streams over WebSockets instead of JavaScript polling.
+
+```ruby
+# app/models/score.rb
+class Score < ApplicationRecord
+  broadcasts_to ->(score) { [score.game] }, inserts_by: :prepend
+end
+```
+
+```erb
+<%# Subscribe in the view %>
+<%= turbo_stream_from @game %>
+
+<div id="scores">
+  <%= render @game.scores %>
+</div>
+```
+
+New scores automatically appear without any JavaScript.
+
+## View Component Patterns
+
+### When to Use ViewComponent vs Partials
+
+Use **partials** for:
+
+- One-off page sections that won't be reused
+- Simple markup extraction to reduce file length
+- Layouts and structural wrappers
+
+Use **ViewComponent** for:
+
+- Reusable UI elements (buttons, cards, badges, modals, alerts)
+- Components with display logic or multiple variants
+- Anything you'd want to unit test in isolation
+- Complex components with slots for flexible content injection
+
+### ViewComponent Example
+
+```ruby
+# app/components/stat_card_component.rb
+class StatCardComponent < ViewComponent::Base
+  def initialize(label:, value:, trend: nil)
+    @label = label
+    @value = value
+    @trend = trend
+  end
+
+  def trend_class
+    case @trend
+    when :up then "text-green-600"
+    when :down then "text-red-600"
+    else "text-gray-500"
+    end
+  end
+end
+```
+
+```erb
+<%# app/components/stat_card_component.html.erb %>
+<div class="rounded-lg border p-4">
+  <dt class="text-sm text-gray-500"><%= @label %></dt>
+  <dd class="text-2xl font-semibold"><%= @value %></dd>
+  <% if @trend %>
+    <span class="<%= trend_class %>"><%= @trend == :up ? "↑" : "↓" %></span>
+  <% end %>
+</div>
+```
+
+```erb
+<%# Usage %>
+<%= render StatCardComponent.new(label: "Batting Avg", value: ".312", trend: :up) %>
+```
+
+## Partial Best Practices
+
+### Use Strict Locals
+
+Always declare expected locals at the top of partials. This was added in Rails 7.1 and prevents silent nil bugs.
+
+```erb
+<%# app/views/players/_card.html.erb %>
+<%# locals: (player:, show_stats: false) %>
+
+<div class="player-card">
+  <h3><%= player.name %></h3>
+  <% if show_stats %>
+    <%= render partial: "players/stats", locals: { player: player } %>
+  <% end %>
+</div>
+```
+
+### Use Collection Rendering
+
+Never loop and render partials manually.
+
+```erb
+<%# Before — slow, verbose %>
+<% @players.each do |player| %>
+  <%= render partial: "players/card", locals: { player: player } %>
+<% end %>
+
+<%# After — collection rendering (faster, cleaner) %>
+<%= render partial: "players/card", collection: @players, as: :player %>
+```
+
+### Avoid Deeply Nested Partials
+
+If partial A renders partial B which renders partial C, it's too deep. Flatten the structure or extract to a ViewComponent that composes its own sub-components.
+
+## Presenters for Complex View Logic
+
+When a view needs data from multiple sources or complex formatting, use a presenter instead of cramming logic into the template.
+
+```ruby
+# app/presenters/player_profile_presenter.rb
+class PlayerProfilePresenter
+  def initialize(player, current_user)
+    @player = player
+    @current_user = current_user
+  end
+
+  def display_name
+    "#{@player.first_name} #{@player.last_name}"
+  end
+
+  def contract_status_badge
+    if @player.free_agent?
+      { text: "Free Agent", color: "green" }
+    elsif @player.contract_years_remaining <= 1
+      { text: "Expiring", color: "yellow" }
+    else
+      { text: "Under Contract", color: "gray" }
+    end
+  end
+
+  def can_edit?
+    @current_user.admin? || @current_user.team == @player.team
+  end
+
+  def formatted_salary
+    ActiveSupport::NumberHelper.number_to_currency(@player.salary)
+  end
+end
+```
+
+```erb
+<%# Clean view %>
+<h1><%= @presenter.display_name %></h1>
+
+<% badge = @presenter.contract_status_badge %>
+<%= render BadgeComponent.new(text: badge[:text], color: badge[:color]) %>
+
+<%= @presenter.formatted_salary %>
+
+<% if @presenter.can_edit? %>
+  <%= link_to "Edit", edit_player_path(@player) %>
+<% end %>
+```
+
+## Eliminating Helper Abuse
+
+Rails helpers that return HTML are hard to test, hard to read, and hard to compose. Move them to ViewComponents.
+
+```ruby
+# Before — helper returning HTML (bad)
+module PlayersHelper
+  def player_avatar(player, size: :md)
+    sizes = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }
+    if player.avatar.attached?
+      image_tag player.avatar, class: "rounded-full #{sizes[size]}"
+    else
+      content_tag :div, player.initials,
+        class: "rounded-full #{sizes[size]} bg-gray-300 flex items-center justify-center"
+    end
+  end
+end
+
+# After — ViewComponent (good)
+# app/components/avatar_component.rb
+class AvatarComponent < ViewComponent::Base
+  SIZES = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }.freeze
+
+  def initialize(player:, size: :md)
+    @player = player
+    @size = size
+  end
+  # ... with its own template and tests
+end
+```
+
+Keep helpers for non-HTML formatting utilities only (number formatting, date formatting, text truncation).
+
+## Refactoring Process
+
+1. **Audit the view layer** — identify inline Ruby logic, jQuery, `remote: true` forms, helpers returning HTML, and deeply nested partials.
+2. **Remove jQuery and inline JS first** — replace with Stimulus controllers. This is the highest-impact change.
+3. **Replace `remote: true` and AJAX** — Turbo handles forms and links natively. Convert to Turbo Frames and Turbo Streams.
+4. **Add strict locals** to all existing partials.
+5. **Extract reusable UI patterns** into ViewComponents.
+6. **Move display logic** from views into presenters or component classes.
+7. **Move HTML-returning helpers** into components.
+8. **Flatten nested partials** — if nesting is deeper than 2 levels, restructure.
+9. **Add collection rendering** wherever loops render partials.
+10. **Remove all instance variables from partials** — pass data via locals only.
+
+## What NOT to Do
+
+- Don't put query calls in views — ever. Not even `count` or `any?`. Use the presenter or controller.
+- Don't use `content_for` for complex logic — it creates invisible dependencies between layouts and views.
+- Don't create Stimulus controllers that replicate what Turbo Frames already handle.
+- Don't mix jQuery and Stimulus in the same app — commit to full migration.
+- Don't render entire pages as ViewComponents — they are for reusable pieces, not whole pages.
+- Don't use `html_safe` or `raw` unless you are certain the content is sanitized.
+- Don't pass more than 3-4 locals to a partial — if you need more, it should be a component or presenter.
+- Don't use `render partial:` inside loops — use collection rendering instead.

package/rails/copy-overwrite/.claude/skills/active-record-model-best-practices/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: active-record-model-best-practices
+description: Best practices for Ruby on Rails models, splitting code into well-organized, maintainable code. Use when a model exceeds ~100 lines, has mixed responsibilities, or when the user asks to refactor, extract, clean up, or organize a Rails model. Applies patterns: concerns, service objects, query objects, form objects, and value objects.
+---
+
+# Rails Model Refactoring
+
+When refactoring a Rails model, analyze the file and extract code into the appropriate pattern based on what the code does. The model itself should only contain associations, enums, basic validations, and concern includes.
+
+## Decision Framework
+
+Read the model file and classify each block of code:
+
+| Code type | Extract to | Location |
+|---|---|---|
+| Related scopes + simple methods sharing a theme | Concern | `app/models/concerns/` |
+| Business logic, multi-step operations, callbacks with side effects | Service object | `app/services/` |
+| Complex queries, multi-join scopes, reporting queries | Query object | `app/queries/` |
+| Context-specific validations (e.g. registration vs admin update) | Form object | `app/forms/` |
+| Domain concepts beyond a primitive (money, coordinates, scores) | Value object | `app/models/` |
+| Associations, enums, core validations, simple scopes | Keep on model | — |
+
+## Patterns
+
+### Concerns
+
+Use for grouping related scopes, validations, callbacks, and simple instance methods that share a single theme. Name the concern after the capability it provides.
+
+```ruby
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :search, ->(query) { where("name ILIKE ?", "%#{query}%") }
+  end
+
+  def matching_terms(query)
+    name.scan(/#{Regexp.escape(query)}/i)
+  end
+end
+```
+
+### Service Objects
+
+Use for business logic, orchestration of multiple models, and anything triggered by a user action that involves more than a simple CRUD operation. Follow the single-responsibility principle — one service, one operation.
+
+```ruby
+# app/services/players/calculate_stats.rb
+module Players
+  class CalculateStats
+    def initialize(player)
+      @player = player
+    end
+
+    def call
+      # complex logic here
+    end
+  end
+end
+```
+
+Conventions:
+- Namespace under the model name: `Players::CalculateStats`
+- Single public method: `call`
+- Accept dependencies via `initialize`
+- Return a result or raise a domain-specific error
+
+### Query Objects
+
+Use for complex database queries that involve joins, subqueries, CTEs, or multi-condition filtering that would clutter a model with scopes.
+
+```ruby
+# app/queries/players/free_agent_query.rb
+module Players
+  class FreeAgentQuery
+    def initialize(relation = Player.all)
+      @relation = relation
+    end
+
+    def call(filters = {})
+      @relation
+        .where(contract_status: :expired)
+        .where("age < ?", filters[:max_age])
+        .joins(:stats)
+        .order(war: :desc)
+    end
+  end
+end
+```
+
+Conventions:
+- Accept a base relation in `initialize` (default to `Model.all`)
+- Return an ActiveRecord relation so it remains chainable
+- Single public method: `call`
+
+### Form Objects
+
+Use when validations only apply in specific contexts, or when a form spans multiple models.
+
+```ruby
+# app/forms/player_registration_form.rb
+class PlayerRegistrationForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :name, :string
+  attribute :email, :string
+  attribute :team_id, :integer
+  attribute :position, :string
+
+  validates :name, :email, :position, presence: true
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+  def save
+    return false unless valid?
+    Player.create!(attributes)
+  end
+end
+```
+
+### Value Objects
+
+Use for domain concepts that deserve their own identity beyond a raw primitive.
+
+```ruby
+# app/models/batting_average.rb
+class BattingAverage
+  include Comparable
+
+  def initialize(hits, at_bats)
+    @hits = hits
+    @at_bats = at_bats
+  end
+
+  def value
+    return 0.0 if @at_bats.zero?
+    (@hits.to_f / @at_bats).round(3)
+  end
+
+  def elite?
+    value >= 0.300
+  end
+
+  def <=>(other)
+    value <=> other.value
+  end
+end
+```
+
+## Refactoring Process
+
+1. **Read the entire model** and identify every method, scope, callback, and validation.
+2. **Classify each block** using the decision framework table above.
+3. **Extract in order**: value objects first, then query objects, then service objects, then concerns. Do concerns last because some may become unnecessary after other extractions.
+4. **Update the model** to include concerns and delegate to new objects.
+5. **Verify** that the slimmed-down model only contains: associations, enums, core validations, and concern includes.
+6. **Create or update tests** for each extracted class. Each new class gets its own spec file mirroring the source path.
+
+## What NOT to Do
+
+- Don't extract everything — simple one-line scopes and basic validations belong on the model.
+- Don't create a class for trivial logic just to hit a line count target.
+- Don't use concerns as junk drawers — each concern should have a clear, single theme.
+- Don't break ActiveRecord conventions (e.g. don't move associations into concerns).
+- Don't introduce callback-heavy service objects — prefer explicit invocation over implicit hooks.

package/rails/copy-overwrite/.versionrc

@@ -0,0 +1,48 @@
+{
+  "types": [
+    {
+      "type": "feat",
+      "section": "Features"
+    },
+    {
+      "type": "fix",
+      "section": "Bug Fixes"
+    },
+    {
+      "type": "chore",
+      "hidden": true
+    },
+    {
+      "type": "docs",
+      "section": "Documentation"
+    },
+    {
+      "type": "style",
+      "hidden": true
+    },
+    {
+      "type": "refactor",
+      "section": "Code Refactoring"
+    },
+    {
+      "type": "perf",
+      "section": "Performance Improvements"
+    },
+    {
+      "type": "test",
+      "hidden": true
+    }
+  ],
+  "packageFiles": [
+    {
+      "filename": "VERSION",
+      "type": "plain-text"
+    }
+  ],
+  "bumpFiles": [
+    {
+      "filename": "VERSION",
+      "type": "plain-text"
+    }
+  ]
+}

package/rails/copy-overwrite/CLAUDE.md

@@ -47,6 +47,7 @@ Never add "BREAKING CHANGE" to a commit message unless there is actually a break
 Never stash changes you can't commit. Either fix whatever is preventing the commit or fail out and let the human know why.
 Never lower thresholds for tests to pass a pre-push hook. You must increase test coverage to make it pass
 Never modify db/schema.rb directly. Use migrations to change the database schema.
+Never handle tasks yourself when working in a team of agents. Always delegate to a specialied agent.
 
 ONLY use rubocop:disable as a last resort and confirm with human before doing so
 ONLY use rubocop:disable for specific cops, never disable all cops at once

package/rails/copy-overwrite/config/initializers/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Reads application version from the VERSION file at project root.
+# The VERSION file is managed by standard-version and bumped during releases.
+APP_VERSION = Rails.root.join('VERSION').read.strip.freeze

package/rails/create-only/.github/workflows/quality.yml

@@ -34,6 +34,27 @@ jobs:
       - run: bundle exec brakeman --no-pager --quiet
       - run: bundle exec bundler-audit check --update
 
+  # Default: PostgreSQL. For MySQL, replace the service block and env vars:
+  #   services:
+  #     mysql:
+  #       image: mysql:8.0
+  #       env:
+  #         MYSQL_ROOT_PASSWORD: password
+  #         MYSQL_DATABASE: test
+  #       ports:
+  #         - 3306:3306
+  #       options: >-
+  #         --health-cmd "mysqladmin ping -h localhost"
+  #         --health-interval 10s
+  #         --health-timeout 5s
+  #         --health-retries 5
+  #   env:
+  #     RAILS_ENV: test
+  #     PRIMARY_DB_HOST: 127.0.0.1
+  #     DATABASE_NAME: test
+  #     DATABASE_PASSWORD: password
+  #     DATABASE_USER: root
+  #     DATABASE_PORT: 3306
   test:
     name: Test
     runs-on: ubuntu-latest
@@ -59,7 +80,7 @@ jobs:
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
-      - run: bin/rails db:schema:load
+      - run: bin/rails db:prepare
       - run: bundle exec rspec
 
   code-quality:

package/rails/create-only/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  push:
+    branches: [main, staging]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: webfactory/ssh-agent@v0.9.0
+        with:
+          ssh-private-key: ${{ secrets.DEPLOY_KEY }}
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+
+      - name: Check for skip conditions
+        id: skip
+        run: |
+          COMMIT_MSG=$(git log -1 --pretty=%B)
+
+          # Skip if last commit is a version bump
+          if echo "$COMMIT_MSG" | grep -q "^chore(release):"; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Skip promotion merges (environment branch → main) only on main
+          if [ "$GITHUB_REF_NAME" = "main" ]; then
+            ENV_BRANCHES="dev|staging"
+
+            # Message-based detection: merge commits
+            # Pattern: "Merge branch 'staging' into main"
+            if echo "$COMMIT_MSG" | grep -qiE "^Merge branch ['\"]?($ENV_BRANCHES)['\"]? into"; then
+              echo "skip=true" >> $GITHUB_OUTPUT
+              exit 0
+            fi
+
+            # Pattern: "Merge pull request #123 from org/staging"
+            if echo "$COMMIT_MSG" | grep -qiE "^Merge pull request.*from .*/($ENV_BRANCHES)$"; then
+              echo "skip=true" >> $GITHUB_OUTPUT
+              exit 0
+            fi
+
+            # Git-based detection: squash/fast-forward promotions
+            for ENV_BRANCH in dev staging; do
+              git fetch origin "$ENV_BRANCH" 2>/dev/null || continue
+              if git merge-base --is-ancestor HEAD "origin/$ENV_BRANCH" 2>/dev/null; then
+                echo "skip=true" >> $GITHUB_OUTPUT
+                exit 0
+              fi
+            done
+          fi
+
+          echo "skip=false" >> $GITHUB_OUTPUT
+
+      - uses: actions/setup-node@v4
+        if: steps.skip.outputs.skip != 'true'
+        with:
+          node-version: '22'
+
+      - name: Configure Git
+        if: steps.skip.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version and create tag
+        if: steps.skip.outputs.skip != 'true'
+        run: npx standard-version@9
+
+      - name: Push changes
+        if: steps.skip.outputs.skip != 'true'
+        run: |
+          git remote set-url origin git@github.com:${{ github.repository }}.git
+          git push --follow-tags origin ${{ github.ref_name }}
+
+      - name: Create GitHub Release
+        if: steps.skip.outputs.skip != 'true' && github.ref_name == 'main'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(cat VERSION)
+          gh release create "v${VERSION}" \
+            --title "v${VERSION}" \
+            --generate-notes

package/rails/create-only/.reek.yml

@@ -24,6 +24,9 @@ directories:
   'app/helpers':
     UtilityFunction:
       enabled: false
+  'app/jobs':
+    UtilityFunction:
+      enabled: false
   'db/migrate':
     IrresponsibleModule:
       enabled: false

package/rails/create-only/.rubocop.local.yml

@@ -2,8 +2,21 @@
 # This file is NOT managed by Lisa — edit freely.
 # Add or override any RuboCop cops below.
 
-# Example:
-# Metrics/MethodLength:
-#   Max: 25
+# Align with Reek's UncommunicativeVariableName (which rejects single-char names)
+Naming/RescuedExceptionsVariableName:
+  PreferredName: error
+
+# Add staging to known environments if your app uses a staging Rails env
+# Rails/UnknownEnv:
+#   Environments:
+#     - development
+#     - test
+#     - staging
+#     - production
+
+# Auto-generated schema files can exceed block length limits
+# Metrics/BlockLength:
 #   Exclude:
-#     - 'app/controllers/api/v1/**/*'
+#     - 'db/queue_schema.rb'
+#     - 'db/cable_schema.rb'
+#     - 'db/cache_schema.rb'

package/rails/create-only/VERSION

@@ -0,0 +1 @@
+0.0.1