Agent Change Records

Quick answer

An Agent Change Record is a machine-readable record of AI-assisted engineering work. It captures task intent, workflow state, changed files, verification evidence, and review status so a human or tool can inspect what happened around a Git diff.

{
  "task": {
    "id": "202605190828-MDXT5W",
    "intent": "Add input validation"
  },
  "changes": {
    "files_changed": ["packages/core/src/input.ts"],
    "work_commit": "abc1234"
  },
  "verification": {
    "checks": ["npm test", "npm run typecheck"],
    "status": "ready_for_review"
  }
}

Why does ACR exist?

A diff shows what changed. An Agent Change Record shows why the change exists, which workflow constrained it, which checks ran, and whether the result is ready for review.

What fields mean?

• Task intent.
• Workflow state.
• Changed files.
• Git revisions.
• Verification evidence.
• Review status.
• Links to supporting artifacts.

Generate and validate

agentplane acr generate <task-id> --work-commit HEAD --write
agentplane acr validate <task-id> --mode local
agentplane acr check <task-id> --mode ci
agentplane acr explain <task-id>

For portable task-local evidence, create and verify an evidence bundle:

agentplane evidence bundle <task-id>
agentplane evidence verify <task-id>

Use ACR with Git

Keep ACR task-local:

.agentplane/tasks/<task-id>/acr.json

Git stores the final diff. The Agent Change Record stores the evidence around that diff.

Attach or link the task ACR in pull request review when a reviewer needs to see approved plan, verification evidence, changed-file summary, and merge-readiness status without reconstructing it from chat history.

Privacy baseline

ACR records evidence pointers, checks, status, and hashes. It should not store secrets, credentials, private tokens, raw prompts, or full model transcripts by default.

Schema reference

See ACR schema for field-level reference and validation notes. See Evidence bundles for deterministic task artifact manifests.