A personal harness for Claude Code and Codex that turns agent work into a scoped, verified and independently reviewed delivery workflow.

Provenant is a personal harness, used daily by its author. Interfaces change without notice and support is best effort. Propose changes through GitHub issues; report vulnerabilities privately through SECURITY.md.

• Why Provenant
• How it fits together
• Quick start
• Providers
• Core workflows
• Lifecycle
• What the harness guarantees
• Skill library
• Documentation and help

A bare coding agent will write and "finish" a change in one pass, with its own author as the only reviewer. Provenant puts structure around that:

• it scopes work in dialogue with the user, returning open decisions as questions, and requires approval before implementation starts;
• it runs deterministic checks before any result surfaces for review;
• it adds review by the other model family once the work is substantial: Claude checks Codex, Codex checks Claude; and
• it keeps acceptance and release as separate user decisions.

A change therefore arrives already scoped, verified and read by a context that did not write it, so user attention goes to judgement rather than to catching an agent's own mistakes.

Three parts bear on every request at once: the constitution sets the rules, a skill supplies the procedure, and Agent Fabric executes and cross-reviews the work. None of them is a stage the work passes through.

flowchart TB
    accTitle: The three parts and the delivery loop they serve
    accDescr: A user request enters the delivery loop, which runs scope, implement, verify and review, and produces a scoped, verified, independently reviewed change. Three parts act on that loop concurrently rather than in sequence. HARNESS.md, the constitution, sets the rules — authority, lifecycle and review pressure. The skills library supplies the procedure, one SKILL.md per task loaded when the task matches. Agent Fabric runs and reviews the work across providers, with Claude Code and Codex as primaries reviewing each other and optional providers separately activated.
    U(["User request"]) --> LOOP["Delivery loop<br/>scope · implement · verify · review"]
    LOOP --> OUT(["Scoped, verified,<br/>independently reviewed change"])
    H["HARNESS.md — the constitution<br/>authority · lifecycle · review pressure"] -. "sets the rules" .-> LOOP
    SK["Skills library — 32 Agent Skills<br/>one procedure per task, loaded on match"] -. "supplies the procedure" .-> LOOP
    F["Agent Fabric — cross-provider execution<br/>Claude Code and Codex review each other;<br/>optional providers stay separately activated"] -. "runs and reviews the work" .-> LOOP
    classDef out fill:#1f6f43,stroke:#4fd08a,color:#ffffff,stroke-width:2px
    class OUT out

• Harness: HARNESS.md is the constitution. It sets authority, the delivery lifecycle, and how much review pressure each risk tier owes, and stays small so it can be read every session.
• Skills: the 32 Agent Skills are task-specific procedures, one folder with a SKILL.md each. Only the one-line descriptions sit in permanent context; a full body loads only when the task matches it.
• Agent Fabric: cross-provider execution and durable coordination, so the primaries can run and review each other's work. Optional providers stay separately activated.

Requirements:

• Git and Python 3.11+;
• a subscription-authenticated Claude Code or Codex installation for each installed primary client;
• Node.js >=24.15.0 <25 and npm >=11.12.1 <12 to run repository verification (the suite shells out to node); and
• PyYAML and pytest for harness checks (uv sync --only-group test installs the locked versions; scripts/check-harness honours HARNESS_PYTHON).

Install either platform independently, or both:

git clone https://github.com/mblauberg/provenant.git "$HOME/.agents"
export AGENTS_HOME="$HOME/.agents"   # optional override; the installed harness defaults here
cd "$AGENTS_HOME"

# install the pinned workspace dependencies and compile Fabric before its first use
npm ci
"$AGENTS_HOME/scripts/agent-fabric-warm"

"$AGENTS_HOME/scripts/install-harness" --platform claude
"$AGENTS_HOME/scripts/install-harness" --platform codex

# discover commands, then verify Fabric
provenant help
provenant doctor

# run the full repository gate when changing Provenant
provenant check

Installation links each skill into ~/.claude/skills/ and ~/.codex/skills/, and links the thin provenant command into ${PROVENANT_BIN_DIR:-$HOME/.local/bin}; it warns when that directory is not on PATH, and never edits shell startup files. If the installer exits non-zero, follow the message it prints: exit 3 flags a command collision, incompatible instruction target, or managed skill-link conflict, and instruction conflicts include the bootstrap line to add.

