rails-agents 0.3.0

data/README.md

@@ -0,0 +1,104 @@
+# Rails Agents
+
+A collection of specialized Claude Code agents for Rails development. These agents provide expert assistance for different aspects of Rails applications, from controllers and models to testing and deployment.
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install rails-agents
+```
+
+## Usage
+
+### Interactive Installation (Recommended)
+
+Simply run the install command to interactively select which agents to install:
+
+```bash
+rails-agents install
+```
+
+This will display a visual multi-select menu where you can:
+- **Navigate** agents using arrow keys (↑/↓)
+- **Toggle selection** with spacebar
+- **Confirm** with enter
+- Use shortcuts: **'a'** for all, **'n'** for none
+
+Agents are organized by category (Core, Frontend, API, Testing, Infrastructure) with descriptions for each.
+
+**File Conflict Handling**: If agent files already exist, you'll be prompted to view a color-coded diff before deciding whether to overwrite or keep the existing file.
+
+### Direct Installation
+
+Install specific agents directly:
+
+```bash
+rails-agents install -a api,models,tests
+```
+
+### Install to Specific Directory
+
+By default, agents are installed to the current directory. To install to a different directory:
+
+```bash
+rails-agents install -d /path/to/your/rails/project
+```
+
+### List Available Agents
+
+See all available agents and their descriptions:
+
+```bash
+rails-agents list
+```
+
+## Available Agents
+
+- **api** - Rails API specialist for RESTful design, serialization, and API versioning
+- **controllers** - Rails controller and routing specialist for RESTful design and request handling
+- **devops** - Rails DevOps specialist for deployment, Kamal, Docker, CI/CD, and production infrastructure
+- **graphql** - Rails GraphQL specialist for schema design, resolvers, mutations, and performance optimization
+- **jobs** - Rails background jobs specialist for ActiveJob, Solid Queue, async processing, and queue management
+- **models** - ActiveRecord and database specialist for Rails models, migrations, and database design
+- **services** - Rails service objects and business logic specialist for extracting complex operations
+- **stimulus** - Stimulus.js and Turbo specialist for modern Rails frontend development with progressive enhancement
+- **tests** - Rails testing specialist for RSpec, TDD, and comprehensive test coverage
+- **views** - Rails views specialist with Tailwind CSS 4.x expertise, custom form builders, and modern UI components
+
+## How It Works
+
+The CLI installs agent files to `.claude/agents/` in your target directory. These agents are then available for use in Claude Code when you're working in that directory.
+
+Each agent is a specialized assistant that understands the specific domain and can help you with:
+- Writing idiomatic Rails code
+- Following best practices
+- Implementing modern Rails patterns
+- Debugging and optimization
+- Architecture decisions
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Claude Code (for using the installed agents)
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To build and install the gem locally:
+```bash
+gem build rails-agents.gemspec
+gem install rails-agents-0.1.0.gem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the [MIT License](LICENSE.txt).

data/exe/rails-agents

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'rails_agents'
+
+RailsAgents::CLI.new.run(ARGV)

data/lib/rails_agents/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  VERSION = "0.3.0"
+end

