---
name: review-gate
description: Quality gate for cross-agent review enforcement.
---

# review-gate

Quality gate for cross-agent review enforcement. Blocks agent completion until work is reviewed and approved.

## Purpose

When agents work autonomously (unattended, CI/CD, batch jobs), they may:
- Claim "done" when work is incomplete
- Miss requirements or make incorrect assumptions
- Take shortcuts that don't serve user intent

review-gate enforces an external quality check before the agent can exit.

## Usage

### Enable review requirement

At the start of work that needs review:

```bash
review-gate enable [session_id]
```

This creates a "pending" review state. The agent will be blocked from exiting until approved.

### Approve review

After reviewing work (manually or via reviewer agent):

```bash
review-gate approve [session_id]
```

### Reject review

If issues are found:

```bash
review-gate reject [session_id] "reason" ["issue1" "issue2" ...]
```

### Check status

```bash
review-gate status [session_id]
review-gate list  # all sessions
```

## Session ID

Session ID is auto-detected in this order:
1. Provided argument
2. `REVIEW_SESSION_ID` env var
3. `CLAUDE_SESSION_ID` env var
4. Generated from git branch + commit

## Hook Integration

For Claude Code, add to your project's `.claude/hooks.json`:

```json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "review-gate check",
        "timeout": 30
      }]
    }]
  }
}
```

The Stop hook runs when the agent tries to exit. If review is pending or rejected, exit is blocked.

## State Storage

Review state is stored in `.review-state/` as JSON files. This directory should be gitignored (transient state, not code).

## Commands

| Command | Description | Exit Code |
|---------|-------------|-----------|
| `check [id]` | Check if exit allowed | 0=allowed, 1=blocked |
| `enable [id]` | Enable review requirement | 0 |
| `approve [id]` | Mark as approved | 0 |
| `reject [id] [reason] [issues...]` | Mark as rejected | 0 |
| `status [id]` | Show review state | 0 |
| `list` | List all sessions | 0 |
| `clean [age]` | Remove old states (default: 7d) | 0 |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `REVIEW_SESSION_ID` | Override session ID |
| `REVIEW_STATE_DIR` | Override state directory (default: `./.review-state`) |
| `CLAUDE_SESSION_ID` | Fallback session ID (set by Claude Code) |

## Cross-Agent Pattern

For agents without Stop hooks, use orchestrator pattern:

```bash
# Orchestrator script
review-gate enable "$SESSION_ID"
<spawn worker agent>
# Worker completes...
<spawn reviewer agent>
# Reviewer approves or rejects...
review-gate check "$SESSION_ID" || {
    echo "Review not passed, looping back to worker"
    # ... retry logic
}
```

## Dependencies

- `jq` - JSON parsing
- `bash` 4.0+
