feat: Add comprehensive branch cleanup tools and documentation

.github/workflows/cleanup-branches.yml

@@ -0,0 +1,65 @@
+name: Clean Up Stale Branches
+
+on:
+  schedule:
+    # Run weekly on Sundays at midnight UTC
+    - cron: '0 0 * * 0'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Run in dry-run mode (preview only)'
+        required: false
+        default: 'true'
+        type: boolean
+
+jobs:
+  cleanup-branches:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch all branches
+        run: git fetch --all --prune
+
+      - name: Run branch cleanup script
+        run: |
+          chmod +x ./scripts/cleanup-branches.sh
+          if [[ "${{ github.event.inputs.dry_run }}" == "true" ]] || [[ "${{ github.event_name }}" == "schedule" ]]; then
+            echo "Running in dry-run mode..."
+            ./scripts/cleanup-branches.sh --dry-run
+          else
+            echo "Running actual cleanup..."
+            ./scripts/cleanup-branches.sh --force
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create summary
+        run: |
+          echo "## Branch Cleanup Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Remaining Branches" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          git branch -r | sort >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Branch Count" >> $GITHUB_STEP_SUMMARY
+          echo "Total remote branches: $(git branch -r | wc -l)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [[ "${{ github.event.inputs.dry_run }}" == "true" ]] || [[ "${{ github.event_name }}" == "schedule" ]]; then
+            echo "⚠️ **Dry Run Mode**: No branches were actually deleted" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "✅ **Cleanup Complete**: Automated branches have been removed" >> $GITHUB_STEP_SUMMARY
+          fi

CONTRIBUTING.md

@@ -567,6 +567,52 @@ We follow [Semantic Versioning](https://semver.org/):
 
 All changes are documented in [CHANGELOG.md](CHANGELOG.md) following [Keep a Changelog](https://keepachangelog.com/) format.
 
+## Repository Maintenance
+
+### Branch Cleanup
+
+To maintain a clean repository structure, we regularly clean up automated branches created by bots and temporary processes:
+
+#### Automated Cleanup
+
+Use the provided cleanup script:
+
+```bash
+# Preview what would be deleted
+./scripts/cleanup-branches.sh --dry-run
+
+# Execute the cleanup
+./scripts/cleanup-branches.sh --force
+```
+
+#### What Gets Cleaned Up
+
+- **Copilot fix branches**: `copilot/fix-*`
+- **Dependabot branches**: `dependabot/*`  
+- **Merge branches**: `merge/*`
+- **Other automated branches**
+
+#### What's Preserved
+
+- `main` - Production branch (protected)
+- `develop` - Development branch (protected)
+- `feature/*` - Feature branches following naming convention
+- Any branches with recent commits or open PRs
+
+For detailed information, see [Branch Cleanup Documentation](docs/BRANCH_CLEANUP.md).
+
+### Dependency Updates
+
+- Dependabot automatically creates PRs for dependency updates
+- Review and merge dependency updates promptly
+- Test thoroughly before merging major version updates
+
+### Code Quality
+
+- Run linting and formatting regularly: `pnpm lint && pnpm format`
+- Keep test coverage above 80%: `pnpm test`
+- Address security vulnerabilities promptly
+
 ## Questions?
 
 If you have questions about contributing, please:

README.md

@@ -236,6 +236,20 @@ We use [Conventional Commits](https://www.conventionalcommits.org/):
 - `test:` Test additions/changes
 - `chore:` Maintenance tasks
 
+## 🧹 Repository Maintenance
+
+### Branch Cleanup
+
+The repository includes automated tools for cleaning up temporary branches created by bots and automated processes:
+
+```bash
+# Clean up automated branches (Copilot, Dependabot, etc.)
+./scripts/cleanup-branches.sh --dry-run  # Preview changes
+./scripts/cleanup-branches.sh --force    # Execute cleanup
+```
+
+See [Branch Cleanup Documentation](docs/BRANCH_CLEANUP.md) for detailed information.
+
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.