chiron 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee3cb5e4893ff687265d9e2d8d2fc75de956dd3abeca8b330e7f7c5f5d6c437a
-  data.tar.gz: 0d53f562161301fa0093939a2eee2a3fa64c5f2a5a2c9f2802ecd31be12038f9
+  metadata.gz: b7dd7f387038865024e9723f8f4b7c6c631c04e2762085781c27b4cf86681c0e
+  data.tar.gz: 366fa17b95df84fcf300712f5ae9c1f377c9b02afbc9426dbd9784e9717b10f7
 SHA512:
-  metadata.gz: '0183d1aa5e2fe30cd565e96ab8680b8cdb8c29066391942c641f2038c3ce0394f6ae6fd03c008ce211fc599b7e3773a429b48fb70115eaa268dd5b5942e27ae4'
-  data.tar.gz: d7a016612648121ed2c031a0180c76637684285bc448f179d81850c8f85800a98964d346363e89d49d41c232d2c4a90f1178ff4606404478b85f06e99e60dafc
+  metadata.gz: 493cdba917d7250cf066ccae6d6ac3838581c3535aba36e28dc6e59aa5670ef125b8719122db4983795777e04ff4ad8cc74d762f6e558a5ff99cd20f06110a7f
+  data.tar.gz: 7f8125670a0dbaa4914bc81e8df9322c7447d50c24466681413addaeaef9d3fe9e120ff9d42e468b5a873b344bb54d9ca6a46c26888ef76c1af2f9d482b13238

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2025-07-01
+
+### Added
+
+#### Branch Tracking for Claude Sessions
+- **`/branch-context` Command**: Comprehensive branch information for Claude session continuity
+- **Branch Management Workflow**: Complete procedures for creating, switching, and managing Git branches
+- **Enhanced Context Commands**: Updated `/quickstart` and `/catchup` with branch awareness
+- **Development Journal Integration**: Branch tracking sections and guidelines for documentation
+- **Session Continuity**: Workflows for maintaining context across Claude sessions and branch switches
+
+#### New Workflow Templates
+- **Branch Context** (`shared/commands/context/branch-context.md`): Detailed branch information and progress tracking
+- **Branch Management** (`shared/commands/workflows/branch-management.md`): Complete branch lifecycle management
+
+#### Enhanced Documentation
+- **CLAUDE.md**: Added branch management section with naming conventions and session continuity guidelines
+- **Development Journal Template**: Enhanced with branch tracking fields and ownership documentation
+- **Context Commands**: Integrated branch awareness into existing workflow commands
+
+### Enhanced
+
+#### Session Management
+- **Context Continuity**: Improved Claude session startup with branch context
+- **Progress Tracking**: Better documentation of branch work and ownership
+- **Collaboration**: Enhanced handoff procedures and shared understanding patterns
+
 ## [0.2.0] - 2025-07-01
 
 ### Added

data/CLAUDE.md

@@ -98,11 +98,40 @@ lib/
 - Test CLI commands with temporary directories
 - Follow RSpec best practices
 
+## Branch Management and Claude Sessions
+
+### Branch Naming Conventions
+- `feature/[description]` - New functionality (e.g., `feature/python-support`)
+- `bugfix/[description]` - Bug fixes (e.g., `bugfix/template-loading`)
+- `hotfix/[description]` - Urgent production fixes
+- `experiment/[description]` - Exploratory work
+
+### Claude Session Continuity
+- **Starting Sessions**: Always run `/quickstart` to get current context
+- **Branch Work**: Use `/branch-context` when working on feature branches
+- **Progress Tracking**: Update development journal for significant changes
+- **Branch Switching**: Document current state before switching branches
+
+### Development Journal Usage
+- Include branch name in all journal entries
+- Update "Active Branches & Ownership" section when creating/merging branches
+- Link journal entries to related PRD files
+- Document architectural decisions and reasoning
+
+### Branch Workflow
+1. Create branch from updated main: `git checkout -b feature/description`
+2. Document branch purpose in development journal
+3. Make initial empty commit with context
+4. Develop with frequent commits and journal updates
+5. Use `/catchup` and `/branch-context` for status updates
+6. Complete pre-commit checklist before merging
+
 ## Important Reminders
 
 - Always run tests before committing
-- Use semantic commit messages
+- Use semantic commit messages with branch context
 - Update the development journal for significant changes
 - Follow the pre-commit checklist in `.claude/commands/quality/pre-commit.md`
+- Use branch management workflows for feature development
 - Update CHANGELOG.md for notable changes
 - Test gem building and installation locally before releasing

data/Gemfile.lock

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

data/docs/development_journal.md

@@ -1,11 +1,129 @@
 # Development Journal - Chiron Gem
 
 ## Project Overview
