name: repo-harness description: Route explicit repo-harness setup, planning, execution, verification, and handoff actions through deterministic repository state. when_to_use: "Use for explicit repo-harness commands or an active repo-harness task; do not use for ordinary questions, explanations, workflow discussion, quoted reports, or general product work."

repo-harness

Use only for an explicit repo-harness action or an active task. Ordinary questions, reviews, explanations, plan discussion, and quoted historical text bypass it.

Start with:

repo-harness state resolve --json

Treat that JSON as the state authority; read Plan, Contract, checks, handoff, or architecture files only when it points to them.

Actions

1. setup — install, init, migrate, repair, or scaffold the harness. Use repo-harness-setup; inspect first with repo-harness init --repo . --dry-run, or run repo-harness docs show harness-overview when detail is needed.
2. plan — create or capture a decision-complete plan. Use repo-harness-plan; run repo-harness docs show agentic-development-flow for promotion boundaries.
3. execute — continue the active task via its resolved profile and allowed paths: Lite (brief → edit → test), Standard (plan → edit → verify → one review), Strict (Contract/worktree/checks/external-acceptance).
4. verify — run targeted tests and the profile-required gates. Use repo-harness-check; never infer provider-owned evidence.
5. handoff — refresh compact recovery state via repo-harness run prepare-codex-handoff/codex-handoff-resume; see references/handoff.md. Inject references and deltas, not full copies.

Safety boundaries (scope, worktree ownership, secrets, destructive commands, high-risk paths, checks freshness, review fingerprints) are deterministic and fail closed; a profile override may raise, never lower, the risk floor.

Command catalogs, scaffold presets, migration, deployment, hook debugging, and other integrations load on demand.

repo-harness

A file-backed, repeatable workflow for Claude and Codex coding sessions

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

Give the agent a complete PRD or Sprint; after that, your loop is just review and next, or start /goal and go AFK.

repo-harness ships a CLI plus skill/runtime hooks that write context, plans, handoffs, checks, and review evidence back into the project, so the next agent session continues from files instead of chat memory. It adopts an existing repo with a tasks-first agent contract that keeps Claude and Codex aligned.

Contents

• Get Started
• Why repo-harness
• Key Features
• How It Works
• Task Workflow
• Hooks
• MCP Connector
• Reviewing Work
• Skills
• Maintainer Reference
• Acknowledgements
• Current Release
• License

Get Started

1. Install the CLI

Prerequisites: a Git working tree, bash, and bun; jq is optional. No Node.js required — the installer uses Bun >= 1.1.35 as the runtime, installing or upgrading Bun first when needed.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

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

With Bun >= 1.1.35 already on PATH, skip the shell installer. Package-manager-owned Bun installs fail closed with the matching upgrade command (brew upgrade bun) instead of overwriting manager-owned files.

bunx repo-harness@latest install     # Bun one-shot bootstrap
bun add -g repo-harness              # or install the persistent CLI first
repo-harness install
npx -y repo-harness@latest install   # npx fallback; the CLI still runs on Bun

2. Bootstrap the host runtime

repo-harness install

The global bootstrap: installs the npm package as the global CLI, refreshes repo-harness skill aliases, installs user-level hook adapters, and records an explicit install profile. It is idempotent and does not apply repo-local workflow files to the current directory. --dry-run --json lists components to install, skip, and remove first. Profiles, native Codex delegation authority, refresh commands, and the read-only setup check audit: install-profiles.md.

3. Preview the repo-local contract

repo-harness init --dry-run

Run this from the target repository root. It reports the specs, task state, helper runtime, hook adapter target, and verification files that would be created or refreshed. It never creates an application stack; new projects and modules use repo-harness-setup's scaffold mode instead.

4. Apply and verify

repo-harness init
bash scripts/check-task-workflow.sh --strict
bun test

Success looks like this

