chiron 0.1.0

data/lib/chiron/cli.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'tty-prompt'
+require 'colorize'
+require 'fileutils'
+require 'erb'
+require 'date'
+
+module Chiron
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'init', 'Initialize Claude workflow in current Rails project'
+    option :project_name, type: :string, desc: 'Project name for CLAUDE.md'
+    option :with_oauth, type: :boolean, default: false, desc: 'Include OAuth workflow examples'
+    option :with_viewcomponents, type: :boolean, default: false, desc: 'Include ViewComponent rules'
+    option :skip_journal, type: :boolean, default: false, desc: 'Skip development journal setup'
+    def init
+      say '🤖 Initializing Claude Rails Setup...'.colorize(:blue)
+
+      @prompt = TTY::Prompt.new
+      @project_name = options[:project_name] || prompt_for_project_name
+
+      check_rails_project
+      create_directories
+      copy_templates
+      update_gitignore
+
+      say "\n✨ Claude workflow initialized successfully!".colorize(:green)
+      say "\nNext steps:".colorize(:yellow)
+      say '  1. Review and customize CLAUDE.md for your project'
+      say '  2. Check .claude/commands/ for available workflows'
+      say "  3. Run 'claude' to start using Claude with your new setup"
+    end
+
+    desc 'migrate-cursor', 'Migrate from .cursor to .claude structure'
+    def migrate_cursor
+      say '🔄 Migrating from .cursor to .claude...'.colorize(:blue)
+
+      unless Dir.exist?('.cursor/rules')
+        error 'No .cursor/rules directory found!'
+        exit 1
+      end
+
+      create_directories
+      migrate_rules
+
+      if @prompt.yes?('Remove .cursor directory after migration?')
+        FileUtils.rm_rf('.cursor')
+        say '✅ .cursor directory removed'.colorize(:green)
+      end
+
+      say "\n✨ Migration completed!".colorize(:green)
+    end
+
+    desc 'add-workflow WORKFLOW', 'Add a specific workflow to your setup'
+    def add_workflow(workflow_name)
+      available_workflows = Dir.glob(File.join(templates_path, 'commands/**/*.md'))
+                               .map { |f| File.basename(f, '.md') }
+
+      unless available_workflows.include?(workflow_name)
+        error "Unknown workflow: #{workflow_name}"
+        say "Available workflows: #{available_workflows.join(', ')}"
+        exit 1
+      end
+
+      copy_workflow(workflow_name)
+      say "✅ Added #{workflow_name} workflow".colorize(:green)
+    end
+
+    desc 'update', 'Update Claude workflows to latest version'
+    def update
+      say '🔄 Updating Claude workflows...'.colorize(:blue)
+
+      # Backup current commands
+      if Dir.exist?('.claude/commands')
+        backup_dir = ".claude/commands.backup.#{Time.now.strftime('%Y%m%d%H%M%S')}"
+        FileUtils.cp_r('.claude/commands', backup_dir)
+        say "📦 Backed up current commands to #{backup_dir}".colorize(:yellow)
+      end
+
+      copy_templates(update: true)
+      say "\n✨ Workflows updated!".colorize(:green)
+    end
+
+    desc 'doctor', 'Check Claude setup health'
+    def doctor
+      say '🏥 Running Claude setup diagnostics...'.colorize(:blue)
+
+      checks = {
+        'Rails project' => Dir.exist?('app') && File.exist?('Gemfile'),
+        'CLAUDE.md exists' => File.exist?('CLAUDE.md'),
+        '.claude directory' => Dir.exist?('.claude'),
+        '.claude/commands' => Dir.exist?('.claude/commands'),
+        'Development journal' => File.exist?('docs/development_journal.md'),
+        'Tasks directory' => Dir.exist?('tasks'),
+        '.gitignore entry' => begin
+          File.read('.gitignore').include?('.claude/')
+        rescue StandardError
+          false
+        end
+      }
+
+      checks.each do |check, result|
+        status = result ? '✅'.colorize(:green) : '❌'.colorize(:red)
+        say "#{status} #{check}"
+      end
+
+      if checks.values.all?
+        say "\n✨ All checks passed!".colorize(:green)
+      else
+        say "\n⚠️  Some checks failed. Run 'claude-rails init' to fix.".colorize(:yellow)
+      end
+    end
+
+    desc 'version', 'Show version'
+    def version
+      say Chiron::VERSION
+    end
+
+    private
+
+    def prompt_for_project_name
+      @prompt.ask("What's your project name?") do |q|
+        q.required true
+        q.default File.basename(Dir.pwd)
+      end
+    end
+
+    def check_rails_project
+      return if File.exist?('Gemfile') && File.read('Gemfile').include?('rails')
+
+      error "This doesn't appear to be a Rails project!"
+      exit 1
+    end
+
+    def create_directories
+      dirs = [
+        '.claude/commands/workflows',
+        '.claude/commands/conventions',
+        '.claude/commands/context',
+        '.claude/commands/journal',
+        '.claude/commands/quality',
+        'tasks',
+        'docs'
+      ]
+
+      dirs.each do |dir|
+        FileUtils.mkdir_p(dir)
+        say "📁 Created #{dir}".colorize(:light_blue) unless Dir.exist?(dir)
+      end
+    end
+
+    def copy_templates(update: false)
+      # Copy CLAUDE.md template
+      unless update
+        template_path = File.join(templates_path, 'CLAUDE.md.erb')
+        if File.exist?(template_path)
+          content = ERB.new(File.read(template_path)).result(binding)
+          File.write('CLAUDE.md', content)
+          say '📄 Created CLAUDE.md'.colorize(:light_blue)
+        end
+      end
+
+      # Copy command templates
+      copy_commands
+
+      # Copy settings.json
+      settings_path = File.join(templates_path, 'claude/settings.json')
+      if File.exist?(settings_path) && !File.exist?('.claude/settings.json')
+        FileUtils.cp(settings_path, '.claude/settings.json')
+        say '⚙️  Created .claude/settings.json'.colorize(:light_blue)
+      end
+
+      # Initialize development journal
+      return if options[:skip_journal] || File.exist?('docs/development_journal.md')
+
+      create_development_journal
+    end
+
+    def copy_commands
+      commands_dir = File.join(templates_path, 'commands')
+      return unless Dir.exist?(commands_dir)
+
+      Dir.glob(File.join(commands_dir, '**/*.md')).each do |file|
+        relative_path = file.sub("#{commands_dir}/", '')
+        target_path = File.join('.claude/commands', relative_path)
+
+        FileUtils.mkdir_p(File.dirname(target_path))
+        FileUtils.cp(file, target_path)
+        say "📋 Copied #{relative_path}".colorize(:light_blue)
+      end
+    end
+
+    def create_development_journal
+      journal_template = File.join(templates_path, 'development_journal.md.erb')
+      return unless File.exist?(journal_template)
+
+      content = ERB.new(File.read(journal_template)).result(binding)
+      File.write('docs/development_journal.md', content)
+      say '📓 Created development journal'.colorize(:light_blue)
+    end
+
+    def update_gitignore
+      gitignore_path = '.gitignore'
+      return unless File.exist?(gitignore_path)
+
+      gitignore_content = File.read(gitignore_path)
+
+      return if gitignore_content.include?('.claude/')
+
+      File.open(gitignore_path, 'a') do |f|
+        f.puts "\n# Claude Code settings (but allow commands directory)"
+        f.puts '.claude/*'
+        f.puts '!.claude/commands/'
+      end
+      say '📝 Updated .gitignore'.colorize(:light_blue)
+    end
+
+    def migrate_rules
+      Dir.glob('.cursor/rules/*.mdc').each do |rule_file|
+        filename = File.basename(rule_file, '.mdc')
+
+        # Map cursor rules to claude command structure
+        target_dir = case filename
+                     when 'create-prd', 'generate-tasks', 'process-task-list'
+                       '.claude/commands/workflows'
+                     when 'rails', 'view_component'
+                       '.claude/commands/conventions'
+                     when 'test-driven'
+                       '.claude/commands/quality'
+                     else
+                       '.claude/commands/workflows'
+                     end
+
+        target_path = File.join(target_dir, "#{filename}.md")
+
+        # Copy and transform the content
+        content = File.read(rule_file)
+        # Remove cursor-specific frontmatter
+        content = content.sub(/---.*?---/m, '').strip
+
+        File.write(target_path, content)
+        say "📋 Migrated #{filename}".colorize(:light_blue)
+      end
+    end
+
+    def templates_path
+      Chiron.templates_path
+    end
+
+    def error(message)
+      say "❌ #{message}".colorize(:red)
+    end
+  end
+end

