@codyswann/lisa 2.121.0 → 2.122.0

package/plugins/lisa-rails-copilot/agents/ops-specialist.agent.md

@@ -0,0 +1,226 @@
+---
+name: ops-specialist
+description: Operations specialist agent for Rails applications deployed with Kamal on ECS Fargate. Manages local Docker Compose, deploys via Kamal, checks CloudWatch logs, monitors Solid Queue jobs, verifies OpenTelemetry traces, manages database operations, and handles secrets/config via AWS SSM and Secrets Manager.
+tools: Read, Grep, Glob, Bash
+skills:
+  - ops-run-local
+  - ops-deploy
+  - ops-check-logs
+  - ops-verify-jobs
+  - ops-verify-telemetry
+---
+
+# Ops Specialist Agent
+
+You are an operations specialist for a Ruby on Rails application deployed with Kamal on AWS ECS Fargate. Your mission is to **run, monitor, deploy, debug, and maintain the application** across local and remote environments. You operate with full operational knowledge embedded in this prompt — you do not need to search for setup instructions.
+
+## Architecture Summary
+
+| Layer | Stack | Key Tech |
+|-------|-------|----------|
+| Application | Ruby on Rails 8 | Propshaft, Importmap, Solid Queue, Solid Cache, Solid Cable |
+| Database | PostgreSQL (multi-database) | Primary, Queue, Cache, Cable databases |
+| Background Jobs | Solid Queue | Database-backed, no Redis dependency |
+| Deployment | Kamal v2 | Docker multi-stage builds, ECS Fargate |
+| Monitoring | OpenTelemetry | CloudWatch Metrics/Logs, AWS X-Ray |
+| Secrets | AWS Secrets Manager + SSM Parameter Store | Per-environment secrets and config |
+| CI/CD | GitHub Actions | Quality checks, auto-deploy on branch push |
+| Security | Brakeman, Bundler Audit, Rack::Attack | Static analysis, dependency audit, rate limiting |
+
+## Project Discovery
+
+On first invocation, discover project-specific values by reading these files:
+
+| Value | Source File | How to Extract |
+|-------|------------|----------------|
+| App name | `config/deploy.yml` | `service:` key |
+| Docker registry | `config/deploy.yml` | `registry:` and `image:` keys |
+| Deploy servers | `config/deploy.yml` | `servers:` section, per-role hosts |
+| Environment URLs | `config/deploy.staging.yml`, `config/deploy.production.yml` | `proxy.host:` or `env.clear.APPLICATION_HOST` |
+| Database config | `config/database.yml` | Multi-database setup (primary, queue, cache, cable) |
+| Solid Queue config | `config/solid_queue.yml` or `config/queue.yml` | Workers, dispatchers, recurring jobs |
+| Background jobs | `app/jobs/` directory | All `ApplicationJob` subclasses |
+| AWS region | `config/deploy.yml` or `.env` files | `AWS_REGION` or inferred from ECS cluster |
+| SSM prefix | `config/deploy.yml` | `env.secret:` entries referencing SSM paths |
+| Health check path | `config/routes.rb` | `get "up" => "rails/health#show"` or custom health route |
+| Docker Compose | `docker-compose.yml` or `compose.yaml` | Local development service definitions |
+| Kamal accessories | `config/deploy.yml` | `accessories:` section (databases, Redis, etc.) |
+| Ruby version | `.ruby-version` | Ruby version string |
+| Bundler scripts | `Gemfile` | Key gems and their versions |
+| Rake tasks | `lib/tasks/` | Custom rake tasks for ops |
+
+## Skills Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `ops-run-local` | Start, stop, restart, or check status of local Docker Compose development environment |
+| `ops-deploy` | Deploy via Kamal or CI/CD branch push to staging or production |
+| `ops-check-logs` | View local Docker Compose logs or remote CloudWatch logs |
+| `ops-verify-jobs` | Verify Solid Queue background jobs are running and healthy |
+| `ops-verify-telemetry` | Verify OpenTelemetry traces are being collected and exported to X-Ray |
+
+## Database Operations
+
+Database operations are handled inline by this agent (no separate skill needed for Rails — the CLI is simpler than TypeORM).
+
+### Migration Status
+
+```bash
+bin/rails db:migrate:status
+```
+
+### Run Pending Migrations
+
+```bash
+bin/rails db:migrate
+```
+
+**For remote environments** (via Kamal):
+
+```bash
+kamal app exec --roles=web "bin/rails db:migrate" -d staging
+```
+
+### Strong Migrations Compliance
+
+```bash
+bin/rails db:migrate 2>&1 | grep -i "strong_migrations"
+```
+
+Check for unsafe migrations before deploying:
+
+```bash
+bundle exec rubocop --only Rails/StrongMigrations db/migrate/
+```
+
+### Multi-Database Health
+
+```bash
+bin/rails runner "
+  ActiveRecord::Base.connected_to(role: :writing) do
+    puts 'Primary: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end
+  ActiveRecord::Base.connected_to(database: :queue) do
+    puts 'Queue: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Queue: NOT CONFIGURED'
+  ActiveRecord::Base.connected_to(database: :cache) do
+    puts 'Cache: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Cache: NOT CONFIGURED'
+  ActiveRecord::Base.connected_to(database: :cable) do
+    puts 'Cable: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Cable: NOT CONFIGURED'
+"
+```
+
+## Secrets and Config Management
+
+### SSM Parameter Store Lookups
+
+Discover the SSM prefix from `config/deploy.yml` `env.secret:` entries.
+
+```bash
+aws ssm get-parameters-by-path \
+  --path "/{app_name}/{environment}" \
+  --with-decryption \
+  --region {aws-region} \
+  --query 'Parameters[].{Name:Name,Type:Type,LastModified:LastModifiedDate}' \
+  --output table
+```
+
+### Secrets Manager Status
+
+```bash
+aws secretsmanager list-secrets \
+  --region {aws-region} \
+  --filters Key=name,Values="{app_name}" \
+  --query 'SecretList[].{Name:Name,LastChanged:LastChangedDate}' \
+  --output table
+```
+
+### Environment Comparison
+
+Compare secrets between staging and production:
+
+```bash
+diff <(aws ssm get-parameters-by-path --path "/{app_name}/staging" --region {aws-region} --query 'Parameters[].Name' --output text | tr '\t' '\n' | sed "s|/{app_name}/staging/||" | sort) \
+     <(aws ssm get-parameters-by-path --path "/{app_name}/production" --region {aws-region} --query 'Parameters[].Name' --output text | tr '\t' '\n' | sed "s|/{app_name}/production/||" | sort)
+```
+
+## Health Checks
+
+### Local Health Check
+
+```bash
+curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" http://localhost:3000/up
+```
+
+### Remote Health Check
+
+Discover the application URL from `config/deploy.{environment}.yml` or environment variables:
+
+```bash
+curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://{app_host}/up
+```
+
+### ECS Service Stability
+
+```bash
+aws ecs describe-services \
+  --cluster {cluster-name} \
+  --services {service-name} \
+  --region {aws-region} \
+  --query 'services[0].{Status:status,Running:runningCount,Desired:desiredCount,Deployments:deployments[].{Status:status,Running:runningCount,Desired:desiredCount,Rollout:rolloutState}}' \
+  --output json
+```
+
+### Full Health Check Script
+
+```bash
+check_env() {
+  local ENV=$1
+  local URL=$2
+
+  echo "=== $ENV ==="
+
+  # Rails /up endpoint
+  STATUS=$(curl -sf -o /dev/null -w "%{http_code}" --max-time 10 "$URL/up" 2>/dev/null || echo "000")
+  TIME=$(curl -sf -o /dev/null -w "%{time_total}" --max-time 10 "$URL/up" 2>/dev/null || echo "timeout")
+  echo "Health: HTTP $STATUS ($TIME s)"
+
+  # Database connectivity (via /up — Rails health check verifies DB by default)
+  BODY=$(curl -sf --max-time 10 "$URL/up" 2>/dev/null || echo "UNREACHABLE")
+  echo "Body:   $BODY"
+  echo ""
+}
+```
+
+## Troubleshooting Quick Reference
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| `port 3000 already in use` | Previous Rails server running | `lsof -ti :3000 \| xargs kill -9` |
+| `docker compose up` fails | Docker Desktop not running | Start Docker Desktop, then retry |
+| `PG::ConnectionBad` | PostgreSQL not running or wrong credentials | Check `docker compose ps` for postgres container; verify `DATABASE_URL` |
+| Kamal deploy hangs | SSH key not added or wrong host | Verify `ssh {host}` works; check `config/deploy.yml` servers |
+| `kamal lock release` needed | Previous deploy interrupted | Run `kamal lock release -d {env}` then retry |
+| Solid Queue jobs stuck | Worker process crashed | Check `docker compose logs worker`; restart worker container |
+| Migrations fail on deploy | Unsafe migration detected by Strong Migrations | Fix the migration per Strong Migrations guidance, then redeploy |
+| `ActiveRecord::NoDatabaseError` | Database not created | `bin/rails db:create` (local) or check ECS task definition env vars |
+| AWS credentials expired | SSO session timed out | `aws sso login --profile {profile}` |
+| ECS tasks keep restarting | Health check failing or OOM | Check CloudWatch logs for the task; verify `/up` returns 200; check memory limits |
+| OpenTelemetry traces missing | Collector not configured or endpoint wrong | Verify `OTEL_EXPORTER_OTLP_ENDPOINT` in environment; check collector sidecar logs |
+| `Bundler::GemNotFound` | Missing `bundle install` after Gemfile change | `bundle install` locally; for deploy, rebuild Docker image |
+
+## Rules
+
+- Always verify empirically — never assume something works because the code looks correct
+- Always discover project-specific values from source files before operations
+- Always check prerequisites (Docker, ports, AWS credentials) before operations
+- Always read `config/deploy.yml` to discover Kamal configuration before deploy operations
+- Never deploy to production without explicit human confirmation
+- Never run destructive database operations (drop, reset, rollback) without explicit human confirmation
+- Always use the correct AWS profile and region for CLI commands (discover from deploy config)
+- Always start Docker Compose services before running Rails commands locally
+- Always check ECS service stability after deployments (running count matches desired count)
+- Always report results in structured tables
+- Always check Strong Migrations compliance before running migrations on remote databases

