⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.31.0

repo-harness-cross-review

ancienttwo@ancienttwo⭐ 436 stars· last commit 3d ago· 10 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 436 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

repo-harness

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

npm version License: MIT Runtime: Bun Hosts

English | 简体中文 | 日本語 | Français | Español

Quick start · How it works · Commands · Usage guide · Changelog


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 harnessWith 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 ≥ 1.4.0 (the installer installs or upgrades it for you), and hc (herdr-core) for host readiness. macOS/Linux need bash; Windows needs Git for Windows. No Node.js required.

# 1. Install the CLI and user-level hook adapters
curl -fsSL https://raw.githubusercontent.com/aimpact-inc/repo-harness/main/install.sh | sh
# 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.

# 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.

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

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>.

Upgrading, uninstalling, Pi, Windows tool pinning and cleanup semantics are in the usage guide.

How it works

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:

LayerWhat lives thereOwner
Task authorityScope, claims, status, dependencies, review evidenceThe GitHub issue and its PR
Repo contextdocs/spec.md, docs/prds/, docs/reference-configs/, tasks/lessons.md, .ai/context/, .ai/harness/Your repository (written by repo-harness init)
RuntimeCLI, typed hook handlers, helpers (repo-harness run <helper>), skillsThe 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:

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.
  • **

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • assets/skills/repo-harness-cross-review/SKILL.md1.8 KBupstream ↗
    ---
    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.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ancienttwo-repo-harness-assets-skills-repo-harness-cross-review.md

// REPO STATS

436 stars
10 open issues
Last commit: 3d ago