provenant doctor checks Fabric configuration and enabled adapters (identity and non-answer interfaces, not login or quota); Provenant never sets or persists provider API keys. provenant check runs the full repository gate.

~/.agents/                cloned once
  HARNESS.md    the constitution
  AGENTS.md     the bootstrap line
  skills/       one folder per skill
  scripts/      install, route, check
  config/       risk, routing, profiles
     |
     |  scripts/install-harness
     v
  ~/.claude/skills/   symlinks
  ~/.codex/skills/    symlinks

The checked-in profile enables all six clients below. Install and authenticate each before provenant doctor.

Provider CLI versions and digests are diagnostic observations, not admission locks. Provenant revalidates vendor identity, wrapper provenance and each bounded provider interface at point of use, so an ordinary signed CLI update does not require a compatibility-table edit.

Each task has a front-door skill; the agent loads it when a request matches.

Every change runs the same delivery loop, and it stops at three gates only the user can pass.

flowchart TB
    accTitle: The delivery loop and its three user gates
    accDescr: After a session sets up clean context, the deliver kernel runs the loop top to bottom: scope writes the specification and risk tier, a user gate approves it, implement writes the test first whenever observable behaviour changes, verify runs deterministic checks, and review reads the work in a fresh context that never wrote it, using targeted lenses plus the other primary from the substantial tier up. Two dotted edges return: the approval gate sends the plan back to scope, and a blocking review finding sends the work back to implement for a bounded repair. A user gate then accepts, leading to retrospect and the next cycle. Release and observe sit outside the loop, behind a third user gate that authorises the external action.
    SC["scope · spec, risk tier, acceptance criteria"] --> G1{{"USER · approve the spec"}}
    G1 -. "send back" .-> SC
    G1 --> IM["implement · test first when behaviour changes"]
    IM --> VF["verify · deterministic checks"]
    VF --> RV["review · fresh context<br/>targeted lenses + other primary at substantial+"]
    RV -. "blocking finding" .-> IM
    RV --> G2{{"USER · accept"}}
    G2 --> RT["retrospect"]
    G2 -. "only if it ships" .-> G3{{"USER · authorise the action"}}
    G3 --> RL["release · observe"]

    classDef gate fill:#8a6d1f,stroke:#f0c674,color:#ffffff,stroke-width:2px
    class G1,G2,G3 gate

Gold hexagons are user gates. Every gate can stop progression; specification approval and acceptance can return work for revision. Scoping itself is usually a conversation: a decision packet with choices and a recommendation, owner calls parked as named questions rather than guesses, and the grill-me interview, one question per round, on request or while material decisions stay unresolved. review runs in a fresh context that never wrote the diff. From the substantial tier up it requires multiple targeted lenses plus the other primary; a receipt missing that leg cannot reach acceptance.

The loop is deliver, the kernel binding one run to one receipt; implement is its software front door, and the full lifecycle lives in docs/ARCHITECTURE.md.

Review pressure scales with the risk tier the work is scoped at:

Solo routine work still completes, but substantial and above cannot reach acceptance with the other-primary leg missing. Distinct-family review is advisory when available; a skipped terminal distinct-family leg records its reason. Evidence and corroboration, not model votes, make a finding blocking. The canonical ladder lives in HARNESS.md.

Durable boundaries hold regardless of tier:

• access and credentials never grant authority;
• creating branches and worktrees for implementation is pre-authorised; merge authority comes from the owning repository (this repo grants it through its GitHub runbook); deletion, force-removal and unauthorised shared-branch pushes stay gated;
• no two agents write one source surface at once; and
• specification approval, acceptance and release stay separate user decisions (HARNESS.md).

Agent Fabric owns answer-bearing provider execution and durable coordination; direct command-line calls are a preflight or a recorded degraded fallback. Herdr is optional: it observes and wakes, never decides.

The full 32-skill catalogue, grouped by area:

• Architecture: system structure and design rationale.
• Specifications: the component contracts.
• Research: evidence and owners.
• Maintenance: how the repository is changed and governed.
• Security: private vulnerability reporting.
• GitHub issues: normal feedback and change proposals.

Legal: MIT licence · Notices · Third-party notices · Acknowledgements