| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 19 | 4 | 8% |
| Commands | 0 | 5 | 0 | 0% |
| Section tags | 3 | 8 | 0 | 27% |
What each file covers
Sections
2 shared · 19 only in A · 4 only in B- − AGENTS.md
- − Project Overview
- − Setup Commands
- − Java Version References
- − Code Style
- − Architecture Guidelines
- − Module Structure
- − Key Patterns
- − Testing
- − Test Locations
- − PR Guidelines
- − Dependency Pinning
- − What PINNED means
- − Current hard pins
- − Before bumping a PINNED dependency
- − PINNED vs. version floors
- − Security Considerations
- − Workflow for each content type
- − Agent Behavior
- + CLAUDE.md — conductor (server repo)
- + For each content type, start here
- + Key source locations
- + Other Guidelines
- Writing Documentation
- When you can't verify
Commands
0 shared · 5 only in A · 0 only in B- − ./gradlew build
- − ./gradlew test
- − ./gradlew :module-name:test
- − ./gradlew spotlessApply
- − ./gradlew clean build
Section tags
3 shared · 8 only in A · 0 only in B- − setup
- − test
- − code-style
- − architecture
- − git-pr
- − security
- − deployment
- − do-not
- types
- agent-behaviour
- docs
Line diff
conductor-oss/conductor · AGENTS.md
@@ −1 @@
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
conductor-oss/conductor · CLAUDE.md
@@ +1 @@
1# CLAUDE.md — conductor (server repo)
2
3Instructions for Claude Code working in this repository.
4
5## Writing Documentation
6
7Documentation in this project is **derived from source**, not composed from memory or intuition. The workflow is: open the source → read what's there → write the doc from what you find. The source is the spec; the doc is a rendering of it.
8
9Concrete reason this matters: a curl equivalent for `conductor workflow start --sync` was once written as `POST /api/workflow/{name}/run` — an endpoint that does not exist. Opening `WorkflowResource.java` first would have given the correct path (`POST /api/workflow/execute/{name}/{version}`) immediately.
10
11### For each content type, start here
12
13**REST endpoint or curl example**
141. Open the controller: `rest/src/main/java/com/netflix/conductor/rest/controllers/`
152. Find the method by its `@PostMapping`/`@GetMapping` annotation — copy the path literally.
163. Read the method signature for query params, path variables, and request body.
174. Write the curl from what you just read.
18
19**CLI command or flag**
201. Open `conductor-cli/cmd/*.go` (separate repo under this workspace).
212. Find the `cobra.Command` for the subcommand and read its `Flags()` declarations.
223. Write the example from what you just read — flag names, types, and defaults.
23
24**SDK code example (Python, JS, Java, Go)**
251. Open the SDK source file for the method you're documenting.
262. Read the method signature and required parameters.
273. If a working test exists for that method, use it as the starting point.
284. Write from the signature — do not infer from the method name alone.
29
30**Expected output block**
311. Get real output: run the command, or find it in test fixtures or CI logs.
322. Paste verbatim. Do not construct output that "looks right."
333. For variable fields (IDs, timestamps), use annotated placeholders like `<workflow-id>`.
34
35**Editing an existing section**
36- Before changing anything, read every code block and command in the section.
37- Verify each one using the steps above, not just the block you plan to change.
38- Fix anything you find while you're there.
39
40### When you can't verify
41
42If a running server or CLI is unavailable:
43- Add `<!-- TODO: verify against live server -->` in the file.
44- Note it explicitly in the PR description.
45- Do not write an unverified example and leave it unmarked.
46
47### Key source locations
48
49| Content | Where to look |
50|---|---|
51| REST API routes | `rest/src/main/java/com/netflix/conductor/rest/controllers/` |
52| Workflow sync execution | `WorkflowResource.java` → `executeWorkflow()` at `@PostMapping("execute/{name}/{version}")` |
53| Task routes | `TaskResource.java` |
54| CLI subcommands and flags | `conductor-cli/cmd/workflow.go`, `cmd/task.go`, etc. |
55
56## Other Guidelines
57
58See [AGENTS.md](AGENTS.md) for full project conventions: code style, testing, dependency pinning, PR guidelines.
59
@@ −1 +1 @@
1−# AGENTS.md
1+# CLAUDE.md — conductor (server repo)
22
3−Instructions for AI coding agents working on the Conductor codebase.
3+Instructions for Claude Code working in this repository.
44
5−## Project Overview
6−
7−Conductor is an open-source, distributed workflow orchestration engine designed for microservices.
8−It uses a pluggable architecture with interface-based abstractions for persistence, queuing, and indexing.
9−The 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−
78−Some dependencies have hard version constraints that **must not be auto-bumped**. These are marked with:
79−
80−```groovy
81−// PINNED (#964): <reason>
82−```
83−
84−The 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−
104−1. Read the comment carefully — it will name the incompatibility and often link to an upstream issue.
105−2. Check whether the upstream blocker has been resolved (e.g., new grpc-java release, new GraalVM release).
106−3. Test locally: `./gradlew clean build` plus `./gradlew test` in the affected modules.
107−4. If bumping GraalVM, bump **all five** `org.graalvm.*` artifacts together using `revGraalVM` in `dependencies.gradle`.
108−5. Update or remove the `// PINNED` comment once the constraint is lifted.
109−
110−### PINNED vs. version floors
111−
112−Hard 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−
122−These 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−
1315 ## Writing Documentation
1326
133−Documentation 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.
7+Documentation in this project is **derived from source**, not composed from memory or intuition. The workflow is: open the source → read what's there → write the doc from what you find. The source is the spec; the doc is a rendering of it.
1348
135−This 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.
9+Concrete reason this matters: a curl equivalent for `conductor workflow start --sync` was once written as `POST /api/workflow/{name}/run` — an endpoint that does not exist. Opening `WorkflowResource.java` first would have given the correct path (`POST /api/workflow/execute/{name}/{version}`) immediately.
13610
137−### Workflow for each content type
11+### For each content type, start here
13812
139−**REST API endpoint or curl example**
140−1. Open the relevant controller: `rest/src/main/java/com/netflix/conductor/rest/controllers/`
141−2. Find the method using its `@PostMapping`/`@GetMapping`/etc. annotation — copy the path literally.
142−3. Read the method signature for query params, path variables, and request body type.
143−4. Write the curl command from what you just read.
13+**REST endpoint or curl example**
14+1. Open the controller: `rest/src/main/java/com/netflix/conductor/rest/controllers/`
15+2. Find the method by its `@PostMapping`/`@GetMapping` annotation — copy the path literally.
16+3. Read the method signature for query params, path variables, and request body.
17+4. Write the curl from what you just read.
14418
14519 **CLI command or flag**
146−1. Open `cmd/*.go` in `conductor-cli` (separate repo).
147−2. Find the `cobra.Command` definition for the subcommand.
148−3. Read the `Flags()` declarations for exact flag names, types, and defaults.
149−4. Write the example from what you just read.
20+1. Open `conductor-cli/cmd/*.go` (separate repo under this workspace).
21+2. Find the `cobra.Command` for the subcommand and read its `Flags()` declarations.
22+3. Write the example from what you just read — flag names, types, and defaults.
15023
15124 **SDK code example (Python, JS, Java, Go)**
152−1. Open the relevant SDK source file.
153−2. Find the method signature and required parameters.
154−3. Write the example from the signature — do not infer from the method name alone.
155−4. If a working test exists for that method, use it as the starting point.
25+1. Open the SDK source file for the method you're documenting.
26+2. Read the method signature and required parameters.
27+3. If a working test exists for that method, use it as the starting point.
28+4. Write from the signature — do not infer from the method name alone.
15629
15730 **Expected output block**
158−1. Get real output: run the command locally, or find it in test fixtures, CI logs, or existing tests.
159−2. Paste verbatim. Do not paraphrase or construct output that "looks right."
160−3. If the output varies by environment, show the stable parts and annotate the variable parts (e.g., `<workflow-id>`).
31+1. Get real output: run the command, or find it in test fixtures or CI logs.
32+2. Paste verbatim. Do not construct output that "looks right."
33+3. For variable fields (IDs, timestamps), use annotated placeholders like `<workflow-id>`.
16134
162−**Editing an existing doc section**
163−1. Before touching prose, read every code block and command in the section.
164−2. Verify each one using the steps above — not just the block you plan to change.
165−3. Fix anything you find while you're there.
35+**Editing an existing section**
36+- Before changing anything, read every code block and command in the section.
37+- Verify each one using the steps above, not just the block you plan to change.
38+- Fix anything you find while you're there.
16639
16740 ### When you can't verify
16841
169−If a running server or CLI binary is unavailable:
170−- Add a `<!-- TODO: verify against live server -->` comment in the file.
42+If a running server or CLI is unavailable:
43+- Add `<!-- TODO: verify against live server -->` in the file.
17144 - Note it explicitly in the PR description.
172−- Do not write a best-guess example and leave it unmarked.
45+- Do not write an unverified example and leave it unmarked.
17346
174−## Agent Behavior
47+### Key source locations
17548
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
49+| Content | Where to look |
50+|---|---|
51+| REST API routes | `rest/src/main/java/com/netflix/conductor/rest/controllers/` |
52+| Workflow sync execution | `WorkflowResource.java` → `executeWorkflow()` at `@PostMapping("execute/{name}/{version}")` |
53+| Task routes | `TaskResource.java` |
54+| CLI subcommands and flags | `conductor-cli/cmd/workflow.go`, `cmd/task.go`, etc. |
55+
56+## Other Guidelines
57+
58+See [AGENTS.md](AGENTS.md) for full project conventions: code style, testing, dependency pinning, PR guidelines.
59+
