chiron 0.2.0 → 0.2.2

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

@@ -8,12 +8,18 @@ This journal tracks significant development work, bug fixes, and feature impleme
 
 ## Active Branches & Ownership
 - `main`: Stable branch for production releases
-- `[feature-branch]`: [Developer Name] - [Feature description]
+- `[feature-branch]`: [Developer Name] - [Feature description] - [Created YYYY-MM-DD]
+
+### Branch Tracking Guidelines
+- Always update this section when creating/merging branches
+- Include branch purpose, owner, and creation date
+- Link to related PRD files when applicable
+- Note dependencies between branches
 
 ---
 
 ## <%= Date.today.strftime('%Y-%m-%d') %> - Initial Setup
-**Developer(s)**: [Your Name] & Claude Code | **Context**: Project initialization
+**Developer(s)**: [Your Name] & Claude Code | **Branch**: main | **Context**: Project initialization
 
 ### What Was Done
 - Initialized Rails <%= Rails.version rescue "8.0.2" %> application
@@ -51,7 +57,7 @@ This journal tracks significant development work, bug fixes, and feature impleme
 Journal Entry Template - Copy for new entries:
 
 ## [YYYY-MM-DD] - [Brief Summary Title]
-**Developer(s)**: [Name] | **Context**: [How work was initiated]
+**Developer(s)**: [Name] | **Branch**: [branch-name] | **Context**: [How work was initiated]
 
 ### What Was Done
 - [Specific actions taken]

data/lib/chiron/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chiron
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Brett McHargue
@@ -133,9 +133,14 @@ files:
 - lib/chiron/project_config.rb
 - lib/chiron/templates/python/CLAUDE.md.erb
 - lib/chiron/templates/python/commands/conventions/python.md
+- lib/chiron/templates/python/commands/quality/python-testing.md
+- lib/chiron/templates/python/commands/workflows/debug-python.md
+- lib/chiron/templates/python/commands/workflows/flask-development.md
+- lib/chiron/templates/python/commands/workflows/python-refactor.md
 - lib/chiron/templates/rails/CLAUDE.md.erb
 - lib/chiron/templates/rails/commands/conventions/rails.md
 - lib/chiron/templates/shared/claude/settings.json
+- lib/chiron/templates/shared/commands/context/branch-context.md
 - lib/chiron/templates/shared/commands/context/catchup.md
 - lib/chiron/templates/shared/commands/context/prime.md
 - lib/chiron/templates/shared/commands/context/quickstart.md
@@ -143,10 +148,13 @@ files:
 - lib/chiron/templates/shared/commands/journal/template.md
 - lib/chiron/templates/shared/commands/quality/pre-commit.md
 - 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