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 this Skill only for an explicit repo-harness action or to continue 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, architecture, or reference files only when the resolved state points to them.

Actions

1. setup — install, adopt, migrate, repair, or scaffold the harness. Inspect first with repo-harness adopt --repo . --dry-run; run repo-harness docs show harness-overview when setup 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 using its resolved profile and allowed paths. Lite uses brief → edit → targeted test; Standard uses plan → edit → verify → at most one review; Strict follows the Contract/worktree/checks/external-acceptance chain.
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 with repo-harness-handoff; inject references and deltas, not full artifact copies.

Safety boundaries are deterministic: scope, worktree ownership, secrets, destructive commands, high-risk paths, checks freshness, and review fingerprints fail closed. A user profile override may raise but never lower the computed risk floor.

Detailed command catalogs, scaffold presets, architecture, migration, deployment, hook debugging, and external integrations are on-demand references, not default routing context.

repo-harness

repo-harness turns Claude/Codex coding sessions into a repeatable repo-local workflow. It 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 can continue from files instead of chat memory.

Use it to:

• adopt an existing repo with a tasks-first agent contract
• keep Claude and Codex aligned on the same plans, checks, handoffs, and context boundaries
• spend fewer tokens rediscovering structure by using CodeGraph and progressive context loading

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

Repository: https://github.com/Ancienttwo/repo-harness

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

Why repo-harness

• File-backed sessions, not chat memory. Separate agent sessions — Claude and Codex, now and later — stay coordinated through the repo, not a thread. .ai/hooks/session-start-context.sh injects the prior session's resume packet (.ai/harness/handoff/resume.md, tasks/current.md) when a new session starts; stop-orchestrator.sh writes the stop handoff, while post-edit-guard.sh refreshes edit-time traces and task status after changes. 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 (callers, callees, definitions) and on progressive context loading via .ai/context/context-map.json and capabilities.json: a small, stable root context (~12KB) plus capability blocks loaded only when the files you touch need them. Agents read a 1KB capability contract or query the index instead of spending thousands of tokens rediscovering structure.

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

Human Review Path

Start with tasks/reviews/<task>.review.md. The ## 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, 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 manual override.

Runtime-heavy validators such as Unity, browser E2E, mobile simulators, hardware rigs, or staging smoke tests can publish external verification manifests under the ignored run-evidence surface. This is a manual convention today, not an automatic repo-harness check discovery or gate. See docs/reference-configs/external-tooling.md.

Agent Tracking Path

Agents read source artifacts before derived summaries:

tasks/current.md is only an orientation snapshot. If it disagrees with the active plan, contract, review, checks, or handoff, the source artifacts win.

What's New

Release notes live in docs/CHANGELOG.md. The current line is 0.10.0.

How It Works

The design has three layers:

1. Source package: this repository owns the CLI, CLI-backed command facades, templates, hook assets, workflow contract, tests, and release gate.
2. Target repo contract: repo-harness adopt 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, it resolves hooks central-first through the packaged install or ~/.repo-harness/hooks/, with repo policy able to pin self-host development back to .ai/hooks/*.

Minimal-change hooks sit inside that same route surface without adding a public adapter route. SessionStart and allowed execution prompts print advisory context when policy opts in, PostToolUse.edit can write bounded change signals to .ai/harness/checks/minimal-change.latest.json when post_edit_observer:true is explicitly enabled, and Stop records the latest review summary in the handoff. Missing or malformed policy defaults to off; even mode: "enforce" is normalized to advisory behavior so tests, contracts, and human review stay the enforcement boundary.

For UserPromptSubmit, the public adapter contract stays repo-harness-hook UserPromptSubmit --route default. The CLI route registry dispatches that route to .ai/hooks/prompt-guard.sh. The shell hook remains the repo-local adapter for host JSON parsing, workflow file reads, capture side effects, and host-safe stdout/stderr. It pipes the prompt text into repo-harness-hook prompt-guard-decide, where every prompt-text intent classifier (Unicode-aware, src/cli/hook/prompt-intents.ts) and the intent x plan state decision table live; the engine returns one verdict JSON line with the action, the classified intent facts, and derived strings. The shell keeps no duplicate classifier or fallback decision table — when the engine is unreachable the prompt layer degrades to a one-shot advisory.

Prompt-layer plan/spec/contract gates are advisory routing. Hard enforcement lives at the edit boundary: pre-edit-guard.sh blocks implementation edits unless the active plan is Approved/Executing (policy .guards.edit_plan_gate: enforce | advice | off). Done-claim gates keep blocking because they verify file-backed completion evidence, not language.

The core invariant is that durable truth lives in the repo, not in a chat thread. Hooks are accelerators and guardrails; the authority remains the file-backed plan, contract, review, checks, and handoff artifacts.

Task Workflow: Plan to Closeout

The diagram below assumes the harness is already installed in the repo. It shows the normal lifecycle from a program sprint backlog down to one contract task: draft or select the task, project it into execution files, check out the contract worktree when policy requires it, implement under hooks, verify, review, complete the sprint task when applicable, and close out. The 0.4.x loop-system surfaces add scheduled heartbeat discovery, state-snapshot/eval evidence for routing changes, architecture queue freshness, and optional contract-run delegation without changing the file-backed authority model.

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?"}
  WorktreePolic