a2a 0.1.0.pre → 0.2.0

data/.agent-docs/types_mapping.md

@@ -0,0 +1,196 @@
+# TypeScript to Ruby A2A Type Mapping
+
+## Design Philosophy
+
+The Ruby implementation follows a **consolidated approach** rather than direct TypeScript translation, favoring:
+- **Inheritance and polymorphism** over separate interfaces for success/error cases
+- **Fewer, more flexible classes** over granular type separation
+- **Ruby idioms** like `success?`/`error?` methods over type-based discrimination
+
+## Legend
+- ✅ **Direct mapping** - 1:1 TypeScript interface to Ruby class
+- 🔄 **Consolidated mapping** - Multiple TypeScript types handled by one Ruby class
+- 📝 **Design choice** - Intentional architectural difference
+
+## Core JSON-RPC Types
+
+| TypeScript Type | Ruby Equivalent | Status | Notes |
+|-----------------|-----------------|--------|-------|
+| `JSONRPCError` | `JSONRPC::Error` | ✅ Direct mapping | |
+| `JSONRPCMessage` | `JSONRPC::Request` + `JSONRPC::Response` | 🔄 **Consolidated** | Ruby uses separate Request/Response base classes |
+| `JSONRPCRequest` | `JSONRPC::Request` | ✅ Direct mapping | |
+| `JSONRPCSuccessResponse` | `JSONRPC::Response` (when `result` present) | 🔄 **Polymorphic** | Use `response.success?` method |
+| `JSONRPCErrorResponse` | `JSONRPC::Response` (when `error` present) | 🔄 **Polymorphic** | Use `response.error?` method |
+
+## Standard JSON-RPC Errors
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `JSONParseError` | `JSONRPC::ParseError` | ✅ Direct mapping |
+| `InvalidRequestError` | `JSONRPC::InvalidRequestError` | ✅ Direct mapping |
+| `MethodNotFoundError` | `JSONRPC::MethodNotFoundError` | ✅ Direct mapping |
+| `InvalidParamsError` | `JSONRPC::InvalidParamsError` | ✅ Direct mapping |
+| `InternalError` | `JSONRPC::InternalError` | ✅ Direct mapping |
+
+## A2A-Specific Errors
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `TaskNotFoundError` | `A2A::TaskNotFoundError` | ✅ Direct mapping |
+| `TaskNotCancelableError` | `A2A::TaskNotCancelableError` | ✅ Direct mapping |
+| `PushNotificationNotSupportedError` | `A2A::PushNotificationNotSupportedError` | ✅ Direct mapping |
+| `UnsupportedOperationError` | `A2A::UnsupportedOperationError` | ✅ Direct mapping |
+| `ContentTypeNotSupportedError` | `A2A::ContentTypeNotSupportedError` | ✅ Direct mapping |
+| `InvalidAgentResponseError` | `A2A::InvalidAgentResponseError` | ✅ Direct mapping |
+| `AuthenticatedExtendedCardNotConfiguredError` | `A2A::AuthenticatedExtendedCardNotConfiguredError` | ✅ Direct mapping |
+| `A2AError` | `A2A::Error` | ✅ Direct mapping |
+
+## A2A Request Types
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `SendMessageRequest` | `A2A::SendMessageRequest` | ✅ Direct mapping |
+| `SendStreamingMessageRequest` | `A2A::SendStreamingMessageRequest` | ✅ Direct mapping |
+| `GetTaskRequest` | `A2A::GetTaskRequest` | ✅ Direct mapping |
+| `CancelTaskRequest` | `A2A::CancelTaskRequest` | ✅ Direct mapping |
+| `SetTaskPushNotificationConfigRequest` | `A2A::SetTaskPushNotificationConfigRequest` | ✅ Direct mapping |
+| `GetTaskPushNotificationConfigRequest` | `A2A::GetTaskPushNotificationConfigRequest` | ✅ Direct mapping |
+| `TaskResubscriptionRequest` | `A2A::TaskResubscriptionRequest` | ✅ Direct mapping |
+| `ListTaskPushNotificationConfigRequest` | `A2A::ListTaskPushNotificationConfigRequest` | ✅ Direct mapping |
+| `DeleteTaskPushNotificationConfigRequest` | `A2A::DeleteTaskPushNotificationConfigRequest` | ✅ Direct mapping |
+| `GetAuthenticatedExtendedCardRequest` | `A2A::GetAuthenticatedExtendedCardRequest` | ✅ Direct mapping |
+| `A2ARequest` | `A2A::Request` | ✅ Direct mapping |
+
+## A2A Response Types - Consolidated Approach
+
+### TypeScript Pattern: Separate Success/Error Types
+```typescript
+// TypeScript defines separate interfaces
+interface SendMessageSuccessResponse extends JSONRPCSuccessResponse {
+  result: Message | Task;
+}
+type SendMessageResponse = SendMessageSuccessResponse | JSONRPCErrorResponse;
+```
+
+### Ruby Pattern: Unified Response Classes
+```ruby
+# Ruby uses single class with polymorphic behavior
+class SendMessageResponse < JSONRPC::Response
+  # Handles both success and error cases
+  # Use response.success? or response.error? to discriminate
+end
+```
+
+| TypeScript Success Type | TypeScript Union Type | Ruby Equivalent | Status |
+|------------------------|----------------------|-----------------|--------|
+| `SendMessageSuccessResponse` | `SendMessageResponse` | `A2A::SendMessageResponse` | 🔄 **Consolidated** |
+| `SendStreamingMessageSuccessResponse` | `SendStreamingMessageResponse` | `A2A::SendStreamingMessageResponse` | 🔄 **Consolidated** |
+| `GetTaskSuccessResponse` | `GetTaskResponse` | `A2A::GetTaskResponse` | 🔄 **Consolidated** |
+| `CancelTaskSuccessResponse` | `CancelTaskResponse` | `A2A::CancelTaskResponse` | 🔄 **Consolidated** |
+| `SetTaskPushNotificationConfigSuccessResponse` | `SetTaskPushNotificationConfigResponse` | `A2A::SetTaskPushNotificationConfigResponse` | 🔄 **Consolidated** |
+| `GetTaskPushNotificationConfigSuccessResponse` | `GetTaskPushNotificationConfigResponse` | `A2A::GetTaskPushNotificationConfigResponse` | 🔄 **Consolidated** |
+| `ListTaskPushNotificationConfigSuccessResponse` | `ListTaskPushNotificationConfigResponse` | `A2A::ListTaskPushNotificationConfigResponse` | 🔄 **Consolidated** |
+| `DeleteTaskPushNotificationConfigSuccessResponse` | `DeleteTaskPushNotificationConfigResponse` | `A2A::DeleteTaskPushNotificationConfigResponse` | 🔄 **Consolidated** |
+| `GetAuthenticatedExtendedCardSuccessResponse` | `GetAuthenticatedExtendedCardResponse` | `A2A::GetAuthenticatedExtendedCardResponse` | 🔄 **Consolidated** |
+
+## Core Protocol Types
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `AgentCard` | `A2A::AgentCard` | ✅ Direct mapping |
+| `AgentProvider` | `A2A::AgentProvider` | ✅ Direct mapping |
+| `AgentCapabilities` | `A2A::AgentCapabilities` | ✅ Direct mapping |
+| `AgentExtension` | `A2A::AgentExtension` | ✅ Direct mapping |
+| `AgentSkill` | `A2A::AgentSkill` | ✅ Direct mapping |
+| `AgentInterface` | `A2A::AgentInterface` | ✅ Direct mapping |
+| `AgentCardSignature` | `A2A::AgentCardSignature` | ✅ Direct mapping |
+| `TransportProtocol` | `A2A::TransportProtocol` | ✅ Direct mapping |
+| `Task` | `A2A::Task` | ✅ Direct mapping |
+| `TaskStatus` | `A2A::TaskStatus` | ✅ Direct mapping |
+| `TaskState` | `A2A::TaskState` | ✅ Direct mapping |
+| `TaskStatusUpdateEvent` | `A2A::TaskStatusUpdateEvent` | ✅ Direct mapping |
+| `TaskArtifactUpdateEvent` | `A2A::TaskArtifactUpdateEvent` | ✅ Direct mapping |
+| `Message` | `A2A::Message` | ✅ Direct mapping |
+| `Artifact` | `A2A::Artifact` | ✅ Direct mapping |
+| `Part` | `A2A::Part` (union type) | ✅ Direct mapping |
+| `TextPart` | `A2A::TextPart` | ✅ Direct mapping |
+| `FilePart` | `A2A::FilePart` | ✅ Direct mapping |
+| `DataPart` | `A2A::DataPart` | ✅ Direct mapping |
+| `PartBase` | `A2A::PartBase` | ✅ Direct mapping |
+| `FileBase` | `A2A::FileBase` | ✅ Direct mapping |
+| `FileWithBytes` | `A2A::FileWithBytes` | ✅ Direct mapping |
+| `FileWithUri` | `A2A::FileWithUri` | ✅ Direct mapping |
+
+## Security Types
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `SecurityScheme` | `A2A::SecurityScheme` (union type) | ✅ Direct mapping |
+| `SecuritySchemeBase` | `A2A::SecuritySchemeBase` | ✅ Direct mapping |
+| `APIKeySecurityScheme` | `A2A::APIKeySecurityScheme` | ✅ Direct mapping |
+| `HTTPAuthSecurityScheme` | `A2A::HTTPAuthSecurityScheme` | ✅ Direct mapping |
+| `MutualTLSSecurityScheme` | `A2A::MutualTLSSecurityScheme` | ✅ Direct mapping |
+| `OAuth2SecurityScheme` | `A2A::OAuth2SecurityScheme` | ✅ Direct mapping |
+| `OpenIdConnectSecurityScheme` | `A2A::OpenIdConnectSecurityScheme` | ✅ Direct mapping |
+| `OAuthFlows` | `A2A::OAuthFlows` | ✅ Direct mapping |
+| `AuthorizationCodeOAuthFlow` | `A2A::AuthorizationCodeOAuthFlow` | ✅ Direct mapping |
+| `ClientCredentialsOAuthFlow` | `A2A::ClientCredentialsOAuthFlow` | ✅ Direct mapping |
+| `ImplicitOAuthFlow` | `A2A::ImplicitOAuthFlow` | ✅ Direct mapping |
+| `PasswordOAuthFlow` | `A2A::PasswordOAuthFlow` | ✅ Direct mapping |
+
+## Parameter Types
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `TaskIdParams` | `A2A::TaskIdParams` | ✅ Direct mapping |
+| `TaskQueryParams` | `A2A::TaskQueryParams` | ✅ Direct mapping |
+| `MessageSendParams` | `A2A::MessageSendParams` | ✅ Direct mapping |
+| `MessageSendConfiguration` | `A2A::MessageSendConfiguration` | ✅ Direct mapping |
+| `GetTaskPushNotificationConfigParams` | `A2A::GetTaskPushNotificationConfigParams` | ✅ Direct mapping |
+| `ListTaskPushNotificationConfigParams` | `A2A::ListTaskPushNotificationConfigParams` | ✅ Direct mapping |
+| `DeleteTaskPushNotificationConfigParams` | `A2A::DeleteTaskPushNotificationConfigParams` | ✅ Direct mapping |
+
+## Push Notification Types
+
+| TypeScript Type | Ruby Equivalent | Status |
+|-----------------|-----------------|--------|
+| `PushNotificationConfig` | `A2A::PushNotificationConfig` | ✅ Direct mapping |
+| `PushNotificationAuthenticationInfo` | `A2A::PushNotificationAuthenticationInfo` | ✅ Direct mapping |
+| `TaskPushNotificationConfig` | `A2A::TaskPushNotificationConfig` | ✅ Direct mapping |
+
+## Usage Examples
+
+### TypeScript Approach
+```typescript
+// Separate types for success/error
+if (response instanceof SendMessageSuccessResponse) {
+  // Handle success
+  console.log(response.result);
+} else if (response instanceof JSONRPCErrorResponse) {
+  // Handle error
+  console.log(response.error);
+}
+```
+
+### Ruby Approach
+```ruby
+# Polymorphic behavior with single class
+response = A2A::SendMessageResponse.new(...)
+
+if response.success?
+  # Handle success
+  puts response.result
+else
+  # Handle error
+  puts response.error
+end
+```
+
+## Benefits of Ruby Consolidated Approach
+
+1. **🔧 Less Code Duplication**: One response class per method vs. two in TypeScript
+2. **📦 Fewer Files**: Easier codebase navigation and maintenance
+3. **🏗️ Inheritance Benefits**: Shared functionality via `JSONRPC::Response` base class
+4. **🎯 Ruby Idioms**: `success?`/`error?` methods are more idiomatic than type checking
+5. **⚡ Same Functionality**: All TypeScript capabilities preserved
+6. **🔍 Type Safety**: Maintained via dry-types and optional RBS signatures

