chiron 0.2.0 → 0.2.2

data/lib/chiron/templates/shared/commands/workflows/branch-management.md

@@ -0,0 +1,256 @@
+# Branch Management Workflow
+
+Comprehensive workflow for creating, switching, and managing Git branches in Claude Code sessions.
+
+## Creating New Branches
+
+### 1. **Pre-Branch Planning**
+Before creating a branch, ensure:
+- [ ] Clear understanding of the feature/fix purpose
+- [ ] Related PRD exists (if for new feature)
+- [ ] No existing branch covers the same work
+- [ ] Clean working directory on current branch
+
+### 2. **Branch Creation Process**
+```bash
+# Ensure you're on the base branch (usually main)
+git checkout main
+git pull origin main
+
+# Create and switch to new branch
+git checkout -b [type]/[descriptive-name]
+
+# Examples:
+git checkout -b feature/user-authentication
+git checkout -b bugfix/login-validation
+git checkout -b hotfix/security-patch
+git checkout -b experiment/new-ui-approach
+```
+
+### 3. **Branch Documentation**
+Immediately after creating a branch:
+
+#### Update Development Journal
+Add to the "Active Branches & Ownership" section:
+```markdown
+- `feature/user-authentication`: [Your Name] - Implement user login/signup system - [Created 2025-07-01]
+  - **PRD**: tasks/prd-user-authentication.md
+  - **Dependencies**: None
+  - **Timeline**: 1 week
+```
+
+#### Create Initial Commit
+```bash
+# Create a planning commit to establish branch purpose
+git commit --allow-empty -m "Start feature/user-authentication
+
+Initial branch creation for implementing user authentication system.
+
+Related PRD: tasks/prd-user-authentication.md
+Estimated timeline: 1 week
+Dependencies: None"
+```
+
+## Branch Switching Workflow
+
+### 1. **Before Switching Away**
+```bash
+# Save current work
+git add .
+git commit -m "WIP: [describe current state]" 
+# OR
+git stash push -m "Work in progress: [description]"
+
+# Update journal with progress
+# Run catchup command to document current state
+```
+
+### 2. **Switching to Different Branch**
+```bash
+# Switch to target branch
+git checkout [target-branch]
+
+# Get branch context (use branch-context command)
+# Update Claude with current branch state
+```
+
+### 3. **After Switching**
+- [ ] Run `/branch-context` command to orient Claude
+- [ ] Review recent commits and current state
+- [ ] Check for any merge conflicts or issues
+- [ ] Resume work from where you left off
+
+## Branch Maintenance
+
+### 1. **Regular Synchronization**
+```bash
+# Keep feature branch updated with main
+git checkout main
+git pull origin main
+git checkout [your-branch]
+git merge main
+# OR for cleaner history:
+git rebase main
+```
+
+### 2. **Progress Tracking**
+Update development journal regularly:
+- When completing major milestones
+- When encountering significant challenges
+- When changing approach or design
+- Before long breaks in development
+
+### 3. **Pre-Merge Checklist**
+Before merging or creating PR:
+- [ ] All tests passing
+- [ ] Code quality checks pass
+- [ ] Documentation updated
+- [ ] Journal entry completed
+- [ ] Branch purpose fully achieved
+- [ ] No debug code or temporary changes
+
+## Claude Session Continuity
+
+### Starting New Session
+When beginning a Claude session:
+1. Run `/quickstart` command
+2. Run `/branch-context` command
+3. Review recent journal entries
+4. Check current task status
+
+### During Development
+- Use `/catchup` to summarize progress
+- Update journal for significant changes
+- Create meaningful commit messages
+- Reference related PRDs or issues
+
+### Ending Session
+Before ending a Claude session:
+1. Commit or stash current work
+2. Update journal with progress
+3. Note any blockers or next steps
+4. Create TODO items if applicable
+
+## Branch Types and Naming
+
+### Feature Branches
+```bash
+feature/[short-description]
+feature/user-authentication
+feature/payment-integration
+feature/admin-dashboard
+```
+- For new functionality
+- Usually based on PRDs
+- Timeline: days to weeks
+
+### Bugfix Branches
+```bash
+bugfix/[issue-description]
+bugfix/login-validation
+bugfix/email-formatting
+bugfix/mobile-layout
+```
+- For fixing existing functionality
+- Should include issue reproduction
+- Timeline: hours to days
+
+### Hotfix Branches
+```bash
+hotfix/[urgent-issue]
+hotfix/security-patch
+hotfix/production-error
+hotfix/data-corruption
+```
+- For urgent production fixes
+- Fast-tracked through review
+- Timeline: hours
+
+### Experiment Branches
+```bash
+experiment/[exploration-area]
+experiment/new-ui-framework
+experiment/performance-optimization
+experiment/alternative-approach
+```
+- For trying new approaches
+- May not be merged
+- Timeline: varies
+
+## Collaboration Patterns
+
+### Multiple Developers
+- Update journal with developer assignments
+- Use PR descriptions to communicate context
+- Reference branch dependencies clearly
+- Coordinate merge timing
+
+### Code Reviews
+- Include branch context in PR description
+- Reference related journal entries
+- Explain design decisions made during development
+- Link to relevant PRD sections
+
+### Handoffs
+When transferring work to another developer:
+1. Complete journal entry for current state
+2. Commit all work with clear messages
+3. Document any known issues or blockers
+4. Update branch ownership in journal
+
+## Troubleshooting Common Issues
+
+### Lost Context
+If Claude loses branch context:
+1. Run `/branch-context` command
+2. Review recent commits: `git log --oneline -10`
+3. Check journal for recent entries
+4. Summarize current work state
+
+### Merge Conflicts
+```bash
+# Resolve conflicts step by step
+git status                    # See conflicted files
+git diff                      # Review conflicts
+# Edit files to resolve conflicts
+git add [resolved-files]
+git commit -m "Resolve merge conflicts"
+```
+
+### Stale Branches
+For branches behind main:
+```bash
+git checkout [your-branch]
+git fetch origin
+git merge origin/main
+# OR for cleaner history:
+git rebase origin/main
+```
+
+## Best Practices Summary
+
+### Branch Creation
+- Always create from updated main/develop
+- Use descriptive, consistent naming
+- Document purpose immediately
+- Create empty initial commit with context
+
+### Development
+- Commit frequently with meaningful messages
+- Update journal for significant progress
+- Keep branches focused on single purpose
+- Sync with main regularly
+
+### Claude Integration
+- Use context commands at session start
+- Maintain journal throughout development
+- Reference branch work in commits
+- Document decisions and rationale
+
+### Cleanup
+- Delete merged branches promptly
+- Archive experiment branches with notes
+- Update journal when closing branches
+- Remove stale branch references
+
+This workflow ensures branch work is well-documented, trackable across Claude sessions, and maintains clear development history.

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