Agent workflow for Better.

First Checks

Before editing, inspect the current Better state and prior related work:

better --json status
better --json release status
better changes
better --json context --task "short task description" --file path/to/file --symbol SymbolName

If context returns reuse_or_inspect, inspect the referenced checkpoint or replacement session before duplicating work. If it returns coordinate, related active work exists.

Start A Session

Create a session with a clear task and accurate file claims:

better --json session start \
  --task "short task description" \
  --owner agent:<name> \
  --file path/to/file

If you later touch another file, update the claim before checkpointing:

better session update <session-id> --file path/to/other-file

Checkpoint And Compose

Prefer Better workspaces for isolated parallel work, then checkpoint the workspace:

better workspace create --session <session-id>
better --json workspace status --session <session-id>
better --json checkpoint --session <session-id> --workspace --message "what changed"

Before integration, run the required project checks and inspect composition:

better --json status
better compose --json

Session Cleanup

better session abandon <session-id> --reason "discarded approach"

Use abandon when work is intentionally discarded. Use supersede when a checkpointed replacement owns the work, and use refresh when continuing stale work from the current frontier.

Abandonment releases active claims but preserves the session, checkpoints, operation history, workspace, files, and stored objects for inspection. It does not delete a workspace or files, and missing_claimed_path remains strict for active sessions. Syncing abandoned sessions requires Better v0.1.0 or later on both peers.

Report Back

End with concrete evidence: session id, checkpoint id, release id if accepted, remote sync result if used, verification commands and outcomes, and any remaining Better signals or risks.