data/lib/chiron/templates/CLAUDE.md.erb

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+<%= @project_name %> is a Rails <%= Rails.version rescue "8.0.2" %> application. [Add your project description here]
+
+## Development Commands
+
+**Important**: Always use binstubs instead of `bundle exec` for better performance and consistency.
+
+```bash
+# Setup
+bundle install
+bin/rails db:create db:migrate db:seed
+
+# Development server
+bin/rails server
+# or with Procfile for concurrent processes
+bin/dev
+
+# Testing
+bin/rspec                            # Run all tests
+bin/rspec spec/models/               # Run specific test directory
+bin/rspec spec/models/user_spec.rb   # Run single test file
+
+# Code quality
+bin/rubocop                          # Linting
+bin/rubocop --autocorrect            # Auto-fix correctable violations
+bin/brakeman                         # Security scanning
+```
+
+## Architecture Overview
+
+### Key Models & Relationships
+[Document your main models and their relationships]
+
+### Core Services
+[List your service objects and their purposes]
+
+### Controllers Structure
+[Describe your controller organization]
+
+## Technical Stack
+
+- **Framework**: Rails <%= Rails.version rescue "8.0.2" %> with Hotwire (Turbo + Stimulus)
+- **Database**: PostgreSQL with Active Record
+- **Frontend**: TailwindCSS, Stimulus controllers
+<% if options[:with_viewcomponents] %>- **ViewComponent**: Component-based architecture for reusable UI elements<% end %>
+- **Testing**: RSpec with FactoryBot
+- **Background Jobs**: [Your job processor]
+- **Authorization**: [Your authorization system]
+
+## Environment Variables
+
+Required for development:
+```
+# Add your required environment variables here
+```
+
+## Rails Conventions
+
+- Standard Rails naming conventions (snake_case)
+- RuboCop for code style enforcement
+- Follow Rails best practices and idioms
+
+## Development Patterns
+
+### Component Architecture
+- Use ViewComponent for reusable UI elements (located in `app/components/`)
+- Follow Rails conventions with Hotwire for reactive interfaces
+- Utilize Stimulus controllers for JavaScript interactions
+
+### PRD Workflow
+- Use `.claude/commands/workflows/create-prd.md` for structured feature development
+- PRDs should be saved in `/tasks/` directory as `prd-[feature-name].md`
+- Follow the clarifying questions process before implementation
+
+### Code Quality
+- RuboCop for consistent styling
+- Brakeman for security scanning
+- Comprehensive test coverage with RSpec
+
+## Testing Standards
+
+- Write tests before implementation (TDD)
+- Maintain high test coverage
+- Use FactoryBot for test data
+- Follow RSpec best practices
+
+## Important Reminders
+
+- Always run tests before committing
+- Use semantic commit messages
+- Update the development journal for significant changes
+- Follow the pre-commit checklist in `.claude/commands/quality/pre-commit.md`

