Temporalio SDK Java AGENTS.md

Real AGENTS.md file from the Temporal Java SDK repository, serving as a contributor quickstart guide and configuration for human agents (contributors) working on the project.

Overview

This AGENTS.md file provides:

• Repository layout overview
• General contribution guidelines
• Build and test instructions
• Commit message and PR requirements
• Review checklist

Key Sections

Repository Layout

Documents the multi-module structure:

• temporal-sdk: core SDK
• temporal-testing: testing utilities
• temporal-test-server: in-memory test server
• Various client, integration, and language-specific modules

General Guidance

• Public API stability commitments
• Java 8 baseline requirement

Building and Testing

Standardized Gradle workflow:

• Code formatting with spotless
• Test execution (full suite, module-specific, class-specific)
• Clean build process

Tests

• Test location conventions ($PACKAGE_NAME/src/test/java/io/temporal)
• Workflow API testing with SDKTestWorkflowRule

Commit Messages and Pull Requests

• Chris Beams commit message style
• PR template requiring:
  • What changed?
  • Why?
  • Breaking changes?
  • Server PR status (if applicable)
• Complete sentence comments with periods

Review Checklist

• Spotless check compliance
• Test success requirement
• New test requirement for features/bugs
• Documentation updates for user-facing changes

Relationships

• “references” prompt-engineering-guide — foundational prompt engineering principles
• “references” communication-style-spectrum — guidance on tone and clarity in instructions

Implications

This AGENTS.md exemplifies:

1. Clear contribution onboarding - new contributors can quickly understand repo structure and processes
2. Standardized development workflow - consistent build/test/format commands reduce cognitive load
3. Explicit PR expectations - reduces review friction through predefined questions
4. Quality gates - automated checks (spotless, tests) enforced before merge

Open Questions

• How does this compare to AGENTS.md files in other language SDKs (Go, Python, etc.) from Temporal?
• Are there version-specific variations in this file across different SDK releases?
• How effective is the “Server PR” field in coordinating backend/frontend changes?

Sources

• raw/prompts/articles/temporalio-sdk-java-agents-md.md — original source capture