# repo-harness-cross-review

Adopt this skill: https://proskills.md/skills/other/ancienttwo-repo-harness-assets-skills-repo-harness-cross-review

Page: https://proskills.md/skills/other/ancienttwo-repo-harness-assets-skills-repo-harness-cross-review
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: assets/skills/repo-harness-cross-review/SKILL.md
size: 1874
upstream: https://github.com/ancienttwo/repo-harness/blob/main/assets/skills/repo-harness-cross-review/SKILL.md

```text
---
name: repo-harness-cross-review
description: Independent outside review of the current review scope (branch diff plus staged, unstaged, untracked changes). Uses the explicit Codex provider; Claude acceptance retains its persistent Herdr domain reviewer. Use before merging, after a tricky change, or for a debug second opinion.
when_to_use: "cross review, second opinion, outside voice, codex review, 让 codex 审, 找外部意见, 二审"
---

# repo-harness-cross-review

Canonical rule owner for independent outside review. Scope capture, provider
invocation, timeout, structured-output validation, and error classification live in
code (`src/core/review`, `src/effects/review`,
`src/cli/commands/cross-review.ts`); this package owns only when to invoke,
how to interpret findings, and the boundaries below.

## Mode Selection

- Explicit Codex advisory review: `references/codex-mode.md`.
- Explicit Claude acceptance review -> `references/claude-mode.md`.
- An explicit provider request wins over the host default.

## When to use

- Before merging an important diff (last gate).
- After writing a spec/tests -- find ambiguity and weak assertions.
- A hard bug whose root cause is unclear (independent diagnosis).

## Interpreting findings

- Present the transcript verbatim -- never summarize or soften it.
- Any `[P1]` finding -> **FAIL** (do not merge until addressed). Only `[P2]` or none -> **PASS**.
- Agreement raises confidence; divergence is where to dig. A recommendation, not a decision -- you decide.

## Boundaries

- Read-only: direct Codex uses a read-only sandbox.
- Bounded: 2 provider attempts, then `SKIPPED` -- advisory, non-blocking (exit 0). Do not re-run it or narrow the diff to retry. `degraded_scope` and `stale_scope` block (exit 1). Never a synthesized pass.
- Never produces or verifies a `merge-gate` receipt; that judge is separate.
```

## File: README.md
upstream: https://github.com/ancienttwo/repo-harness/blob/main/README.md

````text
<div align="center">

# repo-harness

### Hand an AI agent a GitHub issue. Get back a PR you can actually review.

<img src="docs/images/repo-harness-hook-carrot.png" alt="repo-harness hooks leading Codex and Claude forward with repo-local workflow state" width="820">

