First workflow

Initialize a project

mkdir hello-project && cd hello-project && aip init

Save the returned root state ID if you want to compare against the empty project.

Record the purpose

aip intent create \
  --title "Add greeting endpoint" \
  --goal "Expose GET /hello returning JSON" \
  --constraint "Keep existing routes compatible" \
  --format json

Save the intent ID from the response. Create your source files normally, then inspect aip status. AIP does not require a staging area.

Preserve and inspect a candidate

Replace <intent-id> with the returned full ID:

aip snapshot --intent <intent-id>
aip state show HEAD
aip history

A snapshot creates the relevant artifact, operation, and state objects. The operation links the intent to the observed file effects. Objects are immutable.

Use aip diff <root-state-id> HEAD for a file/text comparison.

Validate the exact state

For a Go project with tests:

aip evaluate HEAD -- go test ./...

AIP materializes the state into a fresh directory, runs the command, and records executed evidence. This includes arguments, timing, exit status, output artifacts, and whether the evaluated files changed during execution.

aip evidence add --type test --command "go test ./..." --result pass instead records a report supplied by you. It does not execute the command.

Compare alternative solutions

Save a common parent state ID. Make your first candidate and snapshot it with aip snapshot --base <parent-id> --intent <intent-id>. Make a different candidate and snapshot it with the same parent ID.

         parent
         /    \
 candidate A  candidate B

--base selects the parent; it does not restore or change working files. Each snapshot observes the complete current workspace. Both candidates remain in aip history, and you can compare them with aip diff <candidate-a> <candidate-b>.

To inspect an earlier candidate in ordinary files, use aip materialize <candidate-a> --to <new-directory-outside-project>.

All important commands accept --format json for agent use.