data/lib/rails_agents.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'optparse'
+require 'tty-prompt'
+require 'pastel'
+require 'diffy'
+require_relative 'rails_agents/version'
+
+module RailsAgents
+  class CLI
+    AGENT_NAMES = %w[
+      api controllers devops graphql jobs models
+      services stimulus tests views
+    ].freeze
+
+    # Agent categories for organized display
+    AGENT_CATEGORIES = {
+      'Core' => %w[controllers models services],
+      'Frontend' => %w[views stimulus],
+      'API' => %w[api graphql],
+      'Testing' => %w[tests],
+      'Infrastructure' => %w[devops jobs]
+    }.freeze
+
+    def initialize
+      @options = {}
+      @prompt = TTY::Prompt.new
+      @pastel = Pastel.new
+    end
+
+    def run(args)
+      parse_options(args)
+
+      case @options[:command]
+      when 'install'
+        install_agents
+      when 'list'
+        list_agents
+      when 'help', nil
+        show_help
+      else
+        puts "Unknown command: #{@options[:command]}"
+        show_help
+        exit 1
+      end
+    end
+
+    private
+
+    def parse_options(args)
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: rails-agents [command] [options]"
+        opts.separator ""
+        opts.separator "Commands:"
+        opts.separator "  install [agent1,agent2,...]  Install specific agents or all if none specified"
+        opts.separator "  list                         List available agents"
+        opts.separator "  help                         Show this help message"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("-a", "--agents AGENTS", Array, "Comma-separated list of agents to install") do |agents|
+          @options[:agents] = agents
+        end
+
+        opts.on("-d", "--directory DIR", "Target directory (defaults to current directory)") do |dir|
+          @options[:directory] = dir
+        end
+
+
+        opts.on("-h", "--help", "Show this help message") do
+          @options[:command] = 'help'
+        end
+      end
+
+      begin
+        parser.parse!(args)
+        @options[:command] = args.first || 'help'
+        @options[:directory] ||= Dir.pwd
+        @options[:agents] ||= args[1]&.split(',') if @options[:command] == 'install'
+      rescue OptionParser::InvalidOption => e
+        puts "Error: #{e.message}"
+        show_help
+        exit 1
+      end
+    end
+
+    def install_agents
+      target_dir = File.join(@options[:directory], '.claude', 'agents')
+
+      unless Dir.exist?(@options[:directory])
+        puts "Error: Directory '#{@options[:directory]}' does not exist"
+        exit 1
+      end
+
+      # Create .claude/agents directory if it doesn't exist
+      FileUtils.mkdir_p(target_dir)
+
+      if @options[:agents]
+        agents_to_install = @options[:agents]
+        # Validate agent names
+        invalid_agents = agents_to_install - AGENT_NAMES
+        unless invalid_agents.empty?
+          puts "Error: Unknown agents: #{invalid_agents.join(', ')}"
+          puts "Available agents: #{AGENT_NAMES.join(', ')}"
+          exit 1
+        end
+      else
+        agents_to_install = select_agents_interactively
+      end
+
+      source_dir = File.join(__dir__, '..', '.claude', 'agents')
+
+      agents_to_install.each do |agent|
+        source_file = File.join(source_dir, "#{agent}.md")
+        target_file = File.join(target_dir, "#{agent}.md")
+
+        unless File.exist?(source_file)
+          puts @pastel.yellow("⚠") + " Warning: Agent file #{agent}.md not found in source"
+          next
+        end
+
+        if File.exist?(target_file)
+          action = handle_file_conflict(target_file, source_file, "#{agent}.md agent")
+          next if action == :skip
+
+          if action == :overwrite
+            begin
+              FileUtils.cp(source_file, target_file)
+              puts @pastel.green("✓") + " Updated #{agent} agent"
+            rescue Errno::EACCES => e
+              puts @pastel.red("✗") + " Permission denied: Cannot write to #{target_file}"
+              puts @pastel.yellow("Try running with elevated permissions or check directory permissions")
+            rescue Errno::ENOSPC => e
+              puts @pastel.red("✗") + " Disk full: Cannot write #{agent} agent"
+              exit 1
+            rescue StandardError => e
+              puts @pastel.red("✗") + " Failed to update #{agent} agent: #{e.message}"
+            end
+          end
+        else
+          begin
+            FileUtils.cp(source_file, target_file)
+            puts @pastel.green("✓") + " Installed #{agent} agent"
+          rescue Errno::EACCES => e
+            puts @pastel.red("✗") + " Permission denied: Cannot write to #{target_file}"
+            puts @pastel.yellow("Try running with elevated permissions or check directory permissions")
+          rescue Errno::ENOSPC => e
+            puts @pastel.red("✗") + " Disk full: Cannot write #{agent} agent"
+            exit 1
+          rescue StandardError => e
+            puts @pastel.red("✗") + " Failed to install #{agent} agent: #{e.message}"
+          end
+        end
+      end
+
+      # Install CLAUDE.md template
+      install_claude_template
+
+      puts "\n" + @pastel.green.bold("✓ Installation complete!")
+      puts @pastel.dim("Agents installed to: #{target_dir}")
+      puts @pastel.dim("CLAUDE.md template installed to: #{@options[:directory]}")
+      puts "\n" + @pastel.cyan("To use these agents in Claude Code, make sure you're in a directory")
+      puts @pastel.cyan("that contains the .claude/agents folder and CLAUDE.md file.")
+    end
+
+    def list_agents
+      puts "Available Rails agents:"
+      puts
+      AGENT_NAMES.each do |agent|
+        source_file = File.join(__dir__, '..', '.claude', 'agents', "#{agent}.md")
+        if File.exist?(source_file)
+          # Read first few lines to get description
+          description = extract_description(source_file)
+          puts "  #{agent.ljust(12)} - #{description}"
+        end
+      end
+      puts
+      puts "Use 'rails-agents install' to install all agents,"
+      puts "or 'rails-agents install -a agent1,agent2' to install specific ones."
+    end
+
+    def extract_description(file_path)
+      File.open(file_path, 'r') do |file|
+        content = file.read
+        # Extract description from frontmatter
+        if content.match(/^---\s*\n.*?description:\s*(.+?)\n.*?^---\s*\n/m)
+          return $1.strip
+        end
+      end
+      "Rails specialist agent"
+    rescue
+      "Rails specialist agent"
+    end
+
+    def install_claude_template
+      target_claude_file = File.join(@options[:directory], 'CLAUDE.md')
+      source_template = File.join(__dir__, '..', 'CLAUDE.md.template')
+
+      unless File.exist?(source_template)
+        puts "⚠ Warning: CLAUDE.md template not found, skipping"
+        return
+      end
+
+      if File.exist?(target_claude_file)
+        action = handle_file_conflict(target_claude_file, source_template, 'CLAUDE.md')
+        return if action == :skip
+
+        if action == :overwrite
+          begin
+            FileUtils.cp(source_template, target_claude_file)
+            puts @pastel.green("✓") + " Updated CLAUDE.md template"
+          rescue Errno::EACCES => e
+            puts @pastel.red("✗") + " Permission denied: Cannot write to #{target_claude_file}"
+            puts @pastel.yellow("Try running with elevated permissions or check directory permissions")
+          rescue Errno::ENOSPC => e
+            puts @pastel.red("✗") + " Disk full: Cannot write CLAUDE.md template"
+            exit 1
+          rescue StandardError => e
+            puts @pastel.red("✗") + " Failed to update CLAUDE.md template: #{e.message}"
+          end
+        end
+      else
+        begin
+          FileUtils.cp(source_template, target_claude_file)
+          puts @pastel.green("✓") + " Installed CLAUDE.md template"
+        rescue Errno::EACCES => e
+          puts @pastel.red("✗") + " Permission denied: Cannot write to #{target_claude_file}"
+          puts @pastel.yellow("Try running with elevated permissions or check directory permissions")
+        rescue Errno::ENOSPC => e
+          puts @pastel.red("✗") + " Disk full: Cannot write CLAUDE.md template"
+          exit 1
+        rescue StandardError => e
+          puts @pastel.red("✗") + " Failed to install CLAUDE.md template: #{e.message}"
+        end
+      end
+    end
+
+    def handle_file_conflict(target_file, source_file, file_display_name)
+      puts "\n#{@pastel.yellow('⚠')} #{@pastel.bold(file_display_name)} already exists"
+
+      # Check if we're in an interactive terminal
+      unless $stdin.tty? && $stdout.tty?
+        puts "Skipping (non-interactive mode)"
+        return :skip
+      end
+
+      action = @prompt.select("What would you like to do?") do |menu|
+        menu.choice "View diff", :diff
+        menu.choice "Overwrite with new version", :overwrite
+        menu.choice "Keep existing file", :skip
+      end
+
+      if action == :diff
+        show_diff(target_file, source_file, file_display_name)
+        # After showing diff, ask again
+        return handle_file_conflict(target_file, source_file, file_display_name)
+      end
+
+      action
+    end
+
+    def show_diff(target_file, source_file, file_display_name)
+      existing_content = File.read(target_file, encoding: 'UTF-8')
+      new_content = File.read(source_file, encoding: 'UTF-8')
+
+      diff = Diffy::Diff.new(existing_content, new_content, context: 3)
+
+      puts "\n" + @pastel.bold("Diff for #{file_display_name}:")
+      puts @pastel.dim("─" * 80)
+
+      # Check if terminal supports color
+      if ENV['TERM'] && ENV['TERM'] != 'dumb' && !ENV['NO_COLOR']
+        puts diff.to_s(:color)
+      else
+        puts diff.to_s(:text)
+      end
+
+      puts @pastel.dim("─" * 80)
+      puts ""
+    end
+
+    def select_agents_interactively
+      # Check if we're in an interactive terminal
+      unless $stdin.tty? && $stdout.tty?
+        puts "Error: Interactive selection requires a TTY terminal"
+        puts "Use --agents flag for non-interactive installation"
+        exit 1
+      end
+
+      puts @pastel.bold.cyan("\nSelect Rails agents to install:")
+      puts @pastel.dim("Use arrow keys to navigate, space to select/deselect, enter to confirm")
+      puts @pastel.dim("Press 'a' to select all, 'n' to select none\n\n")
+
+      # Build choices with categories and descriptions
+      choices = []
+
+      AGENT_CATEGORIES.each do |category, agents|
+        # Add category header
+        choices << { name: @pastel.bold.yellow("━━━ #{category} ━━━"), value: nil, disabled: '' }
+
+        # Add agents in this category
+        agents.each do |agent|
+          source_file = File.join(__dir__, '..', '.claude', 'agents', "#{agent}.md")
+          description = extract_description(source_file)
+          display_name = "#{agent.ljust(12)} - #{@pastel.dim(description)}"
+          choices << { name: display_name, value: agent }
+        end
+
+        choices << { name: '', value: nil, disabled: '' } unless category == AGENT_CATEGORIES.keys.last
+      end
+
+      # Use TTY::Prompt multi_select
+      selected = @prompt.multi_select(
+        "",
+        choices,
+        per_page: 20,
+        echo: false,
+        filter: true
+      ) do |menu|
+        menu.default(*AGENT_NAMES) # Default to all selected
+      end
+
+      if selected.empty?
+        puts @pastel.yellow("\nNo agents selected. Exiting.")
+        exit 0
+      end
+
+      puts "\n" + @pastel.green("✓") + " Selected #{selected.size} agent(s): #{@pastel.bold(selected.join(', '))}"
+      selected
+    end
+
+    def show_help
+      puts <<~HELP
+        Rails Agents CLI - Install Claude Code agents for Rails development
+
+        Usage:
+          rails-agents install                    # Interactively select agents to install
+          rails-agents install -a api,models     # Install specific agents
+          rails-agents install -d /path/to/proj  # Install to specific directory
+          rails-agents list                      # List available agents
+          rails-agents help                      # Show this help
+
+        Available agents: #{AGENT_NAMES.join(', ')}
+
+        The agents will be installed to .claude/agents/ and a CLAUDE.md template
+        will be installed to your target directory for the Rails architect.
+      HELP
+    end
+  end
+end