data/lib/chiron/templates/claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "allow": ["Write", "MultiEdit", "Edit", "Bash"],
+    "deny": []
+  }
+}

data/lib/chiron/templates/commands/context/catchup.md

@@ -0,0 +1,77 @@
+# Catchup Command
+
+Use this when the user asks "catchup", "where are we", or wants a project status update.
+
+## Process
+
+1. **Read Development Journal**
+   ```
+   READ: docs/development_journal.md
+   ```
+   Focus on the last 3-5 entries
+
+2. **Check Active Work**
+   - List files in /tasks/ directory
+   - Identify incomplete tasks
+   - Note any blocked items
+
+3. **Review Current Branch**
+   ```bash
+   git branch --show-current
+   git status --short
+   git log --oneline -5
+   ```
+
+4. **Test Status**
+   ```bash
+   bin/rspec --format progress | tail -5
+   ```
+
+## Summary Format
+
+Provide a structured summary:
+
+### Recent Progress
+- Last 3 significant accomplishments
+- Who worked on what (from journal)
+- Key problems solved
+
+### Current State
+- Active branch and purpose
+- Pending changes
+- Test suite status
+- Any known issues
+
+### Next Steps
+- Immediate tasks to complete
+- Blocked items needing attention
+- Suggested priorities
+
+## Example Response
+
+```
+Here's where we are:
+
+**Recent Work:**
+- Fixed authentication modal bugs (3 critical issues resolved)
+- Implemented Phase 1 of in-kind donation form
+- Set up real-time OAuth status monitoring
+
+**Current State:**
+- Branch: feature/treasury_forms (working on treasury reimbursement features)
+- All tests passing (247 examples, 0 failures)
+- No uncommitted changes
+
+**Next Steps:**
+1. Complete remaining tasks for treasury forms (3 tasks pending)
+2. Address RuboCop warnings in recent changes
+3. Update documentation for new features
+```
+
+## Tips
+
+- Be concise but comprehensive
+- Highlight blockers or issues
+- Include contributor attribution
+- Suggest logical next actions
+- Reference specific files/lines when relevant

