# QA Team Role vs `reviews_enabled`

This document clarifies the distinction between the **QA team role** (configured via
`team_config.roles`) and the **`reviews_enabled` feature** in AutoMaintainer. They
are independent mechanisms that serve different purposes.

---

## 1. QA as a Team Role (Write-Access Implementer)

The `team_config.roles` field accepts an array of role strings:
`["architect", "dev", "qa"]`. The legacy `enabled_clis` map indexes these
positions: **0 → architect, 1 → dev, 2 → qa**.

All roles listed in `team_config.roles` are:

- Registered on the **run A2A bus** and spawned together as the implementation
  team in the shared worktree.
- Given **identical workspace write access** — the QA role is **not** inherently
  read-only. Any prompt asking it to "only review" is advisory and **not
  enforced** by the system.

In short: when you include `"qa"` in `team_config.roles`, it joins the
implementation team as a full participant that can create, edit, and delete
files just like the `dev` role.

---

## 2. `reviews_enabled` (Separate Post-PR Review Pass)

`reviews_enabled` triggers an **independent review pass that runs after the PR
is opened**. When enabled:

1. After the implementation team opens a PR, the run calls
   `notifyReviewBroker`.
2. This drops a task onto a **persistent per-repo review bus**
   (`am-reviews-<repoID>`).
3. A dedicated **reviewer + approver team** is spawned on a **separate A2A
   bus** (not the implementation bus).
4. The reviewer reads the PR diff and emits **APPROVE** or
   **REQUEST_CHANGES** — it does **not** edit the workspace.
5. The approver acts on the verdict (e.g., merges when auto-merge is on).

This pass is **read-only** and **diff-oriented**: it judges the PR without
touching any files.

---

## 3. Interaction When Both Are Enabled

When both the QA team role and `reviews_enabled` are configured, the execution
order is:

1. **Implementation team runs** in the shared worktree.
   - Order: architect → dev → qa.
   - The QA role **can modify code** during this phase.
2. **PR is opened** (auto-merge may be evaluated).
3. **`reviews_enabled` review pass** judges the PR diff.

They are **independent**:
- The **QA team role** helps **build** the PR as part of the implementation
  team.
- **`reviews_enabled`** **reviews** the PR afterward in a separate,
  read-only pass.

---

## 4. Recommendation

If you want a **cheap / fast model for review-only**, reserving a stronger
model for implementation:

| Goal | Use |
|------|-----|
| Code review (read-only, diff only) | `reviews_enabled` with an independently configurable reviewer model |
| Extra implementer with write access | `team_config.roles: ["architect", "dev", "qa"]` |

**Do NOT use the QA team role as a review-only gate.** It is a team
implementer with full write access. Use `reviews_enabled` for the intended
read-only, diff-only review pass.

## Related

- [Teams & models](/docs/teams-and-models) · [The Verification Gate](/docs/verification-gate)
- [Auto-merge](/docs/auto-merge)