@hivehub/rulebook 1.2.0

package/templates/git/GIT_WORKFLOW.md

@@ -0,0 +1,1157 @@
+<!-- GIT:START -->
+# Git Workflow Rules
+
+**CRITICAL**: Specific rules and patterns for Git version control workflow.
+
+## Git Workflow Overview
+
+This project follows a strict Git workflow to ensure code quality and proper version control.
+
+**NEVER commit code without tests passing. NEVER create tags without full quality checks.**
+
+## Initial Repository Setup
+
+### New Project Initialization
+
+**⚠️ CRITICAL**: Only run initialization commands if `.git` directory does NOT exist!
+
+```bash
+# Check if Git repository already exists
+if [ -d .git ]; then
+  echo "❌ Git repository already initialized. Skipping git init."
+  echo "Current status:"
+  git status
+  git remote -v
+  exit 0
+fi
+
+# If no .git directory exists, initialize:
+
+# Initialize Git repository
+git init
+
+# Add all files
+git add .
+
+# Initial commit
+git commit -m "chore: Initial project setup"
+
+# Rename default branch to main (GitHub standard)
+git branch -M main
+
+# Add remote (if applicable)
+git remote add origin <repository-url>
+```
+
+**AI Assistant Behavior:**
+
+```
+BEFORE running any Git initialization commands:
+
+1. Check if .git directory exists
+2. If exists:
+   ✅ Repository already configured
+   ❌ DO NOT run: git init
+   ❌ DO NOT run: git branch -M main
+   ✅ Check status: git status
+   ✅ Show remotes: git remote -v
+   
+3. If not exists:
+   ✅ Safe to initialize
+   ✅ Run full initialization sequence
+```
+
+## AI Assistant Git Checks
+
+**CRITICAL**: AI assistants MUST perform these checks before Git operations:
+
+### Automatic Checks
+
+```bash
+# 1. Check if Git repository exists
+if [ ! -d .git ]; then
+  echo "No Git repository found."
+  # Ask user if they want to initialize
+fi
+
+# 2. Check if there are unstaged changes
+git status --short
+
+# 3. Check current branch
+CURRENT_BRANCH=$(git branch --show-current)
+echo "On branch: $CURRENT_BRANCH"
+
+# 4. Check if remote exists
+git remote -v
+
+# 5. Check for unpushed commits
+git log origin/main..HEAD --oneline 2>/dev/null
+```
+
+### Before Git Commands
+
+**NEVER execute if `.git` directory exists:**
+- ❌ `git init` - Repository already initialized
+- ❌ `git branch -M main` - Branch may already be configured
+- ❌ `git remote add origin` - Remote may already exist (check first with `git remote -v`)
+- ❌ `git config user.name/email` - User configuration is personal
+- ❌ Reconfiguration commands - Repository is already set up
+
+**ALWAYS safe to execute:**
+- ✅ `git status` - Check repository state
+- ✅ `git add` - Stage changes
+- ✅ `git commit` - Create commits (after quality checks)
+- ✅ `git log` - View history
+- ✅ `git diff` - View changes
+- ✅ `git branch` - List branches
+- ✅ `git tag` - Create tags (after quality checks)
+
+**Execute with caution (check first):**
+- ⚠️ `git push` - Follow push mode configuration
+- ⚠️ `git pull` - May cause merge conflicts
+- ⚠️ `git merge` - May cause conflicts
+- ⚠️ `git rebase` - Can rewrite history
+- ⚠️ `git reset --hard` - Destructive, only for rollback
+- ⚠️ `git push --force` - NEVER on main/master
+
+### Repository Detection
+
+**AI Assistant MUST check:**
+
+```bash
+# Before ANY Git operation:
+
+# 1. Does .git exist?
+if [ -d .git ]; then
+  echo "✅ Git repository exists"
+  
+  # 2. Check current state
+  git status
+  
+  # 3. Check branch
+  BRANCH=$(git branch --show-current)
+  echo "On branch: $BRANCH"
+  
+  # 4. Check remote
+  REMOTE=$(git remote -v)
+  if [ -z "$REMOTE" ]; then
+    echo "⚠️  No remote configured"
+  else
+    echo "Remote: $REMOTE"
+  fi
+  
+  # 5. Proceed with normal Git operations
+else
+  echo "⚠️  No Git repository found"
+  echo "Ask user if they want to initialize Git"
+fi
+```
+
+## Daily Development Workflow
+
+### 1. Before Making Changes
+
+**CRITICAL**: Always check current state:
+
+```bash
+# Check current branch and status
+git status
+
+# Ensure you're on the correct branch
+git branch
+
+# Pull latest changes if working with team (use --ff-only for safety)
+git pull --ff-only origin main
+```
+
+**Git Safety**: Use `--ff-only` to prevent unexpected merge commits and maintain linear history.
+
+### 2. Making Changes
+
+**CRITICAL**: Commit after every important implementation:
+
+**⚠️ IMPORTANT: All commit messages MUST be in English**
+
+```bash
+# After implementing a feature/fix:
+
+# 1. Run ALL quality checks FIRST
+npm run lint           # or equivalent for your language
+npm run type-check     # TypeScript/typed languages
+npm test              # ALL tests must pass
+npm run build         # Ensure build succeeds
+
+# 2. If ALL checks pass, stage changes
+git add .
+
+# 3. Commit with conventional commit message (ENGLISH ONLY)
+git commit -m "feat: Add user authentication
+
+- Implement login/logout functionality
+- Add JWT token management
+- Include comprehensive tests (95%+ coverage)
+- Update documentation"
+
+# Alternative for smaller changes (ENGLISH ONLY):
+git commit -m "fix: Correct validation logic in user form"
+
+# For signed commits (recommended for production):
+git commit -S -m "feat: Add feature"
+
+# ❌ NEVER use other languages:
+# ❌ git commit -m "feat: Adiciona autenticação de usuário"
+# ❌ git commit -m "fix: Corrige lógica de validação"
+```
+
+## Advanced Git Safeguards
+
+### Safe Push Operations
+
+```bash
+# NEVER use git push --force on main/master branches
+# Instead, use --force-with-lease which prevents overwriting others' work:
+
+# Force push with safety check (only updates if no one else pushed)
+git push --force-with-lease origin feature-branch
+
+# Regular push is always safest
+git push origin main
+```
+
+### Commit Signing
+
+```bash
+# Sign commits with GPG for verified commits
+# Set GPG key: git config --global user.signingkey <KEY_ID>
+git commit -S -m "feat: Signed commit"
+
+# Configure to always sign commits
+git config --global commit.gpgsign true
+```
+
+### Branch Protection (Recommended Settings)
+
+For GitHub/GitLab repositories, configure branch protection rules:
+
+**For main/master branch:**
+- Require pull request reviews
+- Require status checks to pass
+- Require branches to be up to date
+- Do not allow force pushes
+- Do not allow deletions
+- Require signed commits (optional but recommended)
+
+### Destructive Operation Warnings
+
+**NEVER run these on main/master:**
+- ❌ `git push --force` - Use `--force-with-lease` instead
+- ❌ `git reset --hard` - Destructive, use only on feature branches
+- ❌ `git rebase` main into feature - Causes rewriting of main history
+
+### Pre-Push Checklist
+
+Before pushing any changes, verify:
+
+```bash
+✅ Checklist before push:
+- [ ] All quality checks passed locally
+- [ ] Tests pass with 100% success rate
+- [ ] Coverage meets threshold (95%+)
+- [ ] Linting passes with 0 warnings
+- [ ] Build succeeds without errors
+- [ ] No security vulnerabilities in dependencies
+- [ ] Documentation updated if API changed
+- [ ] OpenSpec tasks marked complete if applicable
+- [ ] Conventional commit format used
+- [ ] Commit hash verified: git rev-parse HEAD
+- [ ] Similar changes passed CI before
+- [ ] No console.log or debug code
+- [ ] No credentials or secrets in code
+```
+
+**Only provide push command if ALL items checked.**
+
+### 3. Pushing Changes
+
+**⚠️ IMPORTANT**: Pushing is OPTIONAL and depends on your setup.
+
+```bash
+# IF you have passwordless SSH or want to push:
+git push origin main
+
+# IF you have SSH with password (manual execution required):
+# DO NOT execute automatically - provide command to user:
+```
+
+**For users with SSH password authentication:**
+```
+✋ MANUAL ACTION REQUIRED:
+
+Run this command manually (requires SSH password):
+git push origin main
+```
+
+**NEVER** attempt automatic push if:
+- SSH key has password protection
+- User hasn't confirmed push authorization
+- Any quality check failed
+- Uncertain if changes will pass CI/CD workflows
+
+## Conventional Commits
+
+**MUST** follow conventional commit format:
+
+**⚠️ CRITICAL: All commit messages MUST be in English**
+
+```bash
+# Format: <type>(<scope>): <subject>
+#
+# <body>
+#
+# <footer>
+
+# Types:
+feat:     # New feature
+fix:      # Bug fix
+docs:     # Documentation only
+style:    # Code style (formatting, missing semi-colons, etc)
+refactor: # Code refactoring
+perf:     # Performance improvement
+test:     # Adding tests
+build:    # Build system changes
+ci:       # CI/CD changes
+chore:    # Maintenance tasks
+
+# Language Requirement:
+# ✅ ALWAYS use English for commit messages
+# ❌ NEVER use Portuguese, Spanish, or any other language
+# ❌ NEVER mix languages in commit messages
+
+# Examples (CORRECT - English):
+git commit -m "feat(auth): Add OAuth2 login support"
+git commit -m "fix(api): Handle null response in user endpoint"
+git commit -m "docs: Update README with installation steps"
+git commit -m "test: Add integration tests for payment flow"
+git commit -m "chore: Update dependencies to latest versions"
+
+# Examples (INCORRECT - Other languages):
+# ❌ git commit -m "feat: Adiciona suporte de login OAuth2"
+# ❌ git commit -m "fix: Corrige resposta nula no endpoint"
+# ❌ git commit -m "docs: Atualiza README com passos de instalação"
+```
+
+## Version Management
+
+### Creating New Version
+
+**CRITICAL**: Full quality gate required before versioning!
+
+```bash
+# 1. MANDATORY: Run complete quality suite
+npm run lint          # Must pass with no warnings
+npm test             # Must pass 100%
+npm run type-check   # Must pass (if applicable)
+npm run build        # Must succeed
+npx codespell        # Must pass (if configured)
+
+# 2. Update version in package.json/Cargo.toml/etc
+# Use semantic versioning:
+# - MAJOR: Breaking changes (1.0.0 -> 2.0.0)
+# - MINOR: New features, backwards compatible (1.0.0 -> 1.1.0)
+# - PATCH: Bug fixes (1.0.0 -> 1.0.1)
+
+# 3. Update CHANGELOG.md
+# Document all changes in this version:
+## [1.2.0] - 2024-01-15
+### Added
+- New feature X
+- New feature Y
+
+### Fixed
+- Bug in component Z
+
+### Changed
+- Refactored module A
+
+# 4. Commit version changes
+git add .
+git commit -m "chore: Release version 1.2.0
+
+- Updated version to 1.2.0
+- Updated CHANGELOG.md with release notes"
+
+# 5. Create annotated tag
+git tag -a v1.2.0 -m "Release version 1.2.0
+
+Major changes:
+- Feature X
+- Feature Y
+- Bug fix Z
+
+All tests passing ✅
+Coverage: 95%+ ✅
+Linting: Clean ✅
+Build: Success ✅"
+
+# 6. OPTIONAL: Push tag (manual if SSH password)
+# Only if you're CERTAIN it will pass CI/CD workflows!
+```
+
+**For users requiring manual push:**
+```
+✋ MANUAL ACTIONS REQUIRED:
+
+1. Verify all quality checks passed locally
+2. Push commits:
+   git push origin main
+
+3. Push tag:
+   git push origin v1.2.0
+
+Note: Tag push will trigger CI/CD workflows and may create GitHub release.
+Only push if you're confident all checks will pass.
+```
+
+## Quality Gate Enforcement
+
+**CRITICAL**: Pre-commit checks MUST match GitHub Actions workflow commands to prevent CI/CD failures.
+
+### Language-Specific Pre-Commit Commands
+
+**The commands you run locally MUST be identical to those in your GitHub Actions workflows.**
+
+#### TypeScript/JavaScript Projects
+
+```bash
+# These commands MUST match .github/workflows/*.yml
+
+# 1. Type check (matches workflow)
+npm run type-check        # Must match workflow exactly
+
+# 2. Lint (matches workflow)
+npm run lint              # Must match workflow exactly
+
+# 3. Format check (matches workflow)
+npx prettier --check 'src/**/*.ts' 'tests/**/*.ts'  # Must match workflow
+
+# 4. Tests (matches workflow)
+npm test                  # Must match workflow exactly
+
+# 5. Build (matches workflow)
+npm run build             # Must match workflow exactly
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+#### Rust Projects
+
+```bash
+# These commands MUST match .github/workflows/*.yml
+
+# 1. Format check (matches workflow)
+cargo fmt --all -- --check
+
+# 2. Clippy (matches workflow)
+cargo clippy --all-targets --all-features -- -D warnings
+
+# 3. Tests (matches workflow)
+cargo test --all-features
+
+# 4. Build (matches workflow)
+cargo build --release
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+#### Python Projects
+
+```bash
+# These commands MUST match .github/workflows/*.yml
+
+# 1. Format check (matches workflow)
+black --check .
+
+# 2. Lint (matches workflow)
+ruff check .
+
+# 3. Type check (matches workflow)
+mypy .
+
+# 4. Tests (matches workflow)
+pytest
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+### Before ANY Commit
+
+**MANDATORY CHECKS**:
+
+```bash
+# Checklist - ALL must pass:
+☐ Code formatted
+☐ Linter passes (no warnings)
+☐ Type check passes
+☐ ALL tests pass (100%)
+☐ Coverage meets threshold (95%+)
+☐ Build succeeds
+☐ No console errors/warnings
+
+# Run quality check script:
+npm run quality-check  # or equivalent
+
+# If ANY check fails:
+# ❌ DO NOT COMMIT
+# ❌ FIX THE ISSUES FIRST
+```
+
+### Before Tag Creation
+
+**MANDATORY CHECKS** (even stricter):
+
+```bash
+# Extended checklist - ALL must pass:
+☐ All pre-commit checks passed
+☐ Codespell passes (no typos)
+☐ Security audit clean
+☐ Dependencies up to date
+☐ Documentation updated
+☐ CHANGELOG.md updated
+☐ Version bumped correctly
+☐ All workflows would pass
+
+# Run comprehensive check:
+npm run lint
+npm test
+npm run type-check
+npm run build
+npx codespell
+npm audit
+
+# Only create tag if everything is green!
+```
+
+## Error Recovery & Rollback
+
+### When Implementation Is Failing
+
+If the AI is making repeated mistakes and user is frustrated:
+
+```bash
+# 1. Identify last stable commit
+git log --oneline -10
+
+# 2. Create backup branch of current work
+git branch backup-failed-attempt
+
+# 3. Hard reset to last stable version
+git reset --hard <last-stable-commit-hash>
+
+# 4. Verify stability
+npm test
+npm run build
+
+# 5. Reimplement from scratch using DIFFERENT approach
+# ⚠️ DO NOT repeat the same techniques that failed before
+# ⚠️ Review AGENTS.md for alternative patterns
+# ⚠️ Consider different architecture/design
+
+# 6. After successful reimplementation
+git branch -D backup-failed-attempt  # Delete backup if no longer needed
+```
+
+### Undo Last Commit (Not Pushed)
+
+```bash
+# Keep changes, undo commit
+git reset --soft HEAD~1
+
+# Discard changes completely
+git reset --hard HEAD~1
+```
+
+### Revert Pushed Commit
+
+```bash
+# Create revert commit
+git revert <commit-hash>
+
+# Then push (manual if SSH password)
+```
+
+## Branch Strategy
+
+### Feature Branches
+
+```bash
+# Create feature branch
+git checkout -b feature/user-authentication
+
+# Work on feature...
+# Commit regularly with quality checks
+
+# When feature complete and tested:
+git checkout main
+git merge feature/user-authentication
+
+# Delete feature branch
+git branch -d feature/user-authentication
+```
+
+### Hotfix Workflow
+
+```bash
+# Critical bug in production
+git checkout -b hotfix/critical-security-fix
+
+# Fix the bug
+# MUST include tests
+# MUST pass all quality checks
+
+git commit -m "fix: Critical security vulnerability in auth
+
+- Patch authentication bypass
+- Add regression tests
+- Update security documentation"
+
+# Merge to main
+git checkout main
+git merge hotfix/critical-security-fix
+
+# Tag immediately if production fix
+git tag -a v1.2.1 -m "Hotfix: Security patch"
+
+# Manual push if required
+```
+
+## CRITICAL RESTRICTIONS - HUMAN AUTHORIZATION REQUIRED
+
+**⚠️ IMPERATIVE RULES - THESE ARE NON-NEGOTIABLE ⚠️**
+
+### Destructive Git Operations
+
+**ABSOLUTELY FORBIDDEN without explicit human authorization:**
+
+```
+❌ NEVER execute: git checkout
+   ✋ ALWAYS ask user: "Do you want to checkout [branch/commit]? [Y/n]"
+   ✅ Only execute after explicit user confirmation
+   
+❌ NEVER execute: git reset
+   ✋ ALWAYS ask user: "Do you want to reset to [commit]? This may lose changes. [Y/n]"
+   ✅ Only execute after explicit user confirmation
+   ⚠️  Explain consequences before executing
+```
+
+**Rationale**: These commands can cause data loss. Human oversight is mandatory.
+
+### Merge Conflict Resolution
+
+**When merge conflicts occur:**
+
+```
+❌ NEVER attempt to resolve conflicts by editing files automatically
+❌ NEVER commit merged files without human review
+✅ ALWAYS stop and request human assistance
+✅ ALWAYS provide conflict locations and context
+✅ ALWAYS wait for human to resolve manually
+
+Message to user:
+"⚠️ Merge conflict detected in the following files:
+- [list of conflicted files]
+
+Please resolve these conflicts manually. I cannot auto-resolve merge conflicts.
+
+To resolve:
+1. Open the conflicted files
+2. Look for conflict markers (<<<<<<<, =======, >>>>>>>)
+3. Choose the correct version or merge manually
+4. Remove conflict markers
+5. Run: git add <resolved-files>
+6. Run: git commit
+
+Let me know when you're done, and I can help with the next steps."
+```
+
+**Rationale**: Merge conflicts require human judgment about which code to keep.
+
+### Commit Frequency Management
+
+**⚠️ IMPORTANT: Reduce excessive commits**
+
+```
+❌ DO NOT commit after every small change
+❌ DO NOT create multiple commits for the same logical feature
+✅ COMMIT only when:
+   - A complete feature is implemented and tested
+   - A significant bug fix is completed
+   - A major refactoring is done
+   - Before creating a version tag
+   - User explicitly requests a commit
+   
+✅ GROUP related changes into meaningful commits
+✅ USE conventional commit messages that describe the full scope
+
+Example of GOOD commit frequency:
+- Implement entire authentication system → 1 commit
+- Add login, logout, and session management → 1 commit
+- Complete feature with tests and docs → 1 commit
+
+Example of BAD commit frequency (AVOID):
+- Add login function → commit
+- Add logout function → commit  
+- Add session check → commit
+- Fix typo → commit
+- Update comment → commit
+```
+
+**Rationale**: Too many commits pollute git history and make it harder to track meaningful changes.
+
+### Feature Branch Strategy
+
+**BEFORE starting ANY new task or feature:**
+
+```
+✋ ALWAYS ask user FIRST:
+"Should I create a separate branch for this feature/task? [Y/n]
+
+Options:
+1. Create feature branch: git checkout -b feature/[name]
+2. Work directly on current branch
+3. Create hotfix branch: git checkout -b hotfix/[name]
+
+What would you prefer?"
+
+✅ Wait for user decision
+✅ Respect user's branching strategy
+❌ NEVER assume to work on main without asking
+❌ NEVER create branches without permission
+
+If user says YES to branch:
+  → Create branch with descriptive name
+  → Work on that branch
+  → Ask before merging back to main
+  
+If user says NO to branch:
+  → Proceed on current branch
+  → Be extra careful with commits
+```
+
+**Rationale**: Branching strategy varies by team and project. Always confirm with the human first.
+
+## Critical AI Assistant Rules
+
+### Repository Initialization
+
+**BEFORE any `git init` or setup commands:**
+
+```
+1. Check for .git directory existence
+2. If .git exists:
+   - ❌ STOP - Repository already configured
+   - ❌ DO NOT run git init
+   - ❌ DO NOT run git config
+   - ❌ DO NOT run git branch -M
+   - ❌ DO NOT reconfigure anything
+   - ✅ Use existing repository as-is
+   
+3. If .git does NOT exist:
+   - ✅ Ask user if they want Git initialization
+   - ✅ Run initialization sequence if approved
+```
+
+### Push Command Behavior
+
+**Based on configured push mode:**
+
+```
+Manual Mode (DEFAULT):
+  ❌ NEVER execute: git push
+  ✅ ALWAYS provide: "Run manually: git push origin main"
+  
+Prompt Mode:
+  ⚠️  ALWAYS ask first: "Ready to push. Proceed? [Y/n]"
+  ✅ Execute only if user confirms
+  
+Auto Mode:
+  ⚠️  Check quality first
+  ⚠️  Only if 100% confident
+  ✅ Execute if all checks passed
+```
+
+### Quality Gate Enforcement
+
+**MANDATORY checks before commit:**
+
+```bash
+# Run in this exact order:
+1. npm run lint          # or language equivalent
+2. npm run type-check    # if applicable
+3. npm test             # ALL tests must pass
+4. npm run build        # must succeed
+
+# If ANY fails:
+❌ STOP - DO NOT commit
+❌ Fix issues first
+❌ Re-run all checks
+
+# If ALL pass:
+✅ Safe to commit
+✅ Proceed with git add and commit
+```
+
+**MANDATORY checks before tag:**
+
+```bash
+# Extended checks for version tags:
+1. All commit checks above +
+2. npx codespell        # no typos
+3. npm audit            # no vulnerabilities
+4. CHANGELOG.md updated
+5. Version bumped correctly
+6. Documentation current
+
+# If ANY fails:
+❌ STOP - DO NOT create tag
+❌ Fix issues
+❌ Re-verify everything
+
+# Only create tag if 100% green!
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **ALWAYS** check if .git exists before init commands
+- **ALWAYS** run tests before commit
+- **ALWAYS** use conventional commit messages
+- **ALWAYS** write commit messages in English (never in Portuguese, Spanish, or other languages)
+- **ALWAYS** update CHANGELOG for versions
+- **ALWAYS** ask before executing `git checkout`
+- **ALWAYS** ask before executing `git reset`
+- **ALWAYS** ask user if a feature branch should be created before starting tasks
+- **ALWAYS** request human assistance when merge conflicts occur
+- **COMMIT** only when complete features/fixes are done (not for every small change)
+- **TAG** releases with semantic versions
+- **VERIFY** quality gates before tagging
+- **DOCUMENT** breaking changes clearly
+- **REVERT** when implementation is failing repeatedly
+- **ASK** user before automatic push
+- **PROVIDE** manual commands for SSH password users
+- **CHECK** repository state before operations
+- **RESPECT** existing Git configuration
+- **GROUP** related changes into meaningful commits
+
+### DON'Ts ❌
+
+- **NEVER** run `git init` if .git exists
+- **NEVER** run `git config` (user-specific)
+- **NEVER** run `git checkout` without explicit user authorization
+- **NEVER** run `git reset` without explicit user authorization
+- **NEVER** auto-resolve merge conflicts by editing files
+- **NEVER** commit merged files without human review
+- **NEVER** create excessive commits for small changes
+- **NEVER** assume branching strategy - always ask user first
+- **NEVER** reconfigure existing repository
+- **NEVER** commit without passing tests
+- **NEVER** commit with linting errors
+- **NEVER** commit with build failures
+- **NEVER** write commit messages in languages other than English
+- **NEVER** mix languages in commit messages
+- **NEVER** create tag without quality checks
+- **NEVER** push automatically with SSH password
+- **NEVER** push if uncertain about CI/CD success
+- **NEVER** commit console.log/debug code
+- **NEVER** commit credentials or secrets
+- **NEVER** force push to main/master
+- **NEVER** rewrite published history
+- **NEVER** skip hooks (--no-verify)
+- **NEVER** assume repository configuration
+
+## SSH Configuration
+
+### For Users with SSH Password
+
+If your SSH key has password protection:
+
+**Configuration in AGENTS.md or project settings:**
+
+```yaml
+git_workflow:
+  auto_push: false
+  push_mode: "manual"
+  reason: "SSH key has password protection"
+```
+
+**AI Assistant Behavior:**
+- ✅ Provide push commands in chat
+- ✅ Wait for user manual execution
+- ❌ Never attempt automatic push
+- ❌ Never execute git push commands
+
+### For Users with Passwordless SSH
+
+```yaml
+git_workflow:
+  auto_push: true  # or prompt each time
+  push_mode: "auto"
+```
+
+## Git Hooks
+
+### Pre-commit Hook
+
+Create `.git/hooks/pre-commit`:
+
+```bash
+#!/bin/sh
+
+echo "Running pre-commit checks..."
+
+# Run linter
+npm run lint
+if [ $? -ne 0 ]; then
+  echo "❌ Linting failed. Commit aborted."
+  exit 1
+fi
+
+# Run tests
+npm test
+if [ $? -ne 0 ]; then
+  echo "❌ Tests failed. Commit aborted."
+  exit 1
+fi
+
+# Run type check (if applicable)
+if command -v tsc &> /dev/null; then
+  npm run type-check
+  if [ $? -ne 0 ]; then
+    echo "❌ Type check failed. Commit aborted."
+    exit 1
+  fi
+fi
+
+echo "✅ All pre-commit checks passed!"
+exit 0
+```
+
+### Pre-push Hook
+
+Create `.git/hooks/pre-push`:
+
+```bash
+#!/bin/sh
+
+echo "Running pre-push checks..."
+
+# Run full test suite
+npm test
+if [ $? -ne 0 ]; then
+  echo "❌ Tests failed. Push aborted."
+  exit 1
+fi
+
+# Run build
+npm run build
+if [ $? -ne 0 ]; then
+  echo "❌ Build failed. Push aborted."
+  exit 1
+fi
+
+echo "✅ All pre-push checks passed!"
+exit 0
+```
+
+Make hooks executable:
+```bash
+chmod +x .git/hooks/pre-commit
+chmod +x .git/hooks/pre-push
+```
+
+## CI/CD Integration
+
+### Before Providing Push Commands
+
+**CRITICAL**: Only suggest push if confident about CI/CD success:
+
+```
+✅ Provide push command if:
+- All local tests passed
+- All linting passed
+- Build succeeded
+- Coverage meets threshold
+- No warnings or errors
+- Code follows AGENTS.md standards
+- Similar changes passed CI/CD before
+
+❌ DO NOT provide push command if:
+- ANY quality check failed
+- Uncertain about CI/CD requirements
+- Making experimental changes
+- First time working with this codebase
+- User seems uncertain
+
+Instead say:
+"I recommend running the full CI/CD pipeline locally first to ensure 
+the changes will pass. Once confirmed, you can push manually."
+```
+
+## GitHub MCP Server Integration
+
+**If GitHub MCP Server is available**, use it for automated workflow monitoring.
+
+### Workflow Validation After Push
+
+```
+After every git push (manual or auto):
+
+1. Wait 5-10 seconds for workflows to trigger
+
+2. Check workflow status via GitHub MCP:
+   - List workflow runs for latest commit
+   - Check status of each workflow
+
+3. If workflows are RUNNING:
+   ⏳ Report: "CI/CD workflows in progress..."
+   ✅ Continue with other tasks
+   ✅ Check again in next user interaction
+   
+4. If workflows COMPLETED:
+   - All passed: ✅ Report success
+   - Some failed: ❌ Fetch errors and fix
+
+5. If workflows FAILED:
+   a. Fetch complete error logs via GitHub MCP
+   b. Display errors to user
+   c. Analyze against AGENTS.md standards
+   d. Propose specific fixes
+   e. Implement fixes
+   f. Run local quality checks
+   g. Commit fixes
+   h. Provide push command for retry
+```
+
+### Next Interaction Check
+
+```
+On every user message after a push:
+
+if (github_mcp_available && last_push_timestamp) {
+  // Check workflow status
+  const status = await checkWorkflows();
+  
+  if (status.running) {
+    console.log('⏳ CI/CD still running, will check later');
+  } else if (status.failed) {
+    console.log('❌ CI/CD failures detected!');
+    await analyzeAndFixErrors(status.errors);
+  } else {
+    console.log('✅ All CI/CD workflows passed!');
+  }
+}
+```
+
+### Error Analysis Flow
+
+```
+When workflow fails:
+
+1. Fetch error via GitHub MCP:
+   - Workflow name
+   - Job name  
+   - Failed step
+   - Error output
+   - Full logs
+
+2. Categorize error:
+   - Test failure → Fix test or implementation
+   - Lint error → Format/fix code style
+   - Build error → Fix compilation issues
+   - Type error → Fix type definitions
+   - Coverage error → Add more tests
+
+3. Fix following AGENTS.md:
+   - Apply correct pattern from AGENTS.md
+   - Add tests if needed
+   - Verify locally before committing
+
+4. Commit fix:
+   git commit -m "fix: Resolve CI/CD failure - [specific issue]"
+
+5. Provide push command:
+   "Ready to retry. Run: git push origin main"
+
+6. After next push:
+   - Monitor again
+   - Verify fix worked
+```
+
+### CI/CD Confidence Check
+
+**Before suggesting push:**
+
+```
+Assess confidence in CI/CD success:
+
+HIGH confidence (safe to push):
+✅ All local checks passed
+✅ Similar changes passed CI before
+✅ No experimental changes
+✅ Follows AGENTS.md exactly
+✅ Comprehensive tests
+✅ No unusual patterns
+
+MEDIUM confidence (verify first):
+⚠️ First time with this pattern
+⚠️ Modified build configuration
+⚠️ Changed dependencies
+⚠️ Cross-platform concerns
+→ Suggest: "Let's verify locally first"
+
+LOW confidence (don't push yet):
+❌ Experimental implementation
+❌ Skipped some tests
+❌ Uncertain about compatibility
+❌ Modified CI/CD files
+→ Say: "Let's run additional checks first"
+```
+
+## Troubleshooting
+
+### Merge Conflicts
+
+```bash
+# View conflicts
+git status
+
+# Edit conflicted files (marked with <<<<<<<, =======, >>>>>>>)
+
+# After resolving:
+git add <resolved-files>
+git commit -m "fix: Resolve merge conflicts"
+```
+
+### Accidental Commit
+
+```bash
+# Undo last commit, keep changes
+git reset --soft HEAD~1
+
+# Make corrections
+# Re-commit properly
+```
+
+### Lost Commits
+
+```bash
+# View all actions
+git reflog
+
+# Recover lost commit
+git checkout <commit-hash>
+git checkout -b recovery-branch
+```
+
+<!-- GIT:END -->
+