RepoPact is a repository-native operating system for durable agent work. It makes authority, intent, evidence, and architectural drift visible in the filesystem so that a new contributor or agent can recover the state of the project without depending on a prior conversation.
Make the repository the pact: authority, intent, evidence, and history that survive every session.
Conventions like AGENTS.md, ADRs, and issue trackers each capture a fragment of
project knowledge, but none of them makes the binding part explicit — the
guarantees an agent must not silently weaken. RepoPact's wedge is the binding
invariant: a declared guarantee with a rationale, an escalation path, and (where
possible) a machine enforcer. That, plus evidence-gated completion and a
filesystem state machine, is what turns a folder convention into a contract.
intent -> scoped authority -> work item -> implementation -> evidence -> audit -> history
- Charter & invariants: principles (judgment) and binding invariants
(escalation-gated) in
governance/. - Frozen surface: paths and symbols that require operator approval to change.
- Scopes & roles: layered
AGENTS.mdfiles plus a role/scope map ingovernance/owners.json. - Work items: narrative
README.mdplus machine-readablework-item.json, with evidence-linked acceptance criteria. - Evidence: immutable run manifests under
evidence/runs/. - Decisions & policies: durable choices (
decisions/) and operating rules (governance/policies/) whose rationale outlives any single work item. - Reconciliation: audits and a generated dashboard that surface drift and review staleness rather than hand-maintaining it.
pip install -r requirements.txt
python scripts/validate_repo.py
python scripts/generate_dashboard.py
python -m unittest discover -s tests -v
python scripts/check_frozen_surface.py --base origin/main
Records are validated against schemas/*.json (structure) and by the validator
(cross-record semantics). See decision
0003.
Begin with AGENTS.md, then read
governance/charter.md and
governance/workflow.md.
Install the CLI, then bootstrap:
pipx install git+https://github.com/ForgeWireLabs/repopact # or: pip install .
repopact init --target ../your-repo # seed a valid RepoPact
cd ../your-repo
repopact new work-item "Title of the work" # stamp records from templates/
repopact validaterepopact dispatches init, adopt, validate, new, dashboard, spec, and
check-frozen against the current repository. The loose-script form still works
(python scripts/init_repo.py --target ...) for repos that vendor the scripts.
For a project that already has CODEOWNERS, CI workflows, and nested AGENTS.md
contracts, adopt maps those existing signals into RepoPact records without
overwriting anything:
repopact adopt --target ../existing-repo --dry-run # preview the plan, write nothing
repopact adopt --target ../existing-repo # create records, then validateCODEOWNERS becomes scopes and roles; each .github/workflows/* becomes a binding-gate
policy (plus invariant INV-2 and a frozen-surface entry); every nested AGENTS.md
is registered as a contract; git history seeds the first evidence run. It is
idempotent — re-running skips records that already exist.
init_repo.py writes the minimal valid source records, copies the schemas and
tooling, and validates the result. Templates for every record type live in
templates/. RepoPact is licensed under Apache-2.0 (see
LICENSE and decision 0002);
its spec version is in VERSION.
Work moves between work/active, work/blocked, work/deferred, and
work/completed. Its work-item.json status must match its directory. Moving a
work item never deletes its reasoning, decisions, or evidence links.
Anything computable from source records is generated, not authored by hand. The
dashboard and audit-freshness views are derived; the only hand-maintained files
are genuine sources (charter, invariants, frozen surface, schemas, owners, work
items, evidence, decisions, policies). See policy 001.