data/.claude/commands/gemfile/update.md

@@ -0,0 +1,52 @@
+---
+allowed-tools: Bash(bundle :*), Bash(git :*), Read, Edit, MultiEdit, Glob
+description: Update Gemfile dependencies to latest minor versions
+argument-hint: [gemfile] [commit]
+---
+
+Update the dependencies in the specified Gemfile (or ./Gemfile if no path provided) to their latest minor versions while
+preserving major version constraints. Only update MAJOR.MINOR versions, never PATCH versions unless explicitly needed.
+
+Steps:
+1. Read the Gemfile at the specified path (or ./Gemfile if $ARGUMENTS is empty)
+2. Read the corresponding Gemfile.lock to get current resolved versions
+3. Run `bundle outdated --only-explicit` to check for available minor updates of explicitly declared gems
+4. For each gem in Gemfile, check if Gemfile.lock has a newer minor version than the current Gemfile constraint allows
+5. Update gem version constraints to match the minor version from Gemfile.lock or latest available, whichever is newer (MAJOR.MINOR format)
+6. Use pessimistic version constraints (~> MAJOR.MINOR) to prevent automatic patch updates
+7. Preserve any existing version operators but ensure they follow minor-only update strategy
+8. Run `bundle update` to apply the changes
+7. Skip step 8, 9 and 10 if --commit flag is not provided
+8. Stage Gemfile (only if not gitignored)
+9. Verify if Gemfile.lock is tracked and not gitignored. If both conditions are met, stage it for commit.
+10. Create a git commit with message 'Update development dependencies' and a description listing all updated gems with their old and new versions like:
+
+<commit-message>
+  Updated gems:
+- rubocop: 1.75.2 → 1.78.0
+- rubocop-yard: 0.10.0 → 1.0.0
+</commit-message>
+
+11. If any dependencies were updated, respond only with the update message. And if the user has chose to commit,
+include the update commit message. Otherwise, respond only with the no op message.
+
+<update-message>
+Updated gems:
+- rbs: 3.8 → 3.9
+- rubocop: 1.78 → 1.80
+- rubocop-rspec: 3.6 → 3.7
+
+<update-commit-message>The changes have been committed with the message "Update development dependencies".</update-commit-message>
+</update-message>
+
+<no-op-message>All dependencies are up to date.</no-op-message>
+
+Key bundle outdated flags used:
+- `--only-explicit`: Only show gems explicitly listed in Gemfile (not dependencies)
+- No `--local` flag to ensure remote gem sources are checked for latest versions
+
+Arguments:
+- `gemfile`: Gemfile path (defaults to ./Gemfile if not provided)
+- `--commit`: Create a git commit after updating dependencies with message 'Update development dependencies' and a description listing all updated gems with their old and new versions
+
+Gemfile path: ${ARGUMENTS:-./Gemfile}

