Agent Intent Protocol, version 1

AIP models development as intent, operations, resulting state, and evidence. This experimental local milestone defines a protocol independently of its Go reference implementation. Git, a hosting service, and an agent model are not dependencies.

Read in this order:

1. Objects and invariants
2. Canonical encoding
3. Repository layout and publication
4. States, candidates, observation, and diff
5. Conceptual transport
6. Executed evaluation
7. Experimental HTTP transport (post-milestone-1 development profile)
8. Agent instruction files (reference CLI convenience)

MUST/MUST NOT specify requirements; SHOULD specifies a recommended behavior. The object and encoding specifications are normative. CLI behavior and the filesystem publication mechanism describe this reference implementation. Transport has a conceptual boundary and an experimental loopback HTTP binding. Hosted transport and multi-user authentication are not implemented.

The checked-in testdata/vectors/vectors.json and .cbor files are normative examples. Each entry includes its diagnostic object, exact encoded hex, and SHA-256 identity. {"$bytes":"hex"} is a vector-only notation for byte strings, not a map encoded into that object. generate.py is a separate Python stdlib encoder used to construct the corpus; Go tests never regenerate expectations. An independent implementation must agree with both the prose and these vectors.

Scope

V1 includes six versioned object types, regular filesystem files filtered by a root .aipignore, state candidates, explicit effects, reported and executed evidence, decisions, a local CAS, state materialization into new directories, and a structured CLI. Multi-parent synthesis semantics, hosted networking, signatures, multi-user permissions, checkout, semantic diff, SDKs, and hosting are deferred. AIPHub and MCP can later be adapters around this protocol.

Object hashes provide integrity and identity, not authorship or truthfulness. Intent constraints are recorded text; v1 does not automatically enforce them.

The milestone 1 acceptance record maps requirements to their implementation and validation. It is a completion record, not a normative schema.

Agent interface

--format json produces exactly one JSON value on stdout followed by a newline. Success is {"ok":true,"data":...}; failure is {"ok":false,"error":{"code":"aip_error","message":"..."}}, exit status 1. Exit status 0 means success. Evaluate additionally returns 2 for a recorded failing check and 3 for a recorded unknown outcome, both with ok: true and an evidence ID; exit 1 means a command error. Messages are human descriptions, not stable codes. All current failures share the stable generic aip_error code. Agents SHOULD inspect ok and command-specific fields instead of parsing messages.

--format text is the default; failures go to stderr. Flags may appear before or after positional arguments; --flag=value and --flag value are accepted. -- ends option parsing. IDs are full lowercase hashes, except HEAD where a state/object reference is accepted. Abbreviated IDs are not supported.

init returns repository and initial state. status returns the observed HEAD ID, clean boolean, and ordered file changes. intent create and evidence add return the new ID; evidence also returns provenance. snapshot returns state, operation, intent, parent, and changed-file count. Lists contain records with id and canonical object shown in JSON; byte strings appear as base64.

materialize <state-id|HEAD> --to <directory> returns state, destination (an absolute path with its parent resolved), and files (a count, including zero). The directory must not exist and must have an existing parent outside the source repository. Relative destinations use the caller’s working directory. See states.md for file modes, name representability, concurrency, and failure behavior.

state show adds derived evidence records and direct child candidates IDs. Its text view summarizes intent titles/goals/constraints, parent and operation IDs, file count, direct candidates, and evidence outcomes. Text history shows the same state relationships and evidence summaries, with the current HEAD marked. Reported claims are labeled separately from executed observations; execution summaries include termination, exit code when available, workspace status, and capture truncation. JSON retains full objects rather than these presentation strings. object show for an operation adds resulting_states and evidence IDs. These additions are outside the canonical object. object verify returns the ID, valid: true, and the checks performed, or an error. history lists states in the deterministic ancestor-before-child traversal specified in states.md. log lists all non-artifact objects in ID order; it is not a timestamp-sorted execution audit.

diff returns ordered file changes with path, kind, before, after, and representations. Absent entries are null. Representation types are text/unified and binary; their text is presentation, not canonical history. status uses the same changes with empty representations.

evaluate takes all subprocess arguments after a required -- delimiter; AIP flags must precede it. It saves executed evidence version 2 while evidence add continues to save reported version 1. Type/version pairs, rather than a global object version, determine the schema. Existing object IDs are unchanged. See evaluation.md for result fields, deadlines, process handling, captured output, environment policy, and execution limits.

serve --name NAME [--listen 127.0.0.1:7777] [--visibility private|public] starts the experimental local HTTP service using an environment credential. It blocks until interruption and returns its CLI response on shutdown. See http.md for the wire contract, authorization, and development limits.