@codyswann/lisa 1.48.0 → 1.49.0

package/plugins/lisa-rails/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/plugins/lisa-rails/skills/agent-design-best-practices/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: agent-design-best-practices
+description: Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
+---
+
+# Agent Design Best Practices
+
+## Overview
+
+This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.
+
+## Principles
+
+### 1. Define Capabilities, Not Lifecycle
+
+Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.
+
+```markdown
+<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
+# Security Planner Agent
+
+You are a security specialist in a plan-create Agent Team.
+Given a Research Brief from the team lead, identify security
+considerations for the planned changes.
+
+## Output Format
+
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+...
+```
+
+```markdown
+<!-- Correct: Defines domain expertise, team lead controls usage -->
+# Security Specialist Agent
+
+You are a security specialist who identifies vulnerabilities,
+evaluates threats, and recommends mitigations for code changes.
+
+## Analysis Process
+1. Read affected files
+2. STRIDE analysis
+3. Check input validation
+...
+```
+
+The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.
+
+### 2. One Agent Per Domain, Not Per Phase
+
+Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.
+
+| Wrong | Right |
+|-------|-------|
+| `security-planner` + `security-reviewer` | `security-specialist` |
+| `test-strategist` + `test-coverage-agent` | `test-specialist` |
+| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |
+
+The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."
+
+### 3. Design Focused Domains
+
+Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.
+
+```yaml
+# Too narrow (coupled to one workflow step)
+description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2
+
+# Too broad (no clear expertise)
+description: General-purpose agent that can do anything
+
+# Just right (focused domain, reusable across workflows)
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
+```
+
+### 4. Write Detailed Descriptions
+
+Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.
+
+```yaml
+# Bad: Vague, Claude can't decide when to use it
+description: Reviews code
+
+# Good: Specific domain, clear trigger conditions
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
+```
+
+### 5. Limit Tool Access
+
+Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.
+
+| Agent Type | Appropriate Tools | Rationale |
+|-----------|-------------------|-----------|
+| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
+| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
+| Planner | `Read, Grep, Glob` | Research only, no execution |
+
+Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.
+
+### 6. No Hardcoded Interaction Patterns
+
+Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.
+
+```markdown
+<!-- Wrong: Hardcodes communication protocol -->
+## Input
+You receive a **Research Brief** from the team lead containing...
+
+## Output Format
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+```
+
+```markdown
+<!-- Correct: Defines output structure without prescribing delivery mechanism -->
+## Output Format
+Structure your findings as:
+
+### Threat Model (STRIDE)
+| Threat | Applies? | Description | Mitigation |
+...
+```
+
+The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.
+
+### 7. Context Window Isolation
+
+Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:
+
+- Do not assume the agent has seen previous analysis from other agents
+- Include enough domain knowledge in the agent file for independent operation
+- The team lead bridges context between agents via spawn prompts and messages
+
+### 8. File Ownership in Teams
+
+When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.
+
+Design agent domains so their file ownership naturally separates:
+
+| Agent | Owns |
+|-------|------|
+| `implementer` | Source files (`src/`) |
+| `test-specialist` | Test files (`tests/`) |
+| `quality-specialist` | No files (read-only) |
+
+## Agent File Structure
+
+### Required Frontmatter
+
+```yaml
+---
+name: agent-name           # lowercase with hyphens
+description: When and why to use this agent. Be specific.
+tools: Read, Grep, Glob     # comma-separated, minimal set
+---
+```
+
+### Optional Frontmatter
+
+```yaml
+model: sonnet              # sonnet, opus, haiku, or inherit (default)
+permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
+maxTurns: 50               # limit agentic turns
+skills:                     # skills to preload
+  - skill-name
+memory: user                # persistent memory: user, project, or local
+```
+
+### Body Structure
+
+The markdown body becomes the agent's system prompt. Structure it as:
+
+1. **Role statement** -- one sentence describing what the agent is
+2. **Analysis/workflow process** -- numbered steps for the agent's approach
+3. **Output format** -- structure for findings (without prescribing delivery mechanism)
+4. **Rules/constraints** -- guardrails for the agent's behavior
+
+## Anti-Patterns
+
+### Don't Create Phase-Specific Agents
+
+```markdown
+<!-- Wrong: Two agents for the same domain, split by phase -->
+# Pre-Implementation Security Planner
+...
+# Post-Implementation Security Reviewer
+...
+
+<!-- Correct: One agent, team lead controls timing -->
+# Security Specialist
+...
+```
+
+### Don't Hardcode Workflow Dependencies
+
+```markdown
+<!-- Wrong: Agent assumes specific workflow context -->
+You are part of the plan-create Phase 2 team.
+Wait for the Research Brief from Phase 1.
+After your analysis, the Consistency Checker will validate your output.
+
+<!-- Correct: Agent is self-contained -->
+You are a security specialist who identifies vulnerabilities
+and recommends mitigations for code changes.
+```
+
+### Don't Over-Specify the Model
+
+Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.
+
+## Verification Checklist
+
+Before committing an agent file, verify:
+
+1. **Description is specific** -- Claude can determine when to delegate from the description alone
+2. **Tools are minimal** -- only the tools the agent actually needs
+3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
+4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
+5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
+6. **Role statement is clear** -- first line of body explains what the agent is
+7. **Output format is defined** -- structured output without prescribing delivery