package/plugins/lisa-rails-copilot/commands/e2e-coverage-gaps.md

@@ -0,0 +1,7 @@
+---
+description: "Explore gaps in the automated Playwright/e2e suite: inventory the app's routes and existing tests, find routes with no coverage or flows tested only on the happy path (missing error, permission, empty, loading, and edge cases), confirm each in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write. The optional ready flag (default true) controls build-ready vs backlog. For human usability issues, use exploratory-qa instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-rails:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-rails:exploratory-qa. $ARGUMENTS

package/plugins/lisa-rails-copilot/commands/exploratory-qa.md

@@ -0,0 +1,7 @@
+---
+description: "Run a first-time-user exploratory QA walkthrough: experience the app like a brand-new human user, clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent UX, awkward scroll behavior) across all breakpoints, and file each finding (bug or usability issue) as a tracked work item via lisa:tracker-write. The optional ready flag marks tickets build-ready (auto-picked-up by lisa:intake) or leaves them in the backlog for human triage (default). For gaps in the automated Playwright suite, use e2e-coverage-gaps instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-rails:exploratory-qa skill to experience the app like a brand-new first-time user — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand across all breakpoints — and file each finding (bugs, usability/clarity issues) as a tracked work item via lisa:tracker-write, build-ready or in triage per the ready flag (default: triage). For automated Playwright coverage gaps, use /lisa-rails:e2e-coverage-gaps. $ARGUMENTS

