Cairn for AI Coding Agents: Git, Plans, and Evidence

Updated 5 November 2026 · Standard formula, shown below

Cairn is a way to give AI coding agents a durable record of what they are meant to do, what they changed, and what supports the claim that the work is complete. Git preserves the code history; a plan tracker records task status; evidence links the reported result to checks such as tests, diffs, or command output, so the three answer different questions rather than competing to be the single source of truth.

Why agents need more than a Git log

A Git repository is excellent at storing and comparing file changes. A commit can show exactly which lines changed and when, but it does not necessarily explain the task, whether it is still in progress, which acceptance criteria apply, or whether the change passed relevant tests. Those omissions matter when an agent works across multiple steps, pauses between sessions, or hands work to a person or another agent.

A plan tracker supplies that missing work context. It can represent a larger goal as smaller tasks, mark their state, and capture dependencies or open questions. Evidence then helps establish whether a task’s completion claim is justified. In a Cairn-style workflow, these pieces are connected: the plan describes intended work, Git records implementation, and evidence substantiates the outcome.

How Git, plans, and evidence fit together

Plans answer “What should happen?” They identify goals, subtasks, dependencies, and completion conditions.
Git answers “What changed?” Commits, branches, diffs, and repository state expose the code history and current implementation.
Evidence answers “Why believe it is done?” Test results, build output, reproducible commands, and relevant review notes support specific completion claims.

These records should point to one another where practical. A plan item might reference a commit or pull request; its evidence might record the test command and whether it passed. The code itself remains in Git, rather than being copied into a status note. This separation reduces duplication and makes it easier to check whether a claim still matches the repository.

Consider a task to add validation for an uploaded file. The plan might list allowed formats and the expected rejection behavior. A commit records the implementation. Evidence could state that focused validation tests passed and identify the command used. A vague “done” status is weaker: it says nothing about which requirements were checked or what happened when they were tested.

A practical agent workflow

Inspect the repository first. Check the current branch, working tree, recent changes, and project instructions. Existing uncommitted edits may belong to a person or another task; an agent should not overwrite or casually discard them.
Translate the request into a plan. Write small, verifiable tasks and note assumptions or dependencies. Define what would count as completion before changing code.
Make and review focused changes. Work in manageable increments, inspect the diff, and avoid mixing unrelated cleanup into the requested change. Use commits when they fit the project’s conventions.
Run relevant checks. Start with targeted tests, then run broader checks when appropriate. Record the actual commands and outcomes; distinguish tests that passed from checks that were skipped or could not run.
Update the plan with evidence. Mark a task complete only when its stated conditions are met, and attach enough detail for someone else to verify the claim. If a check fails, record that and leave the task open or explain the remaining limitation.
Hand off clearly. Summarize changed files or commits, checks performed, known gaps, and the next action. Do not imply that a test passed merely because it was intended or attempted.

What counts as useful evidence?

Useful evidence is specific, relevant, and proportionate to the claim. For a code change, a passing focused test is generally stronger than an unqualified statement that the feature works. A build result can support the claim that the project builds, but it does not prove every behavior is correct. A diff can show that code changed, but not that its behavior meets a requirement.

Evidence may include:

The exact test, lint, or build command and its outcome.
A commit identifier or link to the relevant change.
A concise explanation of manual verification, including the scenario checked.
An explicit note that a check was not run, along with the reason, such as missing dependencies or unavailable services.

Evidence is not a guarantee of correctness. Tests can miss edge cases, and logs can be incomplete or stale. Keep evidence tied to the revision it describes, and rerun relevant checks after later edits. Avoid recording secrets, access tokens, or unnecessary personal data in plans and logs; repository history and shared work notes can persist longer than expected.

Common failure modes and misconceptions

“If it is committed, it is finished.” A commit proves that a change was recorded, not that acceptance criteria were met. Completion still depends on the task and the checks appropriate to it.

“The plan is the code’s source of truth.” A plan describes intended work and status; the repository is authoritative for the files that exist. If the plan says one thing and the current diff shows another, investigate and update the record instead of assuming the plan is current.

“A green test suite proves everything.” A passing suite only supports the behaviors it actually exercises. Report its scope honestly, especially when tests are narrow, skipped, or run against a different revision.

Stale status and invisible work. An agent may change code but forget to update the tracker, or mark a task done before recording failed checks. Short, regular updates prevent a second agent or reviewer from mistaking an old status for current truth.

Overly elaborate tracking. Recording every keystroke or duplicating full diffs in a plan creates noise and maintenance work. Keep plans focused on decisions and task state, and use Git for detailed code history.

When this approach helps

Linking plans, Git, and evidence is especially valuable for work that spans multiple sessions, has several acceptance criteria, or will be reviewed by someone who did not watch the agent work. It also helps when tasks depend on one another: a tracker can show which work is blocked, while Git and test results show what has actually landed.

For a tiny, one-file change, a formal plan may be unnecessary. A clear commit and a concise test result may be enough. The useful principle is not “track everything”; it is “make the state and proof visible in proportion to the risk and complexity of the task.”

Frequently Asked Questions

Is Git the source of truth for an AI coding agent?
Git is the source of truth for versioned repository content and its history. It does not, by itself, fully describe task intent, current blockers, or whether requirements were verified.

What should an agent put in a plan tracker?
Record the goal, small tasks, dependencies, acceptance conditions, status, and important blockers. Link to commits or checks rather than copying large amounts of code or output into the plan.

What is evidence in an agent workflow?
Evidence is information that supports a completion claim, such as a test command and result, a relevant diff, or a described manual check. It should identify what was checked and any important limits.

Does a passing test mean the task is complete?
Not automatically. The test must cover the relevant requirement, and other acceptance conditions may remain. Report exactly what passed and what was not checked.

Should every coding task have a plan?
No. The amount of tracking should fit the task. A brief change may need only a clear commit and check result; multi-step or handoff-heavy work benefits from explicit tasks and linked evidence.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.