data/lib/chiron/templates/commands/context/prime.md

@@ -0,0 +1,32 @@
+# Context Window Prime
+
+## Quick Context Loading
+
+1. **Read Project Configuration**
+   ```
+   READ: CLAUDE.md
+   ```
+
+2. **Show Project Structure**
+   ```bash
+   # If eza is available
+   eza . --tree --level 3 --git-ignore
+   
+   # Otherwise use standard ls
+   ls -la
+   ```
+
+3. **Check Current Status**
+   ```bash
+   git status --short
+   git branch --show-current
+   ```
+
+## Usage
+
+This is a minimal context prime for when you need to quickly understand:
+- Project configuration and conventions
+- Directory structure
+- Current git state
+
+For more detailed context, use the `quickstart` command.

data/lib/chiron/templates/commands/context/quickstart.md

@@ -0,0 +1,47 @@
+# Quick Start Context
+
+Use this command to quickly get up to speed with the current project state.
+
+## Steps
+
+1. **Read Project Documentation**
+   - READ: CLAUDE.md
+   - READ: README.md (if different from CLAUDE.md)
+
+2. **Check Current Status**
+   ```bash
+   git status
+   git log --oneline -5
+   git branch --show-current
+   ```
+
+3. **Review Recent Work**
+   - READ: docs/development_journal.md (last 3 entries)
+   - Check for active tasks in /tasks/ directory
+
+4. **Quick Test Status**
+   ```bash
+   bin/rspec --fail-fast
+   ```
+
+5. **Check Code Quality**
+   ```bash
+   bin/rubocop --format simple | tail -20
+   ```
+
+## Output Summary
+
+After running these steps, provide a concise summary:
+- Current branch and its purpose
+- Recent work completed
+- Any failing tests or quality issues
+- Active tasks or PRDs
+- Suggested next steps
+
+## Usage
+
+This is ideal for:
+- Starting a new work session
+- After switching branches
+- When returning to a project after time away
+- Before pair programming sessions

data/lib/chiron/templates/commands/conventions/rails.md

