ag-cortex 0.1.0

package/.agent/skills/dhh-rails-style/references/gems.md

@@ -0,0 +1,266 @@
+# Gems - DHH Rails Style
+
+<what_they_use>
+## What 37signals Uses
+
+**Core Rails stack:**
+- turbo-rails, stimulus-rails, importmap-rails
+- propshaft (asset pipeline)
+
+**Database-backed services (Solid suite):**
+- solid_queue - background jobs
+- solid_cache - caching
+- solid_cable - WebSockets/Action Cable
+
+**Authentication & Security:**
+- bcrypt (for any password hashing needed)
+
+**Their own gems:**
+- geared_pagination (cursor-based pagination)
+- lexxy (rich text editor)
+- mittens (mailer utilities)
+
+**Utilities:**
+- rqrcode (QR code generation)
+- redcarpet + rouge (Markdown rendering)
+- web-push (push notifications)
+
+**Deployment & Operations:**
+- kamal (Docker deployment)
+- thruster (HTTP/2 proxy)
+- mission_control-jobs (job monitoring)
+- autotuner (GC tuning)
+</what_they_use>
+
+<what_they_avoid>
+## What They Deliberately Avoid
+
+**Authentication:**
+```
+devise → Custom ~150-line auth
+```
+Why: Full control, no password liability with magic links, simpler.
+
+**Authorization:**
+```
+pundit/cancancan → Simple role checks in models
+```
+Why: Most apps don't need policy objects. A method on the model suffices:
+```ruby
+class Board < ApplicationRecord
+  def editable_by?(user)
+    user.admin? || user == creator
+  end
+end
+```
+
+**Background Jobs:**
+```
+sidekiq → Solid Queue
+```
+Why: Database-backed means no Redis, same transactional guarantees.
+
+**Caching:**
+```
+redis → Solid Cache
+```
+Why: Database is already there, simpler infrastructure.
+
+**Search:**
+```
+elasticsearch → Custom sharded search
+```
+Why: Built exactly what they need, no external service dependency.
+
+**View Layer:**
+```
+view_component → Standard partials
+```
+Why: Partials work fine. ViewComponents add complexity without clear benefit for their use case.
+
+**API:**
+```
+GraphQL → REST with Turbo
+```
+Why: REST is sufficient when you control both ends. GraphQL complexity not justified.
+
+**Factories:**
+```
+factory_bot → Fixtures
+```
+Why: Fixtures are simpler, faster, and encourage thinking about data relationships upfront.
+
+**Service Objects:**
+```
+Interactor, Trailblazer → Fat models
+```
+Why: Business logic stays in models. Methods like `card.close` instead of `CardCloser.call(card)`.
+
+**Form Objects:**
+```
+Reform, dry-validation → params.expect + model validations
+```
+Why: Rails 7.1's `params.expect` is clean enough. Contextual validations on model.
+
+**Decorators:**
+```
+Draper → View helpers + partials
+```
+Why: Helpers and partials are simpler. No decorator indirection.
+
+**CSS:**
+```
+Tailwind, Sass → Native CSS
+```
+Why: Modern CSS has nesting, variables, layers. No build step needed.
+
+**Frontend:**
+```
+React, Vue, SPAs → Turbo + Stimulus
+```
+Why: Server-rendered HTML with sprinkles of JS. SPA complexity not justified.
+
+**Testing:**
+```
+RSpec → Minitest
+```
+Why: Simpler, faster boot, less DSL magic, ships with Rails.
+</what_they_avoid>
+
+<testing_philosophy>
+## Testing Philosophy
+
+**Minitest** - simpler, faster:
+```ruby
+class CardTest < ActiveSupport::TestCase
+  test "closing creates closure" do
+    card = cards(:one)
+    assert_difference -> { Card::Closure.count } do
+      card.close
+    end
+    assert card.closed?
+  end
+end
+```
+
+**Fixtures** - loaded once, deterministic:
+```yaml
+# test/fixtures/cards.yml
+open_card:
+  title: Open Card
+  board: main
+  creator: alice
+
+closed_card:
+  title: Closed Card
+  board: main
+  creator: bob
+```
+
+**Dynamic timestamps** with ERB:
+```yaml
+recent:
+  title: Recent
+  created_at: <%= 1.hour.ago %>
+
+old:
+  title: Old
+  created_at: <%= 1.month.ago %>
+```
+
+**Time travel** for time-dependent tests:
+```ruby
+test "expires after 15 minutes" do
+  magic_link = MagicLink.create!(user: users(:alice))
+
+  travel 16.minutes
+
+  assert magic_link.expired?
+end
+```
+
+**VCR** for external APIs:
+```ruby
+VCR.use_cassette("stripe/charge") do
+  charge = Stripe::Charge.create(amount: 1000)
+  assert charge.paid
+end
+```
+
+**Tests ship with features** - same commit, not before or after.
+</testing_philosophy>
+
+<decision_framework>
+## Decision Framework
+
+Before adding a gem, ask:
+
+1. **Can vanilla Rails do this?**
+   - ActiveRecord can do most things Sequel can
+   - ActionMailer handles email fine
+   - ActiveJob works for most job needs
+
+2. **Is the complexity worth it?**
+   - 150 lines of custom code vs. 10,000-line gem
+   - You'll understand your code better
+   - Fewer upgrade headaches
+
+3. **Does it add infrastructure?**
+   - Redis? Consider database-backed alternatives
+   - External service? Consider building in-house
+   - Simpler infrastructure = fewer failure modes
+
+4. **Is it from someone you trust?**
+   - 37signals gems: battle-tested at scale
+   - Well-maintained, focused gems: usually fine
+   - Kitchen-sink gems: probably overkill
+
+**The philosophy:**
+> "Build solutions before reaching for gems."
+
+Not anti-gem, but pro-understanding. Use gems when they genuinely solve a problem you have, not a problem you might have.
+</decision_framework>
+
+<gem_patterns>
+## Gem Usage Patterns
+
+**Pagination:**
+```ruby
+# geared_pagination - cursor-based
+class CardsController < ApplicationController
+  def index
+    @cards = @board.cards.geared(page: params[:page])
+  end
+end
+```
+
+**Markdown:**
+```ruby
+# redcarpet + rouge
+class MarkdownRenderer
+  def self.render(text)
+    Redcarpet::Markdown.new(
+      Redcarpet::Render::HTML.new(filter_html: true),
+      autolink: true,
+      fenced_code_blocks: true
+    ).render(text)
+  end
+end
+```
+
+**Background jobs:**
+```ruby
+# solid_queue - no Redis
+class ApplicationJob < ActiveJob::Base
+  queue_as :default
+  # Just works, backed by database
+end
+```
+
+**Caching:**
+```ruby
+# solid_cache - no Redis
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+```
+</gem_patterns>

