chiron 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed0812e658fcd053473ebaeb84d3c0e7b5c0ca35cc9a53a66a316e72ba96d0e5
-  data.tar.gz: 45a146731a3eb6797444ae1b8d469e066da1a3e7d50d8913a414d2944c9d9a40
+  metadata.gz: 111859d544263c1e225be5ed1657738d129b1a3ba2d5408664cb2c79b21797ce
+  data.tar.gz: a65d608c4abea66adbc0780e847547d99173c8467e95e82da60bc63f968809f7
 SHA512:
-  metadata.gz: 0a1d06237d6c61271c7a4313a7242dc9105fdd14dc90a135f8117f18b0a5da1df02a800a5c2f731a02524bdf15a8dc1b698a5efd75f5bb9e7e634c8d6989876a
-  data.tar.gz: 90b73ca6f3b9a550ee4b78220c3f73e83587341e962c0265acdefc1276d06aa89c6f67bedd93258436760f2e6671ef47a0e4bbe0bd76643fd56e0659751ec844
+  metadata.gz: 89e21444318c44696397229933f62b8f41d0056217c89ae22784a70bbf5f1fbc3a25ebab5e5cf338c0da654adbb0e2ad7e4f816e9655ac98b0d06085b0ab9c0a
+  data.tar.gz: 9657fd9dc8b6a0ba32dabd0e82609428ee47ad9bd0fdded4dc7db25b968b5075f4e4200f238a90cd24c4703ffd0972549ae80f0f92bf972b78539e57825c9f50

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    chiron (0.2.0)
+    chiron (0.2.2)
       colorize (~> 1.1)
       thor (~> 1.3)
       tty-prompt (~> 0.23)

data/docs/development_journal.md

@@ -5,6 +5,41 @@ Chiron is a Ruby gem that helps Rails and Python developers set up Claude AI wor
 
 ---
 
+## 2025-07-01 - Enhancement: Claude Code Best Practices Integration
+**Developer(s)**: Claude Code | **Branch**: main | **Context**: User research into Claude Code best practices
+
+### What was accomplished today:
+- **Template Enhancement**: Updated Rails and Python CLAUDE.md templates with best practices from https://www.anthropic.com/engineering/claude-code-best-practices
+- **Extended Thinking Integration**: Added "think" triggers to workflow templates for complex problem solving
+- **Test Verification Focus**: Enhanced TDD template to emphasize test failure verification before implementation
+- **New Workflow Templates**: Created comprehensive Explore-Plan-Code-Commit and Visual Iteration workflows
+- **Tool Permissions Guidance**: Added tool customization sections to help developers manage Claude Code permissions
+- **Documentation Improvements**: Added quick documentation tips and conversational Q&A guidance
+
+### Technical decisions made:
+- **Incremental Enhancement**: Modified existing templates rather than replacing them to maintain backward compatibility
+- **Best Practice Integration**: Incorporated structured workflows (Explore-Plan-Code-Commit) recommended by Anthropic
+- **Visual Development Support**: Added dedicated workflow for screenshot-driven UI development
+- **Test Quality Focus**: Enhanced TDD workflow to prevent test overfitting and ensure proper failure verification
+
+### Implementation details:
+- **Updated Templates**: Both `rails/CLAUDE.md.erb` and `python/CLAUDE.md.erb` now include tool permissions, extended thinking, and visual development guidance
+- **New Workflow Files**: 
+  - `explore-plan-code-commit.md` - Structured development process
+  - `visual-iteration.md` - Screenshot-driven UI development
+- **Enhanced TDD**: Updated `test-driven.md` with failure verification and overfitting prevention
+- **Quality Assurance**: All 41 tests continue to pass, ensuring no breaking changes
+
+### Files modified:
+- `lib/chiron/templates/rails/CLAUDE.md.erb` - Added best practices sections
+- `lib/chiron/templates/python/CLAUDE.md.erb` - Added best practices sections  
+- `lib/chiron/templates/shared/commands/workflows/create-prd.md` - Added extended thinking trigger
+- `lib/chiron/templates/shared/commands/quality/test-driven.md` - Enhanced with failure verification
+- `lib/chiron/templates/shared/commands/workflows/explore-plan-code-commit.md` - New comprehensive workflow
+- `lib/chiron/templates/shared/commands/workflows/visual-iteration.md` - New UI development workflow
+
+---
+
 ## 2025-07-01 - Major Enhancement: Comprehensive Python Project Support
 **Developer(s)**: Claude Code | **Branch**: main | **Context**: User request for Python support
 