data/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./bin/console)",
+      "Bash(mkdir:*)",
+      "Bash(mv:*)",
+      "WebFetchTool(domain:raw.githubusercontent.com)",
+      "Bash(cat:*)",
+      "Bash(find:*)",
+      "WebFetch(domain:dry-rb.org)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "Bash(ruby:*)",
+      "Read(//Users/wilson/projects/rb/jsonrpc-middleware/lib/jsonrpc/**)",
+      "Read(//Users/wilson/projects/rb/jsonrpc-middleware/**)",
+      "Bash(xargs:*)",
+      "Bash(bundle exec rspec:*)",
+      "Bash(bundle exec:*)",
+      "Bash(bundle:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": false
+}

data/.rubocop.yml

@@ -1,4 +1,5 @@
 plugins:
+  - rubocop-factory_bot
   - rubocop-performance
   - rubocop-rake
   - rubocop-rspec
@@ -15,6 +16,10 @@ Gemspec/DevelopmentDependencies:
 
 # ----------------------- Style -----------------------
 
+Style/MixinUsage:
+  Exclude:
+    - bin/console
+
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: single_quotes
@@ -28,23 +33,39 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
   Exclude:
-    - hsr.gemspec
+    - a2a.gemspec
 
 # ---------------------- Metrics ----------------------
 