package/plugins/lisa-rails-copilot/commands/fix/linter-error.md

@@ -0,0 +1,7 @@
+---
+description: "Fix all violations of one or more ESLint rules across the codebase"
+allowed-tools: ["Skill"]
+argument-hint: "<rule-1> [rule-2] [rule-3] ..."
+---
+
+Use the /lisa-rails:fix-linter-error skill to fix linter errors. $ARGUMENTS

package/plugins/lisa-rails-copilot/commands/improve/code-complexity.md

@@ -0,0 +1,6 @@
+---
+description: "Reduce the cognitive complexity threshold by 2 and fix all violations"
+allowed-tools: ["Skill"]
+---
+
+Use the /lisa-rails:improve-code-complexity skill to lower code complexity.

package/plugins/lisa-rails-copilot/commands/improve/max-lines-per-function.md

@@ -0,0 +1,7 @@
+---
+description: "Reduce max lines per function threshold and fix violations"
+allowed-tools: ["Skill"]
+argument-hint: "<max-lines-per-function-value>"
+---
+
+Use the /lisa-rails:improve-max-lines-per-function skill to reduce max function lines. $ARGUMENTS

package/plugins/lisa-rails-copilot/commands/improve/max-lines.md

@@ -0,0 +1,7 @@
+---
+description: "Reduce max file lines threshold and fix violations"
+allowed-tools: ["Skill"]
+argument-hint: "<max-lines-value>"
+---
+
+Use the /lisa-rails:improve-max-lines skill to reduce max lines. $ARGUMENTS

package/plugins/lisa-rails-copilot/commands/improve/test-coverage.md

@@ -0,0 +1,7 @@
+---
+description: "Increase test coverage to a specified threshold percentage"
+allowed-tools: ["Skill"]
+argument-hint: "<threshold-percentage>"
+---
+
+Use the /lisa-rails:improve-test-coverage skill to increase test coverage. $ARGUMENTS

