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.

On top of that contract it runs authorized programs: long-running work that holds its own authorization, budget, task offers, and leases, so a Sprint can advance across sessions without a human driving each step.

Contents

• Get Started
• Why repo-harness
• Two Layers
• Key Features
• How It Works
• Task Workflow
• Authorized Programs
• Hooks
• Local Human Control Board
• MCP Connector
• Reviewing Work
• Skills
• Maintainer Reference
• Acknowledgements
• Current Release
• License

Get Started

1. Install the CLI

Prerequisites: a Git working tree, bun, and usable herdr >=0.9.0 for host readiness; macOS/Linux also require bash, while Windows requires Git for Windows (including its Bash and usr/bin tools). jq is optional. No Node.js required — the installer uses Bun >= 1.4.0 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.4.0 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

Install herdr from herdr.dev and verify herdr --version. Persistent review hosting requires POSIX process groups; on Windows use WSL. Missing or unusable herdr blocks host readiness. Before upgrading from tmux, drain existing reviewers using the previous version and explicitly rebind terminal endpoints. See runtime cutover.

2. Bootstrap the host runtime

repo-harness install

On Windows, keep Git for Windows on the install/update PATH. That explicit ceremony validates and pins git.exe, its matching bash.exe/usr/bin, and the install account's absolute TEMP directory plus native System32 tools in the OS account's ~/.repo-harness/config.json#protectedHelperRuntime. Protected workflow helpers do not rediscover tools from a caller's PATH; rerun repo-harness update after relocating or replacing Git for Windows.

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 --dry-run # preview owned user configuration cleanup
repo-harness uninstall           # remove owned configuration; preserve user changes/history
repo-harness mcp uninstall --dry-run # preview independent MCP setup cleanup
repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP services

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.
• Unattended work stays accountable. A program cannot start without a stored authorization, cannot exceed its budget ledger, cannot hold a task past its lease, and cannot claim acceptance without a receipt. Autonomy is bounded by artifacts, not by trust.

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

Surface	Purpose
docs/spec.md and docs/reference-configs/	Shared standards and stable product intent that every agent session can read.
plans/, plans/prds/, and plans/sprints/	Decision-complete work packages before implementation starts.
tasks/contracts/, tasks/reviews/, and .ai/harness/checks/	Scope, verification, and review evidence for proving the work is done.
.ai/harness/handoff/ and tasks/current.md	Session journal and resumable status, derived from workflow artifacts instead of chat memory.

Two Layers

The product reads as two layers that share one set of files.

Layer 1 — the session contract. One human, one agent session, one task at a time. Plans, contracts, checks, reviews, and handoffs are the durable authority; hooks keep the session inside them. This is the whole product for a solo repo, and everything in Task Workflow belongs here. Nothing below is required to use it.

Layer 2 — authorized programs. Long-running work that outlives a session: an unattended controller stepping a Sprint, a repair campaign that authors and adopts GitHub Issues, a refactor program driven off the architecture model, a collaboration plane where several Module Engineers exchange signals and handoffs. Each program is gated on an operator-minted authorization, draws on a per-goal budget ledger, and holds work through renewable leases. See Authorized Programs.

	Layer 1	Layer 2
Unit of work	One task contract	One authorized program
Who drives it	A human in a session	A controller, under caps
Authority	Plan, contract, review, checks	The above, plus authorization, budget, lease, receipts
Entry point	repo-harness init	repo-harness automation grant mint
Stop condition	Task closeout	Budget exhausted, lease lost, or a terminal receipt

Layer 2 does not replace layer 1: a program's every step still projects into the same plan, contract, and review artifacts a human would have written.

Key Features