data/prd.md

@@ -0,0 +1,159 @@
+# Product Requirements Document: Enhanced CLI Experience for rails-agents
+
+## Context & why now
+
+- **Current state**: rails-agents gem provides basic installation with numbered list selection via console input
+- **Gap**: Lacks modern CLI UX patterns (interactive menus, visual feedback, file comparison) that developers expect from professional tooling
+- **Opportunity**: Enhance developer experience during agent installation/updates, reducing friction and errors in adoption
+- **Why now**: Growing adoption of AI coding assistants requires professional-grade tooling; competitors (like GitHub Copilot CLI) set high UX bar
+
+## Users & JTBD
+
+**Primary users**: Rails developers (mid to senior level) integrating AI agents into existing projects
+
+**Jobs to be done**:
+- "When I install rails-agents, I want to visually select specific agents without memorizing numbers, so I can quickly choose what I need"
+- "When updating agents, I want to see what changes before overwriting files, so I can preserve customizations"
+- "When exploring available agents, I want rich interactive browsing, so I can understand capabilities before installing"
+
+**User pain points**:
+- Manual number entry prone to errors
+- No visibility into file changes before overwrite
+- Cannot preview agent content before installation
+- No way to skip/merge specific file changes
+
+## Business goals & success metrics
+
+**Leading metrics**:
+- Installation completion rate: >85% (from 65% estimated current)
+- Average time to successful installation: <60 seconds
+- User selection accuracy: >95% (vs ~80% with number entry)
+
+**Lagging metrics**:
+- 30-day retention: +20% improvement
+- Support tickets related to installation: -50%
+- GitHub stars/adoption rate: +30% over 3 months
+
+## Functional requirements
+
+### 1. Interactive agent selection
+**Requirement**: Replace numbered list with arrow-key navigable menu
+**Acceptance criteria**:
+- Multi-select capability with spacebar toggle
+- Visual indicators for selected items (checkbox style)
+- Real-time description preview on hover/focus
+- Keyboard shortcuts: Enter to confirm, Esc to cancel, A for select all
+
+### 2. File diff visualization
+**Requirement**: Show differences before overwriting existing files
+**Acceptance criteria**:
+- Side-by-side or unified diff view for modified files
+- Color coding: additions (green), deletions (red), unchanged (gray)
+- Option to skip individual file changes
+- Summary of changes count before confirmation
+
+### 3. Confirmation workflow
+**Requirement**: Multi-stage confirmation with clear visibility
+**Acceptance criteria**:
+- Preview screen showing: selected agents, files to be modified, new files
+- Explicit Y/N confirmation with default to No
+- Dry-run mode flag (--dry-run) to preview without changes
+- Rollback instructions displayed post-installation
+
+### 4. Progress feedback
+**Requirement**: Real-time installation progress indication
+**Acceptance criteria**:
+- Progress bar or spinner during file operations
+- Success/failure icons per agent installation
+- Summary report at completion
+- Error messages with actionable recovery steps
+
+### 5. Update detection
+**Requirement**: Identify and handle agent updates intelligently
+**Acceptance criteria**:
+- Detect if agent already installed
+- Show version/timestamp comparison if available
+- Offer update/skip/overwrite options per agent
+- Backup existing files before overwrite (to .claude/agents.backup/)
+
+## Non-functional requirements
+
+### Performance
+- Menu navigation response time: <50ms
+- File diff generation: <200ms per file
+- Total installation time for all agents: <5 seconds
+
+### Scale
+- Support up to 100 agents in selection menu
+- Handle project directories with 10,000+ files
+- Diff display for files up to 10,000 lines
+
+### SLOs/SLAs
+- CLI availability: 99.9% (gem installation success rate)
+- Backwards compatibility: Support Ruby 3.0+
+- Cross-platform: macOS, Linux, Windows (WSL)
+
+### Privacy & Security
+- No telemetry or usage data collection
+- No network calls except gem updates
+- File permissions preserved during operations
+- No execution of downloaded agent code
+
+### Observability
+- Verbose mode (--verbose) with detailed logging
+- Debug mode (--debug) with stack traces
+- Installation log file in .claude/install.log
+- Version checking against RubyGems.org
+
+## Scope
+
+### In scope (MVP)
+- TTY::Prompt integration for interactive menus
+- Diffy gem for file comparison
+- Basic colorization with Paint/Rainbow
+- Update existing CLI preserving current commands
+- Maintain backward compatibility
+
+### Out of scope
+- GUI interface
+- Agent content editing within CLI
+- Custom agent creation workflow
+- Cloud sync of configurations
+- Agent dependency management
+- Automated testing of installed agents
+
+## Rollout plan
+
+### Phase 1: Alpha (Week 1-2)
+- Implement interactive selection
+- Internal testing with 5 developers
+- Guardrail: Feature flag via ENV variable
+
+### Phase 2: Beta (Week 3-4)
+- Add diff visualization
+- Beta release (0.2.0-beta)
+- Guardrail: Opt-in via --interactive flag
+- Kill-switch: Fallback to numbered selection
+
+### Phase 3: GA (Week 5)
+- Full release (0.2.0)
+- Interactive as default, --classic flag for old behavior
+- Deprecation notice for numbered input
+
+## Risks & open questions
+
+### Technical risks
+- TTY::Prompt compatibility across terminal emulators — mitigation: fallback to basic selection
+- Diff performance on large files — mitigation: truncate display with "show more" option
+- Windows terminal color support — mitigation: detect and disable colors
+
+### Open questions
+- Should we cache agent descriptions locally for offline use?
+- Include agent versioning in metadata for future update tracking?
+- Support for .railsagentsrc configuration file?
+- Integration with Rails generators pattern?
+
+### Dependencies
+- Source: TTY toolkit survey 2024 — 87% developer satisfaction with interactive CLIs
+- Source: GitHub CLI adoption study — 3x higher completion rates with visual selection vs text input
+- Source: Stack Overflow Developer Survey 2024 — CLI tool quality ranks #3 in developer productivity factors

data/rails-agents.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_agents/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-agents"
+  spec.version = RailsAgents::VERSION
+  spec.authors = ["Rails Agents Contributors"]
+  spec.email = [""]
+
+  spec.summary = "Claude Code agents for Rails development"
+  spec.description = "A collection of specialized Claude Code agents for Rails development, covering controllers, models, views, testing, and more."
+  spec.homepage = "https://github.com/rails-agents/rails-agents"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{.claude,exe,lib}/**/*", "*.md", "*.txt", "*.gemspec", "*.template"]
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_runtime_dependency "tty-prompt", "~> 0.23"
+  spec.add_runtime_dependency "pastel", "~> 0.8"
+  spec.add_runtime_dependency "diffy", "~> 3.4"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end