---
description: Workflow to get a code review from FriendlyReviewer, process results, and apply corrections
---

# FriendlyReviewer Code Review Workflow

This workflow guides you through the process of getting a code review from FriendlyReviewer, processing the results, and applying corrections.

<!> IMPORTANT : ALWAYS MAKE A PLAN TO FOLLOW STEP BY STEP THIS WORKFLOW

## Prerequisites

- **`fr-agent`**: Rust CLI for `/api/agent/*`. If it is missing, this workflow installs the latest public build with checksum verification.
- **Git**: Working tree must be clean (`git status --porcelain`).
- **Network**: Access to the FriendlyReviewer API (default: `https://friendlyreviewer.fr`).
- **`jq`**: Optional — only if you want quick shell filtering; `fr-agent` prints JSON on stdout.

## 1. Preparation & Tooling

- Check if the working tree is clean. **STOP** if there are uncommitted changes.
- Check if `fr-agent` is available:
    - Unix/macOS: `command -v fr-agent`.
    - Windows PowerShell: `Get-Command fr-agent`.
- If `fr-agent` is missing, install it:
    - Unix/macOS: `curl -fsSL https://friendlyreviewer.fr/downloads/fr-agent/install.sh | sh`.
    - Windows PowerShell: `irm https://friendlyreviewer.fr/downloads/fr-agent/install.ps1 | iex`.
- If the installer reports that the install directory is not on `PATH`, add it for the current shell or call the installed binary by its full path.
- Verify the CLI is callable: `fr-agent --help`.
- Check auth readiness before starting a protected action: `fr-agent auth status` (reads token from config or env).
- On missing config, invalid token, or HTTP **401** in subsequent steps:
    - Run `fr-agent auth login` (optional `--api-url https://friendlyreviewer.fr`).
    - **Interactive flow**: CLI prints `auth_url`; user completes flow in the browser and pastes the token into the terminal.
    - **Security**: Ensure the config file is protected: `chmod 600 ~/.config/friendly-reviewer/config.json` on Unix.

## 2. Project Identification

- Get the remote URL: `git remote get-url origin`.
- Identify the project: `fr-agent project identify --remote "<REMOTE_URL>"`.
- **Explicit extraction** (example with jq): `PROJECT_ID=$(fr-agent project identify --remote "$REMOTE_URL" | jq -r '.project_id')`
- If identification fails (404), ensure at least one manual review has been performed on the target environment to register the namespace.

## 3. Review Initiation

- Detect branches:
    - **Current Branch**: `CURRENT_BRANCH=$(git branch --show-current)`.
    - **Base Branch**: Determine via `git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'` or ask the user (default: `main` or `develop`).
    - **Integration branch**: For feature work, prefer the branch you merge into (often `develop`) as `BASE_BRANCH` so the server diff matches your PR — not only `origin/HEAD` (which may track `main`).
- Start the review (pass `--remote` so the server matches your forge URL):

```bash
fr-agent review start \
  --project-id "$PROJECT_ID" \
  --branch "$CURRENT_BRANCH" \
  --base-branch "$BASE_BRANCH" \
  --remote "$(git remote get-url origin)"
```

- **Conflict Handling (409)**: `fr-agent` exits **0** and prints the JSON body (including conflict detail). Ask the user if they want to force a new session; if yes, retry with `--force`:

```bash
fr-agent review start \
  --project-id "$PROJECT_ID" \
  --branch "$CURRENT_BRANCH" \
  --base-branch "$BASE_BRANCH" \
  --remote "$(git remote get-url origin)" \
  --force
```

- **Explicit extraction**: `REVIEW_ID=$(fr-agent review start ... | jq -r '.review_id')`.
- **Empty diff**: If `CURRENT_BRANCH` and `BASE_BRANCH` resolve to the same commit on the server, the review may end quickly with `status` `aborted` / `failed` and no manageable files. Ensure the remote feature branch is pushed and ahead of the chosen base.

## 4. Waiting for Results

### Recommended: `review wait --json-progress` (no bash loop needed)

Use `fr-agent review wait` with `--json-progress` for a blocking wait that emits
structured JSON progress events on stdout. No fragile bash polling loop required.

```bash
fr-agent review wait \
  --review-id "$REVIEW_ID" \
  --timeout 45m \
  --interval 10s \
  --json-progress
```

While waiting, each line on stdout is a JSON event:

- `{"event":"progress","status":"processing","phase":"indexing","percent":20,"message":"..."}`
  → Display `phase` and `message` to the user as a progress indicator.
- `{"event":"result","status":"completed","result":{...}}`
  → The review is finished. `result` contains the full payload.
- `{"event":"error","message":"Timeout waiting for review."}` (exit code 4)
  → The review timed out; adjust timeout or retry.

The orchestrating agent reads stdout **line by line** until it receives a
`{"event":"result",...}` line or the process exits. No bash loop, no jq parsing.

Each progress event includes available fields from the server:
`percent`, `phase`, `message`, `review_step`, `parallel_completed`, `parallel_total`.

### Legacy alternatives (no `--json-progress`)

- **Blocking wait** (dots on stderr, final JSON on stdout):
  `fr-agent review wait --review-id "$REVIEW_ID" --timeout 45m --interval 10s`
- **Single probe** (no wait loop): `fr-agent review status --review-id "$REVIEW_ID"`.
- **Polling strategy** (manual loop): interval 10–15s; timeout **30–45 minutes** for full reviews (adjust for trivial changes).
- Wait until `.status` is terminal: **`completed`**, **`failed`**, or **`aborted`**.

### Response shape (`GET /api/agent/reviews/{review_id}`)