File-backed sessions	Plans, contracts, checks, and handoffs live in the repo, so a new session resumes from artifacts instead of a chat thread
Typed hook runtime	Eight shared managed routes plus three Codex-only delegation routes, each bound to exactly one typed in-process handler, with fail-closed guards at the edit boundary
Plan → Contract → Review	One lifecycle from approved plan to projected contract, isolated worktree, structured evidence, and a reviewable closeout
Authorized programs	Campaign, refactor, automation, and collaboration programs that hold their own authorization, budget ledger, task offers, and renewable leases
Bounded unattended controller	One Engineer dispatch loop under hard step, duration, and retry caps, reserving budget before each attempt
Progressive context loading	A ~12KB stable root context plus ~1KB capability contracts loaded only for the files actually being touched
CodeGraph integration	Structural queries (callers, callees, definitions) answered from a pre-built index instead of repeated grep-and-read passes
MCP planner sidecar	ChatGPT reads real repo state and writes PRD/Sprint/Goal artifacts; Codex executes them, with no default source-code write access
Claude + Codex alignment	One user-level adapter contract, one workflow contract, and one set of repo-local artifacts shared by both hosts

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-to-todo.sh --plan"]
  Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
  Project --> SprintActive["Sprint projection<br/>active-sprint marker<br/>tasks/current.md"]
  Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
  Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
  Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]

  Contract --> Delegation["Delegation contract<br/>budget / permission_scope / roles"]
  Delegation --> Delegate{"Use contract-run delegation?"}
  Delegate -->|yes| ContractRun["Worker/verifier child run<br/>scripts/contract-run.ts"]
  Delegate -->|no| WorktreePolicy{"Contract worktree required?"}
  WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
  WorktreePolicy -->|no| CurrentTree["Use current worktree<br/>small or explicitly allowed slice"]
  Checkout --> Implement
  CurrentTree --> Implement
  ContractRun --> Changes

  Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
  PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
  ScopeFix --> Implement
  PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
  Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, drift request, handoff, check evidence"]
  PostHooks --> ArchQueue["Architecture queue<br/>architecture-queue.sh record/reindex<br/>check-architecture-sync.sh"]
  ArchQueue --> Verify["Run verification<br/>tests plus repo workflow checks"]

  Verify --> Checks["Structured evidence<br/>.ai/harness/checks/latest.json<br/>.ai/harness/runs/*.json"]
  Checks --> CheckReview["Evaluator review<br/>Waza /check -> review file"]
  CheckReview --> External["External acceptance advice<br/>or explicit manual override"]
  External --> DoneGate{"Contract, checks, review, and acceptance pass?"}
  DoneGate -->|no| Repair["Repair failing evidence or implementation"]
  Repair --> Implement
  DoneGate -->|yes| SprintComplete{"Sprint task active?"}
  SprintComplete -->|yes| MarkSprint["Mark backlog item complete<br/>sprint-backlog.sh complete-task"]
  SprintComplete -->|no| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
  MarkSprint --> Closeout

  Closeout --> Commit["Commit contract branch"]
  Commit --> Merge["Fast-forward target branch"]
  Merge --> Archive["Archive plan/todo and refresh handoff"]
  Archive --> Cleanup["Cleanup merged worktree<br/>contract-worktree.sh cleanup"]
  Cleanup --> Done["Reviewable completed task"]

For long-running product loops, keep discovery and engineering-plan judgment with the parent agent before Codex loops on execution: geju opens the pre-contract frame, the parent completes P1/P2/P3 and freezes the accepted direction into an upper-layer PRD under plans/prds/ and an ordered sprint backlog under plans/sprints/, then a Codex Goal points at that sprint file. The PRD stays the upper source of truth and the backlog is the durable execution queue, so a resumed Goal session never reinterprets the original chat. See agentic-development-flow.md and workflow-orchestration.md.

Authorized Programs

A program is work that outlives a session. Every one of them starts from the same three primitives, and none of them can be started without the first.

repo-harness automation grant mint   # store one operator ProgramAuthorizationV1
repo-harness automation grant list   # digests held for this repository
repo-harness automation budget show          # the enforceable per-goal ledger
repo-harness automation budget repair        # seal a stopped or expired run's exhaustion receipt

• Authorization. An operator-minted ProgramAuthorizationV1 lives in the harness home gate store. There is no unauthenticated start path, and a program never derives its own actor — the author of every record is resolved from --authorization-id.
• Budget. Provider calls, campaign steps, adoption observations, heartbeat execution, and worker acquisition all reserve against a per-goal ledger before the work is recorded. budget repair only re-runs a locked reconciliation; it never reserves, charges, or changes a cap.
• Lease. Held work carries a renewable lease with a renewal interval, a maximum TTL, and a closed set of evidence sources. An unproven liveness state requires attention instead of reclaiming silently.

Unattended controller

repo-harness automation controller start --maximum-steps 20 --maximum-duration-ms 300000
repo-harness automation controller step
repo-harness automation controller status
repo-harness automation controller stop

One Engineer dispatch loop under hard caps, with deterministic backoff and a bounded attempt-retry ledger. Each attempt reserves budget before it is recorded, and a projected outcome outside the closed enum cannot be counted as satisfied.

Engineer scheduling

repo-harness engineer principal enroll        # map an OAuth authorization to a Binding
repo-harness engineer acquire-next --authorization-id <id> --idempotency-key <key>
repo-harness engineer work-demand propose|transition|materialize|status
repo-harness engineer message send|receive|ack
repo-harness engineer board                   # read-only organization attention

