update-a2a-proto

name	update-a2a-proto
description	Update the A2A Protobuf file (a2a.proto) when the A2A protocol specification changes. Use when the user mentions updating the spec, syncing with upstream A2A, or when a new version of the A2A protocol is released.
compatibility	Requires curl
allowed-tools	Bash(mvn:*) Bash(curl:*) Read Edit Write Glob Grep

Update a2a.proto

Update the A2A gRPC proto file from the upstream specification repository and regenerate Java sources.

Step 1: Capture the current state

Before updating, record what we have now so we can diff later.

1. Read spec-grpc/src/main/proto/a2a.proto to note the current commit hash (located at the top of the file in a comment)
2. Save a copy of the file for diffing:

Step 2: Download the updated specification

1. Ask the user if they want to update from the main branch or pass a tag or a commit cheksum
2. Download the latest a2a.proto from the upstream A2A repository at https://github.com/a2aproject/A2A/blob/main/specification/a2a.proto and save it to spec-grpc/src/main/proto/a2a.proto.
3. Update the java_package option in the downloaded proto file to:

   option java_package = "org.a2aproject.sdk.grpc";
   

4. Update the comment tracking the upstream commit hash (line starting with // From commit) to the commit hash / tag of the downloaded proto file.

Step 3: Analyze specification changes

Compare the old and new versions of the specification to identify changes:

1. Diff specification/a2a.proto with the backup to find:
   • New or changed message types
   • New or changed RPC methods
   • New or changed fields

Step 4: Regenerate gRPC classes

1. Delete all the generated gRPC Java classes (in case of resources removed from the Protobuf definitions):

   find spec-grpc/src/main/java/org/a2aproject/sdk/grpc -maxdepth 1 -name "*.java" -delete```
   

2. Regenerate gRPC Java classes by running:

   mvn generate-sources -pl spec-grpc -Dskip.protobuf.generate=false
   

Step 5: Update the code

Based on the spec diff, update the relevant files

Summarize the changes for the user before proceeding.

Step 6: Validate

Run the tests on all modules to verify the update

mvn clean install

Fix any issues before proceeding.

Step 7: Audit changes

Before committing, audit all code changes.

Highlight any new, modified, or removed changes in the API in the client, common, server-common, and spec modules

Verify the build succeeds for the full project:

mvn clean install

Step 8: Summarize

Present the user with a summary of:

• The old and new spec commit hashes
• What changed in the specification
• What was updated in the code
• Any areas that need manual review or additional test coverage
• Impact on user API (from the client, common, server-common, and spec modules)
  • Write a "migration summary" for breaking changes in the API