Provenance
Living requirements index + CLI for spec-driven development. Works with any AI agent.
Provenance (prov) keeps your requirements in plain markdown next to your
code, gives you a CLI to query them, and teaches your AI agent to read before
it writes. The spec files are always the source of truth — everything is plain
text, and grep always works.
Install
Requires Python 3.9+.
uv tool install provenance-cli # recommended
Alternates:
pipx install provenance-cli
pip install provenance-cli
Quick start
cd /path/to/your-project
prov init # scaffold prov/CONTEXT.md + install agent skills/rules
# edit prov/CONTEXT.md: project name, purpose, constraints, domain map
prov orient # verify — start every session here
After init:
your-project/
prov/
CONTEXT.md ← edit this
<domain>.md ← domain specs as you add them
.claude/skills/ + CLAUDE.md block ← agent assets (Claude standard)
.agents/skills/ + AGENTS.md block ← agent assets (open standard)
CLI
| Command | Purpose |
|---|---|
prov orient |
Project overview — start every session here |
prov scope <path> |
What governs this file or directory? |
prov context <slug> |
Full entry: statement, provenance, deps, code refs |
prov impact <slug> |
Blast radius before changing anything |
prov find <keywords> |
Search when you don't know the slug |
prov domain <name> |
Load a full domain |
prov validate |
Run before every commit — zero errors only |
prov check-slug <slug> |
Is this slug available? |
prov reconcile <path> |
Detect code<->spec drift (read-only) |
prov sync [path] |
Drift report + patch sub-commands to fix it |
prov rebuild |
Regenerate the optional .spec/ cache |
prov write |
Add entries from JSON (validates before writing) |
prov diff [ref] |
Semantic change manifest vs HEAD or any ref |
prov init |
Scaffold CONTEXT.md + agent assets |
Full reference with flags and exit codes: docs/cli.md.
What a spec entry looks like
session-expiry: Sessions expire after 30 days of inactivity.
> inferred: user said "standard session timeout, nothing crazy"
! assumed 30 days — unconfirmed
@ C:jwt-stateless
~ src/middleware/session.py:44
A slug, a current-state statement, provenance (>), agent assumptions (!),
dependencies (@), and code refs (~). Code links back with # spec: session-expiry comments; prov validate checks both directions. Full format
— node types, sigils, provenance source types, validation checks, grep
patterns: docs/spec-format.md.
Agent setup
prov init installs the same skills and rules for both agent standards:
.claude/skills/ plus a managed block in CLAUDE.md (Claude Code), and
.agents/skills/ plus a managed block in AGENTS.md (Codex/GPT-style and
other skill-aware agents; tools like Cursor can point at AGENTS.md). The
rules teach the agent to run prov scope before touching code and
prov validate before committing, and to self-heal missing skills once per
session. Details, the marker-block behavior, and the optional pre-commit
hook: docs/agent-setup.md.
Docs
| Page | Contents |
|---|---|
| docs/cli.md | Full command reference |
| docs/spec-format.md | The spec DSL, validation, grep fallback |
| docs/agent-setup.md | Agent assets, managed blocks, pre-commit hook |
| docs/architecture.md | Complete technical specification |
| docs/publishing.md | Release and publishing flow |
| docs/development.md | Contributor setup and repo layout |
License
MIT — see LICENSE. Contributing: see docs/development.md.
1 maintainer
Metadata
1 maintainer
Release files for provenance-cli 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| provenance_cli-0.2.0.tar.gz | 136.4 kB | Without provenance | Details for provenance_cli-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| provenance_cli-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for provenance_cli-0.2.0-py3-none-any.whl |
Total release size: 200.5 kB
Release files / provenance_cli-0.2.0.tar.gz
| Download URL | provenance_cli-0.2.0.tar.gz |
|---|---|
| Size | 136.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f33b3ff1f98829590e26004bf5df2d18efba0fd84d7153cb7fd107b4b7f545f9
|
|
BLAKE2b-256 checksum How to use checksums |
f07625aabe181159d6e7b1ed7f90fcb1ea3764356f1d7a37b28d51a689fa8f6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / provenance_cli-0.2.0-py3-none-any.whl
| Download URL | provenance_cli-0.2.0-py3-none-any.whl |
|---|---|
| Size | 64.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ac11d16191f523560c7d38e70fc1152b5f481ed90e579f4c9e74983f35bd9ca
|
|
BLAKE2b-256 checksum How to use checksums |
badca7f44aae7fe2b7c4e0f2bf2eee46d51cc2fe0c9bc62ab633deaf42764b2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for provenance-cli 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
