Working with agents

Agents need to know that your project uses AIP. Make the aip binary available on their PATH, then run aip agent setup inside the repository.

The command creates missing root AGENTS.md and local .aip/AGENTS.md guides. Existing files are preserved exactly. If your root guide already exists, integrate the workflow below into it. Putting instructions only inside .aip/ does not guarantee an agent will discover them.

aip init creates the local guide automatically without changing project files. The root guide is an ordinary artifact included in later snapshots. The local guide is excluded, so root instructions should remain useful on their own when a state is materialized. Neither guide is a canonical protocol object.

Suggested repository instructions

This repository uses AIP for version control.

1. Read aip status --format json and aip state show HEAD --format json.
2. Create an intent with the goal and constraints before making a change.
3. Edit ordinary project files. List secrets and generated output in the
   root .aipignore so they stay out of snapshots.
4. Inspect aip status --format json before taking a snapshot.
5. Snapshot with the intent ID, then validate that immutable state using
   aip evaluate HEAD -- PROGRAM ARGS.
6. Inspect evidence and report the state ID with the validation result.

For alternatives, save the common parent ID and use snapshot --base with
that same parent. This does not restore files. Coordinate agents in
separate workspaces so their file edits do not race.

Use --format json. Do not infer command results from decorative text.
Do not claim tests ran when you only recorded reported evidence.

Constraints and evidence

An intent records why work exists and which constraints apply. It does not prove that those constraints were respected. Agents and reviewers still need to evaluate the changes and inspect appropriate evidence.

Executed evidence belongs to the evaluated state. Later edits to working files do not invalidate that record, but they are also not covered by it.

Interface boundaries

The CLI is the agent interface today. AIP does not require a model provider or an agent framework. Language SDKs and an MCP adapter are future adapters around the protocol, not parts of its core.