data/lib/chiron/cli.rb

@@ -15,6 +15,7 @@ module Chiron
 
     desc 'init', 'Initialize Claude workflow in current project'
     option :project_name, type: :string, desc: 'Project name for CLAUDE.md'
+    option :user_name, type: :string, desc: 'User name for templates. Auto-detected from git config if not specified'
     option :type, type: :string, desc: 'Project type (rails, python). Auto-detected if not specified'
     option :with_oauth, type: :boolean, default: false, desc: 'Include OAuth workflow examples'
     option :with_viewcomponents, type: :boolean, default: false, desc: 'Include ViewComponent rules'
@@ -27,6 +28,7 @@ module Chiron
       @prompt = TTY::Prompt.new
       @project_type = determine_project_type
       @project_name = options[:project_name] || prompt_for_project_name
+      @user_name = options[:user_name] || detect_user_name
 
       # Set up project configuration
       if @project_type == :python
@@ -376,6 +378,21 @@ module Chiron
         File.exist?('setup.py') || File.exist?('Pipfile')
     end
 
+    def detect_user_name
+      # Try git config first
+      git_user = `git config user.name 2>/dev/null`.strip
+      return git_user if !git_user.empty?
+
+      # Fall back to environment variables
+      env_user = ENV['USER'] || ENV['USERNAME']
+      return env_user if env_user && !env_user.empty?
+
+      # Last resort: prompt the user
+      @prompt.ask('What is your name?', default: 'Developer')
+    rescue StandardError
+      'Developer'
+    end
+
     def error(message)
       say "❌ #{message}".colorize(:red)
     end

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

@@ -6,6 +6,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 <%= @project_name %> is a Python project<% if @python_framework == :django %> using Django framework<% elsif @python_framework == :fastapi %> using FastAPI framework<% elsif @python_framework == :flask %> using Flask framework<% end %>. [Add your project description here]
 
+## Tool Permissions & Customization
+
+```bash
+# View current tool permissions
+/permissions
+
+# Customize tools for specific sessions
+claude --allowedTools read,edit,bash --no-write  # Example: read-only session
+claude --allowedTools bash,read,write           # Example: development session
+```
+
 ## Development Commands
 
 **Important**: Use virtual environments for dependency isolation.
@@ -118,6 +129,17 @@ JWT_SECRET=your-jwt-secret
 
 ## Development Patterns
 
+### Explore-Plan-Code-Commit Workflow
+1. **Explore**: Read relevant files and understand context
+2. **Plan**: Use "think" to trigger extended thinking mode for complex problems
+3. **Code**: Implement solution incrementally with frequent testing
+4. **Commit**: Create clear commit messages explaining the change
+
+### Visual Development
+- Take screenshots for UI work using Claude Code's image reading
+- Iterate 2-3 times for visual improvements
+- Use incremental screenshots to track progress
+
 ### Code Organization
 <% if @python_framework == :django %>
 - Follow Django's app-based architecture
@@ -150,9 +172,10 @@ JWT_SECRET=your-jwt-secret
 ## Testing Standards
 
 - Write tests before implementation (TDD)
+- **Verify tests fail first** - Confirm tests fail before writing implementation
 - Use pytest fixtures for test data
 - Mock external dependencies
-- Aim for high test coverage
+- Aim for high test coverage but avoid "overfitting to the tests"
 - Test edge cases and error conditions
 
 <% if @python_framework == :django %>
@@ -182,11 +205,19 @@ def test_read_main():
 ```
 <% end %>
 
+## Quick Documentation Tips
+
+- Use `#` key to quickly document guidelines and patterns
+- Be specific in instructions to Claude
+- Course-correct early and often during development
+- Provide clear context and expectations
+
 ## Important Reminders
 
 - Always run tests before committing