+Metrics/AbcSize:
+  Enabled: false
+
 Metrics/BlockLength:
-  Exclude:
-    - '**/*_spec.rb'
-    - hsr.gemspec
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
 
 Metrics/ParameterLists:
   CountKeywordArgs: false
 
+Metrics/PerceivedComplexity:
+  Enabled: false
+
 # ----------------------- RSpec -----------------------
 
 RSpec/ExampleLength:
   Enabled: false
 
+RSpec/MultipleExpectations:
+  Enabled: false
+
 # RuboCop does not like the gem's name.
 RSpec/SpecFilePathFormat:
   Enabled: false

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.2
+ruby 3.4.5

data/CHANGELOG.md

@@ -1,5 +1,89 @@
-## [Unreleased]
+# Changelog
+All notable changes to this project will be documented in this file.
 
-## [0.1.0.pre] - 2025-03-08
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.1.1/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-10-05
+
+### Added
+
+- Type compatibility with version 0.3.0 of the Agent2Agent specification
+- Security scheme types:
+  - `ApiKeySecurityScheme`
+  - `HttpAuthSecurityScheme`
+  - `OAuth2SecurityScheme` with OAuth flow types (authorization code, client credentials, implicit, password)
+  - `MutualTlsSecurityScheme`
+  - `OpenIdConnectSecurityScheme`
+- Agent discovery types:
+  - `AgentCardSignature` for signed agent cards
+  - `AgentExtension` for protocol extensions
+  - `AgentInterface` for defining agent interfaces
+  - `TransportProtocol` enumeration
+- File types:
+  - `FileBase` base class
+  - `FileWithBytes` for inline file content
+  - `FileWithURI` for file references
+- Message and task types:
+  - `MessageSendConfiguration` and `MessageSendParams`
+  - `SendMessageRequest` and `SendMessageResponse`
+  - `SendStreamingMessageRequest` and `SendStreamingMessageResponse`
+- Push notification configuration endpoints:
+  - `GetTaskPushNotificationConfigRequest` and `GetTaskPushNotificationConfigResponse`
+  - `SetTaskPushNotificationConfigRequest`
+  - `DeleteTaskPushNotificationConfigRequest` and `DeleteTaskPushNotificationConfigResponse`
+  - `ListTaskPushNotificationConfigRequest` and `ListTaskPushNotificationConfigResponse`
+  - `PushNotificationAuthenticationInfo`
+- Error types:
+  - `ContentTypeNotSupportedError`
+  - `InvalidAgentResponseError`
+  - `AuthenticatedExtendedCardNotConfiguredError`
+- Claude Code development command for Gemfile updates (`.claude/commands/gemfile/update.md`)
+
+### Changed
+
+- Refactored URL attributes to use `Types::URI` for type safety
+- Switched to `MultiJson` for JSON deserialization
+- Migrated to `jsonrpc-middleware` gem for JSON-RPC protocol implementation
+- Updated `AgentCard` structure with new authentication and extension fields
+- Updated `Message` type with new structure and support for artifacts
+- Updated `Task` type with new structure
+- Refactored `Artifact`, `TaskArtifactUpdateEvent`, and `TaskStatusUpdateEvent` types
+- Refactored agent and message types for specification compliance
+- Updated error types to use structured error responses
+
+### Removed
+
+- `TaskSendParams` (replaced by `MessageSendParams`)
+- `SendTaskRequest` and `SendTaskResponse` (replaced by message send endpoints)
+- `SendTaskStreamingRequest` and `SendTaskStreamingResponse` (replaced by streaming message endpoints)
+- Legacy JSON-RPC types (now provided by `jsonrpc-middleware`):
+  - `JsonrpcMessage`
+  - `JsonrpcRequest`
+  - `JsonrpcResponse`
+  - `JsonrpcError`
+  - `InternalError`
+  - `InvalidParamsError`
+  - `InvalidRequestError`
+  - `JsonParseError`
+  - `MethodNotFoundError`
+- `AgentAuthentication` and `AuthenticationInfo` (replaced by security schemes)
+- `FileContent` (replaced by file type hierarchy)
+
+## [0.1.0] - 2025-05-03
+
+### Added
+
+- Protocol data structures defined according to the Agent2Agent specification
+- Serialization and deserialization of protocol messages
+- Typed data structures with validation
+- Case transformation support (snake_case ↔ camelCase) during instantiation and serialization
+- Flexible schema with support for additional properties beyond defined attributes
+
+## [0.1.0.pre] - 2025-04-08
 
 - Pre-release
