Intent: keep old behavior intact while AI changes your code

The quiet regression

Agent-driven changes get merged because the suite is green. If a test was edited to get there, green means nothing. Intent makes that shortcut visible and blocking in CI.

A lifecycle that pauses only when it must

Inception, construction, and conformance review. Clear work proceeds; a person is asked only for a material decision or when repository policy reserves it.

Open the lifecycle map full screen

Draft to implementing. Concise scope and verification are recorded, then work starts. No approval ceremony by default.
The review gate is conditional. Material ambiguity or repository policy pauses only the work that depends on the answer.
Close with evidence. A conformance record states outcomes, deviations, and verification; a complete change must include it.

Every claim is checked against the repository

The verifier reads the change record and the diff, then reports each unmet rule instead of passing quietly.

Proposal digest matchesSHA-256 over proposal.md bytes, compared to the recorded digest.
Test changes are declaredEvery modified, skipped, or deleted test appears in the proposal and in test_changes.
Protected paths stay intactTest paths are protected by default and configurable per repository.
Scope containmentWhen the change declares path globs, edits outside them fail.
Approval is boundWhen policy requires review, an approval must name the current digest and an authorized reviewer.
Baseline stays greenThe repository check runs at the change and at its base revision.

$ sh .intent/scripts/verify-change.sh --change .intent/changes/CHG-0007 --base origin/main
verify-change: proposal digest matches change.yaml
verify-change: FAIL: protected path changed but not declared in the proposal: tests/export_test.py
verify-change: FAIL: approval evidence for the current proposal digest is missing
verify-change: 2 check(s) failed

$ sh .intent/scripts/verify-change.sh --change .intent/changes/CHG-0007 --base origin/main --command 'make test'
verify-change: proposal digest matches change.yaml
verify-change: changed paths are within declared scope
verify-change: change verification command passed
verify-change: change verified: .intent/changes/CHG-0007

Open the change flow full screen

Approval binds to the proposal digest

An approval names the SHA-256 of proposal.md. Edit the proposal after approval and the digest stops matching, so the old approval no longer opens the gate.

Approval constraints travel with the decision. An agent cannot approve its own proposal, and a merge or comment is not approval unless the policy adapter verifies it.

Records live in your repository

No central service. The protocol, schemas, verifier, decision log, and every change record live in .intent/ and travel with the code.

The installer pins the versions your records were written under. Upgrading is a deliberate reinstall with --upgrade, and existing configuration and project facts are preserved.

.intent/
  config.yaml            # policy, reviewers, protected paths
  PROJECT.md             # repo facts, build and test commands
  decisions/             # durable rationale across changes
  changes/CHG-0007/
    proposal.md          # the intent, digest bound
    change.yaml          # state, scope, digest, test changes
    review.yaml          # approval evidence, when required
    conformance.md       # verification record
  protocol/v1.md         # pinned contract
  schemas/v1/            # machine-checkable rules
  scripts/verify-change.sh
AGENTS.md                # managed guidance block

Install once, verify in CI

The installer writes only its marked sections and never stages or commits anything. Approval stays off until policy turns it on.

Install the pinned bundle into any Git repository on macOS or Linux.
Set policy.verify_command in .intent/config.yaml so checks run without flags.
Run the verifier in CI against the change's base revision, with the baseline required.

Or hand it to your agent: the install prompt runs the dry run first, then installs and completes the project facts.

Install

sh scripts/install.sh --target /path/to/your/repo

Verify in CI

sh .intent/scripts/verify-change.sh \
  --change .intent/changes/CHG-0007 \
  --base origin/main \
  --command 'make test' --baseline

Agent prompt

Clone https://github.com/xpressabhi/intent with --depth 1 to a temporary directory, read docs/install-prompt.md from the clone, and follow it to install Intent in this repository.