chiron 0.2.0 → 0.2.2

data/lib/chiron/templates/python/commands/workflows/python-refactor.md

@@ -0,0 +1,336 @@
+# Python Refactoring Workflow
+
+Follow this systematic approach when refactoring Python code to improve its structure, readability, and maintainability.
+
+## Pre-Refactoring Checklist
+
+- [ ] Ensure comprehensive test coverage exists
+- [ ] Run all tests and confirm they pass
+- [ ] Commit current working state to version control
+- [ ] Identify specific refactoring goals
+- [ ] Review Python conventions and PEP 8
+
+## Refactoring Patterns
+
+### 1. Extract Function
+```python
+# Before
+def process_user_data(users):
+    for user in users:
+        # Complex validation logic
+        if user.age < 18:
+            user.status = 'minor'
+        elif user.age >= 65:
+            user.status = 'senior'
+        else:
+            user.status = 'adult'
+        
+        # Complex calculation
+        user.discount = calculate_complex_discount(user)
+
+# After
+def process_user_data(users):
+    for user in users:
+        user.status = categorize_user_by_age(user.age)
+        user.discount = calculate_user_discount(user)
+
+def categorize_user_by_age(age: int) -> str:
+    if age < 18:
+        return 'minor'
+    elif age >= 65:
+        return 'senior'
+    return 'adult'
+```
+
+### 2. Extract Class
+```python
+# Before
+def send_email(to, subject, body, smtp_server, port, username, password):
+    # Email sending logic
+    pass
+
+# After
+class EmailService:
+    def __init__(self, smtp_server: str, port: int, username: str, password: str):
+        self.smtp_server = smtp_server
+        self.port = port
+        self.username = username
+        self.password = password
+    
+    def send(self, to: str, subject: str, body: str) -> None:
+        # Email sending logic
+        pass
+
+# Usage
+email_service = EmailService(smtp_server, port, username, password)
+email_service.send(to, subject, body)
+```
+
+### 3. Replace Conditionals with Polymorphism
+```python
+# Before
+def calculate_shipping(order_type, weight, distance):
+    if order_type == 'standard':
+        return weight * 0.5 + distance * 0.1
+    elif order_type == 'express':
+        return weight * 1.0 + distance * 0.2
+    elif order_type == 'overnight':
+        return weight * 2.0 + distance * 0.5
+
+# After
+from abc import ABC, abstractmethod
+
+class ShippingStrategy(ABC):
+    @abstractmethod
+    def calculate(self, weight: float, distance: float) -> float:
+        pass
+
+class StandardShipping(ShippingStrategy):
+    def calculate(self, weight: float, distance: float) -> float:
+        return weight * 0.5 + distance * 0.1
+
+class ExpressShipping(ShippingStrategy):
+    def calculate(self, weight: float, distance: float) -> float:
+        return weight * 1.0 + distance * 0.2
+
+class OvernightShipping(ShippingStrategy):
+    def calculate(self, weight: float, distance: float) -> float:
+        return weight * 2.0 + distance * 0.5
+
+# Usage
+shipping_strategies = {
+    'standard': StandardShipping(),
+    'express': ExpressShipping(),
+    'overnight': OvernightShipping()
+}
+
+def calculate_shipping(order_type: str, weight: float, distance: float) -> float:
+    strategy = shipping_strategies.get(order_type)
+    if not strategy:
+        raise ValueError(f"Unknown order type: {order_type}")
+    return strategy.calculate(weight, distance)
+```
+
+### 4. Simplify Complex Conditionals
+```python
+# Before
+def can_withdraw(account, amount):
+    if account.balance >= amount and account.is_active and not account.is_frozen and amount > 0:
+        return True
+    return False
+
+# After
+def can_withdraw(account, amount):
+    has_sufficient_funds = account.balance >= amount
+    is_valid_amount = amount > 0
+    is_account_available = account.is_active and not account.is_frozen
+    
+    return has_sufficient_funds and is_valid_amount and is_account_available
+```
+
+### 5. Use List Comprehensions and Generators
+```python
+# Before
+def get_active_user_emails(users):
+    emails = []
+    for user in users:
+        if user.is_active:
+            emails.append(user.email)
+    return emails
+
+# After
+def get_active_user_emails(users):
+    return [user.email for user in users if user.is_active]
+
+# For large datasets, use generator
+def get_active_user_emails_generator(users):
+    return (user.email for user in users if user.is_active)
+```
+
+### 6. Replace Magic Numbers with Named Constants
+```python
+# Before
+def calculate_circle_area(radius):
+    return 3.14159 * radius ** 2
+
+def is_valid_age(age):
+    return 18 <= age <= 65
+
+# After
+import math
+
+MINIMUM_AGE = 18
+RETIREMENT_AGE = 65
+
+def calculate_circle_area(radius):
+    return math.pi * radius ** 2
+
+def is_valid_age(age):
+    return MINIMUM_AGE <= age <= RETIREMENT_AGE
+```
+
+### 7. Use Type Hints
+```python
+# Before
+def process_items(items, multiplier):
+    return [item * multiplier for item in items]
+
+# After
+from typing import List, Union
+
+def process_items(
+    items: List[Union[int, float]], 
+    multiplier: Union[int, float]
+) -> List[Union[int, float]]:
+    return [item * multiplier for item in items]
+```
+
+### 8. Replace Nested Loops with Iterator Tools
+```python
+# Before
+def get_combinations(list1, list2):
+    result = []
+    for item1 in list1:
+        for item2 in list2:
+            result.append((item1, item2))
+    return result
+
+# After
+from itertools import product
+
+def get_combinations(list1, list2):
+    return list(product(list1, list2))
+```
+
+## Code Organization Refactoring
+
+### 1. Module Structure
+```python
+# Before: everything in one file
+# app.py (1000+ lines)
+
+# After: organized modules
+# project/
+#   ├── __init__.py
+#   ├── models/
+#   │   ├── __init__.py
+#   │   ├── user.py
+#   │   └── order.py
+#   ├── services/
+#   │   ├── __init__.py
+#   │   ├── email_service.py
+#   │   └── payment_service.py
+#   └── utils/
+#       ├── __init__.py
+#       └── validators.py
+```
+
+### 2. Dependency Injection
+```python
+# Before
+class OrderService:
+    def process_order(self, order):
+        db = Database()  # Hard-coded dependency
+        payment = PaymentGateway()  # Hard-coded dependency
+        # Process order
+
+# After
+class OrderService:
+    def __init__(self, db: Database, payment_gateway: PaymentGateway):
+        self.db = db
+        self.payment_gateway = payment_gateway
+    
+    def process_order(self, order):
+        # Process order using injected dependencies
+```
+
+## Testing During Refactoring
+
+### 1. Maintain Test Coverage
+```bash
+# Run tests with coverage
+pytest --cov=myproject tests/
+
+# Generate coverage report
+pytest --cov=myproject --cov-report=html tests/
+```
+
+### 2. Test Each Refactoring Step
+```python
+# Write characterization tests before refactoring
+def test_original_behavior():
+    # Capture current behavior
+    result = legacy_function(test_input)
+    assert result == expected_output
+
+# Ensure behavior remains the same after refactoring
+def test_refactored_behavior():
+    result = refactored_function(test_input)
+    assert result == expected_output
+```
+
+## Performance Considerations
+
+### 1. Profile Before and After
+```python
+import cProfile
+import pstats
+
+# Profile original code
+cProfile.run('original_function()', 'original_stats')
+
+# Profile refactored code
+cProfile.run('refactored_function()', 'refactored_stats')
+
+# Compare results
+original = pstats.Stats('original_stats')
+refactored = pstats.Stats('refactored_stats')
+```
+
+### 2. Memory Usage
+```python
+from memory_profiler import profile
+
+@profile
+def function_to_refactor():
+    # Your code here
+    pass
+```
+
+## Refactoring Tools
+
+### 1. Automated Refactoring with rope
+```bash
+pip install rope
+
+# Use rope for automated refactoring
+# - Extract method
+# - Rename
+# - Move
+# - Inline
+```
+
+### 2. Code Formatting
+```bash
+# Format with black
+black myproject/
+
+# Sort imports with isort
+isort myproject/
+
+# Type check with mypy
+mypy myproject/
+```
+
+## Post-Refactoring Checklist
+
+- [ ] All tests pass
+- [ ] Code coverage maintained or improved
+- [ ] Performance is acceptable
+- [ ] Code follows PEP 8 and project conventions
+- [ ] Type hints added where appropriate
+- [ ] Documentation updated
+- [ ] Complex parts have explanatory comments
+- [ ] No code duplication
+- [ ] SOLID principles followed
+- [ ] Code reviewed by team member

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/context/branch-context.md