-- Use semantic commit messages
+- Use semantic commit messages with clear explanations
 - Update the development journal for significant changes
 - Follow the pre-commit checklist in `.claude/commands/quality/pre-commit.md`
 - Keep dependencies updated in requirements.txt
-- Document API changes
+- Document API changes
+- Use conversational Q&A to explore unfamiliar parts of the codebase

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

@@ -6,6 +6,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 <%= @project_name %> is a Rails <%= Rails.version rescue "8.0.2" %> application. [Add your project description here]
 
+## Tool Permissions & Customization
+
+```bash
+# View current tool permissions
+/permissions
+
+# Customize tools for specific sessions
+claude --allowedTools read,edit,bash --no-write  # Example: read-only session
+claude --allowedTools bash,read,write           # Example: development session
+```
+
 ## Development Commands
 
 **Important**: Always use binstubs instead of `bundle exec` for better performance and consistency.
@@ -67,6 +78,17 @@ Required for development:
 
 ## Development Patterns
 
+### Explore-Plan-Code-Commit Workflow
+1. **Explore**: Read relevant files and understand context
+2. **Plan**: Use "think" to trigger extended thinking mode for complex problems
+3. **Code**: Implement solution incrementally with frequent testing
+4. **Commit**: Create clear commit messages explaining the change
+
+### Visual Development
+- Take screenshots for UI work using Claude Code's image reading
+- Iterate 2-3 times for visual improvements
+- Use incremental screenshots to track progress
+
 ### Component Architecture
 - Use ViewComponent for reusable UI elements (located in `app/components/`)
 - Follow Rails conventions with Hotwire for reactive interfaces
@@ -85,13 +107,23 @@ Required for development:
 ## Testing Standards
 
 - Write tests before implementation (TDD)
-- Maintain high test coverage
+- **Verify tests fail first** - Confirm tests fail before writing implementation
+- Maintain high test coverage but avoid "overfitting to the tests"
 - Use FactoryBot for test data
 - Follow RSpec best practices
+- Test both happy path and edge cases
+
+## Quick Documentation Tips
+
+- Use `#` key to quickly document guidelines and patterns
+- Be specific in instructions to Claude
+- Course-correct early and often during development
+- Provide clear context and expectations
 
 ## Important Reminders
 
 - Always run tests before committing
-- Use semantic commit messages
+- Use semantic commit messages with clear explanations
 - Update the development journal for significant changes
-- Follow the pre-commit checklist in `.claude/commands/quality/pre-commit.md`
+- Follow the pre-commit checklist in `.claude/commands/quality/pre-commit.md`
+- Use conversational Q&A to explore unfamiliar parts of the codebase

data/lib/chiron/templates/shared/commands/quality/test-driven.md

@@ -2,13 +2,20 @@
 
 ## Core Principles
 
-1. **Red**: Write a failing test first
+1. **Red**: Write a failing test first and **verify it fails**
 2. **Green**: Write minimal code to make the test pass
 3. **Refactor**: Improve the code while keeping tests green
 
+## Key: Always Verify Test Failure First
+
+**Critical**: Before writing implementation, run the test to confirm it fails for the expected reason. This prevents false positives and ensures your test actually validates the behavior.
+
 ## TDD Process
 
-### Step 1: Write a Failing Test
+### Step 1: Think Through Complex Features
+For complex functionality, use "think" to trigger extended thinking mode to plan your test strategy.
+
+### Step 2: Write a Failing Test
 ```ruby
 # spec/models/user_spec.rb
 it 'returns the full name' do
@@ -17,13 +24,14 @@ it 'returns the full name' do
 end
 ```
 
-### Step 2: Run Test (See it Fail)
+### Step 3: **VERIFY** Test Fails (Critical Step)
 ```bash
 bin/rspec spec/models/user_spec.rb
 # Expected failure: undefined method `full_name'
+# CONFIRM: Test fails for the RIGHT reason
 ```
 
-### Step 3: Write Minimal Code
+### Step 4: Write Minimal Code
 ```ruby
 # app/models/user.rb
 def full_name
