| name | bee:requesting-code-review |
| description | Gate 4 of development cycle - dispatches 6 specialized reviewers (code, business-logic,
security, test, nil-safety, consequences) in parallel for comprehensive code review feedback.
|
| trigger | - Gate 4 of development cycle
- After completing major feature implementation
- Before merge to main branch
- After fixing complex bug
|
| NOT_skip_when | - "Code is simple" → Simple code can have security issues. Review required.
- "Just refactoring" → Refactoring may expose vulnerabilities. Review required.
- "Already reviewed similar code" → Each change needs fresh review.
|
| sequence | {"after":["bee:dev-testing"],"before":["bee:dev-validation"]} |
| related | {"complementary":["bee:dev-cycle","bee:dev-implementation","bee:dev-testing"]} |
| input_schema | {"required":[],"optional":[{"name":"unit_id","type":"string","description":"Task or subtask identifier (auto-generated if not provided)"},{"name":"base_sha","type":"string","description":"Git SHA before implementation (auto-detected via git merge-base HEAD main)"},{"name":"head_sha","type":"string","description":"Git SHA after implementation (auto-detected via git rev-parse HEAD)"},{"name":"implementation_summary","type":"string","description":"Summary of what was implemented (auto-generated from git log if not provided)"},{"name":"requirements","type":"string","description":"Requirements or acceptance criteria (reviewers will infer from code if not provided)"},{"name":"implementation_files","type":"array","items":"string","description":"List of files changed (auto-detected via git diff if not provided)"},{"name":"gate0_handoff","type":"object","description":"Full handoff from Gate 0 (only when called from bee:dev-cycle)"},{"name":"skip_reviewers","type":"array","items":"string","enum":["bee:code-reviewer","bee:business-logic-reviewer","bee:security-reviewer","bee:test-reviewer","bee:nil-safety-reviewer","bee:consequences-reviewer"],"description":"Reviewers to skip (use sparingly)"},{"name":"skip_preanalysis","type":"boolean","default":false,"description":"Skip pre-analysis pipeline for faster reviews (reviewers work without static analysis context)"},{"name":"preanalysis_timeout","type":"integer","default":300000,"description":"Timeout for pre-analysis pipeline in milliseconds (default: 5 minutes)"},{"name":"skip_opencode","type":"boolean","default":false,"description":"Skip OpenCode external review (only valid if OpenCode CLI is not installed)"},{"name":"opencode_model","type":"string","default":"bailian-coding-plan/qwen3-max-2026-01-23","description":"Model to use for OpenCode review (e.g., bailian-coding-plan/qwen3-coder-plus, opencode/gpt-5-nano)"}]} |
| output_schema | {"format":"markdown","required_sections":[{"name":"Review Summary","pattern":"^## Review Summary","required":true},{"name":"Issues by Severity","pattern":"^## Issues by Severity","required":true},{"name":"Reviewer Verdicts","pattern":"^## Reviewer Verdicts","required":true},{"name":"CodeRabbit External Review","pattern":"^## CodeRabbit External Review","required":false},{"name":"OpenCode External Review","pattern":"^## OpenCode External Review","required":false},{"name":"Handoff to Next Gate","pattern":"^## Handoff to Next Gate","required":true}],"metrics":[{"name":"result","type":"enum","values":["PASS","FAIL","NEEDS_FIXES"]},{"name":"reviewers_passed","type":"string","description":"X/6 format"},{"name":"issues_critical","type":"integer"},{"name":"issues_high","type":"integer"},{"name":"issues_medium","type":"integer"},{"name":"issues_low","type":"integer"},{"name":"iterations","type":"integer"},{"name":"coderabbit_status","type":"enum","values":["PASS","ISSUES_FOUND","SKIPPED","NOT_INSTALLED"]},{"name":"coderabbit_validation_mode","type":"enum","values":["SUBTASK_LEVEL","TASK_LEVEL"],"description":"Granularity of CodeRabbit validation"},{"name":"coderabbit_units_validated","type":"integer","description":"Number of units (subtasks or tasks) validated by CodeRabbit"},{"name":"coderabbit_units_passed","type":"integer","description":"Number of units that passed CodeRabbit validation"},{"name":"coderabbit_issues","type":"integer","description":"Total number of issues found by CodeRabbit across all units (0 if skipped)"},{"name":"opencode_status","type":"enum","values":["PASS","ISSUES_FOUND","SKIPPED","NOT_INSTALLED"],"description":"OpenCode external review status"},{"name":"opencode_model","type":"string","description":"Model used for OpenCode review"},{"name":"opencode_issues","type":"integer","description":"Total number of issues found by OpenCode (0 if skipped)"}]} |
| examples | [{"name":"Feature review","input":{"unit_id":"task-001","base_sha":"abc123","head_sha":"def456","implementation_summary":"Added user authentication with JWT","requirements":"AC-1: User can login, AC-2: Invalid password returns error"},"expected_output":"## Review Summary\n**Status:** PASS\n**Reviewers:** 6/6 PASS\n\n## Issues by Severity\n| Severity | Count |\n|----------|-------|\n| Critical | 0 |\n| High | 0 |\n| Medium | 0 |\n| Low | 2 |\n\n## Reviewer Verdicts\n| Reviewer | Verdict |\n|----------|---------|\n| bee:code-reviewer | ✅ PASS |\n| bee:business-logic-reviewer | ✅ PASS |\n| bee:security-reviewer | ✅ PASS |\n| bee:test-reviewer | ✅ PASS |\n| bee:nil-safety-reviewer | ✅ PASS |\n| bee:consequences-reviewer | ✅ PASS |\n\n## Handoff to Next Gate\n- Ready for Gate 5: YES\n"}] |
Code Review (Gate 4)
Overview
Dispatch all six reviewer subagents in parallel for fast, comprehensive feedback:
- bee:code-reviewer - Architecture, design patterns, code quality
- bee:business-logic-reviewer - Domain correctness, business rules, edge cases
- bee:security-reviewer - Vulnerabilities, authentication, OWASP risks
- bee:test-reviewer - Test quality, coverage, edge cases, anti-patterns
- bee:nil-safety-reviewer - Nil/null pointer safety for PHP and TypeScript
- bee:consequences-reviewer - Ripple effects, caller chain impact, downstream consequences
Core principle: All 6 reviewers run simultaneously in a single message with 6 Task tool calls.
⛔ Agent Name Resolution: bee: names in this skill MUST be resolved to runtime-qualified names for Agent/Task tool dispatch. See shared-patterns/shared-orchestrator-principle.md → "Agent Runtime Resolution" for the full mapping table.
CRITICAL: Role Clarification
This skill ORCHESTRATES. Reviewer Agents REVIEW.
| Who | Responsibility |
|---|
| This Skill | Dispatch reviewers, aggregate findings, track iterations |
| Reviewer Agents | Analyze code, report issues with severity |
| Implementation Agent | Fix issues found by reviewers |
Step 1: Gather Context (Auto-Detect if Not Provided)
This skill supports TWO modes:
1. WITH INPUTS: Called by any skill/user that provides structured inputs (unit_id, base_sha, etc.)
2. STANDALONE: Called directly without inputs - auto-detects everything from git
FOR EACH INPUT, check if provided OR auto-detect:
1. unit_id:
IF provided → use it
ELSE → generate: "review-" + timestamp (e.g., "review-20241222-143052")
2. base_sha:
IF provided → use it
ELSE → Execute: git merge-base HEAD main
IF git fails → Execute: git rev-parse HEAD~10 (fallback to last 10 commits)
3. head_sha:
IF provided → use it
ELSE → Execute: git rev-parse HEAD
4. implementation_files:
IF provided → use it
ELSE → Execute: git diff --name-only [base_sha] [head_sha]
5. implementation_summary:
IF provided → use it
ELSE → Execute: git log --oneline [base_sha]..[head_sha]
Format as: "Changes: [list of commit messages]"
6. requirements:
IF provided → use it
ELSE → Set to: "Infer requirements from code changes and commit messages"
(Reviewers will analyze code to understand intent)
AFTER AUTO-DETECTION, display context:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODE REVIEW CONTEXT │
├─────────────────────────────────────────────────────────────────┤
│ Unit ID: [unit_id] │
│ Base SHA: [base_sha] │
│ Head SHA: [head_sha] │
│ Files Changed: [count] files │
│ Commits: [count] commits │
│ │
│ Dispatching 6 reviewers in parallel... │
└─────────────────────────────────────────────────────────────────┘
Step 2: Initialize Review State
review_state = {
unit_id: [from input],
base_sha: [from input],
head_sha: [from input],
reviewers: {
code_reviewer: {verdict: null, issues: []},
business_logic_reviewer: {verdict: null, issues: []},
security_reviewer: {verdict: null, issues: []},
test_reviewer: {verdict: null, issues: []},
nil_safety_reviewer: {verdict: null, issues: []},
consequences_reviewer: {verdict: null, issues: []}
},
aggregated_issues: {
critical: [],
high: [],
medium: [],
low: [],
cosmetic: []
},
iterations: 0,
max_iterations: 3
}
preanalysis_state = {
enabled: true,
success: false,
context: {
"bee:code-reviewer": null,
"bee:security-reviewer": null,
"bee:business-logic-reviewer": null,
"bee:test-reviewer": null,
"bee:nil-safety-reviewer": null,
"bee:consequences-reviewer": null
}
}
Step 3: Dispatch All 6 Reviewers in Parallel
⛔ CRITICAL: All 6 reviewers MUST be dispatched in a SINGLE message with 6 Task calls.
Task:
subagent_type: "bee:code-reviewer"
description: "Code review for [unit_id]"
prompt: |
## Code Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
[implementation_files or "Use git diff"]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:code-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:code-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Architecture and design patterns
- Code quality and maintainability
- Naming conventions
- Error handling patterns
- Performance concerns
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |
[positive observations]
Task:
subagent_type: "bee:business-logic-reviewer"
description: "Business logic review for [unit_id]"
prompt: |
## Business Logic Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:business-logic-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:business-logic-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Domain correctness
- Business rules implementation
- Edge cases handling
- Requirements coverage
- Data validation
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW/COSMETIC] | [issue] | [location] | [fix] |
| Requirement | Status | Evidence |
|-------------|--------|----------|
| [req] | ✅/❌ | [file:line] |
Task:
subagent_type: "bee:security-reviewer"
description: "Security review for [unit_id]"
prompt: |
## Security Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:security-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:security-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Authentication and authorization
- Input validation
- SQL injection, XSS, CSRF
- Sensitive data handling
- OWASP Top 10 risks
| Severity | Description | File:Line | OWASP Category | Recommendation |
|----------|-------------|-----------|----------------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [A01-A10] | [fix] |
| Check | Status |
|-------|--------|
| Input validation | ✅/❌ |
| Auth checks | ✅/❌ |
| No hardcoded secrets | ✅/❌ |
Task:
subagent_type: "bee:test-reviewer"
description: "Test quality review for [unit_id]"
prompt: |
## Test Quality Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:test-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:test-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Test coverage for business logic
- Edge case testing (empty, null, boundary)
- Error path coverage
- Test independence and isolation
- Assertion quality (not just "no error")
- Test anti-patterns (testing mock behavior)
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
| Test Type | Count | Coverage |
|-----------|-------|----------|
| Unit | [N] | [areas] |
| Integration | [N] | [areas] |
| E2E | [N] | [areas] |
Task:
subagent_type: "bee:nil-safety-reviewer"
description: "Nil/null safety review for [unit_id]"
prompt: |
## Nil-Safety Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
**Languages:** [PHP|TypeScript|both - detect from files]
[implementation_summary]
[requirements]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:nil-safety-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:nil-safety-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Nil/null pointer risks in changed code
- Missing nil guards before dereference
- Null dereference without isset/null check (PHP)
- Unsafe nullable type access (PHP)
- Optional chaining misuse (TypeScript)
- Error-then-use patterns
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
[For each risk: Source → Propagation → Dereference point]
Task:
subagent_type: "bee:consequences-reviewer"
description: "Consequences review for [unit_id]"
prompt: |
## Consequences Review Request
**Unit ID:** [unit_id]
**Base SHA:** [base_sha]
**Head SHA:** [head_sha]
[implementation_summary]
[requirements]
**Static Analysis Results:**
The following findings were automatically extracted by the pre-analysis pipeline.
Use these to INFORM your review, not REPLACE your analysis.
---
[IF preanalysis_state.context["bee:consequences-reviewer"] exists AND is not empty:]
[INSERT the content of preanalysis_state.context["bee:consequences-reviewer"]]
[ELSE:]
_No pre-analysis context available. Perform standard review based on git diff._
---
- Caller chain impact analysis
- Consumer contract integrity
- Shared state and configuration consequences
- Type and interface propagation
- Error handling chain consequences
- Database/schema ripple effects
| Severity | Description | File:Line | Recommendation |
|----------|-------------|-----------|----------------|
| [CRITICAL/HIGH/MEDIUM/LOW] | [issue] | [location] | [fix] |
[For each changed symbol: callers found, consumers found, impact status]
Step 4: Wait for All Reviewers and Parse Output
Wait for all 6 Task calls to complete.
For each reviewer:
1. Extract VERDICT (PASS/FAIL)
2. Extract Issues Found table
3. Categorize issues by severity
review_state.reviewers.code_reviewer = {
verdict: [PASS/FAIL],
issues: [parsed issues]
}
// ... same for other reviewers
Aggregate all issues by severity:
review_state.aggregated_issues.critical = [all critical from all reviewers]
review_state.aggregated_issues.high = [all high from all reviewers]
// ... etc
Step 5: Handle Results by Severity
Count blocking issues:
blocking_count = critical.length + high.length + medium.length
IF blocking_count == 0:
→ All reviewers PASS
→ Proceed to Step 8 (Success)
IF blocking_count > 0:
→ review_state.iterations += 1
→ IF iterations >= max_iterations: Go to Step 9 (Escalate)
→ Go to Step 6 (Dispatch Fixes)
Step 6: Dispatch Fixes to Implementation Agent
⛔ CRITICAL: You are an ORCHESTRATOR. You CANNOT edit source files directly.
You MUST dispatch the implementation agent to fix ALL review issues.
Orchestrator Boundaries (HARD GATE)
See dev-team/skills/shared-patterns/standards-boundary-enforcement.md for core enforcement rules.
Key prohibition: Edit/Write/Create on source files is FORBIDDEN. Always dispatch agent.
If you catch yourself about to use Edit/Write/Create on source files → STOP. Dispatch agent.
Dispatch Implementation Agent
Task:
subagent_type: "[implementation_agent from Gate 0]"
description: "Fix review issues for [unit_id]"
prompt: |
⛔ FIX REQUIRED - Code Review Issues Found
- **Unit ID:** [unit_id]
- **Iteration:** [iterations] of [max_iterations]
[list critical issues with file:line and recommendation]
[list high issues]
[list medium issues]
1. Fix ALL Critical, High, and Medium issues
2. Run tests to verify fixes
3. Commit fixes with descriptive message
4. Return list of fixed issues with evidence
Add TODO/FIXME comments:
- Low: `// TODO(review): [Issue] - [reviewer] on [date]`
- Cosmetic: `// FIXME(nitpick): [Issue] - [reviewer] on [date]`
Anti-Rationalization for Direct Editing
See shared-patterns/orchestrator-direct-editing-anti-rationalization.md for complete anti-rationalization table.
Applies to: Step 6 (Fix dispatch after Bee reviewers) & Step 7.5.3 (Fix dispatch after CodeRabbit)
Step 7: Re-Run All Reviewers After Fixes
After fixes committed:
1. Get new HEAD_SHA
2. Go back to Step 3 (dispatch all 6 reviewers again)
⛔ CRITICAL: Always re-run ALL 6 reviewers after fixes.
Do NOT cherry-pick reviewers.
Step 7.5: CodeRabbit CLI Validation (Per-Subtask/Task)
⛔ NEW APPROACH: CodeRabbit validates EACH subtask/task as it completes, accumulating findings to a file.
CodeRabbit Integration Overview
┌─────────────────────────────────────────────────────────────────┐
│ CODERABBIT PER-UNIT VALIDATION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ DURING REVIEW (after each subtask/task Bee reviewers pass): │
│ 1. Run CodeRabbit for that unit's files │
│ 2. Append findings to .coderabbit-findings.md │
│ 3. Continue to next unit │
│ │
│ BEFORE COMMIT (Step 8): │
│ 1. Display accumulated .coderabbit-findings.md │
│ 2. User decides: fix issues OR acknowledge and proceed │
│ │
│ BENEFITS: │
│ • Catches issues close to when code was written │
│ • Smaller scope = faster reviews (7-30 min per unit) │
│ • Issues isolated to specific units, easier to fix │
│ • Accumulated file provides audit trail │
│ │
└─────────────────────────────────────────────────────────────────┘
Rate Limits (Official - per developer per repository per hour)
| Limit Type | Value | Notes |
|---|
| Files reviewed | 200 files/hour | Per review |
| Reviews | 3 back-to-back, then 4/hour | 7 reviews possible in first hour |
| Conversations | 25 back-to-back, then 50/hour | For follow-up questions |
⏱️ TIMING: Each CodeRabbit review takes 7-30+ minutes depending on scope.
Run in background and check periodically for completion.
Common Commands Reference
CodeRabbit Installation Check:
which coderabbit || which cr
Used in Step 7.5.1 and after installation to verify CLI availability.
⚠️ PREREQUISITES & ENVIRONMENT REQUIREMENTS
Before attempting Step 7.5, verify your environment supports the required operations:
| Requirement | Local Dev | CI/CD | Containerized | Remote/SSH |
|---|
curl | sh install | ✅ Yes | ⚠️ May require elevated permissions | ❌ Often blocked | ⚠️ Depends on config |
Browser auth (coderabbit auth login) | ✅ Yes | ❌ No browser | ❌ No browser | ❌ No browser |
Write to $HOME/.coderabbit/ | ✅ Yes | ⚠️ Ephemeral | ⚠️ Ephemeral | ✅ Usually |
Internet access to cli.coderabbit.ai | ✅ Yes | ⚠️ Check firewall | ⚠️ Check firewall | ⚠️ Check firewall |
⛔ HARD STOP CONDITIONS - Skip Step 7.5 if ANY apply:
- Running in containerized environment without persistent storage
- CI/CD pipeline without pre-installed CodeRabbit CLI
- Non-interactive environment (no TTY for browser auth)
- Network restrictions blocking
cli.coderabbit.ai
- Read-only filesystem
Environment-Specific Guidance
Local Development (RECOMMENDED)
Standard flow works: curl | sh install + browser authentication.
CI/CD Pipelines
Option A: Pre-install in CI image
# Add to your CI Dockerfile
RUN curl -fsSL https://cli.coderabbit.ai/install.sh | sh
Option B: Use API token authentication (headless)
export CODERABBIT_API_TOKEN="your-api-token"
coderabbit auth login --token "$CODERABBIT_API_TOKEN"
Option C: Skip CodeRabbit in CI, run locally
export SKIP_CODERABBIT_REVIEW=true
Containerized/Docker Environments
docker run -v ~/.coderabbit:/root/.coderabbit ...
docker run -e CODERABBIT_API_TOKEN="..." ...
Non-Interactive/Headless Authentication
coderabbit auth login --token "cr_xxxxxxxxxxxxx"
Step 7.5 Flow Logic
┌─────────────────────────────────────────────────────────────────┐
│ ✅ ALL 3 RING REVIEWERS PASSED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Checking CodeRabbit CLI availability... │
│ │
│ CodeRabbit provides additional AI-powered code review that │
│ catches race conditions, memory leaks, security vulnerabilities,│
│ and edge cases that may complement Bee reviewers. │
│ │
└─────────────────────────────────────────────────────────────────┘
⛔ HARD GATE: CodeRabbit Execution Rules (NON-NEGOTIABLE)
| Scenario | Rule | Action |
|---|
| Installed & authenticated | MANDATORY - CANNOT skip | Run CodeRabbit review, no prompt |
| Not installed | MUST ask user about installation | Present installation option |
| User declines installation | Optional - can proceed | Skip and continue to Step 8 |
Why this distinction:
- If CodeRabbit IS installed → User has committed to using it → MUST run
- If CodeRabbit is NOT installed → User choice to add it → MUST ask, but can decline
FLOW:
1. Run CodeRabbit Installation Check
2. IF installed AND authenticated → Run CodeRabbit (MANDATORY, NO prompt, CANNOT skip)
3. IF installed BUT NOT authenticated → Guide authentication (REQUIRED before proceeding)
4. IF NOT installed → MUST ask user about installation (REQUIRED prompt)
5. IF user declines installation → Skip CodeRabbit, proceed to Step 8 (only valid skip path)
Anti-Rationalization for CodeRabbit Execution
| Rationalization | Why It's WRONG | Required Action |
|---|
| "CodeRabbit is optional, I'll skip it" | If installed, it's MANDATORY. Optional only means installation is optional. | Run CodeRabbit if installed |
| "Bee reviewers passed, that's enough" | Different tools catch different issues. CodeRabbit complements Bee. | Run CodeRabbit if installed |
| "User didn't ask for CodeRabbit" | User installed it. Installation = consent to mandatory execution. | Run CodeRabbit if installed |
| "Takes too long, skip this time" | Time is irrelevant. Installed = mandatory. | Run CodeRabbit if installed |
| "I'll just proceed without asking about install" | MUST ask every user if they want to install. No silent skips. | Ask user about installation |
Step 7.5.1: Check CodeRabbit Installation
Run the CodeRabbit Installation Check command.
IF INSTALLED AND AUTHENTICATED → MANDATORY EXECUTION (CANNOT SKIP):
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI detected - MANDATORY EXECUTION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit CLI is installed and authenticated. │
│ │
│ ⛔ CodeRabbit review is MANDATORY when installed. │
│ This step CANNOT be skipped. Proceeding automatically... │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Proceed directly to Step 7.5.2 (Run CodeRabbit Review) - NO user prompt, NO skip option
IF NOT INSTALLED → MUST ASK USER (REQUIRED PROMPT):
⛔ You MUST present this prompt to the user. Silent skips are FORBIDDEN.
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ CodeRabbit CLI not found - INSTALLATION PROMPT REQUIRED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit CLI is not installed on your system. │
│ │
│ CodeRabbit provides additional AI-powered review that catches: │
│ • Race conditions and concurrency issues │
│ • Memory leaks and resource management │
│ • Security vulnerabilities │
│ • Edge cases missed by other reviewers │
│ │
│ ⛔ You MUST choose one of the following options: │
│ │
│ (a) Yes, install CodeRabbit CLI (I'll guide you) │
│ (b) No, skip CodeRabbit and proceed to Gate 5 │
│ │
│ ⚠️ ENVIRONMENT CHECK: │
│ • Interactive terminal with browser? → Standard install │
│ • CI/headless? → Requires API token auth │
│ • Container? → See Environment-Specific Guidance above │
│ │
└─────────────────────────────────────────────────────────────────┘
If user selects (a) Yes, install:
→ Proceed to Installation Flow below
If user selects (b) No, skip:
→ Record: "CodeRabbit review: SKIPPED (not installed, user declined installation)"
→ Proceed to Step 8 (Success Output)
→ This is the ONLY valid path to skip CodeRabbit
Step 7.5.1a: CodeRabbit Installation Flow
┌─────────────────────────────────────────────────────────────────┐
│ 📦 INSTALLING CODERABBIT CLI │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ⚠️ ENVIRONMENT CHECK FIRST: │
│ │
│ This installation requires: │
│ • curl command available │
│ • Write access to $HOME or /usr/local/bin │
│ • Internet access to cli.coderabbit.ai │
│ • Non-containerized environment (or persistent storage) │
│ │
│ If in CI/container, see "Environment-Specific Guidance" above. │
│ │
└─────────────────────────────────────────────────────────────────┘
Check environment before proceeding:
curl --version && echo "curl: OK" || echo "curl: MISSING"
test -w "$HOME" && echo "HOME writable: OK" || echo "HOME writable: NO"
curl -sI https://cli.coderabbit.ai | head -1 | grep -q "200\|301\|302" && echo "Network: OK" || echo "Network: BLOCKED"
If prerequisites pass, install:
┌─────────────────────────────────────────────────────────────────┐
│ 📦 Step 1: Installing CodeRabbit CLI... │
└─────────────────────────────────────────────────────────────────┘
curl -fsSL https://cli.coderabbit.ai/install.sh | sh
After installation, verify: Run the CodeRabbit Installation Check command.
If installation successful:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI installed successfully! │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 2: Authentication required │
│ │
│ Choose your authentication method: │
│ │
│ (a) Browser login (interactive - opens browser) │
│ → Best for: Local development with GUI │
│ → Command: coderabbit auth login │
│ │
│ (b) API token (headless - no browser needed) │
│ → Best for: CI/CD, containers, SSH sessions │
│ → Get token: https://app.coderabbit.ai/settings/api-tokens│
│ → Command: coderabbit auth login --token "cr_xxx" │
│ │
│ (c) Skip authentication and CodeRabbit review │
│ │
│ Note: Free tier allows 1 review/hour. │
│ Paid plans get enhanced reviews + higher limits. │
│ │
└─────────────────────────────────────────────────────────────────┘
If user selects (a) Browser login:
coderabbit auth login
If user selects (b) API token:
coderabbit auth login --token "cr_xxxxxxxxxxxxx"
After authentication:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ CodeRabbit CLI ready! │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Installation: Complete │
│ Authentication: Complete │
│ │
│ Proceeding to CodeRabbit review... │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Proceed to Step 7.5.2 (Run CodeRabbit Review)
If installation failed:
┌─────────────────────────────────────────────────────────────────┐
│ ❌ CodeRabbit CLI installation failed │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Error: [error message from curl/sh] │
│ │
│ Troubleshooting: │
│ • Check internet connection │
│ • Try manual install: https://docs.coderabbit.ai/cli/overview │
│ • macOS/Linux only (Windows not supported yet) │
│ │
│ Would you like to: │
│ (a) Retry installation │
│ (b) Skip CodeRabbit and proceed to Gate 5 │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.2: Run CodeRabbit Review
⛔ GRANULAR VALIDATION: CodeRabbit MUST validate at the most granular level available.
DETERMINE VALIDATION SCOPE:
1. Check if current work has subtasks (from gate0_handoff or implementation context)
2. IF subtasks exist → Validate EACH SUBTASK separately
3. IF no subtasks → Validate the TASK as a whole
WHY GRANULAR VALIDATION:
- Subtask-level validation catches issues early
- Easier to pinpoint which subtask introduced problems
- Prevents "works for task A, breaks task B" scenarios
- Enables incremental fixes without re-running entire review
Step 7.5.2a: Determine Validation Scope
validation_scope = {
mode: null, // "subtask" or "task"
units: [], // list of {id, files, commits} to validate
current_index: 0
}
IF gate0_handoff.subtasks exists AND gate0_handoff.subtasks.length > 0:
→ validation_scope.mode = "subtask"
→ FOR EACH subtask in gate0_handoff.subtasks:
→ Get files changed by this subtask (from commits or file mapping)
→ Add to validation_scope.units: {
id: subtask.id,
name: subtask.name,
files: [files touched by this subtask],
base_sha: [sha before subtask],
head_sha: [sha after subtask]
}
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT VALIDATION MODE: SUBTASK-LEVEL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Detected [N] subtasks. Will validate each separately: │
│ │
│ 1. [subtask-1-id]: [subtask-1-name] │
│ Files: [file1.php, file2.php] │
│ │
│ 2. [subtask-2-id]: [subtask-2-name] │
│ Files: [file3.php, file4.php] │
│ │
│ ... (up to N subtasks) │
│ │
└─────────────────────────────────────────────────────────────────┘
ELSE:
→ validation_scope.mode = "task"
→ Add single unit: {
id: unit_id,
name: implementation_summary,
files: implementation_files,
base_sha: base_sha,
head_sha: head_sha
}
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT VALIDATION MODE: TASK-LEVEL │
├─────────────────────────────────────────────────────────────────┤
│ │
│ No subtasks detected. Validating entire task: │
│ │
│ Task: [unit_id] │
│ Files: [N] files changed │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.2b: Run CodeRabbit for Each Validation Unit
coderabbit_results = {
overall_status: "PASS", // PASS only if ALL units pass
units: []
}
FOR EACH unit IN validation_scope.units:
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 🔍 VALIDATING: [unit.id] ([current]/[total]) │
├─────────────────────────────────────────────────────────────────┤
│ Name: [unit.name] │
│ Files: [unit.files.join(", ")] │
└─────────────────────────────────────────────────────────────────┘
coderabbit --prompt-only --type uncommitted --base [base_branch]
coderabbit --prompt-only --type uncommitted --base-commit [unit.base_sha]
Parse output and record:
unit_result = {
id: unit.id,
status: "PASS" | "ISSUES_FOUND",
issues: {
critical: [list],
high: [list],
medium: [list],
low: [list]
}
}
coderabbit_results.units.push(unit_result)
IF unit_result.issues.critical.length > 0 OR unit_result.issues.high.length > 0:
→ coderabbit_results.overall_status = "ISSUES_FOUND"
─────────────────────────────────────────────────────────────────
⛔ MANDATORY: APPEND FINDINGS TO .coderabbit-findings.md
─────────────────────────────────────────────────────────────────
After EACH unit validation, append results to findings file:
IF .coderabbit-findings.md does NOT exist:
→ Create file with header (see "Findings File Format" below)
APPEND to .coderabbit-findings.md:
Unit: [unit.id] - [unit.name]
Validated: [timestamp]
Status: [PASS | ISSUES_FOUND]
Files: [unit.files.join(", ")]
Issues Found
| # | Severity | Description | File:Line | Recommendation |
|---|
| 1 | [severity] | [description] | [file:line] | [recommendation] |
| ... | ... | ... | ... | ... |
This ensures ALL findings are accumulated for review before commit.
AFTER ALL UNITS VALIDATED:
Display summary:
┌─────────────────────────────────────────────────────────────────┐
│ 📊 CODERABBIT VALIDATION SUMMARY │
├─────────────────────────────────────────────────────────────────┤
│ Mode: [SUBTASK-LEVEL | TASK-LEVEL] │
│ Units Validated: [N] │
│ Overall Status: [PASS | ISSUES_FOUND] │
│ │
│ Per-Unit Results: │
│ ┌──────────────┬────────────┬──────┬──────┬────────┬─────┐ │
│ │ Unit ID │ Status │ Crit │ High │ Medium │ Low │ │
│ ├──────────────┼────────────┼──────┼──────┼────────┼─────┤ │
│ │ [subtask-1] │ ✅ PASS │ 0 │ 0 │ 0 │ 1 │ │
│ │ [subtask-2] │ ❌ ISSUES │ 1 │ 2 │ 0 │ 0 │ │
│ └──────────────┴────────────┴──────┴──────┴────────┴─────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Parse CodeRabbit output for:
- Critical issues
- High severity issues
- Security vulnerabilities
- Performance concerns
Findings File Format (.coderabbit-findings.md)
This file accumulates ALL CodeRabbit findings across all validated units.
# CodeRabbit Findings
**Generated:** [initial timestamp]
**Last Updated:** [latest timestamp]
**Total Units Validated:** [N]
**Overall Status:** [PASS | ISSUES_FOUND]
## Summary
| Severity | Count | Status |
|----------|-------|--------|
| Critical | [N] | [N pending / N fixed] |
| High | [N] | [N pending / N fixed] |
| Medium | [N] | [N pending / N fixed] |
| Low | [N] | [N pending / N fixed] |
---
## Unit: [subtask-1-id] - [subtask-1-name]
**Validated:** [timestamp]
**Status:** [PASS | ISSUES_FOUND]
**Files:** [file1.php, file2.php]
### Issues Found
| # | Severity | Description | File:Line | Recommendation | Status |
|---|----------|-------------|-----------|----------------|--------|
| 1 | CRITICAL | Unhandled exception in controller | UserController.php:45 | Add try/catch | PENDING |
| 2 | HIGH | Unchecked null return | UserRepository.php:123 | Handle null | PENDING |
---
## Unit: [subtask-2-id] - [subtask-2-name]
**Validated:** [timestamp]
**Status:** PASS
**Files:** [file3.php]
### Issues Found
_No issues found._
---
[... additional units ...]
File Location: Project root (.coderabbit-findings.md)
Lifecycle:
- Created when first CodeRabbit validation runs
- Appended after each unit validation
- Displayed before commit (Step 8)
- User decides: fix issues or acknowledge and proceed
- After commit, file can be deleted or kept for audit
Step 7.5.3: Handle CodeRabbit Findings
⛔ CRITICAL: You are an ORCHESTRATOR. You CANNOT edit source files directly.
You MUST dispatch the implementation agent to fix issues.
⛔ GRANULAR FIX DISPATCH: Fixes MUST be dispatched per-unit (subtask or task).
IF coderabbit_results.overall_status == "ISSUES_FOUND":
→ FIRST: Display EACH issue in detail (REQUIRED before any action):
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ CODERABBIT ISSUES FOUND - DETAILED DESCRIPTION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UNIT: [subtask-1] - [subtask name] │
│ ───────────────────────────────────────────────────────────────│
│ Issue #1 [CRITICAL] │
│ Description: Unhandled exception in controller │
│ File: src/UserController.php:45 │
│ Code Context: │
│ 43 | public function store(Request $request) { │
│ 44 | $user = $this->service->create($request->all()); │
│ 45 | return response()->json($user); │
│ Why it matters: Exception propagates uncaught to client │
│ Recommendation: Wrap in try/catch, return proper response │
│ │
│ Issue #2 [HIGH] │
│ Description: Unchecked null return from repository │
│ File: src/UserRepository.php:123 │
│ Code Context: │
│ 121 | public function findById(int $id): User { │
│ 122 | $user = User::find($id); // ← CAN BE NULL │
│ 123 | return $user->toArray(); // ← NULL DEREFERENCE │
│ Why it matters: Null dereference causes fatal error │
│ Recommendation: Check null before accessing properties │
│ │
│ UNIT: [subtask-2] - [subtask name] │
│ ───────────────────────────────────────────────────────────────│
│ Issue #3 [HIGH] │
│ Description: SQL injection vulnerability │
│ File: src/ReportQuery.php:89 │
│ Code Context: │
│ 87 | public function buildQuery(string $input): string { │
│ 88 | return "SELECT * FROM users WHERE │
│ 89 | name = '$input'"; // ← INJECTABLE │
│ Why it matters: Attacker can execute arbitrary SQL │
│ Recommendation: Use parameterized queries / Query Builder │
│ │
└─────────────────────────────────────────────────────────────────┘
→ THEN: Ask user for action:
"CodeRabbit found [N] issues in [M] units. What would you like to do?"
(a) Fix all issues - dispatch implementation agent per unit
(b) Proceed to Gate 5 (acknowledge risk)
(c) Review findings in detail (show code context)
IF user selects (a) Fix issues:
→ ⛔ DO NOT edit files directly
→ FOR EACH unit WITH issues (validation_scope.units where status == "ISSUES_FOUND"):
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 🔧 DISPATCHING FIX: [unit.id] ([current]/[total with issues]) │
├─────────────────────────────────────────────────────────────────┤
│ Unit: [unit.name] │
│ Critical Issues: [N] │
│ High Issues: [N] │
└─────────────────────────────────────────────────────────────────┘
→ DISPATCH implementation agent with unit-specific findings:
Task:
subagent_type: "[same agent used in Gate 0]"
description: "Fix CodeRabbit issues for [unit.id]"
prompt: |
## CodeRabbit Issues to Fix - [unit.id]
**Scope:** This fix is for [subtask/task]: [unit.name]
**Files in Scope:** [unit.files.join(", ")]
The following issues were found by CodeRabbit CLI external review
for THIS SPECIFIC [subtask/task].
⚠️ IMPORTANT: Only fix issues in files belonging to this unit:
[unit.files list]
### Critical Issues
[list from unit.issues.critical]
### High Issues
[list from unit.issues.high]
## Requirements
1. Fix each issue following Bee Standards
2. Only modify files in scope: [unit.files]
3. Run tests to verify fixes don't break functionality
4. Commit fixes with message referencing unit: "fix([unit.id]): [description]"
→ Wait for agent to complete
→ Record fix result for this unit
→ VALIDATE EACH ISSUE INDIVIDUALLY:
┌─────────────────────────────────────────────────────────────────┐
│ 🔍 VALIDATING FIXES FOR: [unit.id] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Each issue MUST be validated individually: │
│ │
│ Issue #1: [issue description] │
│ File: [file:line] │
│ Severity: CRITICAL │
│ Fix Applied: [description of fix] │
│ Validation: ✅ RESOLVED / ❌ NOT RESOLVED │
│ Evidence: [code snippet or test result] │
│ │
│ Issue #2: [issue description] │
│ File: [file:line] │
│ Severity: HIGH │
│ Fix Applied: [description of fix] │
│ Validation: ✅ RESOLVED / ❌ NOT RESOLVED │
│ Evidence: [code snippet or test result] │
│ │
│ ... (repeat for ALL issues) │
│ │
└─────────────────────────────────────────────────────────────────┘
→ IF any issue NOT RESOLVED:
→ Identify the correct agent for re-dispatch:
- Check gate0_handoff.implementation_agent (if available)
- OR infer from file type:
- *.php files → bee:backend-engineer-php
- *.ts files (backend) → bee:backend-engineer-typescript
- *.ts/*.tsx files (frontend) → bee:frontend-engineer
→ Re-dispatch ONLY unresolved issues to the correct agent:
Task:
subagent_type: "[correct agent based on file type or gate0_handoff]"
model: "opus"
description: "Retry fix for unresolved issues in [unit.id]"
prompt: |
## RETRY: Unresolved CodeRabbit Issues - [unit.id]
Previous fix attempt did NOT resolve these issues.
This is attempt [N] of 2 maximum.
### Unresolved Issues (MUST FIX)
| # | Severity | Description | File:Line | Previous Attempt | Why It Failed |
|---|----------|-------------|-----------|------------------|---------------|
| [issue.id] | [severity] | [description] | [file:line] | [what was tried] | [why not resolved] |
### Requirements
1. Review the previous fix attempt and understand why it failed
2. Apply a different/better solution
3. Verify the fix resolves the issue
4. Run relevant tests
5. Commit with message: "fix([unit.id]): retry [issue description]"
→ Max 2 fix attempts per issue
→ IF issue still NOT RESOLVED after 2 attempts:
→ Mark as UNRESOLVED_ESCALATE
→ Add to escalation report for manual review
→ Record per-issue validation results:
unit_validation = {
id: unit.id,
issues_validated: [
{
issue_id: 1,
description: "[issue]",
severity: "CRITICAL",
file: "[file:line]",
fix_applied: "[description]",
status: "RESOLVED" | "NOT_RESOLVED",
evidence: "[snippet or test]",
attempts: 1
},
...
],
all_resolved: true | false
}
→ AFTER ALL UNITS FIXED:
Display:
┌─────────────────────────────────────────────────────────────────┐
│ ✅ FIX DISPATCH COMPLETE │
├─────────────────────────────────────────────────────────────────┤
│ Units Fixed: [N] / [total with issues] │
│ Total Issues Validated: [N] │
│ Issues Resolved: [N] / [N] │
│ │
│ Per-Unit Fix Status: │
│ ┌──────────────┬────────────┬───────────────────────┐ │
│ │ Unit ID │ Status │ Commit │ │
│ ├──────────────┼────────────┼───────────────────────┤ │
│ │ [subtask-1] │ ✅ FIXED │ abc123 │ │
│ │ [subtask-2] │ ✅ FIXED │ def456 │ │
│ └──────────────┴────────────┴───────────────────────┘ │
│ │
│ Issue-Level Validation Details: │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ UNIT: [subtask-1] │ │
│ ├──────────────────────────────────────────────────────────┤ │
│ │ #1 [CRITICAL] Unhandled exception in controller │ │
│ │ File: src/UserController.php:45 │ │
│ │ Fix: Added try/catch with proper response │ │
│ │ Status: ✅ RESOLVED │ │
│ │ Evidence: Test UserControllerTest.php passes │ │
│ ├──────────────────────────────────────────────────────────┤ │
│ │ #2 [HIGH] Unchecked null return │ │
│ │ File: src/UserRepository.php:67 │ │
│ │ Fix: Added error check with proper handling │ │
│ │ Status: ✅ RESOLVED │ │
│ │ Evidence: Error path verified in unit test │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
LEGACY FLOW (when validation_scope.mode == "task"):
IF CodeRabbit found CRITICAL or HIGH issues:
→ Display findings to user
→ Ask: "CodeRabbit found [N] critical/high issues. Fix now or proceed anyway?"
(a) Fix issues - dispatch to implementation agent
(b) Proceed to Gate 5 (acknowledge risk)
(c) Review findings in detail
IF user selects (a) Fix issues:
→ ⛔ DO NOT edit files directly
→ DISPATCH implementation agent with CodeRabbit findings:
Task:
subagent_type: "[same agent used in Gate 0]"
model: "opus"
description: "Fix CodeRabbit issues for [unit_id]"
prompt: |
## CodeRabbit Issues to Fix
The following issues were found by CodeRabbit CLI external review.
Fix ALL Critical and High severity issues.
### Critical Issues
[list from CodeRabbit output]
### High Issues
[list from CodeRabbit output]
## Requirements
1. Fix each issue following Bee Standards
2. Run tests to verify fixes don't break functionality
3. Commit fixes with descriptive message
→ After agent completes, re-run CodeRabbit: `coderabbit --prompt-only`
→ If CodeRabbit issues remain, repeat fix cycle (max 2 iterations for CodeRabbit)
→ ⛔ AFTER CodeRabbit passes, MUST re-run Bee reviewers:
┌─────────────────────────────────────────────────────────────────┐
│ 🔄 RE-RUNNING RING REVIEWERS AFTER CODERABBIT FIXES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ CodeRabbit fixes may have introduced new issues detectable by │
│ Bee reviewers. Re-validation is MANDATORY before Gate 5. │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.5.3a: Re-Run All 6 Bee Reviewers
─────────────────────────────────────────
1. Get new HEAD_SHA after CodeRabbit fixes
2. Dispatch all 6 reviewers in parallel (per Step 3):
- bee:code-reviewer
- bee:business-logic-reviewer
- bee:security-reviewer
- bee:test-reviewer
- bee:nil-safety-reviewer
- bee:consequences-reviewer
3. Wait for all 6 to complete
Step 7.5.3b: Handle Bee Reviewer Results
─────────────────────────────────────────
IF all 6 Bee reviewers PASS:
→ Proceed to Step 8 (Success Output)
IF any Bee reviewer finds CRITICAL/HIGH/MEDIUM issues:
→ Increment ring_revalidation_iterations counter
→ IF ring_revalidation_iterations >= 2:
→ ESCALATE: "Max iterations reached after CodeRabbit fixes"
→ Go to Step 9 (Escalate)
→ DISPATCH implementation agent to fix Bee reviewer issues
→ After fixes committed:
→ Re-run CodeRabbit: `coderabbit --prompt-only`
→ IF CodeRabbit passes:
→ Re-run all 6 Bee reviewers (loop back to Step 7.5.3a)
→ IF CodeRabbit finds issues:
→ Fix CodeRabbit issues first, then re-run Bee reviewers
State tracking for CodeRabbit fix cycle:
```
coderabbit_fix_state = {
coderabbit_iterations: 0, // max 2 for CodeRabbit-only fixes
ring_revalidation_iterations: 0, // max 2 for Bee reviewer re-runs
total_max_iterations: 4 // absolute cap: 2 CR + 2 Bee
}
```
IF CodeRabbit found only MEDIUM/LOW issues:
→ Display summary
→ ⛔ DO NOT edit files directly to add TODOs
→ DISPATCH implementation agent to add TODO comments:
Task:
subagent_type: "[same agent used in Gate 0]"
description: "Add TODO comments for CodeRabbit findings"
prompt: |
Add TODO comments for these CodeRabbit findings:
[list MEDIUM/LOW issues with file:line]
Format: // TODO(coderabbit): [issue description]
→ After TODO comments added (code changed):
→ Re-run all 6 Bee reviewers (per Step 7.5.3a above)
→ IF Bee reviewers PASS: Proceed to Step 8
→ IF Bee reviewers find issues: Fix and re-run (max 2 iterations)
IF CodeRabbit found no issues:
→ Display: "✅ CodeRabbit review passed - no additional issues found"
→ No code changes made by CodeRabbit flow
→ Proceed directly to Step 8 (no Bee re-run needed)
Anti-Rationalization for Direct Editing
See shared-patterns/orchestrator-direct-editing-anti-rationalization.md - same table applies here.
Applies to: Step 6 (Fix dispatch after Bee reviewers) & Step 7.5.3 (Fix dispatch after CodeRabbit)
Step 7.5.4: CodeRabbit Results Summary
## CodeRabbit External Review
**Status:** [PASS|ISSUES_FOUND|SKIPPED]
**Validation Mode:** [SUBTASK-LEVEL|TASK-LEVEL]
**Units Validated:** [N]
**Total Issues Found:** [N]
**Issues Resolved:** [N]/[N]
### Per-Unit Validation Results
| Unit ID | Unit Name | Status | Critical | High | Medium | Low |
|---------|-----------|--------|----------|------|--------|-----|
| [subtask-1] | [name] | ✅ PASS | 0 | 0 | 0 | 1 |
| [subtask-2] | [name] | ✅ FIXED | 1→0 | 2→0 | 0 | 0 |
| [task-id] | [name] | ✅ PASS | 0 | 0 | 0 | 0 |
### Issues Found - Detailed Description (ALWAYS shown when issues exist)
#### Unit: [subtask-2]
| # | Severity | Description | File:Line | Code Context | Why It Matters | Recommendation |
|---|----------|-------------|-----------|--------------|----------------|----------------|
| 1 | CRITICAL | Unhandled exception | UserController.php:45 | `service->create()` uncaught | Fatal error exposed | Add try/catch |
| 2 | HIGH | Null dereference | UserRepository.php:123 | `User::find()` can return null | Fatal error | Check null before use |
| 3 | HIGH | SQL injection | ReportQuery.php:89 | `"...name = '$input'"` | Security breach | Parameterized query |
### Issue-Level Validation (REQUIRED after fixes are applied)
#### Unit: [subtask-2]
| # | Severity | Description | File:Line | Fix Applied | Status | Evidence |
|---|----------|-------------|-----------|-------------|--------|----------|
| 1 | CRITICAL | Unhandled exception in controller | UserController.php:45 | Added try/catch with proper response | ✅ RESOLVED | UserControllerTest.php passes |
| 2 | HIGH | Null dereference from repository | UserRepository.php:123 | Added null check before access | ✅ RESOLVED | Null path tested |
| 3 | HIGH | SQL injection vulnerability | ReportQuery.php:89 | Used Query Builder bindings | ✅ RESOLVED | Security test added |
#### Unit: [subtask-3] (if applicable)
| # | Severity | Description | File:Line | Fix Applied | Status | Evidence |
|---|----------|-------------|-----------|-------------|--------|----------|
| 1 | HIGH | Missing input validation | UserRequest.php:34 | Added Form Request validation | ✅ RESOLVED | Validation test passes |
### Overall Summary by Severity
| Severity | Found | Resolved | Remaining | Action |
|----------|-------|----------|-----------|--------|
| Critical | [N] | [N] | 0 | Fixed |
| High | [N] | [N] | 0 | Fixed |
| Medium | [N] | [N] | 0 | TODO added |
| Low | [N] | - | [N] | TODO added |
CodeRabbit Skip Scenarios (ONLY VALID PATHS)
⛔ CodeRabbit can ONLY be skipped in these specific scenarios. Any other skip is a VIOLATION.
| Scenario | Record As | Next Step | Why Valid |
|---|
| CLI not installed, user explicitly declines install | SKIPPED (not installed, user declined) | Step 8 | User was asked and chose not to install |
| Installation failed after attempt, user skips | SKIPPED (installation failed) | Step 8 | Technical failure, user informed |
| Authentication failed after attempt, user skips | SKIPPED (auth failed) | Step 8 | Technical failure, user informed |
| Environment doesn't support (CI/container) | SKIPPED (unsupported environment) | Step 8 | Technical limitation |
⛔ INVALID SKIP SCENARIOS (FORBIDDEN):
| Invalid Scenario | Why FORBIDDEN | Required Action |
|---|
| CLI installed but "skipped for speed" | Installed = MANDATORY | Run CodeRabbit |
| CLI installed but "Bee reviewers passed" | Complementary tools, both required | Run CodeRabbit |
| CLI not installed, no prompt shown | MUST ask user about installation | Show installation prompt |
| Silent skip without user interaction | All skips require explicit user choice | Ask user |
⛔ NON-NEGOTIABLE: When CodeRabbit CLI IS installed and authenticated, execution is MANDATORY - it CANNOT be skipped under any circumstance.
Step 7.6: OpenCode External Review
⛔ OpenCode provides a second AI perspective using a different model via OpenCode CLI.
REQUIRED SUB-SKILL: See bee:opencode-review for full details.
OpenCode Integration Overview
┌─────────────────────────────────────────────────────────────────┐
│ OPENCODE EXTERNAL REVIEW FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Check if OpenCode CLI is installed (which opencode) │
│ 2. Collect diff: git diff [base_sha]..[head_sha] │
│ 3. Send to external model via: opencode run -m [model] -f diff │
│ 4. Parse response for verdict + issues │
│ 5. Present findings (advisory, not hard gate) │
│ │
│ DIFFERENCE FROM CODERABBIT: │
│ • OpenCode = advisory (user decides to act) │
│ • CodeRabbit = mandatory when installed │
│ • OpenCode CRITICAL findings MUST be presented to user │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 7.6.1: Check OpenCode Installation
which opencode
| Result | Action |
|---|
| Found | Proceed to Step 7.6.2 |
| Not found | Record opencode_status = NOT_INSTALLED, skip to Step 8 |
If skip_opencode input is true: Record opencode_status = SKIPPED, skip to Step 8.
Step 7.6.2: Collect Diff and Execute Review
BASE_SHA="[base_sha from review_state]"
HEAD_SHA="[head_sha from review_state]"
git diff "$BASE_SHA".."$HEAD_SHA" > /tmp/bee-opencode-review-diff.txt
opencode run \
-m "[opencode_model input or default: bailian-coding-plan/qwen3-max-2026-01-23]" \
-f docs/opencode-instructions.md \
-f /tmp/bee-opencode-review-diff.txt \
--format json \
"Review the attached code diff following the instructions provided. Output your review as markdown."
Model Selection (use opencode_model input or default):
| Model | When to Use |
|---|
bailian-coding-plan/qwen3-max-2026-01-23 | Default - strong general review |
bailian-coding-plan/qwen3-coder-plus | Code-focused review |
opencode/gpt-5-nano | Fast lightweight review |
Timeout: 120 seconds. If OpenCode times out, record opencode_status = SKIPPED with reason and proceed.
Step 7.6.3: Parse and Handle Results
Parse the JSON output from OpenCode and extract the assistant's review.
opencode_result = {
model: "[model used]",
verdict: "[PASS|FAIL|NEEDS_DISCUSSION]",
issues: {
critical: [N],
high: [N],
medium: [N],
low: [N]
},
raw_output: "[full review text]"
}
| OpenCode Verdict | opencode_status | Action |
|---|
| PASS | PASS | Record in summary, proceed to Step 8 |
| FAIL (CRITICAL/HIGH) | ISSUES_FOUND | Present to user, ask: fix or acknowledge |
| NEEDS_DISCUSSION | ISSUES_FOUND | Present findings, ask user for decision |
| Error/Timeout | SKIPPED | Log error, proceed to Step 8 |
Step 7.6.4: Handle OpenCode Findings
IF opencode_result.verdict == "FAIL" AND (critical > 0 OR high > 0):
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ OPENCODE FOUND CRITICAL/HIGH ISSUES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Model: [model used] │
│ Issues: [N] Critical, [N] High, [N] Medium, [N] Low │
│ │
│ [detailed issue list from OpenCode] │
│ │
│ OpenCode review is advisory. What would you like to do? │
│ │
│ (a) Fix issues - dispatch implementation agent │
│ (b) Acknowledge and proceed (issues documented) │
│ │
└─────────────────────────────────────────────────────────────────┘
IF user selects (a):
→ Dispatch implementation agent with OpenCode findings
→ After fixes, re-run OpenCode review (max 1 re-run)
→ After OpenCode re-run, MUST re-run Bee reviewers (Step 3)
IF user selects (b):
→ Record: "OpenCode issues acknowledged by user"
→ Proceed to Step 8
IF opencode_result.verdict == "PASS" OR only MEDIUM/LOW issues:
→ Record findings in summary
→ Proceed to Step 8
Step 7.6.5: Cleanup
rm -f /tmp/bee-opencode-review-diff.txt
OpenCode Skip Scenarios (VALID PATHS)
| Scenario | Record As | Next Step |
|---|
| CLI not installed | NOT_INSTALLED | Step 8 |
skip_opencode = true | SKIPPED | Step 8 |
| Execution timeout/error | SKIPPED (error) | Step 8 |
| User declines fixes, acknowledges issues | ISSUES_FOUND (acknowledged) | Step 8 |
Anti-Rationalization for OpenCode Execution
| Rationalization | Why It's WRONG | Required Action |
|---|
| "Bee reviewers already covered everything" | Different models catch different issues - shared biases exist | Run OpenCode review if installed |
| "OpenCode model is weaker" | Model strength is irrelevant - diversity of perspective matters | Run OpenCode review if installed |
| "Results will duplicate Bee findings" | Unique findings are common across different models | Run OpenCode review if installed |
| "Too much review overhead" | One extra minute for a fresh perspective is minimal | Run OpenCode review if installed |
Step 8: Display Accumulated Findings & Prepare Success Output
⛔ BEFORE generating success output, MUST display accumulated CodeRabbit and OpenCode findings.
Step 8.1: Display Accumulated CodeRabbit Findings
IF .coderabbit-findings.md exists:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 CODERABBIT FINDINGS - ACCUMULATED DURING REVIEW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ The following issues were identified by CodeRabbit during the │
│ review process. Review before proceeding to commit. │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Display contents of .coderabbit-findings.md
→ Show summary table:
┌─────────────────────────────────────────────────────────────────┐
│ 📊 CODERABBIT FINDINGS SUMMARY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ | Severity | Count | Status | │
│ |----------|-------|--------| │
│ | Critical | [N] | [pending/fixed] | │
│ | High | [N] | [pending/fixed] | │
│ | Medium | [N] | [pending/fixed] | │
│ | Low | [N] | [pending/fixed] | │
│ │
│ Total Issues: [N] | Fixed: [N] | Pending: [N] │
│ │
└─────────────────────────────────────────────────────────────────┘
→ Ask user:
┌─────────────────────────────────────────────────────────────────┐
│ ❓ ACTION REQUIRED │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [N] CodeRabbit issues are pending. What would you like to do? │
│ │
│ (a) Fix all pending issues now (dispatch implementation agent)│
│ (b) Review and fix issues one-by-one (interactive mode) │
│ (c) Acknowledge and proceed to commit (issues documented) │
│ │
│ Note: Choosing (c) will include findings file in commit for │
│ tracking. Issues remain documented for future fixing. │
│ │
└─────────────────────────────────────────────────────────────────┘
IF user selects (a) Fix all issues:
→ Dispatch implementation agent with ALL pending issues from findings file
→ After fixes, update .coderabbit-findings.md (mark issues as FIXED)
→ Re-run CodeRabbit validation for affected files
→ Loop back to Step 8.1 to display updated findings
IF user selects (b) Interactive mode (one-by-one):
→ Go to Step 8.1.1 (Interactive Issue Review)
IF user selects (c) Acknowledge and proceed:
→ Record: "CodeRabbit issues acknowledged by user"
→ Include .coderabbit-findings.md in commit (for audit trail)
→ Proceed to Step 8.2 (Success Output)
─────────────────────────────────────────────────────────────────
Step 8.1.1: Interactive Issue Review (One-by-One)
─────────────────────────────────────────────────────────────────
issues_to_fix = []
issues_to_skip = []
FOR EACH issue IN pending_issues (ordered by severity: CRITICAL → HIGH → MEDIUM → LOW):
Display:
┌─────────────────────────────────────────────────────────────────┐
│ 🔍 ISSUE [current]/[total] - [SEVERITY] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Unit: [unit.id] - [unit.name] │
│ File: [file:line] │
│ │
│ Description: │
│ [issue description] │
│ │
│ Code Context: │
│ [code snippet around the issue] │
│ │
│ Why it matters: │
│ [explanation of impact] │
│ │
│ Recommendation: │
│ [suggested fix] │
│ │
├─────────────────────────────────────────────────────────────────┤
│ What would you like to do with this issue? │
│ │
│ (f) Fix this issue │
│ (s) Skip this issue (acknowledge) │
│ (a) Fix ALL remaining issues │
│ (k) Skip ALL remaining issues │
│ │
└─────────────────────────────────────────────────────────────────┘
IF user selects (f) Fix:
→ Add to issues_to_fix list
→ Continue to next issue
IF user selects (s) Skip:
→ Add to issues_to_skip list
→ Continue to next issue
IF user selects (a) Fix ALL remaining:
→ Add current + all remaining to issues_to_fix list
→ Break loop
IF user selects (k) Skip ALL remaining:
→ Add current + all remaining to issues_to_skip list
→ Break loop
AFTER loop completes:
Display summary:
┌─────────────────────────────────────────────────────────────────┐
│ 📋 INTERACTIVE REVIEW COMPLETE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Issues to fix: [N] │
│ [list of issues selected for fixing] │
│ │
│ Issues to skip: [N] │
│ [list of issues selected to skip] │
│ │
│ Proceed with this selection? (y/n) │
│ │
└─────────────────────────────────────────────────────────────────┘
IF user confirms (y):
IF issues_to_fix.length > 0:
→ Dispatch implementation agent with ONLY issues_to_fix
→ After fixes, update .coderabbit-findings.md:
- Mark fixed issues as FIXED
- Mark skipped issues as ACKNOWLEDGED
→ Re-run CodeRabbit validation for affected files
→ Loop back to Step 8.1
ELSE:
→ All issues skipped/acknowledged
→ Proceed to Step 8.2 (Success Output)
IF user cancels (n):
→ Return to Step 8.1 main prompt
ELSE (no findings file exists):
→ CodeRabbit was skipped or found no issues
→ Proceed directly to Step 8.2 (Success Output)
Step 8.1.5: Visual Review Report
MANDATORY: Generate a visual HTML report before presenting the review summary.
Invokes Skill("bee:visual-explainer") to produce a self-contained HTML page showing review results visually. This complements the markdown output with an interactive browser view.
Read the code-diff template first: Read default/skills/visual-explainer/templates/code-diff.html to absorb the patterns before generating.
Generate the HTML report with these sections:
1. Review Dashboard
- Overall status (PASS/FAIL) with large status indicator
- Unit ID, iterations count, total duration
- KPI cards: Total issues found, issues fixed, issues remaining, reviewers passed (X/6)
2. Reviewer Verdicts Panel
- 6 reviewer cards in a grid layout, each showing:
- Reviewer name, PASS/FAIL badge
- Issue count by severity (severity badges)
- Key findings summary (1-2 lines)
3. Issues by Severity
- Severity breakdown bar (Critical red / High orange / Medium violet / Low dim)
- Per-issue cards with: severity badge, description, file:line reference, reviewer that found it, recommendation
- Issues that were fixed during iterations: show before (issue) vs after (fix applied) using diff panels
4. CodeRabbit Findings (if applicable)
- Separate section showing CodeRabbit-specific issues
- Status per unit validated
4b. OpenCode Findings (if applicable)
- Model used, verdict, and issue count
- Side-by-side comparison with Bee reviewer findings (unique vs overlapping)
5. Fix Iteration Timeline (if iterations > 0)
- Visual timeline showing: Iteration 1 → Issues found → Fixes applied → Iteration 2 → ...
Output: Save to docs/codereview/review-report-{unit_id}.html
Open in browser:
macOS: open docs/codereview/review-report-{unit_id}.html
Linux: xdg-open docs/codereview/review-report-{unit_id}.html
Tell the user the file path. The visual report opens before the markdown summary is displayed.
See dev-team/skills/shared-patterns/anti-rationalization-visual-report.md for anti-rationalization table.
Step 8.2: Generate Success Output
Generate skill output:
## Review Summary
**Status:** PASS
**Unit ID:** [unit_id]
**Iterations:** [review_state.iterations]
## Issues by Severity
| Severity | Count |
|----------|-------|
| Critical | 0 |
| High | 0 |
| Medium | 0 |
| Low | [count] |
| Cosmetic | [count] |
## Reviewer Verdicts
| Reviewer | Verdict | Issues |
|----------|---------|--------|
| bee:code-reviewer | ✅ PASS | [count] |
| bee:business-logic-reviewer | ✅ PASS | [count] |
| bee:security-reviewer | ✅ PASS | [count] |
| bee:test-reviewer | ✅ PASS | [count] |
| bee:nil-safety-reviewer | ✅ PASS | [count] |
| bee:consequences-reviewer | ✅ PASS | [count] |
## Low/Cosmetic Issues (TODO/FIXME added)
[list with file locations]
## CodeRabbit Findings
**Findings File:** .coderabbit-findings.md
**Total Issues Found:** [N]
**Issues Fixed:** [N]
**Issues Acknowledged:** [N]
**Status:** [ALL_FIXED | ACKNOWLEDGED | NO_ISSUES]
## OpenCode External Review
**Model:** [model used]
**Status:** [PASS | ISSUES_FOUND | SKIPPED | NOT_INSTALLED]
**Issues Found:** [N]
**Issues Fixed:** [N]
**Issues Acknowledged:** [N]
## Handoff to Next Gate
- Review status: COMPLETE
- All blocking issues: RESOLVED
- Reviewers passed: 6/6
- CodeRabbit findings: [status]
- OpenCode findings: [status]
- Ready for Gate 5 (Validation): YES
Step 9: Escalate - Max Iterations Reached
VISUAL REPORT: Generate the same visual HTML report as Step 8.1.5, but with FAIL status prominently displayed. The report highlights unresolved issues in red, shows which reviewers still have FAIL verdicts, and includes the full iteration history. Save to docs/codereview/review-report-{unit_id}.html and open in browser.
Generate skill output:
## Review Summary
**Status:** FAIL
**Unit ID:** [unit_id]
**Iterations:** [max_iterations] (MAX REACHED)
## Issues by Severity
| Severity | Count |
|----------|-------|
| Critical | [count] |
| High | [count] |
| Medium | [count] |
## Unresolved Issues
[list all Critical/High/Medium still open]
## Reviewer Verdicts
| Reviewer | Verdict |
|----------|---------|
| bee:code-reviewer | [PASS/FAIL] |
| bee:business-logic-reviewer | [PASS/FAIL] |
| bee:security-reviewer | [PASS/FAIL] |
## Handoff to Next Gate
- Review status: FAILED
- Unresolved blocking issues: [count]
- Ready for Gate 5: NO
- **Action Required:** User must manually resolve issues