acquire-next selects and claims the first canonical offer for an enrolled principal. Dependency edges resolve from receipt authorities, not inference, and Sprint task IDs are immutable identities under backlog schema v2 — run repo-harness sprint migrate-schema once on an older backlog.

Development campaign

repo-harness campaign audit          # budgeted read-only group audit
repo-harness campaign author         # persist an IssueBatchIntentV1, open the GPT Pro authoring lane
repo-harness campaign adopt          # exact-SHA readback, seal authoring, publish a repair batch
repo-harness campaign step           # hand one adopted task to its local planning session
repo-harness campaign prepare-resume # zero-provider resume request from stored evidence

A seeded repair program: audit a group, author its Issues through the GPT Pro lane, adopt them against an exact SHA readback, then step each adopted task into the ordinary plan → contract → review lifecycle. prepare-resume reconstructs a resume request from stored adoption, continuation, and budget evidence without contacting a provider.

Refactor Mode

repo-harness refactor discover        # bounded shadow scan of one local proposal
repo-harness refactor materialize     # one recommendation into N Work Packages
repo-harness refactor verify-candidate
repo-harness refactor board

An ArchContext-backed program that turns an architecture recommendation into work packages against a single canonical Sprint task authority. Activation is gated: the canary set and rung-promotion evidence must be refreshed against the installed provider before it turns on.

Collaboration plane

repo-harness collaboration exchange              # one Work Exchange snapshot
repo-harness collaboration threads               # lanes, hotspot scores, opportunities
repo-harness collaboration post                  # append one CoordinationSignalV1
repo-harness collaboration handoff publish|list|adopt
repo-harness collaboration packet build|read

Several Module Engineers read one Work Exchange and publish bounded coordination records. Handoff adoption is deliberately non-exclusive: it grants no Task, Claim, or Lease.

The substrate keeps one Module Engineer and one writer while bounded read-only Workers exchange untrusted signals and explicit handoffs. Run the source-checkout live gate with bun scripts/c9-collaboration-canary.ts --live; it creates isolated disposable repositories for three matched baseline/treatment traces and records provider-authoritative Codex token usage, context size, signal reuse, handoff adoption, writer count, and delivery-plane digests. The accepted C9 result is deliberately a negative multi-seat decision: the three-reader treatment preserved authority and reused state, but did not outproduce the single-reader baseline. Persistent same-capability EngineerSeatV2, an independent Review marketplace, and unattended Merge remain inactive. See 20260830-c9-real-multi-agent-canary.md.

External source intake

repo-harness external-source refresh   # one bounded, explicitly enabled GitHub observation
repo-harness external-source bind      # one immutable revision to one pending canonical task
repo-harness external-source bindings  # binding edges and current drift attention

Intake is inert by design. An observed Issue mints no execution authority and does not become a runnable task on its own; binding attaches an immutable source revision to a task that already has an approved plan and contract.

Persistent acceptance review

repo-harness claude-review round --timeout-ms 1800000
repo-harness claude-review status
repo-harness claude-review close

A read-only Claude reviewer hosted in an owned herdr session that survives up to three repair rounds against prepared verify-sprint evidence. A repeat session past the round budget is refused with claude_review_session_budget_exhausted.

Hooks

The installed adapter owns eight shared managed hook routes. The route tuple event + routeId + matcher is the stable contract; each tuple binds exactly one typed in-process handler.

Route	Matcher	Handler	Function
SessionStart.default	all sessions	src/cli/hook/session-context.ts (in-process builder)	Injects prior handoff, sprint status, minimal-change guidance, and read-only config-security findings before work starts.
PreToolUse.edit	Edit|Write	src/cli/hook/mutation-guard.ts (in-process handler)	Enforces worktree policy and plan/contract readiness before implementation edits.
PreToolUse.subagent	Task|Agent|SendUserMessage	src/cli/hook/subagent-handler.ts	Keeps delegated work returning through the parent session instead of leaking completion claims.
PostToolUse.edit	Edit|Write	src/cli/hook/mutation-observed.ts (in-process handler)	Writes at most one small journal event with dirty bits per qualifying edit; contract verification, architecture/context/capability sync, and minimal-change evidence are deferred to Stop instead of run per edit.
PostToolUse.bash	Bash	src/cli/hook/command-observed.ts	Observes command results and captures verification evidence without replacing the command runner.
PostToolUse.always	all tools	src/cli/hook/trace-observer.ts	Provides low-noise always-on trace and runtime observation.
UserPromptSubmit.default	all prompts	src/cli/hook/prompt-handler.ts	Classifies prompt intent, routes planning/check hints, and renders host-safe workflow guidance.
Stop.default	session stop	src/cli/hook/stop-handler.ts (in-process handler)	Finalizes handoff and guards against ending with unresolved draft-plan or completion evidence gaps.

