An AI agent running on your computer validates its checkout with workspace validate, without a delivery package. A web chatbot or AI handing changes to a different checkout needs a producer with Git and POLIS to create and transfer a .polis file.
The deciding factor is where the code and validation run, not just the chat interface. Both workflows require a contract, appropriate proof, and gates.
The agent can access the repository and run the CLI in the checkout it edits. After locking the contract, collecting required proof, and implementing the change, validate that workspace.
polis workspace validateNo delivery .polis file. An optional external checkpoint report is not a package.
For delivery to another checkout, a producer must actually access the source, Git, and POLIS CLI. A chat-only conversation cannot build or verify a package.
polis build → verify → preflight → applyA transferable .polis file is built outside the repository. The consumer verifies it and applies only with authorization.
.polis file ≠ .polis/ directory change.polis is a transferable package produced by polis build. The .polis/ directory holds project configuration such as .polis/policy.json, .polis/policy-provenance.json, and optional evidence under .polis/artifacts/. A separate JSON policy can also be supplied with --policy. This directory does not mean a package was built, and new packages are never retained there.
POLIS connects requirements, development proof, validation policies, and identifiable code changes.
Every change begins with defined requirements, acceptance criteria, file scope, and proof.
Explore contracts 02 / EVIDENCEGates, Red/Green proof, input identity, and explicit PASS, FAIL, or BLOCKED outcomes.
Explore validation 03 / CONSUMPTIONThe consumer checks the package in its own environment before authorizing changes.
Understand preflight and applyThe diagram below applies only to transfer: a producer with the CLI builds a .polis file, and the consumer decides whether to accept it. For an agent in the same checkout, use workspace validate without a package.
Specifies, implements, and packages for another checkout.
polis startcapture-redpolis buildVerifies and applies with authorization.
polis verifypolis preflightpolis applyThis diagram describes remote delivery. For the same checkout, use workspace validate without a package. Red-to-Green requires capture-red; Green-to-Green uses characterization. Plans are optional. Learn more.
Install the CLI to begin. doctor checks your environment; init generates project policy; plan previews validation from the explicitly supplied policy.
# Requires Go 1.23+ and Git
go install github.com/MarcosAlves90/polis/v6/cmd/polis@latest
# Verify installation
polis doctor
# Explore your validation configuration
# Run at the root of a Git repository with a Go module
# Temporary directory outside the repository
POLIS_OUTSIDE="${POLIS_OUTSIDE:-$(mktemp -d)}"
mkdir -p "$POLIS_OUTSIDE"
polis init --repo . --profile auto --dry-run > "$POLIS_OUTSIDE/policy.json"
polis doctor --repo . --policy "$POLIS_OUTSIDE/policy.json"
polis plan --repo . --policy "$POLIS_OUTSIDE/policy.json"From your first run to contracts, verification, and trust boundaries.
Choose local validation or remote delivery.
02 — REFERENCECommand reference with examples and effects.
03 — FOUNDATIONSLearn what the system guarantees and where its limits lie.
04 — PROJECTUnderstand the Guide, Specification, and CLI layers.
Explore the source code, read the V6 specification, and follow POLIS development.