The JSON body matches what `fr-agent review status` / `review wait` prints on stdout. Top-level keys:

| Field | Type | Description |
|--------|------|-------------|
| `review_id` | string | Session token (e.g. `_sk_...`) echoed back. |
| `status` | string | Queue state: `pending`, `processing`, then `completed`, `failed`, `aborted`, or `closed` after session close. |
| `progress` | object | Live progress while `pending` / `processing` (see below). |
| `result` | object or null | Populated when the review finishes; shape depends on outcome. |

#### `progress` object

Always includes **`phase`**, **`message`**, **`percent`** (0–100). Optional fields when the server supports granular agent progress:

| Field | Type | When present |
|--------|------|----------------|
| `review_step` | string | Stable machine-readable step, e.g. `file_indexing`, `plan_generation`, `parallel_review`, `synthesizing_report`, `posting_results`. |
| `parallel_completed` | int | During parallel executor phase: number of planner tasks finished. |
| `parallel_total` | int | Total planner tasks for this run (may be `0` if the plan has no tasks). |

Typical **`phase`** values include: `pending`, `cloning`, `indexing`, `planning`, `executing`, `aggregating`, `finalizing`, `in_progress`, `failed`.

**Optional jq** on stdout:

```bash
fr-agent review status --review-id "$REVIEW_ID" | jq '{status, phase: .progress.phase, pct: .progress.percent, step: .progress.review_step, parallel: "\(.progress.parallel_completed // "?")/\(.progress.parallel_total // "?")"}'
```

#### `result` when the review completes

- On success, `result` usually contains a **`review`** object (summary, status, comments, metrics) plus metadata such as **`review_duration_seconds`** and **`status`** (`success` / inner review status).
- On failure or abort, `result` may contain **`error`**, **`reason`**, **`status`**, or MR-size fields — inspect JSON rather than assuming a single shape.

Initial review verdict for agents: treat **`result.review`** (when present) like a single code review: **`summary`**, **`status`**, **`comments`**.

### Polling exit conditions

- **`completed`**: Read `result` / `result.review` and proceed to step 5.
- **`failed`**: Inspect `result` for `error` or message; fix configuration or branch issues; do not treat as a normal review outcome.
- **`aborted`**: Often policy or size limits (`reason` in `result`); adjust branch or MR and start a new review if appropriate.

## 5. Result Processing & Correction Plan

- Treat the completed review JSON **globally** (like a GitHub/GitLab review). The initial review payload is usually under **`result.review`**: use **`result.review.summary`**, **`result.review.status`**, and **`result.review.comments`** as a single feedback bundle — **not** a per-finding workflow with `fix` / `skip` / `discuss`. (If `result.review` is absent, fall back to inspecting `result` for error fields.)
- Synthesize one correction plan (which files to touch, what to change) from that bundle.
- **STOP**: Present that plan to the user and wait for explicit approval before writing code or committing.

## 6. Execution & Validation

> [!IMPORTANT]
> **Subcommand confusion warning**: In this step you MUST use **`fr-agent validation start`**. Do **NOT** use **`fr-agent review start`** again (that is step 3 only).

- Apply the approved changes, commit, and push the branch to `origin`.
- Start validation:

```bash
fr-agent validation start --review-id "$REVIEW_ID"
```

- **Explicit extraction**: `VALIDATION_ID=$(fr-agent validation start --review-id "$REVIEW_ID" | jq -r '.validation_id')`
- Wait for validation (with JSON progress events):

```bash
fr-agent validation wait \
  --review-id "$REVIEW_ID" \
  --validation-id "$VALIDATION_ID" \
  --timeout 30m \
  --interval 10s \
  --json-progress
```

  Without `--json-progress`, validation wait behaves as before (dots on stderr, final JSON on stdout).

- Read the outcome from the validation JSON: path `.result.review` (`summary`, `status`, `comments`) — authoritative post-fix review.
- **Status check**: Ensure validation `.status` is `completed`. If `result.review` still requests changes, return to **Section 5 (Result Processing & Correction Plan)** for a new approved correction cycle (then Section 6 again); otherwise continue to step 7.
- Optional legacy diagnostic (`GET .../validate/status`, initial thread only): not exposed as an `fr-agent` subcommand; use direct REST if needed.

## 7. Cleanup & Finalization

- Close the review session: `fr-agent review close --review-id "$REVIEW_ID"`.
- Propose to merge the branch if all fixes are validated.
- **Rollback**: If validation fails or the process is interrupted, offer to discard local changes or keep them for manual adjustment.

---

## Orchestrated workflow (Phase F)

When this checklist runs inside [full-implementation-orchestrated.md](full-implementation-orchestrated.md) **Phase F**, do not duplicate steps in the orchestrated file — execute the sections below and write handoff artefacts:

| Section | Orchestrated step | Actor | Extra outputs |
|---------|-------------------|-------|---------------|
| §1–4 | F.1 | subagent `shell` | `.workflow/review_session.json`, `.workflow/review_report.md` |
| §5 | F.2.1–F.2.2 | subagent + **Gate 4** | `.workflow/review_correction_plan.md` |
| §6 (apply) | F.3 | subagent `generalPurpose` | `.workflow/review_fix_summary.md` |
| §6 (validation) | F.4 | subagent `shell` | `.workflow/validation_report.md` |
| §7 | F.5.2 | parent | — |

**Orchestrated-only** (not in §1–7): branch `LINEAR-{key}`, base `develop`; **Gate 5**; direct `git merge` into `develop` without GitHub PR (F.5.3–F.5.5). See Phase F in the orchestrated workflow for merge policy and Linear cleanup.