+
+[0.2.0]: https://github.com/wilsonsilva/a2a/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/wilsonsilva/a2a/compare/v0.1.0.pre...v0.1.0
+[0.1.0.pre]: https://github.com/wilsonsilva/a2a/compare/a20b9b6...v0.1.0.pre

data/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About This Project
+
+This is the A2A (Agent2Agent) Ruby gem - an implementation of the Agent2Agent protocol enabling communication and
+interoperability between opaque agentic applications. The gem provides typed data structures,
+serialization/deserialization, and validation according to the A2A specification.
+
+## Development Commands
+
+### Testing and Quality Assurance
+- `bundle exec rake spec` - Run RSpec tests
+- `bundle exec rake coverage` - Run tests with coverage report (opens browser)
+- `bundle exec rake qa` - Run full quality assurance suite (tests, linting, docs, security audit)
+- `bundle exec rspec spec/path/to/specific_spec.rb` - Run a single test file
+- `bundle exec rspec spec/path/to/specific_spec.rb:42` - Run specific test by line number
+
+### Code Quality
+- `bundle exec rake rubocop` - Run RuboCop linting
+- `bundle exec rake rubocop:autocorrect` - Auto-fix safe RuboCop offenses
+- `bundle exec rake rubocop:autocorrect_all` - Auto-fix all RuboCop offenses (including unsafe)
+
+### Documentation
+- `bundle exec rake yard` - Generate YARD documentation
+- `bundle exec rake yard:junk` - Check for documentation issues
+- `bundle exec rake verify_measurements` - Ensure 100% documentation coverage (yardstick)
+
+### Type Checking (Optional but Available)
+- `bundle exec typeprof lib/a2a.rb` - Generate RBS type signatures
+- `bundle exec steep check` - Run Steep type checking
+
+### Security
+- `bundle exec rake bundle:audit:check` - Check for security vulnerabilities
+- `bundle exec rake bundle:audit:update` - Update security vulnerability database
+
+### Build and Release
+- `bundle exec rake build` - Build gem
+- `bundle exec rake install` - Install gem locally
+- `bin/console` - Open interactive console with gem loaded
+
+## Architecture Overview
+
+### Core Structure
+The gem is organized around the A2A protocol specification with the following key components:
+
+1. **Type System (`lib/a2a/types/`)**: Complete typed implementation of A2A protocol data structures
+   - Agent discovery objects (AgentCard, AgentSkill, AgentCapabilities)
+   - Message and task objects (Message, Task, TaskStatus, Artifact)
+   - Security schemes and authentication structures
+   - JSON-RPC request/response objects
+   - Implements the type system defined in `.agent-docs/types.ts` (TypeScript reference definitions)
+   - Type mapping between TypeScript types/interfaces and Ruby classes documented in `.agent-docs/types_mapping.md`
+
+2. **Extensions System (`lib/a2a/extensions/`)**:
+   - `AdditionalProperties`: Allows flexible schema with additional properties beyond defined attributes
+   - `JSONDeserialization`: Handles case transformation (snake_case ↔ camelCase) during instantiation
+
+### Key Design Patterns
+
+1. **Case Transformation**: The gem handles automatic conversion between Ruby's snake_case conventions and the protocol's camelCase requirements during serialization/deserialization.
+2. **Typed Data Structures**: All protocol objects are implemented as Ruby classes with proper validation and type checking support via RBS signatures.
+3. **JSON-RPC Integration**: Built on the `jsonrpc-middleware` gem for proper JSON-RPC 2.0 protocol compliance.
+4. **Factory Pattern**: Test factories are provided for all major objects to support testing.
+
+### File Organization
+- `lib/a2a.rb` - Main entry point with Zeitwerk loader configuration
+- `lib/a2a/types/` - All protocol data structure implementations (collapsed namespace)
+- `lib/a2a/extensions/` - Mixin modules for additional functionality
+- `spec/` - RSpec test suite with comprehensive coverage
+- `sig/a2a.rbs` - RBS type signatures for type checking
+
+## Development Guidelines
+
+### Code Style
+- Follow RuboCop configuration in `.rubocop.yml`
+- Target Ruby 3.4 compatibility
+- Use single quotes for strings, double quotes in interpolation
+- Max line length: 120 characters
+- Frozen string literals required
+
+### Testing
+- Use RSpec for all tests
+- FactoryBot factories for test data
+- Match JSON matchers for JSON comparison
+- Aim for comprehensive test coverage
+- Tests are organized to mirror the lib structure
+
+### Quality Thresholds
+- 100% documentation coverage enforced by yardstick
+- RuboCop compliance required
+- Security audit checks via bundler-audit
+- Type checking available via Steep
+
+### Git Workflow
+- Overcommit hooks enforce RuboCop and trailing whitespace checks on pre-commit
+- Follow conventional commit message format based on existing history