Codex also installs three Codex-only bounded-delegation routes — UserPromptSubmit.delegation, SubagentStart.context, and SubagentStop.quality, all bound to src/cli/hook/subagent-handler.ts; Claude keeps only the shared PreToolUse.subagent return-channel route.

repo-harness-hook and its typed handler registry are the host-event runtime; ~/.claude/settings.json and ~/.codex/hooks.json are the user-level adapters, and Codex must mark its file as trusted in Settings before those hooks run. Repo-local .claude/settings.json and .codex/hooks.json are legacy config to retire. Debug in order: adapter config -> repo-harness-hook -> route registry -> typed handler.

When a hook blocks work, read the structured terminal output first: guard, reason, fix, failure_class, and run_id. Durable records live in .ai/harness/failures/latest.jsonl, with surrounding tool activity in .claude/.trace.jsonl. The common guards are PlanStatusGuard (no active or executable plan), ContractGuard (missing contract scaffold, or completion claimed before the contract passed), and WorktreeGuard (writes from the wrong worktree). Full playbook: docs/reference-configs/hook-operations.md.

Local Human Control Board

Run the observe-only operator view on the same machine as the adopted repositories:

repo-harness operator serve

The command binds to loopback only and prints the local URL. The browser shows the canonical Fleet summary, an attention-first worklist, a resident task detail pane, and degraded snapshot states. Refresh is explicit; the board carries exactly one write action — sending a task-addressed message — and does not acquire tasks, mutate workflow state, launch agents, or expose repository paths.

MCP Connector

As an optional sidecar, repo-harness mcp exposes workflow artifacts to MCP clients through the default planner profile. ChatGPT reads real repo state and moves an idea through PRD, checklist Sprint, and Codex goal handoff artifacts — with no default source-code write access, arbitrary shell execution, or default runner. Codex remains the executor.

repo-harness mcp setup chatgpt --repo .
repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner

Expose that local server through an HTTPS tunnel, register the /mcp URL, and the human workflow is:

1. ChatGPT reads repo-harness workflow files through MCP.
2. ChatGPT writes a PRD with write_prd_from_idea.
3. ChatGPT writes a checklist Sprint with write_checklist_sprint.
4. ChatGPT prepares .ai/harness/handoff/codex-goal.md with prepare_codex_goal_from_sprint.
5. Codex runs the host-native /goal prompt and stages each completed Sprint phase.

General repo reader/writer tools, snapshot and index consistency, server profiles, and the opt-in dev runner: general-repo-mcp.md. Direct-coding profile: chatgpt-coding-mcp.md. Index-stale, CodeGraph-down, and rollback operations: general-repo-mcp-codegraph.md.

Reviewing Work

Start with tasks/reviews/<task>.review.md. Its ## Human Review Card is the one-screen decision surface: verdict, change type, intended vs actual files, commands passed, external acceptance, residual risk, reviewer action, and rollback. Then inspect the active contract, the latest trace in .ai/harness/checks/latest.json, and the changed files. Accept only when the review recommends pass, the card verdict is pass, and external acceptance is pass, not_required, or an explicit override.

Execution facts and acceptance are separate authorities: a passing verify-contract run proves a command ran, not that the work is accepted. Acceptance is its own typed receipt.

Agents read source artifacts before derived summaries:

Agent reads first	Human reviews first
Current user prompt and referenced files	tasks/reviews/<task>.review.md Human Review Card
AGENTS.md / CLAUDE.md	Changed files and diff
Active plan in .ai/harness/active-plan	Active contract allowed paths and exit criteria
Active contract in tasks/contracts/	.ai/harness/checks/latest.json and run trace
Latest handoff in .ai/harness/handoff/	Residual risks and rollback

tasks/current.md is an ignored local orientation snapshot, not a tracked file. If it disagrees with the active plan, contract, review, checks, or handoff, the source artifacts win.

Runtime-heavy validators (Unity, browser E2E, mobile simulators, hardware rigs, staging smoke tests) can publish external verification manifests under the ignored run-evidence surface — a manual convention today, not an automatic repo-harness check gate. See external tooling.

Skills

Canonical rule-owner packages live under assets/skills/ and assets/skill-commands/, keeping host skill discovery bounded while the CLI and hooks own execution.