@@ -0,0 +1,166 @@
+# Rails Development Conventions
+
+You are an expert in Ruby on Rails, PostgreSQL, Hotwire (Turbo and Stimulus), and Tailwind CSS.
+
+## Code Style and Structure
+- Write concise, idiomatic Ruby code with accurate examples
+- Follow Rails conventions and best practices
+- Use object-oriented and functional programming patterns as appropriate
+- Prefer iteration and modularization over code duplication
+- Use descriptive variable and method names (e.g., `user_signed_in?`, `calculate_total`)
+- Structure files according to Rails conventions (MVC, concerns, helpers, etc.)
+
+## Naming Conventions
+- Use snake_case for file names, method names, and variables
+- Use CamelCase for class and module names
+- Follow Rails naming conventions for models, controllers, and views
+- Use meaningful names that express intent
+
+## Ruby and Rails Usage
+- Use Ruby 3.x features when appropriate (pattern matching, endless methods)
+- Leverage Rails' built-in helpers and methods
+- Use ActiveRecord effectively for database operations
+- Follow RESTful routing conventions
+- Use concerns for shared behavior across models or controllers
+
+## Rails 8 Specific Features
+- Use the `encrypts` macro for sensitive data:
+  ```ruby
+  class User < ApplicationRecord
+    encrypts :api_key
+    encrypts :personal_data
+  end
+  ```
+- Leverage Solid Queue for background jobs
+- Use Solid Cache for caching
+- Take advantage of Propshaft for assets
+
+## Syntax and Formatting
+- Follow the Ruby Style Guide (https://rubystyle.guide/)
+- Use Ruby's expressive syntax (e.g., `unless`, `||=`, `&.`)
+- Prefer single quotes for strings unless interpolation is needed
+- Use modern hash syntax: `{ key: value }`
+- Keep methods small and focused
+
+## Error Handling and Validation
+- Use exceptions for exceptional cases, not for control flow
+- Implement proper error logging and user-friendly messages
+- Use ActiveModel validations in models
+- Handle errors gracefully in controllers with appropriate responses
+- Use strong parameters for mass assignment protection
+
+## Database and ActiveRecord
+- Write efficient queries using includes, joins, or select
+- Avoid N+1 queries with eager loading
+- Use database indexes effectively
+- Write reversible migrations
+- Use scopes for commonly used queries
+- Leverage ActiveRecord callbacks judiciously
+
+## Testing Approach
+- Write comprehensive tests using RSpec
+- Follow TDD/BDD practices
+- Use factories (FactoryBot) for test data
+- Write unit tests for models and services
+- Write integration tests for controllers
+- Write system tests for user workflows
+- Aim for high test coverage
+
+## UI and Frontend
+- Use Hotwire (Turbo and Stimulus) for dynamic interactions
+- Implement responsive design with Tailwind CSS
+- Use Rails view helpers and partials to keep views DRY
+- Leverage ViewComponent for reusable UI components
+- Use Turbo Frames for partial page updates
+- Use Turbo Streams for real-time updates
+
+## Performance Optimization
+- Use database indexing effectively
+- Implement caching strategies:
+  - Fragment caching for views
+  - Russian Doll caching for nested content
+  - Low-level caching for expensive operations
+- Use background jobs for time-consuming tasks
+- Optimize asset delivery with CDNs
+- Monitor and optimize database queries
+
+## Security Best Practices
+- Use strong parameters in controllers
+- Implement proper authentication (e.g., Devise, custom)
+- Use authorization (e.g., Pundit, CanCanCan)
+- Protect against common vulnerabilities:
+  - XSS (Rails handles by default)
+  - CSRF (use Rails tokens)
+  - SQL injection (use parameterized queries)
+- Keep dependencies updated
+- Use encrypted credentials for secrets
+
+## Service Objects Pattern
+```ruby
+# app/services/user_registration_service.rb
+class UserRegistrationService
+  def initialize(params)
+    @params = params
+  end
+  
+  def call
+    ActiveRecord::Base.transaction do
+      user = User.create!(@params)
+      send_welcome_email(user)
+      track_registration(user)
+      user
+    end
+  end
+  
+  private
+  
+  def send_welcome_email(user)
+    UserMailer.welcome(user).deliver_later
+  end
+  
+  def track_registration(user)
+    Analytics.track('User Registered', user_id: user.id)
+  end
+end
+```
+
+## Background Jobs
+```ruby
+# app/jobs/data_import_job.rb
+class DataImportJob < ApplicationJob
+  queue_as :default
+  
+  def perform(file_path)
+    DataImporter.new(file_path).import
+  rescue StandardError => e
+    Rails.logger.error "Import failed: #{e.message}"
+    raise
+  end
+end
+```
+
+## API Development
+- Use Rails API mode for API-only applications
+- Implement versioning for APIs
+- Use serializers for JSON responses
+- Implement proper authentication (JWT, OAuth)
+- Follow REST principles
+- Document APIs thoroughly
+
+## Deployment Considerations
+- Use environment variables for configuration
+- Implement health check endpoints
+- Set up proper logging and monitoring
+- Use asset precompilation
+- Configure database connection pooling
+- Set up SSL/TLS properly
+
+## Common Pitfalls to Avoid
+- Don't use inline styles or JavaScript
+- Avoid fat controllers - keep them thin
+- Don't skip validations or tests
+- Avoid modifying core classes
+- Don't store sensitive data in code
+- Avoid premature optimization
+
+Remember: Convention over Configuration - follow Rails conventions unless you have a very good reason not to!