conductor: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working on the Conductor codebase.

Project Overview

Conductor is an open-source, distributed workflow orchestration engine designed for microservices. It uses a pluggable architecture with interface-based abstractions for persistence, queuing, and indexing. The project is built with Java 21 and uses Gradle as the build system.

Setup Commands

Command	Description
./gradlew build	Build the entire project
./gradlew test	Run all tests
./gradlew :module-name:test	Run tests for a specific module
./gradlew spotlessApply	Apply code formatting
./gradlew clean build	Clean and rebuild

Important: Always run ./gradlew spotlessApply after making code changes to ensure consistent formatting.

Java Version References

Never link to a specific Java distribution (e.g., Adoptium, Temurin, OpenJDK.org, Amazon Corretto) in docs, READMEs, or comments. Just say "Java 21+" and let users install it however they prefer.

Code Style

• Use the Spotless plugin for uniform code formatting—always run before committing
• Conductor is pluggable: when introducing new concepts, always use an interface-based approach
• DAO interfaces MUST be defined in the core module
• Implementation classes go in their respective persistence modules (e.g., postgres-persistence, redis-persistence)
• Follow existing patterns in the codebase for consistency
• Do not use emojis such as ✅ in the code, logs, or comments. Keep comments professionals
• When adding new logic, comment the algorithm, design etc.

Architecture Guidelines

Module Structure

• core: Contains interfaces, domain models, and core business logic
• persistence modules: Implementations of DAO interfaces (postgres, redis, mysql, etc.)
• server: Spring Boot application that brings everything together
• client: SDK for interacting with Conductor
• ui: React-based user interface