Automation and JSON protocol

agent-context returns task-relevant conventions, the selected entity, API cards, diagnostics, and next actions. Summary output is intentionally bounded; request full detail only when a complete graph is necessary.

bashnpx tavo agent-context --json --task modify-route --target /account
npx tavo inspect route /account --json

Start with this complete plan, saved at the project root as change.json. It creates one TypeScript data file and refuses to overwrite an existing file at that path.

json{
  "schemaVersion": 1,
  "operations": [
    {
      "id": "add-project-status",
      "kind": "create-file",
      "file": "src/data/project-status.ts",
      "content": "export const projectStatuses = [\"planned\", \"active\", \"complete\"] as const;
"
    }
  ]
}

• For edits or deletions, inspect the target and capture its current SHA-256 hash.

• Use expectedSha256 for replace-range and delete-file; create-file requires a missing destination. apply-fix accepts a hash or expectedMissing.

• Run change with --dry-run and review every operation.

• Apply the same plan and retain the returned receipt.

• Verify only the changed files and their dependent Tavo.js modules.

bashnpx tavo change --from-json change.json --dry-run
npx tavo change --from-json change.json > change-receipt.json
npx tavo verify --receipt change-receipt.json --smoke --no-project-scripts --json

change prints its receipt as a JSON protocol envelope; it does not create .tavo/change-receipt.json automatically. Save stdout to a project-relative file, check that the change command exited successfully, then pass that exact file to verify.

After applying this example, inspect src/data/project-status.ts and the receipt's data.fileHashes. A second application fails because the destination now exists. If a hash check fails on an edit, read the changed source and prepare a new plan; do not reuse an old range with a newly substituted hash. The installed package includes schemas/change-plan-v1.schema.json for the full operation format.

JSON forms of routes, inventory, doctor, check, and verify are stable inputs for editors and agents. Validate generation specs independently and use doctor fix dry runs when tooling needs suggested repairs without immediate writes.

bashnpx tavo doctor --fix-dry-run --json
npx tavo generate --validate-spec tavo.generated.json
npx tavo verify --spec tavo.generated.json --no-project-scripts --json