diff --git a/GERRIT.md b/GERRIT.md
new file mode 100644
index 0000000..db3eedb
--- /dev/null
+++ b/GERRIT.md
@@ -0,0 +1,143 @@
+# Gerrit Integration Guide
+
+Staff AI Agent System now supports Gerrit as an alternative to GitHub for pull request management. This guide explains how to configure and use Gerrit with Staff.
+
+## Overview
+
+Gerrit integration provides the same capabilities as GitHub:
+- Create changes (Gerrit's equivalent of pull requests)
+- List and manage changes
+- Update change descriptions
+- Close (abandon) changes
+- Submit (merge) changes
+- Structured logging for all operations
+
+## Configuration
+
+### YAML Configuration
+
+Add Gerrit configuration to your `config.yaml`:
+
+```yaml
+# Either GitHub OR Gerrit is required
+gerrit:
+  username: "your-gerrit-username" 
+  password: "your-gerrit-http-password-or-token"
+  base_url: "https://gerrit.example.com"
+  project: "your-project-name"
+```
+
+### Environment Variables
+
+You can also configure Gerrit using environment variables:
+
+```bash
+export GERRIT_USERNAME="your-username"
+export GERRIT_PASSWORD="your-password-or-token"
+export GERRIT_BASE_URL="https://gerrit.example.com" 
+export GERRIT_PROJECT="your-project"
+```
+
+## Provider Priority
+
+When both GitHub and Gerrit are configured, GitHub takes precedence for backward compatibility. To use Gerrit when both are configured, remove the GitHub configuration.
+
+## Authentication
+
+Gerrit integration supports:
+- **HTTP Password**: Traditional Gerrit HTTP password
+- **HTTP Token**: Generate from Gerrit Settings → HTTP Credentials
+
+## URL Format
+
+Generated change URLs follow Gerrit's standard format:
+```
+https://gerrit.example.com/c/project-name/+/12345
+```
+
+## Agent Behavior
+
+Agents work identically with Gerrit:
+1. Process assigned tasks
+2. Generate solutions using LLM
+3. Create Git branches and commits
+4. Create Gerrit changes for review
+5. Update task status with change URL
+
+## Configuration Validation
+
+Use the config check command to verify your Gerrit setup:
+
+```bash
+./staff config-check
+```
+
+This will show:
+- Which Git provider is configured (GitHub/Gerrit)
+- Validation of all required fields
+- Connection status
+
+## Example Configuration
+
+See `config-gerrit-example.yaml` for a complete example configuration using Gerrit instead of GitHub.
+
+## Structured Logging
+
+All Gerrit operations include structured logging:
+
+```
+INFO Creating Gerrit change url=https://gerrit.example.com/a/changes/ project=my-project subject="Task ABC-123: Implement feature" branch=main topic=task/ABC-123-implement-feature
+```
+
+## Comparison with GitHub
+
+| Feature | GitHub | Gerrit |
+|---------|--------|--------|
+| Changes/PRs | Pull Requests | Changes |
+| Review System | GitHub Reviews | Gerrit Code Review |
+| Merge | Merge PR | Submit Change |
+| Close | Close PR | Abandon Change |
+| URL Format | `/pull/123` | `/c/project/+/123` |
+| Authentication | Token | Username + Password/Token |
+
+## Migration
+
+To migrate from GitHub to Gerrit:
+
+1. Update configuration file or environment variables
+2. Remove GitHub configuration 
+3. Restart the Staff system
+4. All new agent operations will use Gerrit
+
+Existing GitHub pull requests are not affected and remain accessible.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failed**
+   - Verify username and password/token
+   - Check Gerrit HTTP credentials settings
+   - Ensure HTTP authentication is enabled
+
+2. **Project Not Found**
+   - Verify project name matches exactly
+   - Check user has access to the project
+   - Ensure project exists in Gerrit
+
+3. **Network Issues**
+   - Verify base URL is correct and accessible
+   - Check firewall/proxy settings
+   - Test connectivity to Gerrit server
+
+### Debug Logging
+
+Enable debug logging to troubleshoot issues:
+
+```yaml
+# Add to your configuration
+logging:
+  level: debug
+```
+
+This will show detailed HTTP requests and responses for Gerrit operations.
\ No newline at end of file