Apply ends with === Migration Report ===, naming where generated hook behavior comes from, the user-level ~/.claude/settings.json and ~/.codex/hooks.json adapter target, the repo-local surfaces created or refreshed, the .ai/harness/scripts/* helper runtime, and an --- External Tooling --- readiness block. Stable intent then lives in docs/spec.md, execution state in plans/ and tasks/, resume state in .ai/harness/handoff/. If the dry run looks wrong, stop and read hook-operations.md first.

Update and remove

repo-harness update          # reconcile CLI, mandatory deps, profile tooling, and CodeGraph
repo-harness update --check  # read-only repair guidance, no writes
repo-harness uninstall       # remove managed host adapters only

Why repo-harness

• File-backed sessions, not chat memory. Separate Claude and Codex sessions stay coordinated through the repo. SessionStart injects the prior session's resume packet, Stop writes the handoff, and each edit records a small journal event. A session can end mid-task and the next one resumes the exact next step, blockers, and changed files without re-deriving them.
• Token-lean by design. Instead of grep-and-read loops that re-scan the repo every session, the harness leans on a pre-built CodeGraph index for structural queries and on progressive context loading: a stable ~12KB root context plus capability blocks loaded only when the files you touch need them. Agents read a ~1KB capability contract instead of rediscovering structure.
• Review-ready evidence. Every task leaves a contract, structured check evidence, and a review card behind. The human decision surface is one screen — verdict, intended vs actual files, commands passed, residual risk, rollback — rather than a reconstruction of what the agent claims it did.

In an adopted repo, the surface area is intentionally small:

Key Features

How It Works

1. Source package: this repository owns the CLI, command facades, templates, typed hook handlers, the operator-helper asset, workflow contract, tests, and release gate.
2. Target repo contract: repo-harness init or migration writes repo-local files such as docs/spec.md, plans/, tasks/, .ai/context/, .ai/harness/, helper scripts, and .ai/hooks/.
3. Host adapters: user-level ~/.claude/settings.json and ~/.codex/hooks.json route Claude/Codex events into repo-harness-hook.

The hook entrypoint exits silently for non-opt-in repos. For opted-in repos, the route registry binds the public event tuple to exactly one packaged typed handler. .ai/hooks/ holds operator-helper projection only; it is never a host-event dispatcher.

The core invariant is that durable truth lives in the repo, not a chat thread. Hooks are accelerators and guardrails; authority remains the file-backed plan, contract, review, checks, and handoff artifacts. Prompt-layer plan/spec/contract gates are advisory routing; hard enforcement lives at the edit boundary. Handler internals, the minimal-change surface, and policy modes: hook-operations.md and minimal-change-hooks.md.

Task Workflow

The diagram assumes the harness is installed. It shows the normal lifecycle from a program sprint backlog down to one contract task: select the task, project it into execution files, check out the contract worktree when policy requires it, implement under hooks, verify, review, and close out.

flowchart TD
  Program["Program goal or release theme"] --> Sprint{"Sprint layer needed?"}
  Sprint -->|yes| PRD["Upper-layer PRD<br/>plans/prds/*.prd.md"]
  PRD --> SprintDoc["Sprint backlog<br/>plans/sprints/*.sprint.md"]
  SprintDoc --> NextTask["Select next sprint task<br/>sprint-backlog.sh next"]
  Sprint -->|no| UserTask["User task or planning prompt"]
  Heartbeat["Heartbeat triage<br/>scripts/heartbeat-triage.sh<br/>.ai/harness/triage/"] --> UserTask
  NextTask --> UserTask

  UserTask --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
  Discovery --> LoopEvidence["Loop evidence when routing changes<br/>state-snapshot --json<br/>route-nl-vs-ts / cutover gate"]
  LoopEvidence --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
  PlanDraft --> PlanReview{"Plan ready for execution?"}
  PlanReview -->|no| Refine["Refine plan, scope, evidence contract"]
  Refine --> PlanDraft
  PlanReview -->|yes| Approve["Approved plan<br/>Status: Approved"]

  Approve --> Project["Project plan into execution<br/>capture-plan.sh --execute<br/>or plan-