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.
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 act on every request at once: the constitution sets the rules, a skill supplies the procedure, and cross-provider dispatch runs 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. Cross-provider dispatch runs and reviews the work, with Claude Code and Codex as primaries reviewing each other and Fabric carrying the messages, tasks and activity between them.
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 — 33 Agent Skills<br/>one procedure per task, loaded on match"] -. "supplies the procedure" .-> LOOP
F["Cross-provider dispatch<br/>Claude Code and Codex review each other;<br/>Fabric carries messages, tasks and activity"] -. "runs and reviews the work" .-> LOOP
classDef out fill:#1f6f43,stroke:#4fd08a,color:#ffffff,stroke-width:2px
class OUT out
- Harness:
HARNESS.mdis 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 33 Agent Skills are task-specific
procedures, one folder with a
SKILL.mdeach. Only the one-line descriptions sit in permanent context; a full body loads only when the task matches it. - Fabric: messages, shared tasks and an activity log between the agents working on one project, so the primaries can run and review each other's work. One SQLite file, no daemon, nothing to provision.
Requirements:
- Git and Python 3.11+
- Claude Code or Codex, subscription-authenticated, per primary client
- Node.js
>=24.15.0 <25and npm>=11.12.1 <12for repository verification (the suite shells out tonode) - PyYAML and pytest for harness checks (
uv sync --only-group testinstalls the locked versions;scripts/check-harnesshonoursHARNESS_PYTHON)
Install either platform independently, or both:
git clone https://github.com/mblauberg/provenant.git "<PRODUCT_ROOT>"
cd "<PRODUCT_ROOT>"
# install the pinned workspace dependencies
npm ci
scripts/install-harness --platform claude
scripts/install-harness --platform codex
# discover commands, then verify the daemonless Fabric bus
provenant help
provenant fabric whoami
# run the repository gates when changing Provenant
provenant check # harness policy gate
npm run check # TypeScript gatesEach installer command registers the Fabric MCP server for the platform it
installs. Pass --mcp-clients all to either one to register all six clients
instead.
Installation links each skill into ~/.claude/skills/ and ~/.codex/skills/,
installs the Claude subagents from agents/ into ~/.claude/agents/,
and installs a managed copy of the thin provenant command in
${PROVENANT_BIN_DIR:-$HOME/.local/bin}; it warns when that directory is not
on PATH, and never edits shell startup files. During an upgrade, the installer
replaces only the legacy link that exactly names
<instance-root>/scripts/provenant, including a dangling link. It preserves
other files and links as user-owned. 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.
The Claude subagent links have a separate
.agent-harness-agents-installation.json receipt beside ~/.claude/agents/.
Re-running the installer repairs recorded links, while unmanaged files remain
untouched.
provenant fabric whoami creates the project-local Fabric identity and shared
SQLite bus on first use. There is no daemon, trust record, seat bootstrap or
warm/build step. provenant check runs the harness policy gate; npm run check
covers the Fabric typecheck and tests.
Filesystem layout, Codex config and uninstall
<PRODUCT_ROOT>/ product checkout
HARNESS.md product constitution
runtime/ agents/ skills/ workflows/
scripts/ config/
|
| scripts/install-harness
v
~/.agents/ thin instance
AGENTS.md instance-owned instructions
config/ instance-owned configuration
.agent-fabric/product-root.json machine-local product pointer
~/.claude/skills/ managed links
~/.claude/agents/ managed Claude subagent links
~/.codex/skills/ managed links
~/.claude/workflows/ managed links
~/.local/bin/provenant managed command
The Codex installer appends one block to ~/.codex/config.toml disabling
Codex's bundled skill-creator, leaving skill-craft canonical; the rest of
that file is preserved.
From the product checkout,
scripts/manage_installation.py uninstall-managed --target <skills-dir>
reclaims the harness-owned skill links and nothing else. The bootstrap line and
the Codex block remain until removed by hand.
Fabric derives the project from the current working directory. Run
provenant fabric whoami from the project you mean; the first call creates its
database and registers the caller without a separate activation step.
The checked-in profile enables all six clients below. Install and authenticate each before dispatching work through that provider.
| Client or provider | Current integration |
|---|---|
| Claude Code | Primary client and enabled Anthropic provider |
| Codex | Primary client and enabled OpenAI provider |
| Agy | Enabled optional Gemini/Claude provider |
| Cursor | Enabled optional Composer/Grok and hosted third-party provider |
| Kiro | Enabled optional open-weight ACP provider |
| OpenCode | Enabled optional ACP provider for its built-in account models |
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 a signed CLI update needs no compatibility-table edit.
Each task has a front-door skill; the agent loads it when a request matches.
| Need | Skill |
|---|---|
| Agree what to build | scope |
| Deliver an approved code change | implement |
| Deliver research, analysis or documents | deliver |
| Find a root cause | diagnose |
| Review without changing the code | code-review |
| Coordinate parallel agents | orchestrate |
| Promote an accepted artifact | release |
Every change runs the delivery loop and stops at three gates reserved to the user; receipts declare approval rather than authenticating it.
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; specification approval and acceptance can also
return work for revision. Scoping 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, while material decisions stay unresolved.
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:
| Risk | Minimum review pressure |
|---|---|
routine |
chair plus objective and native checks |
substantial |
multiple targeted lenses plus a strong other-primary review |
crucial |
substantial coverage plus a distinct-family review when available |
terminal |
all preceding coverage with stronger targeted and adversarial pressure |
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 beyond post-merge pruning, 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).
Provider workers are dispatched as direct command-line calls; Fabric carries the messages, shared tasks and activity log between them. Herdr is optional: it observes and wakes, never decides.
The full 33-skill catalogue, grouped by area:
All 33 skills
| Area | Skills |
|---|---|
| Delivery | session, scope, deliver, implement, tdd, refactor, diagnose, code-review, evaluate, release, retrospect, work-map, setup-repo |
| Orchestration | orchestrate, autopilot |
| Writing and documentation | engineering-docs, engineering-writing, academic-writing, legal-writing, natural-writing |
| Design and diagrams | ui-ux-design, prototype, d2-diagrams, uml-diagrams |
| Web engineering | playwright, react-performance, tanstack-query, typescript-clean-code, web-stack-conventions |
| Harness development | grill-me, skill-craft |
| Project operations | project-activation |
| Presentation | caveman |
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