@@ -0,0 +1,176 @@
+# Branch Context Command
+
+Use this command when switching branches, starting new work, or when Claude needs to understand the current branch context.
+
+## Purpose
+
+Provides comprehensive branch information to maintain context across Claude sessions, especially important when:
+- Switching between branches
+- Starting a new Claude session on an existing branch
+- Collaborating with others on feature branches
+- Resuming work after time away
+
+## Process
+
+### 1. **Current Branch Status**
+```bash
+git branch --show-current
+git status --porcelain
+git log --oneline -5
+```
+
+### 2. **Branch Information**
+```bash
+# Show branch creation point
+git merge-base main HEAD
+
+# Show commits unique to this branch
+git log --oneline main..HEAD
+
+# Show files changed in this branch
+git diff --name-only main...HEAD
+```
+
+### 3. **Branch Purpose Discovery**
+Check for:
+- **Tasks Directory**: Look for related PRD files in `/tasks/`
+- **Development Journal**: Search for branch-related entries
+- **Commit Messages**: Analyze recent commits for context
+- **Pull Request**: Check if PR exists for this branch
+
+### 4. **Work Context**
+```bash
+# Check for uncommitted work
+git diff --stat
+
+# Check for untracked files
+git ls-files --others --exclude-standard
+
+# Check for stashed changes
+git stash list
+```
+
+## Output Format
+
+Provide a structured summary:
+
+### Branch Overview
+- **Name**: Current branch name
+- **Type**: feature/bugfix/hotfix/experiment
+- **Base**: Branch point from main/develop
+- **Age**: How long since branch creation
+- **Status**: ahead/behind/up-to-date with base
+
+### Current Work
+- **Purpose**: What this branch is implementing
+- **Progress**: Completed vs remaining work
+- **Files Modified**: Key files changed
+- **Tests**: Test status and coverage
+
+### Context for Claude
+- **Related PRD**: Link to requirements document
+- **Dependencies**: Other branches or external dependencies
+- **Blockers**: Known issues or waiting items
+- **Next Steps**: Immediate tasks to continue
+
+## Example Response
+
+```
+🌿 **Branch Context: feature/python-support**
+
+**Overview:**
+- Type: Feature branch
+- Created: 3 days ago from main
+- Status: 15 commits ahead of main
+- Purpose: Add comprehensive Python project support to Chiron
+
+**Current State:**
+- 📁 Files changed: 25 files (mostly new Python templates)
+- ✅ Tests: 41 examples, all passing
+- 📝 Documentation: README and CHANGELOG updated
+- 🚀 Status: Ready for merge
+
+**Work Completed:**
+- ✅ Python project detection (Django, FastAPI, Flask)
+- ✅ ProjectConfig class for language abstraction
+- ✅ Python workflow templates created
+- ✅ Comprehensive test coverage added
+
+**Context for Claude:**
+- PRD: Located at tasks/prd-python-support.md
+- Dependencies: None
+- Blockers: None
+- Next: Final review and merge to main
+
+**Recommended Actions:**
+1. Run final test suite
+2. Update version number for release
+3. Create pull request for review
+```
+
+## Command Variations
+
+### Quick Branch Info
+```bash
+# Just the essentials
+git branch --show-current && git status --short && git log --oneline -3
+```
+
+### Detailed Branch Analysis
+```bash
+# Comprehensive branch analysis
+git log --graph --oneline --all -10
+git diff --stat main...HEAD
+```
+
+### Branch Comparison
+```bash
+# Compare with main branch
+git log --left-right --graph --cherry-pick --oneline main...HEAD
+```
+
+## Integration with Other Commands
+
+### Use with Quickstart
+- Automatically called when starting work session
+- Provides branch context before task planning
+
+### Use with Catchup
+- Shows branch progress in relation to project goals
+- Identifies if branch work aligns with current priorities
+
+### Use before PRs
+- Ensures all branch work is documented
+- Confirms branch is ready for review
+
+## Tips for Effective Branch Tracking
+
+### Branch Naming
+- Use prefixes: `feature/`, `bugfix/`, `hotfix/`, `experiment/`
+- Include ticket numbers: `feature/PROJ-123-user-auth`
+- Be descriptive: `feature/python-project-support`
+
+### Commit Messages
+- Reference related issues or PRDs
+- Use conventional commits format
+- Include context for future sessions
+
+### Documentation
+- Update journal when creating branches
+- Link branches to PRDs or task lists
+- Note collaboration context
+
+### Session Continuity
+- Run this command at session start
+- Update when switching branches
+- Use before major commits or pushes
+
+## Automation Opportunities
+
+Consider adding git hooks to:
+- Auto-update journal on branch creation
+- Prompt for branch purpose on first commit
+- Remind about documentation updates
+- Check for related PRD files
+
+This command ensures Claude always has full context about your current branch and work progress, making sessions more productive and reducing ramp-up time.

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

@@ -22,7 +22,12 @@ Use this when the user asks "catchup", "where are we", or wants a project status
    git log --oneline -5
    ```
 
-4. **Test Status**
+4. **Get Branch Context**
+   - Run `/branch-context` command for detailed branch information
+   - Check branch purpose and progress
+   - Review commits unique to this branch
+
+5. **Test Status**
    ```bash
    bin/rspec --format progress | tail -5
    ```

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

@@ -15,16 +15,21 @@ Use this command to quickly get up to speed with the current project state.
    git branch --show-current
    ```
 
-3. **Review Recent Work**
+3. **Get Branch Context**
+   - Run `/branch-context` command if not on main branch
+   - Understand current branch purpose and progress
+   - Check for any uncommitted work or stashes
+
+4. **Review Recent Work**
    - READ: docs/development_journal.md (last 3 entries)
    - Check for active tasks in /tasks/ directory
 
-4. **Quick Test Status**
+5. **Quick Test Status**
    ```bash
    bin/rspec --fail-fast
    ```
 
-5. **Check Code Quality**
+6. **Check Code Quality**
    ```bash
    bin/rubocop --format simple | tail -20
    ```

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