package/.agent/skills/dhh-rails-style/references/models.md

@@ -0,0 +1,359 @@
+# Models - DHH Rails Style
+
+<model_concerns>
+## Concerns for Horizontal Behavior
+
+Models heavily use concerns. A typical Card model includes 14+ concerns:
+
+```ruby
+class Card < ApplicationRecord
+  include Assignable
+  include Attachments
+  include Broadcastable
+  include Closeable
+  include Colored
+  include Eventable
+  include Golden
+  include Mentions
+  include Multistep
+  include Pinnable
+  include Postponable
+  include Readable
+  include Searchable
+  include Taggable
+  include Watchable
+end
+```
+
+Each concern is self-contained with associations, scopes, and methods.
+
+**Naming:** Adjectives describing capability (`Closeable`, `Publishable`, `Watchable`)
+</model_concerns>
+
+<state_records>
+## State as Records, Not Booleans
+
+Instead of boolean columns, create separate records:
+
+```ruby
+# Instead of:
+closed: boolean
+is_golden: boolean
+postponed: boolean
+
+# Create records:
+class Card::Closure < ApplicationRecord
+  belongs_to :card
+  belongs_to :creator, class_name: "User"
+end
+
+class Card::Goldness < ApplicationRecord
+  belongs_to :card
+  belongs_to :creator, class_name: "User"
+end
+
+class Card::NotNow < ApplicationRecord
+  belongs_to :card
+  belongs_to :creator, class_name: "User"
+end
+```
+
+**Benefits:**
+- Automatic timestamps (when it happened)
+- Track who made changes
+- Easy filtering via joins and `where.missing`
+- Enables rich UI showing when/who
+
+**In the model:**
+```ruby
+module Closeable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one :closure, dependent: :destroy
+  end
+
+  def closed?
+    closure.present?
+  end
+
+  def close(creator: Current.user)
+    create_closure!(creator: creator)
+  end
+
+  def reopen
+    closure&.destroy
+  end
+end
+```
+
+**Querying:**
+```ruby
+Card.joins(:closure)         # closed cards
+Card.where.missing(:closure) # open cards
+```
+</state_records>
+
+<callbacks>
+## Callbacks - Used Sparingly
+
+Only 38 callback occurrences across 30 files in Fizzy. Guidelines:
+
+**Use for:**
+- `after_commit` for async work
+- `before_save` for derived data
+- `after_create_commit` for side effects
+
+**Avoid:**
+- Complex callback chains
+- Business logic in callbacks
+- Synchronous external calls
+
+```ruby
+class Card < ApplicationRecord
+  after_create_commit :notify_watchers_later
+  before_save :update_search_index, if: :title_changed?
+
+  private
+    def notify_watchers_later
+      NotifyWatchersJob.perform_later(self)
+    end
+end
+```
+</callbacks>
+
+<scopes>
+## Scope Naming
+
+Standard scope names:
+
+```ruby
+class Card < ApplicationRecord
+  scope :chronologically, -> { order(created_at: :asc) }
+  scope :reverse_chronologically, -> { order(created_at: :desc) }
+  scope :alphabetically, -> { order(title: :asc) }
+  scope :latest, -> { reverse_chronologically.limit(10) }
+
+  # Standard eager loading
+  scope :preloaded, -> { includes(:creator, :assignees, :tags) }
+
+  # Parameterized
+  scope :indexed_by, ->(column) { order(column => :asc) }
+  scope :sorted_by, ->(column, direction = :asc) { order(column => direction) }
+end
+```
+</scopes>
+
+<poros>
+## Plain Old Ruby Objects
+
+POROs namespaced under parent models:
+
+```ruby
+# app/models/event/description.rb
+class Event::Description
+  def initialize(event)
+    @event = event
+  end
+
+  def to_s
+    # Presentation logic for event description
+  end
+end
+
+# app/models/card/eventable/system_commenter.rb
+class Card::Eventable::SystemCommenter
+  def initialize(card)
+    @card = card
+  end
+
+  def comment(message)
+    # Business logic
+  end
+end
+
+# app/models/user/filtering.rb
+class User::Filtering
+  # View context bundling
+end
+```
+
+**NOT used for service objects.** Business logic stays in models.
+</poros>
+
+<verbs_predicates>
+## Method Naming
+
+**Verbs** - Actions that change state:
+```ruby
+card.close
+card.reopen
+card.gild      # make golden
+card.ungild
+board.publish
+board.archive
+```
+
+**Predicates** - Queries derived from state:
+```ruby
+card.closed?    # closure.present?
+card.golden?    # goldness.present?
+board.published?
+```
+
+**Avoid** generic setters:
+```ruby
+# Bad
+card.set_closed(true)
+card.update_golden_status(false)
+
+# Good
+card.close
+card.ungild
+```
+</verbs_predicates>
+
+<validation_philosophy>
+## Validation Philosophy
+
+Minimal validations on models. Use contextual validations on form/operation objects:
+
+```ruby
+# Model - minimal
+class User < ApplicationRecord
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+end
+
+# Form object - contextual
+class Signup
+  include ActiveModel::Model
+
+  attr_accessor :email, :name, :terms_accepted
+
+  validates :email, :name, presence: true
+  validates :terms_accepted, acceptance: true
+
+  def save
+    return false unless valid?
+    User.create!(email: email, name: name)
+  end
+end
+```
+
+**Prefer database constraints** over model validations for data integrity:
+```ruby
+# migration
+add_index :users, :email, unique: true
+add_foreign_key :cards, :boards
+```
+</validation_philosophy>
+
+<error_handling>
+## Let It Crash Philosophy
+
+Use bang methods that raise exceptions on failure:
+
+```ruby
+# Preferred - raises on failure
+@card = Card.create!(card_params)
+@card.update!(title: new_title)
+@comment.destroy!
+
+# Avoid - silent failures
+@card = Card.create(card_params)  # returns false on failure
+if @card.save
+  # ...
+end
+```
+
+Let errors propagate naturally. Rails handles ActiveRecord::RecordInvalid with 422 responses.
+</error_handling>
+
+<default_values>
+## Default Values with Lambdas
+
+Use lambda defaults for associations with Current:
+
+```ruby
+class Card < ApplicationRecord
+  belongs_to :creator, class_name: "User", default: -> { Current.user }
+  belongs_to :account, default: -> { Current.account }
+end
+
+class Comment < ApplicationRecord
+  belongs_to :commenter, class_name: "User", default: -> { Current.user }
+end
+```
+
+Lambdas ensure dynamic resolution at creation time.
+</default_values>
+
+<rails_71_patterns>
+## Rails 7.1+ Model Patterns
+
+**Normalizes** - clean data before validation:
+```ruby
+class User < ApplicationRecord
+  normalizes :email, with: ->(email) { email.strip.downcase }
+  normalizes :phone, with: ->(phone) { phone.gsub(/\D/, "") }
+end
+```
+
+**Delegated Types** - replace polymorphic associations:
+```ruby
+class Message < ApplicationRecord
+  delegated_type :messageable, types: %w[Comment Reply Announcement]
+end
+
+# Now you get:
+message.comment?        # true if Comment
+message.comment         # returns the Comment
+Message.comments        # scope for Comment messages
+```
+
+**Store Accessor** - structured JSON storage:
+```ruby
+class User < ApplicationRecord
+  store :settings, accessors: [:theme, :notifications_enabled], coder: JSON
+end
+
+user.theme = "dark"
+user.notifications_enabled = true
+```
+</rails_71_patterns>
+
+<concern_guidelines>
+## Concern Guidelines
+
+- **50-150 lines** per concern (most are ~100)
+- **Cohesive** - related functionality only
+- **Named for capabilities** - `Closeable`, `Watchable`, not `CardHelpers`
+- **Self-contained** - associations, scopes, methods together
+- **Not for mere organization** - create when genuine reuse needed
+
+**Touch chains** for cache invalidation:
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :card, touch: true
+end
+
+class Card < ApplicationRecord
+  belongs_to :board, touch: true
+end
+```
+
+When comment updates, card's `updated_at` changes, which cascades to board.
+
+**Transaction wrapping** for related updates:
+```ruby
+class Card < ApplicationRecord
+  def close(creator: Current.user)
+    transaction do
+      create_closure!(creator: creator)
+      record_event(:closed)
+      notify_watchers_later
+    end
+  end
+end
+```
+</concern_guidelines>