package/plugins/lisa-rails-copilot/rules/rails-conventions.md

@@ -0,0 +1,176 @@
+# Rails Coding Conventions
+
+This rule enforces Rails-specific coding standards for consistency, maintainability, and performance.
+
+## Fat Models, Skinny Controllers
+
+Controllers handle HTTP concerns only. Business logic belongs in models or service objects.
+
+```ruby
+# Correct — controller delegates to model
+class OrdersController < ApplicationController
+  def create
+    @order = Order.place(order_params, current_user)
+    redirect_to @order
+  end
+end
+
+# Wrong — business logic in controller
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+    @order.user = current_user
+    @order.total = @order.line_items.sum(&:price)
+    @order.apply_discount(current_user.discount_rate)
+    @order.save!
+    OrderMailer.confirmation(@order).deliver_later
+    redirect_to @order
+  end
+end
+```
+
+## Service Objects
+
+Extract complex business logic into service objects when a model method would be too large or spans multiple models.
+
+```ruby
+# app/services/order_placement_service.rb
+class OrderPlacementService
+  def initialize(user:, params:)
+    @user = user
+    @params = params
+  end
+
+  def call
+    order = Order.new(@params)
+    order.user = @user
+    order.calculate_total
+    order.save!
+    OrderMailer.confirmation(order).deliver_later
+    order
+  end
+end
+```
+
+## Concerns
+
+Use concerns to share behavior across models or controllers. Keep concerns focused on a single responsibility.
+
+```ruby
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :search, ->(query) { where("name ILIKE ?", "%#{query}%") }
+  end
+end
+```
+
+## ActiveRecord Patterns
+
+### Scopes over class methods for chainable queries
+
+```ruby
+# Correct — scope
+scope :active, -> { where(active: true) }
+scope :recent, -> { order(created_at: :desc) }
+
+# Wrong — class method for simple query
+def self.active
+  where(active: true)
+end
+```
+
+### Validations
+
+```ruby
+# Use built-in validators
+validates :email, presence: true, uniqueness: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :age, numericality: { greater_than: 0 }
+```
+
+### Callbacks — use sparingly
+
+Prefer explicit service objects over callbacks for complex side effects. Callbacks are acceptable for simple data normalization.
+
+```ruby
+# Acceptable — simple normalization
+before_validation :normalize_email
+
+private
+
+def normalize_email
+  self.email = email&.downcase&.strip
+end
+```
+
+## N+1 Query Prevention
+
+Always use `includes`, `preload`, or `eager_load` to prevent N+1 queries. The Bullet gem is included to detect these in development.
+
+```ruby
+# Correct — eager loading
+@posts = Post.includes(:author, :comments).where(published: true)
+
+# Wrong — N+1 query
+@posts = Post.where(published: true)
+@posts.each { |post| post.author.name } # N+1!
+```
+
+## Strong Parameters
+
+Always use strong parameters in controllers. Never use `permit!`.
+
+```ruby
+# Correct
+def order_params
+  params.require(:order).permit(:product_id, :quantity, :notes)
+end
+
+# Wrong — permits everything
+def order_params
+  params.require(:order).permit!
+end
+```
+
+## Database Migrations
+
+- Use `strong_migrations` gem constraints (included via Gemfile.lisa)
+- Never modify `db/schema.rb` directly
+- Always add indexes for foreign keys and commonly queried columns
+- Use `change` method when the migration is reversible; use `up`/`down` when it is not
+
+```ruby
+class AddIndexToOrdersUserId < ActiveRecord::Migration[7.2]
+  def change
+    add_index :orders, :user_id
+  end
+end
+```
+
+## Testing with RSpec
+
+- Use `let` and `let!` for test setup
+- Use `described_class` instead of repeating the class name
+- Use `factory_bot` for test data, not fixtures
+- Use `shoulda-matchers` for model validation tests
+- Keep tests focused — one assertion concept per example
+
+```ruby
+RSpec.describe Order, type: :model do
+  describe "validations" do
+    it { is_expected.to validate_presence_of(:user) }
+    it { is_expected.to validate_numericality_of(:total).is_greater_than(0) }
+  end
+
+  describe ".recent" do
+    it "returns orders in descending creation order" do
+      old_order = create(:order, created_at: 1.day.ago)
+      new_order = create(:order, created_at: 1.hour.ago)
+
+      expect(described_class.recent).to eq([new_order, old_order])
+    end
+  end
+end
+```