-Chiron is a Ruby gem that helps Rails developers set up Claude AI workflows, PRD templates, and development journaling systems.
+Chiron is a Ruby gem that helps Rails and Python developers set up Claude AI workflows, PRD templates, and development journaling systems.
+
+---
+
+## 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
+
+### What was accomplished today:
+- **Major Feature Release**: Added complete Python project support to Chiron gem
+- **Framework Detection**: Implemented auto-detection for Django, FastAPI, Flask, and generic Python projects
+- **Architecture Overhaul**: Created `ProjectConfig` class for language-agnostic tool management
+- **Template Reorganization**: Restructured templates into `rails/`, `python/`, and `shared/` directories
+- **Comprehensive Testing**: Expanded test suite from 5 to 41 tests with full Python coverage
+- **Documentation Update**: Enhanced README, CHANGELOG, and CLI help with Python examples
+- **RubyGems Publication**: Successfully published version 0.2.0 to RubyGems
+
+### Technical decisions made:
+- **Multi-Language Architecture**: Designed extensible system supporting both Rails and Python
+- **Project Detection**: Auto-detects project type via `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`
+- **Framework Intelligence**: Identifies Django (`manage.py`), FastAPI/Flask (via requirements analysis)
+- **Template Strategy**: Shared workflows with language-specific conventions and patterns
+- **Backward Compatibility**: Maintained 100% compatibility with existing Rails functionality
+- **Configuration Management**: `ProjectConfig` class abstracts tool selection (pytest vs RSpec, black vs RuboCop)
+
+### Features added:
+- **Python CLI Options**: `--type=python`, `--with-django`, `--with-fastapi` flags
+- **Smart Project Detection**: Interactive prompts for unknown project types
+- **Python Workflow Templates**:
+  - Python Conventions (PEP 8, type hints, async patterns, framework best practices)
+  - Python Testing (pytest patterns, fixtures, mocking, async testing, CI/CD)
+  - Python Debugging (pdb workflows, logging strategies, performance profiling)
+  - Python Refactoring (SOLID principles, design patterns, code organization)
+  - Flask Development (blueprints, forms, testing, deployment patterns)
+- **Framework-Specific Content**: Dynamic CLAUDE.md templates based on detected frameworks
+- **Project-Specific Tips**: Contextual setup guidance after initialization
+
+### Code quality metrics:
+- **RSpec**: 41 examples, 0 failures (8x increase in test coverage)
+- **New Test Categories**: Framework detection, ProjectConfig functionality, Python workflows
+- **RuboCop**: 29 minor offenses (mostly method length in CLI - acceptable for feature-rich CLI)
+- **Backward Compatibility**: All existing Rails tests continue to pass
+
+### Architecture improvements:
+- **Template Structure**: 
+  ```
+  lib/chiron/templates/
+  ├── rails/           # Rails-specific templates
+  ├── python/          # Python-specific templates  
+  └── shared/          # Language-agnostic workflows
+  ```
+- **Language Detection**: Robust project type identification with fallback mechanisms
+- **Tool Configuration**: Abstracted command generation for testing, linting, formatting
+- **ERB Enhancement**: Framework-aware template rendering with conditional content
+
+### Bugs fixed:
+- **Template Fallbacks**: Graceful handling when project-specific templates don't exist
+- **CLI Robustness**: Improved error handling for unknown project types
+- **Cross-Platform**: Ensured Python detection works across different package managers
+
+### Version and release:
+- **Version Bump**: 0.1.0 → 0.2.0 (major feature enhancement)
+- **Gem Build**: Successfully built `chiron-0.2.0.gem`
+- **RubyGems**: Published to RubyGems registry
+- **Documentation**: Comprehensive CHANGELOG with technical details
+
+### Impact and usage:
+- **Multi-Language Support**: Chiron now serves both Rails and Python ecosystems
+- **Framework Coverage**: Django, FastAPI, Flask, and generic Python projects supported
+- **Developer Experience**: Auto-detection eliminates manual configuration
+- **Workflow Richness**: Language-specific best practices and patterns included
+
+### Next steps:
+- Monitor RubyGems adoption and user feedback
+- Consider additional language support (Node.js, Go, etc.)
+- Enhance framework detection with more sophisticated analysis
+- Add more Python-specific workflow templates based on community needs
+- Create video documentation showing Python project initialization
+
+### Notes:
+- This represents the largest enhancement to Chiron since its creation
+- Successfully maintained backward compatibility while adding major new functionality
+- Python support is comprehensive and production-ready
+- Architecture now supports easy addition of future languages
 
 ---
 
 ## 2025-01-21 - Initial Setup and Module Rename
+**Developer(s)**: Claude Code | **Branch**: main | **Context**: Initial gem development
 
 ### What was accomplished today:
 - Set up complete gem development infrastructure

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