AGENTS.md

1# AGENTS.md
2 
3Instructions for AI coding agents working on the Conductor codebase.
4 
5## Project Overview
6 
7Conductor is an open-source, distributed workflow orchestration engine designed for microservices.
8It uses a pluggable architecture with interface-based abstractions for persistence, queuing, and indexing.
9The project is built with Java 21 and uses Gradle as the build system.
10 
11## Setup Commands
12 
13| Command | Description |
14|---------|-------------|
15| `./gradlew build` | Build the entire project |
16| `./gradlew test` | Run all tests |
17| `./gradlew :module-name:test` | Run tests for a specific module |
18| `./gradlew spotlessApply` | Apply code formatting |
19| `./gradlew clean build` | Clean and rebuild |
20 
21> **Important**: Always run `./gradlew spotlessApply` after making code changes to ensure consistent formatting.
22 
23## Java Version References
24 
25**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.
26 
27## Code Style
28 
29- Use the Spotless plugin for uniform code formatting—always run before committing
30- Conductor is pluggable: when introducing new concepts, always use an **interface-based approach**
31- DAO interfaces **MUST** be defined in the `core` module
32- Implementation classes go in their respective persistence modules (e.g., `postgres-persistence`, `redis-persistence`)
33- Follow existing patterns in the codebase for consistency
34- Do not use emojis such as ✅ in the code, logs, or comments.  Keep comments professionals
35- When adding new logic, comment the algorithm, design etc.   
36 
37## Architecture Guidelines
38 
39### Module Structure
40 
41- **core**: Contains interfaces, domain models, and core business logic
42- **persistence modules**: Implementations of DAO interfaces (postgres, redis, mysql, etc.)
43- **server**: Spring Boot application that brings everything together
44- **client**: SDK for interacting with Conductor
45- **ui**: React-based user interface
46 
47### Key Patterns
48 
49- DAOs are defined as interfaces in `core` and implemented in persistence modules
50- System tasks extend `WorkflowSystemTask` and are registered via Spring
51- Worker tasks use the `@WorkerTask` annotation for automatic discovery
52- Configuration is primarily done through Spring properties
53 
54## Testing
55 
56- **Avoid mocks**: Use real implementations whenever possible
57- **Test actual behavior**: Tests must verify real implementation logic, not duplicate it
58- **Use Testcontainers**: For database, cache, and other external dependencies
59- **Cover concurrency**: Ensure multi-threading scenarios are tested
60- **Run tests before submitting**: `./gradlew test` must pass
61 
62### Test Locations
63 
64- Unit tests: `src/test/java` in each module
65- Integration tests: `test-harness` module and `*-integration-test` modules
66- E2E tests: `e2e` module
67 
68## PR Guidelines
69 
70- Submit PRs against the `main` branch
71- Use clear, descriptive commit messages
72- Run `./gradlew spotlessApply` and `./gradlew test` before pushing
73- Add or update tests for any code changes
74- Keep PRs focused—one logical change per PR
75 
76## Dependency Pinning
77 
78Some dependencies have hard version constraints that **must not be auto-bumped**. These are marked with:
79 
80```groovy
81// PINNED (#964): <reason>
82```
83 
84The issue number links back to https://github.com/conductor-oss/conductor/issues/964, which documents the full audit and upgrade path for each constraint.
85 
86### What PINNED means
87 
88`// PINNED (#964):` means the version is intentionally locked and upgrading it without understanding the constraint will break the build or cause a runtime failure. Do not bump a PINNED dependency as part of routine dependency updates or refactoring.
89 
90### Current hard pins
91 
92| Dependency | Pinned at | Why |
93|---|---|---|
94| `com.google.protobuf:protobuf-java` | `3.x` | 4.x + GraalVM polyglot 25.x causes Gradle to require `polyglot4`, which does not exist on Maven Central |
95| `com.google.protobuf:protoc` | `3.25.5` | Must match `grpc-protobuf:1.73.0`, which depends on protobuf-java 3.x |
96| `org.graalvm.*` (all 5 artifacts) | same version | All must share one version — mixing causes a `"polyglot version X not compatible with Truffle Y"` runtime error |
97| `redis.clients:jedis` in `redis-concurrency-limit` | `3.6.0` | `revJedis` (6.0.0) does not work with Spring Data Redis in that module |
98| `org.codehaus.jettison:jettison` | `strictly 1.5.4` | Gradle `strictly` constraint — no higher version has been validated |
99| `org.conductoross:conductor-client` in `test-harness` | `5.0.1` | Fat JAR classpath conflict with conductor-common; resolved via a stripped JAR task |
100| `org.awaitility:awaitility` in functional tests | `4.x` | e2e tests call `pollInterval(Duration)` added in Awaitility 4.0 |
101 
102### Before bumping a PINNED dependency
103 
1041. Read the comment carefully — it will name the incompatibility and often link to an upstream issue.
1052. Check whether the upstream blocker has been resolved (e.g., new grpc-java release, new GraalVM release).
1063. Test locally: `./gradlew clean build` plus `./gradlew test` in the affected modules.
1074. If bumping GraalVM, bump **all five** `org.graalvm.*` artifacts together using `revGraalVM` in `dependencies.gradle`.
1085. Update or remove the `// PINNED` comment once the constraint is lifted.
109 
110### PINNED vs. version floors
111 
112Hard caps use `// PINNED (#964):`. Version floors — where a minimum is enforced but higher versions are always welcome — use one of two lowercase prefixes instead:
113 
114```groovy
115// Security: CVE-2025-12183 — lz4-java minimum patched version
116// Compat: commons-lang3 3.18.0+ required by Testcontainers/commons-compress
117```
118 
119- `// Security:` — minimum set to address a CVE or known vulnerability
120- `// Compat:` — minimum set for compatibility with another library or framework
121 
122These are grep-able (`grep "// Security:" **/*.gradle`, `grep "// Compat:" **/*.gradle`) but read as normal developer comments. Dependabot may raise these freely; no special review needed beyond the usual.
123 
124## Security Considerations
125 
126- Never commit secrets, API keys, or credentials
127- Be cautious with external dependencies—prefer well-maintained libraries
128- Follow secure coding practices for input validation and error handling
129- Review [SECURITY.md](SECURITY.md) for vulnerability reporting procedures
130 
131## Writing Documentation
132 
133Documentation in this project is **derived from source**, not composed from memory. Open the source first, read what's there, then write the doc from what you find. The source is the spec; the doc is a rendering of it.
134 
135This matters because plausible-looking docs can be silently wrong. Concretely: a curl equivalent for `conductor workflow start --sync` was once written as `POST /api/workflow/{name}/run` — an endpoint that does not exist. Reading the controller first would have given the correct path immediately.
136 
137### Workflow for each content type
138 
139**REST API endpoint or curl example**
1401. Open the relevant controller: `rest/src/main/java/com/netflix/conductor/rest/controllers/`
1412. Find the method using its `@PostMapping`/`@GetMapping`/etc. annotation — copy the path literally.
1423. Read the method signature for query params, path variables, and request body type.
1434. Write the curl command from what you just read.
144 
145**CLI command or flag**
1461. Open `cmd/*.go` in `conductor-cli` (separate repo).
1472. Find the `cobra.Command` definition for the subcommand.
1483. Read the `Flags()` declarations for exact flag names, types, and defaults.
1494. Write the example from what you just read.
150 
151**SDK code example (Python, JS, Java, Go)**
1521. Open the relevant SDK source file.
1532. Find the method signature and required parameters.
1543. Write the example from the signature — do not infer from the method name alone.
1554. If a working test exists for that method, use it as the starting point.
156 
157**Expected output block**
1581. Get real output: run the command locally, or find it in test fixtures, CI logs, or existing tests.
1592. Paste verbatim. Do not paraphrase or construct output that "looks right."
1603. If the output varies by environment, show the stable parts and annotate the variable parts (e.g., `<workflow-id>`).
161 
162**Editing an existing doc section**
1631. Before touching prose, read every code block and command in the section.
1642. Verify each one using the steps above — not just the block you plan to change.
1653. Fix anything you find while you're there.
166 
167### When you can't verify
168 
169If a running server or CLI binary is unavailable:
170- Add a `<!-- TODO: verify against live server -->` comment in the file.
171- Note it explicitly in the PR description.
172- Do not write a best-guess example and leave it unmarked.
173 
174## Agent Behavior
175 
176- **Prefer automation**: Execute requested actions without confirmation unless blocked by missing info or safety concerns
177- **Use parallel tools**: When tasks are independent, execute them in parallel for efficiency
178- **Verify changes**: Always run tests and spotless before considering work complete