package/plugins/lisa-rails/skills/git-commit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: git-commit
+description: This skill should be used when creating conventional commits for current changes. It groups related changes into logical commits, ensures all files are committed, and verifies the working directory is clean afterward.
+allowed-tools: ["Bash"]
+---
+
+# Git Commit Workflow
+
+Create conventional commits for current changes. Optional hint: $ARGUMENTS
+
+## Workflow
+
+### See what has changed
+
+!git status
+!git diff --stat
+
+### Apply these requirements
+
+1. **Branch Check**: If on `dev`, `staging`, or `main`, create a feature branch named after the changes
+2. **Commit Strategy**: Group related changes into logical conventional commits (feat, fix, chore, docs, etc.)
+3. **Commit ALL Files**: Every file must be assigned to a commit group - no file gets left out or unstaged
+4. **Commit Creation**: Stage and commit each group with clear messages
+5. **Verification**: Run `git status` to confirm working directory is clean - must show "nothing to commit"
+
+### Use conventional commit format
+
+- `feat:` for new features
+- `fix:` for bug fixes
+- `docs:` for documentation
+- `chore:` for maintenance
+- `style:` for formatting
+- `refactor:` for code restructuring
+- `test:` for test additions
+
+### Never
+
+- use `--no-verify` flag
+- attempt to bypass tests or quality checks
+- skip tests or quality checks
+- stash changes - ALL changes must be committed
+- skip or exclude any files from the commit - even if they're unrelated
+- leave uncommitted changes in the working directory
+- ask the user which files to commit - commit everything
+
+## Execute
+
+Execute the workflow now.

package/plugins/lisa-rails/skills/git-commit-and-submit-pr/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: git-commit-and-submit-pr
+description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. It combines the git:commit and git:submit-pr skills into a single workflow.
+allowed-tools: ["Bash"]
+---
+
+1. Run /git-commit $ARGUMENTS
+2. Run /git-submit-pr $ARGUMENTS

package/plugins/lisa-rails/skills/git-commit-submit-pr-and-verify/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: git-commit-submit-pr-and-verify
+description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. And then verifying the pull request was approved.
+allowed-tools: ["Bash"]
+---
+
+Run the /git-commit-and-submit-pr with $ARGUMENTS and set the PR to auto-merge. Fix any pre-commit or pre-push issues and then follow the pr, make sure all checks pass and comments are resolved or addressed. Fix anything that is broken and repeat.

package/plugins/lisa-rails/skills/git-commit-submit-pr-deploy-and-verify/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: git-commit-submit-pr-deploy-and-verify
+description: This skill should be used when creating conventional commits for current changes and then submitting the current branch as a pull request for code review. And then verifying the pull request was approved. As well as making sure the resutling deploy succeeds.
+allowed-tools: ["Bash"]
+---
+
+Run the /git-commit-submit-pr-and-verify with $ARGUMENTS. Once the merge is complete, follow the resulting deploy and fix anything that breaks with the deploy and then follow this process again with a new PR until the deploy succeeds.