data/Guardfile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 guard 'bundler' do
-  watch('hsr.gemspec')
+  watch('a2a.gemspec')
 end
 
 guard 'bundler_audit', run_on_start: true do

data/README.md

@@ -2,8 +2,8 @@
 
 [![Gem Version](https://badge.fury.io/rb/a2a.svg)](https://badge.fury.io/rb/a2a)
 ![Build](https://github.com/wilsonsilva/a2a/actions/workflows/main.yml/badge.svg)
-[![Maintainability](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/maintainability)](https://codeclimate.com/github/wilsonsilva/a2a/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/c7633eb2c89eb95ee7f2/test_coverage)](https://codeclimate.com/github/wilsonsilva/a2a/test_coverage)
+[![Maintainability](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/maintainability.svg)](https://qlty.sh/gh/wilsonsilva/projects/a2a)
+[![Code Coverage](https://qlty.sh/badges/73ebc4bb-d1db-4b5b-9a7c-a4acd59dfe69/test_coverage.svg)](https://qlty.sh/gh/wilsonsilva/projects/a2a)
 
 An open protocol enabling communication and interoperability between opaque agentic applications.
 
@@ -21,7 +21,11 @@ An open protocol enabling communication and interoperability between opaque agen
 
 ## 🔑 Key features
 
-TODO
+- Protocol data structures defined according to the Agent2Agent specification
+- Serialization and deserialization of protocol messages
+- Typed data structures with validation
+- Case transformation support (snake_case ↔ camelCase) during instantiation and serialization
+- Flexible schema with support for additional properties beyond defined attributes
 
 ## 📦 Installation
 
@@ -31,7 +35,54 @@ Install the gem by executing:
 
 ## ⚡️ Quickstart
 
-TODO
+```ruby
+require 'a2a'
+
+# Create message parts
+text_part = A2A::TextPart.new(text: 'Plan a trip to Paris')
+
+# Create a message
+message = A2A::Message.new(
+  role: 'user',
+  parts: [text_part],
+  message_id: 'msg-123',
+  kind: 'message'
+)
+
+# Create message send parameters object
+message_params = A2A::MessageSendParams.new(
+  message: message
+)
+
+# Build a JSON-RPC request object (no actual network request is made)
+request = A2A::SendMessageRequest.new(
+  id: 1,
+  params: message_params
+)
+
+# Convert to JSON with camelCase formatting (as per protocol spec)
+json_request = request.to_json
+puts json_request
+# => {"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":"Plan a trip to Paris"}],"messageId":"msg-123","kind":"message"}}}
+
+# Parse a JSON response string
+agent_response = '{"jsonrpc":"2.0","id":1,"result":{"id":"task-123","contextId":"ctx-456","status":{"state":"completed"},"kind":"task"}}'
+
+# Method 1: Parse the JSON first, then create the object
+response_data = JSON.parse(agent_response)
+response = A2A::SendMessageResponse.new(response_data)
+
+# Method 2: Directly create the object from JSON (using the new from_json method)
+response = A2A::SendMessageResponse.from_json(agent_response)
+
+# Access the task information
+if response.result
+  puts "Task status: #{response.result.status}"
+  puts "Messages: #{response.result.history&.length || 0}"
+else
+  puts "Error: #{response.error&.message}"
+end
+```
 
 ## 📚 Documentation
 

data/Rakefile

@@ -14,9 +14,7 @@ yardstick_options = YAML.load_file('.yardstick.yml')
 
 Bundler::Audit::Task.new
 RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new do |task|
-  task.requires << 'rubocop-yard'
-end
+RuboCop::RakeTask.new
 YARD::Rake::YardocTask.new
 YardJunk::Rake.define_task
 Yardstick::Rake::Measurement.new(:yardstick_measure, yardstick_options)