chiron 0.1.0

data/lib/chiron/templates/commands/journal/instructions.md

@@ -0,0 +1,129 @@
+# Journal Instructions for Claude Code
+
+This governs how Claude Code should maintain an ongoing development journal for tracking work progress and providing daily catchup summaries.
+
+## Journal Location and Structure
+
+**File**: `docs/development_journal.md`
+
+**Format**: Chronological entries with structured sections for easy scanning and context building.
+
+## When to Update the Journal
+
+Update the journal after completing significant work sessions, specifically:
+
+1. **Bug fixes** - Any bugs identified and resolved
+2. **Feature implementations** - New features or enhancements added
+3. **Refactoring** - Code improvements or architectural changes  
+4. **Infrastructure changes** - CI/CD, testing, or deployment modifications
+5. **Important decisions** - Technical choices, architecture decisions, or approach changes
+6. **Problem investigations** - Research into issues, even if not fully resolved
+
+## Journal Entry Structure
+
+Each entry should follow this format:
+
+```markdown
+## [Date] - [Brief Summary Title]
+**Developer(s)**: [Name/Handle] | **Context**: [How work was initiated]
+
+### What Was Done
+- Bullet point list of specific actions taken
+- Include file names and line numbers where applicable
+- Mention any tools, commands, or scripts used
+
+### Why It Was Done  
+- Context for the changes
+- Problem being solved
+- User request or issue being addressed
+
+### Technical Details
+- Key code changes made
+- Architectural decisions
+- Testing approach used
+- Any notable implementation details
+
+### Results
+- What works now that didn't before
+- Test results (passing/failing counts)
+- Performance improvements if applicable
+- Any remaining issues or follow-up needed
+
+### Next Steps (if applicable)
+- Related work that should be done
+- Known issues to address
+- Improvements to consider
+
+---
+```
+
+## Daily Catchup Format
+
+When the user asks for a "catchup" or "where are we":
+
+1. **Read the journal** to understand recent work
+2. **Summarize the last 3-5 entries** in a concise format
+3. **Highlight current state** of key features/systems
+4. **Identify any pending work** or unresolved issues
+5. **Suggest logical next steps** based on recent work patterns
+
+## Developer Attribution Guidelines
+
+**For Claude Code entries**:
+- Use "Claude Code (with [User])" format 
+- Include how work was initiated (user request, bug report, etc.)
+
+**For human developer entries**:
+- Use developer's preferred name/handle
+- Include context (pair programming, solo work, code review, etc.)
+
+**For collaborative work**:
+- List all contributors: "Jane Doe & Claude Code (with Brett)"
+- Note the nature of collaboration in context
+
+## Multi-Developer Collaboration Features
+
+### Developer Activity Summary
+Maintain a running summary at the top of the journal showing recent contributors:
+
+```markdown
+## Recent Contributors (Last 30 Days)
+- **[Developer Name]**: [Their focus areas]
+- **Claude Code**: [AI-assisted work areas]
+
+## Active Branches & Ownership
+- `branch-name`: [Developer(s) working on it]
+```
+
+### Conflict Prevention
+- **Before starting work**: Check recent journal entries for conflicts
+- **Branch coordination**: Note active branches and who's working on what
+- **Handoff documentation**: When passing work between developers, include detailed context
+
+## Important Guidelines
+
+1. **Be Specific**: Include file paths, line numbers, method names, and test results
+2. **Provide Context**: Explain why changes were needed, not just what was changed
+3. **Track Progress**: Show how issues evolve and get resolved over time
+4. **Include Failures**: Document what didn't work and why, for future reference
+5. **Link Related Work**: Connect entries that build on each other
+6. **Keep It Scannable**: Use clear headings and bullet points for quick reading
+
+## Journal Maintenance
+
+- **Update frequency**: After each significant work session
+- **Entry length**: Aim for 100-300 words per entry
+- **File size**: If journal exceeds 10,000 lines, create monthly archives
+- **Cross-references**: Link to related PRs, issues, or documentation
+
+## Automation Triggers
+
+Consider updating the journal when:
+- Completing tasks from a task list
+- Test suite goes from failing to passing
+- Major refactoring (>100 lines changed)
+- Before switching branches
+- After resolving complex bugs
+- When implementing new features
+
+This journal serves as both a development log and a knowledge base for understanding the project's evolution and current state.

data/lib/chiron/templates/commands/journal/template.md

