---
name: code-review-and-quality
description: Reviews agent changes along Standards and Spec axes. Use when reviewing PRs, auditing generated agents, or checking platform harness compliance.
---

# Code Review and Quality Assurance

## Overview

Two-axis review process for evaluating platform agent changes. Evaluates code along two independent dimensions — **Standards** (compliance with platform harness standards & coding guidelines) and **Spec** (faithful implementation of issue/PRD contracts).

## When to Use

- Auditing newly generated or refactored `crucible-agent-*` repositories
- Reviewing pull requests, git diffs, or feature branches
- Checking compliance with platform harness contracts (`execution-contract.md`, `base-state-contract.md`)

---

## Two-Axis Review Framework

### Axis 1: Standards (Compliance & Code Smells)
Inspect code against documented platform standards:

- **Harness Boundary**: Verify `crucible-agent-factory-harness` vs `crucible-agents-sdk` boundary rules. No runnable runtime code inside harness standard repos.
- **Base State Schema**: Verify state schemas extend `BaseAgentState` (`messages`, `errors`, `has_errors`, `workflow_id`, `current_step`, `next_step`).
- **Container Hardening**: Verify multi-stage Dockerfiles, non-root execution (`UID 10001`), and `/health` probes.
- **Code Smell Check**: Look for Fowler smells (Duplicated Code, Shotgun Surgery, Speculative Generality, Feature Envy).

### Axis 2: Spec (Requirement & Contract Fidelity)
Inspect code against the originating specification (`spec/<contract>.md`):

- **Missing/Partial Requirements**: Are all contract endpoints, connector types, and trigger modes fully implemented?
- **Scope Creep**: Was functionality added that was not requested in the contract spec?
- **Incorrect Behavior**: Do connector error handling, cursor advancement, or tenant isolation checks deviate from the spec contract?

---

## Review Output Format

```markdown
## Standards Review
- [Pass/Fail] Harness & Base State Compliance
- [Pass/Fail] Container & Security Hardening
- Findings & Code Smells

## Spec Review
- [Pass/Fail] Contract & Requirement Coverage
- Findings & Scope Creep

## Worst Issue Per Axis
- Standards: <worst issue>
- Spec: <worst issue>
```