@@ -31,13 +39,13 @@ def full_name
 end
 ```
 
-### Step 4: Run Test (See it Pass)
+### Step 5: Run Test (See it Pass)
 ```bash
 bin/rspec spec/models/user_spec.rb
 # All tests should pass
 ```
 
-### Step 5: Refactor if Needed
+### Step 6: Refactor if Needed
 ```ruby
 # Improved version
 def full_name
@@ -68,6 +76,8 @@ end
 - Never delete or modify tests just to make them pass
 - If a test is wrong, fix it and document why
 - Use `skip` or `pending` for incomplete tests
+- **Avoid overfitting**: Ensure tests validate real behavior, not just current implementation
+- Write tests that would catch regressions if the implementation changed
 
 ## Test Plan Management
 

data/lib/chiron/templates/shared/commands/workflows/create-prd.md

@@ -7,9 +7,10 @@ To create a detailed Product Requirements Document (PRD) in Markdown format base
 ## Process
 
 1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
-2. **Ask Clarifying Questions:** Before writing the PRD, *always* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out).
-3. **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
-4. **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/tasks` directory.
+2. **Think Through Complexity:** Use "think" to trigger extended thinking mode for complex features requiring deep analysis.
+3. **Ask Clarifying Questions:** Before writing the PRD, *always* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out).
+4. **Generate PRD:** Based on the initial prompt and the user's answers to the clarifying questions, generate a PRD using the structure outlined below.
+5. **Save PRD:** Save the generated document as `prd-[feature-name].md` inside the `/tasks` directory.
 
 ## Clarifying Questions (Examples)
 

data/lib/chiron/templates/shared/commands/workflows/explore-plan-code-commit.md

@@ -0,0 +1,192 @@
+# Explore-Plan-Code-Commit Workflow
+
+## Overview
+
+A structured approach to feature development that emphasizes understanding before building, thoughtful planning, and clear documentation of changes.
+
+## The Four Phases
+
+### 1. Explore Phase
+
+**Goal**: Understand the codebase, context, and requirements before making changes.
+
+#### Actions:
+- Read relevant files to understand current implementation
+- Explore related code and dependencies
+- Review existing tests and documentation
+- Use conversational Q&A to understand unfamiliar parts of the codebase
+- Search for similar implementations or patterns
+
+#### Commands:
+```bash
+# Find related files
+find . -name "*.rb" | grep user
+grep -r "authentication" app/
+
+# Understand file structure
+ls -la app/models/
+head -20 app/models/user.rb
+```
+
+#### Questions to Ask:
+- What does the current code do?
+- How does this feature fit into the existing architecture?
+- What patterns are already established?
+- Are there similar implementations to reference?
+- What are the dependencies and constraints?
+
+### 2. Plan Phase
+
+**Goal**: Create a clear implementation strategy before writing code.
+
+#### Use Extended Thinking
+For complex features, use "think" to trigger extended thinking mode:
+- Analyze multiple implementation approaches
+- Consider edge cases and error scenarios
+- Plan the sequence of changes
+- Identify potential risks or complications
+
+#### Planning Activities:
+- Break down the feature into small, testable chunks
+- Identify the files that need changes
+- Plan the order of implementation (models → controllers → views)
+- Consider backward compatibility
+- Plan rollback strategy if needed
+
+#### Documentation:
+- Update or create PRD if the scope is significant
+- Add notes to development journal
+- Create a checklist of implementation steps
+
+### 3. Code Phase
+
+**Goal**: Implement the solution incrementally with frequent validation.
+
+#### Best Practices:
+- Start with tests (TDD approach)
+- Make small, atomic changes
+- Test frequently during development
+- Commit early and often with descriptive messages
+- Follow established code patterns and conventions
+
+#### Implementation Order:
+1. Write failing tests first
+2. Implement minimal code to pass tests
+3. Refactor while keeping tests green
+4. Add edge case handling
+5. Update documentation and comments
+
+#### Validation:
+- Run tests after each change
+- Test in development environment
+- Verify edge cases work correctly
+- Check for performance implications
+
+### 4. Commit Phase
+
+**Goal**: Document changes clearly and ensure code quality.
+
+#### Pre-Commit Checklist:
+- [ ] All tests pass
+- [ ] Code follows project style guidelines
+- [ ] No debug code or console.logs left behind
+- [ ] Documentation updated if needed
+- [ ] Performance implications considered
+- [ ] Security implications reviewed
+
+#### Commit Message Structure:
+```
+Type: Brief description
+
+More detailed explanation of what was changed and why.
+Include context about the problem being solved.
+
+- Key change 1
+- Key change 2
+- Key change 3
+
+Closes #issue-number (if applicable)
+```
+
+#### Commit Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `refactor`: Code refactoring
+- `docs`: Documentation changes
+- `test`: Adding or updating tests
+- `style`: Code style changes (formatting, etc.)
+
+## When to Use This Workflow
+
+### Ideal For:
+- New feature development
+- Complex bug fixes
+- Refactoring existing code
+- Working with unfamiliar code
+- Cross-cutting changes affecting multiple files
+
+### Not Necessary For:
+- Simple typo fixes
+- Trivial configuration changes
+- Emergency hotfixes (but document afterwards)
+
+## Advanced Techniques
+
+### Subagent Usage
+For very complex problems, consider using subagents:
+- Create specialized agents for different aspects (backend, frontend, testing)
+- Have each agent focus on their specific domain
+- Coordinate between agents for integrated solutions
+
+### Incremental Development
+- Start with the simplest possible implementation
+- Add complexity gradually
+- Maintain working code at each step
+- Use feature flags for incomplete features
+
+### Documentation as You Go
+- Update README files for significant changes
+- Add inline comments for complex logic
+- Update API documentation
+- Keep development journal current
+
+## Common Pitfalls to Avoid
+
+### In Explore Phase:
+- Don't skip understanding existing code
+- Don't assume you know how things work
+- Don't ignore existing patterns and conventions
+
+### In Plan Phase:
+- Don't skip planning for complex features
+- Don't plan too far ahead (avoid waterfall)
+- Don't ignore edge cases in planning
+
+### In Code Phase:
+- Don't write all code before testing
+- Don't ignore failing tests
+- Don't commit broken code
+- Don't leave debug code in commits
+
+### In Commit Phase:
+- Don't write vague commit messages
+- Don't commit multiple unrelated changes together
+- Don't skip the pre-commit checklist
+- Don't forget to update documentation
+
+## Integration with Other Workflows
+
+This workflow complements:
+- **TDD**: The Code phase follows TDD principles
+- **PRD Process**: Use PRDs for significant features in the Plan phase
+- **Code Review**: Structured commits make reviews easier
+- **CI/CD**: Clean commits integrate better with automated pipelines
+
+## Success Metrics
+
+You're using this workflow successfully when:
+- You rarely encounter unexpected issues during implementation
+- Your commits are focused and well-documented
+- Code reviews are faster and more productive
+- You can easily explain your changes to others
+- You spend less time debugging integration issues

data/lib/chiron/templates/shared/commands/workflows/visual-iteration.md

@@ -0,0 +1,269 @@
+# Visual Iteration Workflow for UI Development
+
+## Overview
+
+A screenshot-driven development process that leverages Claude Code's image reading capabilities to iteratively improve user interfaces through visual feedback and refinement.
+
+## Core Principle
+
+Use screenshots as the primary feedback mechanism for UI development, allowing for rapid iteration and visual validation of changes before and after implementation.
+
+## The Visual Iteration Process
+
+### 1. Capture Initial State
+
+**Goal**: Document the current state before making changes.
+
+#### Actions:
+- Take a screenshot of the current UI
+- Share the screenshot with Claude Code using drag-and-drop or file path
+- Document what needs to be changed or improved
+
+#### Commands:
+```bash
+# macOS screenshot shortcuts
+Cmd+Shift+4         # Select area to screenshot
+Cmd+Shift+3         # Full screen screenshot
+Cmd+Shift+5         # Screenshot options menu
+
+# After taking screenshot, drag file into Claude Code chat
+```
+
+#### Documentation:
+- Describe the current problems or limitations
+- Identify specific UI elements that need attention
+- Note any accessibility or usability concerns
+
+### 2. Visual Analysis
+
+**Goal**: Analyze the current UI and plan improvements.
+
+#### Claude Code Analysis:
+When you share a screenshot, ask Claude to:
+- Identify UI/UX issues
+- Suggest specific improvements
+- Recommend modern design patterns
+- Point out accessibility concerns
+- Suggest component organization
+
+#### Questions to Ask:
+- What design patterns would improve this interface?
+- Are there accessibility issues to address?
+- How can we improve the visual hierarchy?
+- What CSS/styling changes would have the biggest impact?
+- How does this compare to modern UI conventions?
+
+### 3. Incremental Implementation
+
+**Goal**: Make small, visual changes and validate each step.
+
+#### Implementation Strategy:
+- Make one visual change at a time
+- Focus on the most impactful changes first
+- Use CSS/styling changes before structural changes
+- Test responsiveness at each step
+
+#### Change Types by Priority:
+1. **Layout & Spacing**: Margins, padding, alignment
+2. **Typography**: Font sizes, weights, line spacing
+3. **Colors & Contrast**: Brand colors, accessibility compliance
+4. **Components**: Buttons, forms, cards, navigation
+5. **Interactions**: Hover states, transitions, animations
+6. **Responsive**: Mobile, tablet, desktop breakpoints
+
+### 4. Screenshot After Changes
+
+**Goal**: Capture and validate the results of each change.
+
+#### Process:
+- Take a new screenshot after each significant change
+- Compare with the previous screenshot
+- Share the new screenshot with Claude Code for feedback
+- Document what was changed and why
+
+#### Validation Questions:
+- Does this change improve the user experience?
+- Are there any unintended side effects?
+- Does it work across different screen sizes?
+- Is the change consistent with the design system?
+
+### 5. Iterate 2-3 Times
+
+**Goal**: Refine the UI through multiple feedback cycles.
+
+#### Typical Iteration Pattern:
+- **Iteration 1**: Major layout and structural improvements
+- **Iteration 2**: Color, typography, and spacing refinements
+- **Iteration 3**: Polish, micro-interactions, and edge cases
+
+#### When to Stop Iterating:
+- The UI meets functional requirements
+- Visual design is cohesive and accessible
+- User experience feels intuitive
+- No obvious improvements remain
+- Time/budget constraints require moving on
+
+## UI Development Best Practices
+
+### Component-First Approach
+```ruby
+# For Rails with ViewComponent
+# app/components/button_component.rb
+class ButtonComponent < ViewComponent::Base
+  def initialize(variant: :primary, size: :medium, **options)
+    @variant = variant
+    @size = size
+    @options = options
+  end
+
+  private
+
+  attr_reader :variant, :size, :options
+
+  def css_classes
+    ["btn", "btn--#{variant}", "btn--#{size}", @options[:class]].compact.join(" ")
+  end
+end
+```
+
+### CSS Organization
+```scss
+// Use BEM methodology
+.btn {
+  &--primary { /* primary styles */ }
+  &--secondary { /* secondary styles */ }
+  &--small { /* small size */ }
+  &--medium { /* medium size */ }
+  &--large { /* large size */ }
+}
+```
+
+### Responsive Design Testing
+```css
+/* Test at common breakpoints */
+/* Mobile: 320px - 768px */
+/* Tablet: 768px - 1024px */
+/* Desktop: 1024px+ */
+
+@media (max-width: 768px) {
+  .component {
+    /* mobile styles */
+  }
+}
+```
+
+## Tools and Techniques
+
+### Screenshot Tools
+- **macOS**: Built-in screenshot tools (Cmd+Shift+4/5)
+- **Windows**: Snipping Tool, Windows+Shift+S
+- **Browser**: Developer tools device emulation
+- **Third-party**: CleanShot X, LightShot
+
+### Browser Development
+```javascript
+// Test different viewport sizes in browser console
+// Responsive design testing
+window.resizeTo(375, 812);  // iPhone X
+window.resizeTo(768, 1024); // iPad
+window.resizeTo(1440, 900); // Desktop
+```
+
+### CSS Grid and Flexbox Debugging
+```css
+/* Temporary debug styles */
+.debug-grid {
+  outline: 1px solid red !important;
+}
+
+.debug-flex {
+  background: rgba(255, 0, 0, 0.1) !important;
+}
+```
+
+## Common UI Improvement Patterns
+
+### Layout Issues
+- **Problem**: Cramped spacing
+- **Solution**: Add consistent padding/margins using design tokens
+- **Validation**: Elements have breathing room, visual hierarchy is clear
+
+### Typography Problems
+- **Problem**: Poor readability
+- **Solution**: Improve font sizes, line heights, contrast ratios
+- **Validation**: Text is easy to read at all screen sizes
+
+### Color and Contrast
+- **Problem**: Accessibility violations
+- **Solution**: Use WCAG AA compliant color combinations
+- **Validation**: Passes automated accessibility testing
+
+### Interactive Elements
+- **Problem**: Unclear interactive states
+- **Solution**: Add hover, focus, and active states
+- **Validation**: Users can identify clickable elements
+
+## Integration with Testing
+
+### Visual Regression Testing
+```ruby
+# RSpec with Capybara
+scenario "homepage layout" do
+  visit root_path
+  # Take screenshot for comparison
+  save_screenshot("homepage_#{Date.current}.png")
+  
+  expect(page).to have_css(".hero-section")
+  expect(page).to have_css(".call-to-action")
+end
+```
+
+### Accessibility Testing
+```ruby
+# Include accessibility testing
+require 'axe-capybara'
+
+scenario "homepage accessibility" do
+  visit root_path
+  expect(page).to be_axe_clean
+end
+```
+
+## Documentation and Handoff
+
+### Design System Updates
+- Update component documentation with screenshots
+- Document new CSS classes and their usage
+- Add examples of component variations
+- Include accessibility notes
+
+### Developer Handoff
+- Provide before/after screenshots
+- Document CSS changes made
+- Include responsive breakpoint notes
+- Add any new dependencies or setup requirements
+
+## When to Use Visual Iteration
+
+### Ideal For:
+- New UI component development
+- Redesigning existing interfaces
+- Fixing visual bugs or inconsistencies
+- Improving accessibility
+- Responsive design implementation
+
+### Not Necessary For:
+- Backend logic changes
+- API development
+- Database migrations
+- Non-visual bug fixes
+
+## Success Metrics
+
+You're using visual iteration successfully when:
+- UI changes are intentional and validated
+- Screenshots provide clear before/after documentation
+- Multiple stakeholders can review visual progress
+- Accessibility and usability improve with each iteration
+- Development time spent on UI revisions decreases
+- User feedback on interface quality improves

data/lib/chiron/templates/shared/development_journal.md.erb

@@ -3,7 +3,7 @@
 This journal tracks significant development work, bug fixes, and feature implementations for <%= @project_name %>.
 
 ## Recent Contributors (Last 30 Days)
-- **[Your Name]**: Project owner, initial setup
+- **<%= @user_name %>**: Project owner, initial setup
 - **Claude Code**: AI-assisted development
 
 ## Active Branches & Ownership
@@ -19,11 +19,12 @@ This journal tracks significant development work, bug fixes, and feature impleme
 ---
 
 ## <%= Date.today.strftime('%Y-%m-%d') %> - Initial Setup
-**Developer(s)**: [Your Name] & Claude Code | **Branch**: main | **Context**: Project initialization
+**Developer(s)**: <%= @user_name %> & Claude Code | **Branch**: main | **Context**: Project initialization
 
 ### What Was Done
-- Initialized Rails <%= Rails.version rescue "8.0.2" %> application
-- Set up Claude workflow with claude-rails-setup gem
+<% if @project_type == :rails %>
+- Initialized Rails <%= defined?(Rails) ? Rails.version : "8.0+" %> application
+- Set up Claude workflow with Chiron gem
 - Created initial project structure
 - Configured development environment
 
@@ -33,7 +34,7 @@ This journal tracks significant development work, bug fixes, and feature impleme
 - Setting up for collaborative development
 
 ### Technical Details
-- Rails <%= Rails.version rescue "8.0.2" %> with PostgreSQL database
+- Rails <%= defined?(Rails) ? Rails.version : "8.0+" %> with PostgreSQL database
 - Hotwire (Turbo + Stimulus) for frontend interactivity
 - TailwindCSS for styling
 - RSpec for testing framework
@@ -50,6 +51,88 @@ This journal tracks significant development work, bug fixes, and feature impleme
 - Set up continuous integration
 - Implement initial models based on requirements
 - Create first PRD for core functionality
+<% elsif @project_type == :python %>
+- Initialized Python project
+<% if @python_framework == :django %>
+- Set up Django project structure
+<% elsif @python_framework == :fastapi %>
+- Set up FastAPI project structure
+<% elsif @python_framework == :flask %>
+- Set up Flask project structure
+<% else %>
+- Set up generic Python project structure
+<% end %>
+- Set up Claude workflow with Chiron gem
+- Configured development environment
+
+### Why It Was Done
+- Starting new Python project with AI-assisted development workflow
+- Establishing consistent development patterns from the beginning
+- Setting up for collaborative development
+
+### Technical Details
+<% if @python_framework == :django %>
+- Django framework for web development
+- PostgreSQL database (recommended)
+- Django REST framework for APIs
+<% elsif @python_framework == :fastapi %>
+- FastAPI framework for high-performance APIs
+- Pydantic for data validation
+- SQLAlchemy for database ORM
+<% elsif @python_framework == :flask %>
+- Flask framework for web development
+- SQLAlchemy for database ORM
+- Flask-RESTful for API development
+<% else %>
+- Python 3.x+ project structure
+<% end %>
+- pytest for testing framework
+- black for code formatting
+- flake8 for linting
+- Claude AI workflow integration
+
+### Results
+- ✅ Python project structure created
+- ✅ Claude workflow initialized with commands and templates
+- ✅ Development journal started
+- ✅ Git repository initialized
+
+### Next Steps
+- Set up virtual environment and install dependencies
+- Configure database and create initial models
+- Set up continuous integration
+- Implement core functionality based on requirements
+- Create first PRD for feature development
+<% else %>
+- Initialized project structure
+- Set up Claude workflow with Chiron gem
+- Created initial project structure
+- Configured development environment
+
+### Why It Was Done
+- Starting new project with AI-assisted development workflow
+- Establishing consistent development patterns from the beginning
+- Setting up for collaborative development
+
+### Technical Details
+- Project initialized with Claude AI workflow integration
+- Development journal and task tracking system
+- Command templates for consistent workflows
+- Quality assurance and testing patterns
+
+### Results
+- ✅ Project structure created
+- ✅ Claude workflow initialized with commands and templates
+- ✅ Development journal started
+- ✅ Git repository initialized
+
+### Next Steps
+- Set up development dependencies
+- Configure testing framework
+- Set up continuous integration
+- Implement core functionality based on requirements
+- Create first PRD for feature development
+<% end %>
 
 ---
 

data/lib/chiron/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chiron
-  VERSION = '0.2.1'
+  VERSION = '0.2.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chiron
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Brett McHargue
@@ -150,9 +150,11 @@ files:
 - lib/chiron/templates/shared/commands/quality/test-driven.md
 - lib/chiron/templates/shared/commands/workflows/branch-management.md
 - lib/chiron/templates/shared/commands/workflows/create-prd.md
+- lib/chiron/templates/shared/commands/workflows/explore-plan-code-commit.md
 - lib/chiron/templates/shared/commands/workflows/feature-complete.md
 - lib/chiron/templates/shared/commands/workflows/generate-tasks.md
 - lib/chiron/templates/shared/commands/workflows/process-tasks.md
+- lib/chiron/templates/shared/commands/workflows/visual-iteration.md
 - lib/chiron/templates/shared/development_journal.md.erb
 - lib/chiron/version.rb
 homepage: https://github.com/ebrett/chiron