@@ -0,0 +1,87 @@
+# Journal Entry Template
+
+Copy this template when manually adding entries to `docs/development_journal.md`:
+
+```markdown
+## [YYYY-MM-DD] - [Brief Summary Title]
+**Developer(s)**: [Your Name] | **Context**: [How this work was initiated]
+
+### What Was Done
+- [Specific action taken]
+- [Include file paths: `app/controllers/example_controller.rb:25`]
+- [Commands run: `bin/rspec`, `bin/rubocop --autocorrect`]
+- [Tools used: Claude Code, VS Code, etc.]
+
+### Why It Was Done  
+- [Problem being solved]
+- [User request or business need]
+- [Technical debt being addressed]
+- [Bug report or issue being fixed]
+
+### Technical Details
+- [Key code changes made]
+- [Architecture decisions]
+- [Libraries or frameworks used]
+- [Database changes if applicable]
+- [Testing approach]
+
+### Results
+- [What works now that didn't before]
+- [Test results: X examples, Y failures]
+- [Performance improvements if applicable]
+- [Screenshots or demos if relevant]
+
+### Next Steps (if applicable)
+- [Related work that should be done]
+- [Known issues to address]
+- [Improvements to consider]
+- [Dependencies for other developers]
+
+---
+```
+
+## Quick Examples for Common Scenarios
+
+**Bug Fix:**
+```markdown
+**Developer(s)**: Jane Doe | **Context**: User reported login failure in Issue #42
+```
+
+**Feature Development:**
+```markdown
+**Developer(s)**: John Smith | **Context**: Implementing payment workflow from prd-payment-system.md
+```
+
+**Pair Programming:**
+```markdown
+**Developer(s)**: Alice & Bob | **Context**: Pair programming session on OAuth integration
+```
+
+**Code Review Follow-up:**
+```markdown
+**Developer(s)**: Charlie | **Context**: Addressing PR #35 review comments from Brett
+```
+
+**Collaborative AI Work:**
+```markdown
+**Developer(s)**: Dana & Claude Code | **Context**: Investigating performance issues with AI assistance
+```
+
+## Tips for Good Journal Entries
+
+1. **Be specific about files changed** - include paths and line numbers when relevant
+2. **Include test results** - show the impact of your changes
+3. **Explain the "why"** - context helps other developers understand decisions
+4. **Link to related work** - mention PRs, issues, or previous journal entries
+5. **Note blocking issues** - help other developers avoid conflicts
+6. **Update the contributor summary** - keep the top section current
+7. **Time tracking** - Consider adding time spent for future estimates
+
+## Commit Message Integration
+
+When making commits related to journal entries, reference them:
+```bash
+git commit -m "Fix authentication timeout issue
+
+See development journal entry 2025-06-21 for details"
+```

data/lib/chiron/templates/commands/quality/pre-commit.md

@@ -0,0 +1,95 @@
+# Pre-Commit Checklist
+
+Run these commands in sequence before committing code changes.
+
+## Required Steps
+
+### 1. Code Quality
+```bash
+bin/rubocop --autocorrect
+```
+- Fix all auto-correctable violations
+- Review remaining violations
+- Document any acceptable violations
+
+### 2. Test Suite
+```bash
+bin/rspec
+```
+- Ensure all tests pass
+- If tests fail, fix them before proceeding
+- Add new tests for new functionality
+
+### 3. Security Check
+```bash
+bin/brakeman
+```
+- Review any security warnings
+- Address critical issues immediately
+- Document false positives
+
+### 4. Review Changes
+```bash
+git diff --cached
+```
+- Verify all changes are intentional
+- Check for debugging code
+- Ensure no sensitive data is included
+
+### 5. Update Documentation
+- Update CLAUDE.md if workflow changes
+- Add/update code comments if complex logic
+- Update README if user-facing changes
+
+### 6. Development Journal
+For significant work:
+- Add entry to docs/development_journal.md
+- Include what, why, and results
+- Note any follow-up tasks
+
+## Quick Command
+```bash
+# Run all checks at once
+bin/rubocop --autocorrect && bin/rspec && bin/brakeman && git diff --cached
+```
+
+## Commit Message Format
+```
+type: Brief description (max 50 chars)
+
+Longer explanation if needed. Wrap at 72 characters.
+Explain what and why, not how.
+
+- Bullet points for multiple changes
+- Reference issue numbers: Fixes #123
+- Reference PRD if applicable: Implements prd-feature-name
+
+Co-authored-by: Name <email> (if pair programming)
+```
+
+### Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, missing semicolons, etc)
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests
+- `chore`: Changes to build process or auxiliary tools
+
+## Warning Signs to Check
+
+Before committing, ensure you haven't:
+- Left debugging statements (puts, console.log, binding.pry)
+- Included commented-out code without explanation
+- Added TODO comments without creating issues
+- Modified tests just to make them pass
+- Included hardcoded values that should be configurable
+- Forgotten to add new files to git
+
+## Final Verification
+```bash
+git status
+```
+- All intended files are staged
+- No untracked files forgotten
+- Working directory is clean (or intentionally not)

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