[![npm version](https://img.shields.io/npm/v/repo-harness.svg)](https://www.npmjs.com/package/repo-harness)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.4.0-black.svg)](https://bun.sh)
[![Hosts](https://img.shields.io/badge/hosts-Claude%20%C2%B7%20Codex%20%C2%B7%20Pi-6b4fbb.svg)](#supported-hosts)

[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)

[Quick start](#quick-start) · [How it works](#how-it-works) · [Commands](#command-cheat-sheet) · [Usage guide](docs/usage.md) · [Changelog](docs/CHANGELOG.md)

</div>

---

`repo-harness` is a CLI, a set of hooks and a set of skills that wrap an existing
repository so that **Claude, Codex and Pi** can do long-running engineering work
in it — across sessions, machines and worktrees — and leave behind evidence a
human can review in minutes.

It is built for solo developers and small teams who let AI write the code and
keep the human job to one thing: **deciding whether to accept the change.**

## Why

Coding agents are fast, but three things break as soon as work spans more than
one chat:

| Without a harness | With repo-harness |
| --- | --- |
| Context lives in a chat thread and dies with it. | The **GitHub issue and PR** own the task. Any new session re-reads them and resumes the exact next step. |
| Every session re-greps the repo to rediscover its structure. | A ~12 KB stable root context, ~1 KB **capability contracts** loaded only for the files being touched, and a **CodeGraph** index for callers/callees. |
| "Done" means "the agent said it's done." | The PR carries **changed files, executed checks, residual risk and rollback**. Execution evidence and acceptance are separate, typed authorities. |
| Agents wander outside the repo or into private folders. | **Typed hooks** guard the edit boundary and print one `[Guard] reason` + one `Fix:` line when they block. |

## Quick start

**Prerequisites:** a Git working tree, [Bun](https://bun.sh) ≥ 1.4.0 (the
installer installs or upgrades it for you), and [`hc`](https://herdr.dev/)
(herdr-core) for host readiness. macOS/Linux need `bash`; Windows needs Git for
Windows. No Node.js required.

```bash
# 1. Install the CLI and user-level hook adapters
curl -fsSL https://raw.githubusercontent.com/aimpact-inc/repo-harness/main/install.sh | sh
```

```powershell
# Windows (PowerShell)
irm https://raw.githubusercontent.com/aimpact-inc/repo-harness/main/install.ps1 | iex
```

Already have Bun? Use `bunx repo-harness@latest install` instead.

```bash
# 2. From the root of the repository you want to adopt: preview, then apply
repo-harness init --dry-run   # reports every file it would write; writes nothing
repo-harness init
```

Init ends with a `=== Migration Report ===` that lists what was created or
refreshed and an `--- External Tooling ---` readiness block. That's it — open
Claude or Codex in the repo, hand it an issue, and the hooks take over.

<details>
<summary><b>What <code>init</code> adds to your repository</b></summary>

From a `repo-harness init --dry-run` on a fresh repository (abridged):

```text
your-repo/
├── AGENTS.md · CLAUDE.md          # agent rules, one standalone file per host
├── docs/
│   ├── spec.md                    # stable product intent and safety boundary
│   ├── prds/                      # product intent and design briefs
│   ├── reference-configs/         # shared standards every session can read
│   ├── researches/
│   └── architecture/              # index, modules/, diagrams/
├── tasks/lessons.md               # the one local lesson ledger
├── .ai/
│   ├── context/                   # capabilities.json, context-map.json
│   ├── harness/                   # workflow-contract.json (opt-in marker), policy.json,
│   │                              # runs/, failures/, worktrees/, events.jsonl
│   └── hooks/README.md            # operator-helper projection, not a dispatcher
├── deploy/                        # runbooks/, release-checklists/, sql/, …
├── _ops/                          # git-ignored private operations state
└── .gitignore                     # one managed block appended
```

No helper scripts are copied in. Downstream repos call `repo-harness run <helper>`.

</details>

> Upgrading, uninstalling, Pi, Windows tool pinning and cleanup semantics are in
> the [usage guide](docs/usage.md#install-in-depth).

## How it works

```mermaid
flowchart TB
  Issue["GitHub issue<br/><sub>scope · deps · acceptance</sub>"] --> Start
  subgraph Session["Agent session (Claude · Codex · Pi)"]
    direction LR
    Start["SessionStart hook<br/><sub>loads context + state pointers</sub>"] --> Work["Bounded work<br/><sub>branch or worktree</sub>"]
    Work --> Guard["Edit guards<br/><sub>scope · _ops/ · _ref/</sub>"]
    Guard --> Verify["Typecheck +<br/>affected tests"]
    Verify -->|fail| Work
  end
  Verify -->|pass| PR["Pull request<br/><sub>changes · checks · risk · rollback</sub>"]
  PR --> Review["Acceptance review<br/><sub>when risk requires it</sub>"]
  Review --> Merge["Merge<br/><sub>publication merge</sub>"]
  Work -. Stop hook .-> Checkpoint["Evidence checkpoint<br/><sub>publishes accepted evidence only</sub>"]
  PR -. next session re-reads issue, PR, branch .-> Start
```

Three layers, each with one owner:

| Layer | What lives there | Owner |
| --- | --- | --- |
| **Task authority** | Scope, claims, status, dependencies, review evidence | The GitHub issue and its PR |
| **Repo context** | `docs/spec.md`, `docs/prds/`, `docs/reference-configs/`, `tasks/lessons.md`, `.ai/context/`, `.ai/harness/` | Your repository (written by `repo-harness init`) |
| **Runtime** | CLI, typed hook handlers, helpers (`repo-harness run <helper>`), skills | The globally installed package — never vendored into your repo |

The user-level adapters in `~/.claude/settings.json` and `~/.codex/hooks.json`
route host events into `repo-harness-hook`. For repositories that haven't opted
in, the hook exits silently.

### One task, two sessions

A session can end in the middle of a task. The next session — on another day,
host or agent — continues from the branch, the issue and the PR, not from the
old chat. No local handoff file is written:

```mermaid
sequenceDiagram
  autonumber
  participant I as GitHub issue + PR
  participant A as Session A (Codex)
  participant R as Repo files
  participant B as Session B (Claude)
  A->>I: Read scope, claims, linked PRs
  A->>R: Work on a branch, run checks
  A->>I: Push commits, write result and next step in the PR
  Note over A: Session ends (context limit, reboot)
  A-->>R: Stop hook publishes the existing evidence checkpoint
  B->>R: SessionStart emits Effective State<br/>(issue + branch from the branch name)
  B->>I: Re-read issue, latest claim, PR
  B->>R: Continue from the step the PR names
  B->>I: Final checks, risk and rollback in PR
```

## Design principles

- **Files over chat.** Durable truth lives in the issue, the PR and repo files.
  Chat history, transcripts and agent memory are caches.
- **Evidence over narration.** A passing check proves a command ran; acceptance
  is its own receipt. Reviewers read the PR description first, then the diff and
  the trace.
- **Guardrails, not autopilot.** Hooks load context and enforce edit boundaries.
  They never make product decisions, merge, publish or bypass review.
- **The Bot decides, the harness supplies.** repo-harness keeps no scheduler,
  budget ledger or unattended controller. Your Bot (or you) schedules work
  through the CLI and Herdr; repo-harness provides the tools and the evidence.
- **
````