Skill	Purpose
repo-harness	Root router Skill, synced unconditionally to every profile
repo-harness-setup	Init, migrate, upgrade, repair, scaffold, and capability-configuration modes; router-only
repo-harness-plan	Create a decision-complete plan, or review an existing one
repo-harness-product	PRD, Sprint, and Goal modes for upper-layer product planning
repo-harness-check	Workflow and release checks plus a deploy-readiness reference
repo-harness-ship	Validate finished worktrees, push branches, and open PRs
repo-harness-architecture	Architecture docs, drift requests, and diagrams without a full harness refresh
repo-harness-cross-review	Independent outside review: Claude hosts use direct Codex; Codex hosts use OpenAI's official codex@openai-codex plugin app-server runtime
claude-plan	Codex-side provider skill: independent Claude plan-mode consult for a design fork or high-stakes decision; not a direct user entrypoint
repo-harness-chatgpt	Oracle browser/GPT Pro consults, MCP Connector setup, and bridge handoff; explicit setup only
merge-gate (external)	Exact-candidate final gate; repo-harness ships no merge-gate Skill — see external tooling

The planning chain is intentionally layered:

idea -> PRD mode -> Sprint mode -> Goal mode

repo-harness init is for an existing repo; repo-harness-setup's scaffold mode creates a new project or module. hooks-init, docs-init, and create-project-dirs are internal steps, not public commands. Per-mode routing boundaries: agentic-development-flow.md and repo-harness docs show harness-overview.

Maintainer Reference

Editing the package itself needs a source checkout:

git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
cd ~/Projects/repo-harness && bun src/cli/index.ts update

That checkout is the only editable source of truth; local Claude/Codex skill paths are symlink-backed runtime entrypoints rebuilt by scripts/sync-codex-installed-copies.sh.

bun run check:ci is the single CI-equivalent gate; bun run check:release only adds the npm unpublished-version preflight before delegating to it. Governance and functional checks run as independent CI jobs, and bun run check:route-eval holds a pinned coverage floor over every prompt-guard intent and action.

bun run check:ci                    # the whole gate
bun run check:context-map           # .ai/context drift against ArchContext nodes
repo-harness docs list              # runtime reference docs, resolved from the package
repo-harness docs show harness-overview
bun scripts/assemble-template.ts --plan C --name "MyProject"

Hook changes update canonical assets/hooks/ once, then run bun run sync:hooks with bun run check:hooks in verification. Reference docs are canonical under assets/reference-configs/ and projected into docs/reference-configs/; bun run check:reference-configs verifies that projection.

Acknowledgements

repo-harness is built around a small set of external skills, repos, and agent runtimes that shaped the workflow contract. They are not ordinary bundled dependencies.

Tool or repo	Used for	Dependency shape
Hylarucoder / Geju	P1/P2/P3 due-diligence method and Geju practice that shaped the planning, tracing, and decision-rationale discipline in this workflow	Methodology contribution and acknowledgement; not a bundled dependency
Waza by TW93, including think, hunt, check, and health	Daily planning, bug hunts, verification, health checks, and Codex-first skill sync	Installed through the skills CLI into host skill roots
mermaid	Authoring and readability review for Mermaid architecture and system-flow source	Runtime-referenced review skill, not vendored into generated repos and never an HTML artifact generator
herdr	Required peer-terminal runtime: notification dispatch, peer collaboration, and hosting the persistent acceptance reviewer	Externally installed binary, checksum-pinned in .ai/harness/policy.json; replaces the retired tmux runtime
reverse-skill-router	Routes reverse-engineering and security tasks to specialist playbooks	Recommended explicit-only Skill (--with-reverse-skill); not profile-selected because upstream's target-mention authorization assumption requires independent scope review
CodeGraph (@colbymchenry/codegraph)	Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo	Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in
Oracle by Peter Steinberger (@steipete/oracle, MIT)	Default GPT Pro / ChatGPT Web browser consult engine that the chatgpt-browser Oracle provider shells out to for gptpro consults	Externally-resolved binary (--oracle-bin, REPO_HARNESS_ORACLE_BIN, node_modules/.bin, or PATH); never auto-downloaded, and a missing binary is a hard ORACLE_NOT_INSTALLED failure
OpenAI Codex	Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work	External agent runtime; attribution is an explicit commit trailer, not hidden hook automation

GitHub Contributor Attribution

When Codex materially contributes to a commit, use GitHub's standard co-author trailer at the end of the message:

Co-authored-by: codex <codex@openai.com>

Keep this opt-in and visible per commit. Do not bake it into downstream repo-harness commit scripts or hooks unless that repo adopts the same policy.

Current Release

• npm package: repo-harness@0.19.0
• Generated workflow stamp: repo-harness@0.19.0+template@0.19.0
• GitHub repository: Ancienttwo/repo-harness
• Release notes and history: docs/CHANGELOG.md

License

MIT — see LICENSE.