@@ -0,0 +1,187 @@
+# Test-Driven Development (TDD) Workflow
+
+## Core Principles
+
+1. **Red**: Write a failing test first
+2. **Green**: Write minimal code to make the test pass
+3. **Refactor**: Improve the code while keeping tests green
+
+## TDD Process
+
+### Step 1: Write a Failing Test
+```ruby
+# spec/models/user_spec.rb
+it 'returns the full name' do
+  user = User.new(first_name: 'John', last_name: 'Doe')
+  expect(user.full_name).to eq('John Doe')
+end
+```
+
+### Step 2: Run Test (See it Fail)
+```bash
+bin/rspec spec/models/user_spec.rb
+# Expected failure: undefined method `full_name'
+```
+
+### Step 3: Write Minimal Code
+```ruby
+# app/models/user.rb
+def full_name
+  "#{first_name} #{last_name}"
+end
+```
+
+### Step 4: Run Test (See it Pass)
+```bash
+bin/rspec spec/models/user_spec.rb
+# All tests should pass
+```
+
+### Step 5: Refactor if Needed
+```ruby
+# Improved version
+def full_name
+  [first_name, last_name].compact.join(' ')
+end
+```
+
+## Rules
+
+### Write One Test at a Time
+- Write test
+- See it fail
+- Make it pass
+- Refactor
+- Repeat
+
+### Only Write Code to Pass Current Test
+- Don't add functionality not required by current test
+- Don't anticipate future needs
+- Keep it simple
+
+### Committing Rules
+- Only commit when all tests pass
+- Never commit with failing tests
+- Include all changed files in commit
+
+### Test Integrity
+- 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
+
+## Test Plan Management
+
+### Create Test Plan First
+```markdown
+## User Model Test Plan
+- [ ] validates presence of email
+- [ ] validates uniqueness of email
+- [ ] validates email format
+- [ ] returns full name
+- [ ] returns initials
+- [ ] has many posts
+- [ ] scopes for active users
+```
+
+### Track Progress
+- Check off completed tests
+- Add new tests as discovered
+- Keep plan updated
+
+## Common Patterns
+
+### Model Testing
+```ruby
+describe User do
+  describe 'validations' do
+    it { should validate_presence_of(:email) }
+  end
+  
+  describe '#full_name' do
+    it 'returns concatenated name' do
+      # test here
+    end
+  end
+end
+```
+
+### Controller Testing
+```ruby
+describe UsersController do
+  describe 'GET #index' do
+    before { get :index }
+    
+    it 'returns success' do
+      expect(response).to be_successful
+    end
+  end
+end
+```
+
+### System Testing
+```ruby
+describe 'User registration' do
+  it 'allows new users to sign up' do
+    visit new_user_registration_path
+    fill_in 'Email', with: 'test@example.com'
+    # ... more steps
+    expect(page).to have_content('Welcome!')
+  end
+end
+```
+
+## Best Practices
+
+### Good Tests Are:
+- **Fast**: Run quickly
+- **Independent**: Don't depend on other tests
+- **Repeatable**: Same result every time
+- **Self-Validating**: Clear pass/fail
+- **Timely**: Written before code
+
+### Test Naming
+```ruby
+# Bad
+it 'works' do
+it 'test user' do
+
+# Good
+it 'returns full name when both names present' do
+it 'returns only first name when last name is nil' do
+```
+
+### Edge Cases
+Always test:
+- Nil values
+- Empty strings
+- Boundary conditions
+- Invalid input
+- Error conditions
+
+## Useful Commands
+
+```bash
+# Run specific test file
+bin/rspec spec/models/user_spec.rb
+
+# Run specific line
+bin/rspec spec/models/user_spec.rb:42
+
+# Run with documentation format
+bin/rspec --format documentation
+
+# Run only failing tests
+bin/rspec --only-failures
+
+# Run tests matching pattern
+bin/rspec --example "full name"
+```
+
+## When to Break TDD Rules
+
+Acceptable exceptions:
+- Exploring new libraries/APIs
+- Spike solutions (throw away after)
+- UI styling (but test behavior)
+
+Always return to TDD after exploration!

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

@@ -0,0 +1,57 @@
+# Creating a Product Requirements Document (PRD)
+
+## Goal
+
+To create a detailed Product Requirements Document (PRD) in Markdown format based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.
+
+## 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.
+
+## Clarifying Questions (Examples)
+
+Adapt your questions based on the prompt, but here are common areas to explore:
+
+* **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?"
+* **Target User:** "Who is the primary user of this feature?"
+* **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?"
+* **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)"
+* **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?"
+* **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?"
+* **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
+* **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?"
+* **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?"
+
+## PRD Structure
+
+The generated PRD should include the following sections:
+
+1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
+2. **Goals:** List the specific, measurable objectives for this feature.
+3. **User Stories:** Detail the user narratives describing feature usage and benefits.
+4. **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements.
+5. **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
+6. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable.
+7. **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module").
+8. **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X").
+9. **Open Questions:** List any remaining questions or areas needing further clarification.
+
+## Target Audience
+
+Assume the primary reader of the PRD is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.
+
+## Output
+
+* **Format:** Markdown (`.md`)
+* **Location:** `/tasks/`
+* **Filename:** `prd-[feature-name].md`
+
+## Important Reminders
+
+1. Do NOT start implementing the PRD
+2. Always ask the user clarifying questions
+3. Take the user's answers to the clarifying questions and improve the PRD
+4. Update the development journal when creating significant PRDs

data/lib/chiron/templates/commands/workflows/feature-complete.md

@@ -0,0 +1,139 @@
+# Feature Completion Checklist
+
+Use this checklist when you believe a feature is complete to ensure nothing is missed.
+
+## Pre-Completion Review
+
+### 1. Task Verification
+- [ ] All tasks from `tasks-*.md` are marked complete
+- [ ] No blocked tasks remain unresolved
+- [ ] All subtasks have been implemented
+
+### 2. Code Quality
+- [ ] All tests are passing (`bin/rspec`)
+- [ ] RuboCop violations addressed (`bin/rubocop`)
+- [ ] No commented-out code without explanation
+- [ ] No debugging statements left in code
+
+### 3. Test Coverage
+- [ ] Unit tests for all models
+- [ ] Request specs for all controllers
+- [ ] System tests for user workflows
+- [ ] Edge cases tested
+- [ ] Error conditions handled
+
+### 4. Documentation
+- [ ] Code comments for complex logic
+- [ ] README updated if needed
+- [ ] API documentation if applicable
+- [ ] CLAUDE.md updated for workflow changes
+
+### 5. Performance
+- [ ] Database queries optimized (no N+1)
+- [ ] Appropriate indexes added
+- [ ] Caching implemented where beneficial
+- [ ] Background jobs for slow operations
+
+### 6. Security
+- [ ] Authorization checks in place
+- [ ] Strong parameters used
+- [ ] No sensitive data exposed
+- [ ] Security scan passed (`bin/brakeman`)
+
+## Feature-Specific Checks
+
+### Frontend Features
+- [ ] Responsive design verified
+- [ ] Accessibility requirements met
+- [ ] Cross-browser testing done
+- [ ] Loading states implemented
+- [ ] Error states handled gracefully
+
+### API Features
+- [ ] Versioning implemented
+- [ ] Rate limiting considered
+- [ ] Documentation generated
+- [ ] Integration tests written
+- [ ] Error responses standardized
+
+### Background Jobs
+- [ ] Idempotency ensured
+- [ ] Retry logic implemented
+- [ ] Failure notifications set up
+- [ ] Performance monitored
+- [ ] Dead letter queue configured
+
+## Final Steps
+
+### 1. Development Journal
+Add comprehensive entry including:
+- Summary of implementation
+- Key decisions made
+- Challenges overcome
+- Performance metrics
+- Lessons learned
+
+### 2. Pull Request
+Create PR with:
+- Reference to original PRD
+- Summary of changes
+- Screenshots/demos if UI changes
+- Testing instructions
+- Deployment notes
+
+### 3. Knowledge Transfer
+- [ ] Document any gotchas
+- [ ] Update team wiki if needed
+- [ ] Schedule demo if significant feature
+- [ ] Plan monitoring strategy
+
+## Post-Completion
+
+### Monitoring Plan
+- Key metrics to track
+- Error rate thresholds
+- Performance benchmarks
+- User feedback channels
+
+### Follow-up Tasks
+- Performance optimization opportunities
+- Additional features to consider
+- Technical debt to address
+- Documentation improvements
+
+## Success Criteria Verification
+
+Review the original PRD and verify:
+- All functional requirements implemented
+- Success metrics achievable
+- Acceptance criteria met
+- Non-goals respected
+
+## Sign-off Template
+
+```markdown
+## Feature Complete: [Feature Name]
+
+**PRD Reference**: prd-[feature-name].md
+**Tasks Reference**: tasks-prd-[feature-name].md
+
+### Verification
+- ✅ All tasks completed
+- ✅ Tests passing: [X examples, 0 failures]
+- ✅ Code quality verified
+- ✅ Documentation updated
+- ✅ Security review passed
+
+### Metrics
+- Test coverage: X%
+- Performance: Xms average response
+- Code changes: +X -Y lines
+
+### Notes
+[Any important notes for deployment or future work]
+
+**Developer**: [Name]
+**Date**: [YYYY-MM-DD]
+```
+
+Remember: "Done" means deployed, documented, and monitored!