Contribution Guidelines

// Good example
public class ClaudeCodeAgentModel implements AgentModel<AgentRequest, AgentResponse> {

    private final ClaudeCodeClient client;
    private final ClaudeCodeAgentOptions options;

    /**
     * Creates a new Claude Code agent model with the specified client and options.
     *
     * @param client the Claude Code client for CLI communication
     * @param options configuration options for the agent
     * @throws IllegalArgumentException if client or options are null
     */
    public ClaudeCodeAgentModel(ClaudeCodeClient client, ClaudeCodeAgentOptions options) {
        this.client = Objects.requireNonNull(client, "Client cannot be null");
        this.options = Objects.requireNonNull(options, "Options cannot be null");
    }

    // Implementation...
}

// Unit test example
class AgentClientTest {

    @Test
    void shouldCreateClientWithValidModel() {
        // Test implementation
    }
}

// Integration test example
class ClaudeCodeClientIT {

    @Test
    void shouldExecuteSimpleTaskSuccessfully() {
        // Test implementation
    }
}

# Good commit message
Add timeout configuration for Claude Code agent

- Add timeout option to ClaudeCodeAgentOptions
- Implement timeout handling in ClaudeCodeClient
- Add tests for timeout scenarios
- Update documentation with timeout examples

# Poor commit message
Fix bug

@ExtendWith(MockitoExtension.class)
class AgentClientTest {

    @Mock
    private AgentModel<AgentRequest, AgentResponse> mockModel;

    @Test
    void shouldCallModelWithCorrectRequest() {
        // Given
        AgentClient client = AgentClient.create(mockModel);
        when(mockModel.call(any())).thenReturn(createMockResponse());

        // When
        AgentClientResponse response = client.run("test goal");

        // Then
        assertThat(response).isNotNull();
        verify(mockModel).call(any(AgentRequest.class));
    }
}

class ClaudeQuerySmokeTest {

    @Test
    @EnabledIf("org.springaicommunity.agents.claudecode.sdk.integration.ClaudeCliDiscovery#isClaudeCliAvailable")
    void shouldExecuteSimpleQuery() {
        // Test simple agent interaction
        AgentClientResponse response = agentClient.run("Echo hello world");
        assertThat(response.isSuccessful()).isTrue();
    }
}

@Test
void shouldHandleTimeoutGracefully() {
    // Given
    ClaudeCodeAgentOptions options = ClaudeCodeAgentOptions.builder()
        .timeout(Duration.ofMillis(100))  // Very short timeout
        .build();
    AgentClient client = createClientWithOptions(options);

    // When
    Exception exception = assertThrows(AgentTimeoutException.class, () -> {
        client.run("Complex long-running goal");
    });

    // Then
    assertThat(exception.getMessage()).contains("timed out");
    assertThat(exception.getTimeout()).isEqualTo(Duration.ofMillis(100));
}

public class TestDataBuilder {

    public static ClaudeCodeAgentOptions defaultOptions() {
        return ClaudeCodeAgentOptions.builder()
            .model("claude-sonnet-4-0")
            .yolo(false)
            .timeout(Duration.ofMinutes(2))
            .build();
    }

    public static AgentRequest simpleRequest(String goal) {
        return new AgentRequest(goal, Paths.get("."), Collections.emptyMap());
    }
}

provider-sdks/
└── your-agent-sdk/
    ├── pom.xml
    └── src/
        ├── main/java/org/springaicommunity/agents/youragent/
        │   ├── sdk/
        │   │   ├── YourAgentClient.java
        │   │   ├── YourAgentCommand.java
        │   │   └── YourAgentResponse.java
        │   └── exceptions/
        └── test/java/

public class YourAgentClient {

    private final Path workingDirectory;
    private final String commandPath;

    public static YourAgentClient create() {
        return create(Paths.get(System.getProperty("user.dir")));
    }

    public static YourAgentClient create(Path workingDirectory) {
        String commandPath = YourAgentCliDiscovery.discoverYourAgentCommand();
        return new YourAgentClient(workingDirectory, commandPath);
    }

    public YourAgentResponse execute(YourAgentCommand command) {
        // Implementation follows established patterns
    }
}

agent-models/
└── spring-ai-your-agent/
    ├── pom.xml
    └── src/
        └── main/java/org/springaicommunity/agents/youragent/
            ├── YourAgentModel.java
            ├── YourAgentOptions.java
            └── YourAgentProperties.java

public class YourAgentModel implements AgentModel<AgentRequest, AgentResponse> {

    private final YourAgentClient client;
    private final YourAgentOptions options;

    public YourAgentModel(YourAgentClient client, YourAgentOptions options) {
        this.client = client;
        this.options = options;
    }

    @Override
    public AgentResponse call(AgentRequest request) {
        // Convert AgentRequest to YourAgentCommand
        // Execute via client
        // Convert YourAgentResponse to AgentResponse
    }
}