docs: Add comprehensive hybrid workflow documentation

.github/HYBRID_WORKFLOW.md

@@ -0,0 +1,198 @@
+# Hybrid Workflow Guide
+
+This repository uses a hybrid workflow that balances automation with human oversight, optimized for Claude Code CLI development while maintaining best practices for collaborative work.
+
+## Overview
+
+The hybrid workflow uses two primary branches:
+- **`main`** - Protected, stable branch for production-ready code
+- **`dev`** - Active development branch with relaxed rules for rapid iteration
+
+## Key Principles
+
+1. **Incremental Development**: Small, focused commits and PRs
+2. **Automated Synchronization**: Nightly rebases keep branches in sync
+3. **Smart Automation**: Automate repetitive tasks, keep human oversight for critical decisions
+4. **Clear Conventions**: Consistent naming and process standards
+
+## Branch Strategy
+
+### Main Branch
+- **Purpose**: Stable, production-ready code
+- **Protection**: Strict (requires reviews, all checks passing)
+- **Merge Strategy**: Squash and merge
+- **Who can push**: Nobody directly (PR only)
+
+### Dev Branch
+- **Purpose**: Active development and integration
+- **Protection**: Relaxed (no reviews required, allows force push)
+- **Merge Strategy**: Regular merges or rebases
+- **Who can push**: Developers after PR merge
+
+### Feature Branches
+- **Naming**: `feat/`, `fix/`, `docs/`, `test/`, `chore/` prefixes
+- **Base**: Usually `dev`, occasionally `main` for hotfixes
+- **Lifecycle**: Create → Develop → PR → Merge → Delete
+
+## Workflows
+
+### 1. Starting New Work
+
+```bash
+# Use the claude-branch script for easy branch creation
+./scripts/claude-branch.sh my-new-feature
+
+# Or with a draft PR
+./scripts/claude-branch.sh my-new-feature --pr
+
+# For fixes targeting main
+./scripts/claude-branch.sh critical-fix --base main --pr
+```
+
+### 2. Development Process
+
+#### Commit Standards
+- Maximum 30 files per commit
+- Maximum 800 lines per commit
+- Use conventional commit format: `type(scope): description`
+- Commit frequently (approximately every 30 minutes of active work)
+
+#### Pushing Changes
+- Auto-push is enabled for single source of truth
+- Use `--force-with-lease` for safety when needed
+- Pre-commit hooks ensure standards compliance
+
+### 3. Pull Request Process
+
+#### To Dev Branch
+- No review required (but welcomed)
+- Small PRs (<200 lines) auto-merge when approved
+- Focus on rapid iteration
+- CI must pass
+
+#### To Main Branch
+- Requires 1 approval
+- All conversations must be resolved
+- Branch must be up-to-date
+- More thorough review expected
+
+### 4. Automated Processes
+
+#### Nightly Rebase (3 AM UTC)
+- Automatically rebases `dev` onto `main`
+- Creates PR for conflicts requiring manual resolution
+- Sends notifications on success/failure
+- Cleans up old rebase branches after 7 days
+
+#### PR Management
+- Auto-labels by size (XS to XL)
+- Adds target branch labels
+- Detects and warns about conflicts
+- Manages stale PRs (7-day warning, 14-day close)
+
+#### Commit Enforcement
+- Pre-commit hooks check size limits
+- CI validates commit standards
+- Protected files require PR review
+
+## Tools and Scripts
+
+### claude-branch.sh
+Creates properly formatted branches with optional draft PRs.
+
+```bash
+# Examples
+./scripts/claude-branch.sh add-search      # Creates feat/add-search
+./scripts/claude-branch.sh fix-bug --pr    # Creates fix/fix-bug with PR
+./scripts/claude-branch.sh docs-update     # Creates docs/docs-update
+```
+
+### apply-branch-protection.sh
+Applies the correct protection rules to main and dev branches.
+
+```bash
+# Dry run to see what would change
+./scripts/apply-branch-protection.sh --dry-run
+
+# Apply protection
+./scripts/apply-branch-protection.sh
+```
+
+## Best Practices
+
+### For Claude Code CLI Users
+1. Work primarily with `dev` as your base branch
+2. Use the `claude-branch.sh` script for consistency
+3. Commit frequently within size limits
+4. Let automation handle rebasing and synchronization
+
+### For Human Developers
+1. Review PRs to `main` carefully
+2. Use `dev` for experimental work
+3. Leverage automation for routine tasks
+4. Override automation when judgment is needed
+
+### Conflict Resolution
+When the nightly rebase encounters conflicts:
+1. A PR is automatically created with instructions
+2. Check out the rebase branch locally
+3. Resolve conflicts following the guide in the PR
+4. Push the resolved branch
+5. Merge the PR to update dev
+
+## Migration Guide
+
+For existing repositories adopting this workflow:
+
+1. **Create dev branch** (if doesn't exist):
+   ```bash
+   git checkout -b dev main
+   git push -u origin dev
+   ```
+
+2. **Apply branch protection**:
+   ```bash
+   ./scripts/apply-branch-protection.sh
+   ```
+
+3. **Update CI/CD** to recognize both branches
+
+4. **Configure team**:
+   - Set `dev` as default branch for new PRs
+   - Communicate new workflow to team
+   - Update documentation references
+
+## Troubleshooting
+
+### Common Issues
+
+**Commits rejected by pre-commit hook**
+- Check file count and line count
+- Split large changes into multiple commits
+- Use `SKIP_CLAUDE_RULES=true git commit` for exceptions (use sparingly)
+
+**Nightly rebase failing repeatedly**
+- Check for persistent conflicts
+- Consider manually rebasing during work hours
+- Review if dev has diverged too far from main
+
+**PR not auto-merging**
+- Verify it's under 200 lines
+- Ensure all checks are passing
+- Confirm it targets dev branch
+- Check for merge conflicts
+
+### Getting Help
+- Check workflow status in Actions tab
+- Review PR comments for automation feedback
+- See individual workflow files for detailed configuration
+
+## Philosophy
+
+This hybrid workflow recognizes that:
+- Automation should reduce toil, not replace judgment
+- Different branches serve different purposes
+- Both AI and human developers have unique strengths
+- Flexibility and structure must be balanced
+
+By following this workflow, we maintain high code quality while enabling rapid development and experimentation.