schema-sync

name	schema-sync
description	Synchronizes Swift types with the ACP protocol schema. Use when updating SDK types to match the latest protocol specification.

Schema Sync Skill

Synchronizes Swift types with the ACP protocol schema.

Trigger

User says: "/schema-sync" or "update schema" or "sync with ACP protocol"

Process

1. Fetch latest schema files from the ACP protocol repository:

   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/schema.json
   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/schema.unstable.json
   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/meta.json

2. Compare with current types in Sources/ACP/:

   • Methods in Client/Methods/
   • Notifications in Client/Methods/Notifications.swift
   • Models in Models/

3. Report changes:

   • New types to add
   • Modified types to update
   • Removed types to deprecate

4. Update Swift files:

   • Add new Method/Notification definitions
   • Update Parameters/Result structs
   • Mark RFD APIs with appropriate deprecation warnings:
     • Draft RFD: @available(*, deprecated, message: "Draft RFD - API may change without notice")
     • Preview RFD: @available(*, deprecated, message: "Preview RFD - API may change")
   • Reference the RFD URL in doc comments

5. Update SCHEMA_VERSION.md with:

   • New commit hash
   • Schema date
   • Protocol version
   • List of changes

6. Run tests to verify changes:

   swift test
   

Schema Mapping

JSON Schema	Swift Type
string	String
integer	Int
number	Double
boolean	Bool
object	struct or Value
array	[T]
null	nil or optional
oneOf	enum

Naming Conventions

• JSON snake_case → Swift camelCase
• JSON sessionId → Swift sessionID (use ID suffix)
• JSON tool_call_id → Swift toolCallID

Example Update

When adding a new method like session/get_config:

/// Gets session configuration.
public enum SessionGetConfig: Method {
    public static let name = "session/get_config"

    public struct Parameters: Codable, Hashable, Sendable {
        public var sessionID: String

        private enum CodingKeys: String, CodingKey {
            case sessionID = "sessionId"
        }

        public init(sessionID: String) {
            self.sessionID = sessionID
        }
    }

    public struct Result: Codable, Hashable, Sendable {
        public var config: Value

        public init(config: Value) {
            self.config = config
        }
    }
}

RFD Status Handling

ACP uses an RFD (Request for Dialog) process for new features:

Stage	Location	SDK Treatment
Draft	docs/rfds/ with "Draft" group	@available(*, deprecated, message: "Draft RFD - API may change without notice")
Preview	docs/rfds/ with "Preview" group	@available(*, deprecated, message: "Preview RFD - API may change")
Completed	docs/protocol/	No deprecation warning (stable)

When syncing schema:

1. Check docs/docs.json for RFD status groupings
2. Apply appropriate deprecation warnings
3. Include RFD URL in doc comments for draft/preview APIs

Notes

• Always maintain backward compatibility when possible
• Use deprecation warnings for removed APIs
• Update golden test files when protocol changes
• Run full test suite after updates