package/plugins/lisa-rails/skills/git-prune/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: git-prune
+description: This skill should be used when pruning local branches that have been deleted on the remote. It fetches remote changes, identifies stale local branches, and safely deletes them.
+allowed-tools: ["Bash"]
+---
+
+# Git Prune Local Branches
+
+Remove local branches whose upstream tracking branches have been deleted on remote.
+
+## Workflow
+
+### Fetch and prune remote-tracking references
+
+!git fetch --prune
+
+### Find and delete stale local branches
+
+!git branch -vv | grep ': gone]' | awk '{print $1}'
+
+### Apply these requirements
+
+1. **Preview**: Show which branches will be deleted before deleting
+2. **Safe Delete**: Use `-d` (safe delete) which refuses to delete unmerged branches
+3. **Report**: Show summary of deleted branches
+
+### Never
+
+- Force delete (`-D`) without user confirmation
+- Delete the current branch
+- Delete protected branches (dev, staging, main)
+
+## Execute
+
+Execute the workflow now.

package/plugins/lisa-rails/skills/git-submit-pr/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: git-submit-pr
+description: This skill should be used when pushing changes and creating or updating a pull request. It verifies the branch state, pushes to remote, creates or updates a PR with a comprehensive description, and enables auto-merge.
+allowed-tools: ["Bash", "mcp__github__create_pull_request", "mcp__github__get_pull_request", "mcp__github__update_pull_request"]
+---
+
+# Submit Pull Request Workflow
+
+Push current branch and create or update a pull request. Optional hint: $ARGUMENTS
+
+## Workflow
+
+### Check current state
+
+!git status
+!git log --oneline -10
+
+### Apply these requirements
+
+1. **Branch Check**: Verify not on `dev`, `staging`, or `main` (cannot create PR from protected branches)
+2. **Commit Check**: Ensure all changes are committed before pushing
+3. **Push**: Push current branch to remote with `-u` flag and the following environment variable - GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"
+4. **PR Management**:
+   - Check for existing PR on this branch
+   - If exists: Update description with latest changes
+   - If not: Create PR with comprehensive description (not a draft)
+5. **Auto-merge**: Enable auto-merge on the PR using `gh pr merge --auto --merge`
+
+### PR Description Format
+
+Include in the PR description:
+
+- **Summary**: Brief overview of changes (1-3 bullet points)
+- **Test plan**: How to verify the changes work correctly
+
+### Never
+
+- use `--force` push without explicit user request
+- create PR from protected branches (dev, staging, main)
+- skip pushing before PR creation
+
+## Execute
+
+Execute the workflow now.

package/plugins/lisa-rails/skills/jira-add-journey/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: jira-add-journey
+description: "Add a Validation Journey section to an existing JIRA ticket by reading the ticket description, understanding the feature, and generating the journey steps and assertions."
+---
+
+# Add Validation Journey to Existing JIRA Ticket
+
+Read an existing JIRA ticket, understand the feature or fix it describes, analyze the codebase to determine the verification approach, and append a Validation Journey section to the ticket description.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`)
+
+## Workflow
+
+### Step 1: Read the Ticket
+
+Use the Atlassian MCP or jira-cli to read the full ticket details:
+
+```bash
+jira issue view <TICKET_ID>
+```
+
+Extract: title, description, acceptance criteria, components, labels, linked tickets.
+
+### Step 2: Check for Existing Journey
+
+Run the parser to see if a Validation Journey already exists:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID> 2>&1
+```
+
+If the parser succeeds and returns steps, the ticket already has a journey. Report this to the user and stop.
+
+### Step 3: Analyze the Feature
+
+Based on the ticket description and acceptance criteria, determine the appropriate verification approach. Stack-specific overrides provide the analysis logic.
+
+### Step 4: Draft the Validation Journey
+
+Compose the journey following the Validation Journey format with: Prerequisites, Steps (with evidence markers), and Assertions.
+
+### Step 5: Present to User for Approval
+
+Display the drafted Validation Journey to the user and ask for confirmation before appending it to the ticket.
+
+### Step 6: Append to Ticket Description
+
+After user approval, use the JIRA REST API to append the Validation Journey to the existing ticket description.
+
+### Step 7: Verify
+
+Run the parser again to confirm the journey was added correctly:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```

package/plugins/lisa-rails/skills/jira-create/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: jira-create
+description: This skill should be used when creating JIRA epics, stories, and tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation.
+allowed-tools: ["Read", "Glob", "LS", "mcp__atlassian__createJiraIssue", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all mandatory quality gates.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope
+2. **Determine Structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+3. **Create Issues** with hierarchy:
+   ```
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Feature Flags**: All features behind flags with lifecycle plan
+**Cleanup**: Remove temporary code, scripts, dev configs
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: SE (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+Execute the analysis and create the complete JIRA structure with proper parent-child relationships.