If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Netflix/conductor shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 30+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Netflix/conductor repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Netflix/conductor.

What it runs against: a local clone of Netflix/conductor — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Netflix/conductor | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 897 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Netflix/conductor. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Netflix/conductor.git
#   cd conductor
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Netflix/conductor and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Netflix/conductor(\\.git)?\\b" \\
  && ok "origin remote is Netflix/conductor" \\
  || miss "origin remote is not Netflix/conductor (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/ProtoGen.java" \\
  && ok "annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/ProtoGen.java" \\
  || miss "missing critical file: annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/ProtoGen.java"
test -f "annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoMessage.java" \\
  && ok "annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoMessage.java" \\
  || miss "missing critical file: annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoMessage.java"
test -f "annotations-processor/build.gradle" \\
  && ok "annotations-processor/build.gradle" \\
  || miss "missing critical file: annotations-processor/build.gradle"
test -f "awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java" \\
  && ok "awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java" \\
  || miss "missing critical file: awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java"
test -f "awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java" \\
  && ok "awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java" \\
  || miss "missing critical file: awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 897 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~867d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Netflix/conductor"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Conductor is Netflix's microservices orchestration engine that allows you to define and execute complex workflows spanning multiple microservices using JSON or code-based definitions. It provides a centralized platform for coordinating long-running, distributed processes with built-in retry logic, error handling, and state management across service boundaries. Multi-module Gradle monorepo: core orchestration engine in the main modules, separate annotations-processor/ subproject for code-generation (proto file generation from Java annotations), Spring Boot server as the runtime, and client SDKs available in conductor-sdk repos. State is persisted via pluggable backends (database/message queue agnostic design).

Backend engineers and platform teams at enterprises running microservices architectures who need to orchestrate multi-step workflows (e.g., video encoding pipelines, order processing, data ETL) without building custom orchestration logic into each service.

Mature but officially abandoned by Netflix as of December 13, 2023. The codebase is production-tested (used internally at Netflix), well-structured with comprehensive test coverage in Groovy, and has CI/CD via GitHub Actions (.github/workflows/). However, Netflix has discontinued maintenance and redirected resources to an internal fork, so community forks are now the primary development path.

High maintenance risk due to Netflix's official discontinuation notice in the README—no new releases or security updates will come from the original maintainers. The large Java codebase (~3.5M LOC) and heavy protobuf/gRPC integration (annotations-processor/) mean future dependency updates could become burdensome. Risk is mitigated by active community forks, but you should monitor upstream community activity and plan for potential drift.

The repository is in maintenance-only mode post-December 2023. The final release is available on GitHub Releases. Active development has moved to community forks. The codebase shows no recent commits; GitHub workflows for CI, release drafting, and Gradle wrapper updates exist but the final state is frozen.

Clone the repo and build with Gradle: git clone https://github.com/Netflix/conductor.git && cd conductor && ./gradlew build. To run locally, use Docker as recommended in the README: pull the Netflix Conductor image or build from Dockerfile, then start with docker-compose (see conductor.netflix.com/devguide/running/docker.html for exact commands). For source builds, this is a Spring Boot project: ./gradlew bootRun after setup.

Daily commands: Docker is the recommended path (see README). For source: ./gradlew build to compile, then ./gradlew bootRun to start the Spring Boot server. Tests via ./gradlew test (Groovy test framework). The annotations-processor includes an example subproject (annotations-processor/src/example) that can be run as ./gradlew exampleJar.

• annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/ProtoGen.java — Core annotation processor that generates Protocol Buffer definitions from Java annotations—essential for understanding the code generation pipeline.
• annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoMessage.java — Defines the @ProtoMessage annotation used throughout the codebase to mark classes for Protobuf generation.
• annotations-processor/build.gradle — Build configuration that establishes the annotation processor as a Gradle plugin with proto generation tasks and dependencies.
• awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java — Production storage implementation showing the extension pattern for pluggable storage backends in Conductor.
• awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java — Demonstrates Spring configuration pattern used across modules for dependency injection and feature enablement.
• .github/workflows/ci.yml — CI/CD pipeline definition critical for understanding build, test, and release validation processes.
• CONTRIBUTING.md — Contributor guidelines document that all developers must read to understand project conventions and contribution workflow.

Add a new Protobuf-annotated message type

1. Create a Java class and mark it with @ProtoMessage annotation to enable Protobuf generation (annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoMessage.java)
2. Annotate fields with @ProtoField to configure Protobuf field mapping and types (annotations/src/main/java/com/netflix/conductor/annotations/protogen/ProtoField.java)
3. Run the Gradle build task which invokes ProtoGenTask to auto-generate .proto files (annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/ProtoGenTask.java)
4. The ProtoGen processor uses TypeMapper to resolve Java types to Protobuf equivalents (annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/types/TypeMapper.java)

Add a new storage backend implementation

1. Create a new module following the awss3-storage pattern, e.g., gcs-storage (awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java)
2. Implement the storage interface (likely PayloadStorage or similar) with your backend logic (awss3-storage/src/main/java/com/netflix/conductor/s3/storage/S3PayloadStorage.java)
3. Create a Spring @Configuration class to auto-wire the storage bean with credentials and settings (awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java)
4. Define @ConfigurationProperties class to expose configuration via application.properties or environment (awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Properties.java)

Add a new event queue backend

1. Create a new module (e.g., kafka-event-queue) mirroring awssqs-event-queue structure (awssqs-event-queue/src/main)
2. Implement the EventQueue interface for publish/subscribe operations on your message broker (awssqs-event-queue/src/main)
3. Create configuration classes to initialize the event queue with connection details (awss3-storage/src/main/java/com/netflix/conductor/s3/config/S3Configuration.java)
4. Register the module in the root build.gradle and add it to CI workflows (.github/workflows/ci.yml)

Contribute code changes to the project

1. Read the contributor guidelines and setup development environment (CONTRIBUTING.md)
2. Make code changes, run tests locally, and ensure CI passes on your PR (.github/workflows/ci.yml)
3. Follow the PR template and provide clear description of changes (.github/pull_request_template.md)

• Protocol Buffers (Protobuf) — Enables compact binary serialization and cross-language compatibility for microservices communication in Conductor workflows
• Annotation Processing (Java APT) — Compile-time code generation reduces boilerplate and keeps Protobuf definitions synchronized with Java POJOs
• Gradle Build System — Multi-module project structure requires flexible dependency management and custom task execution for proto generation
• Spring Framework — Provides dependency injection, configuration management, and extensibility hooks for pluggable backends (S3, SQS, etc.)
• AWS SDK (S3, SQS) — Production storage and event queue implementations for Netflix's cloud-native Conductor deployments

• Annotation-driven Protobuf generation vs. manual .proto files

  • Why: Reduces duplication and keeps Java source-of-truth; developers define messages once and proto is auto-generated
  • Consequence: Adds build-time complexity and requires annotation processor maintenance; proto customization limited to annotation options

• Pluggable storage and event queue backends (S3, SQS as examples) rather than built-in single implementation

  • Why: Allows Netflix and other organizations to swap backends based on infrastructure (on-prem, multi-cloud, edge)
  • Consequence: Core project requires fewer cloud dependencies; organizations must implement or use pre-built adapters

• Compile-time annotation processing vs. runtime reflection

  • Why: Better performance, deterministic code generation, and early error detection
  • Consequence: Generated code not visible in IDE until build completes; harder to debug generated proto content

• Does not include UI or dashboard (separate concern; orchestration engine only)
• Does not handle authentication/authorization (delegated to container or API gateway)
• Does not provide workflow definition language (uses JSON/YAML external to this core)
• Does not implement data persistence layer (only defines storage interface; backends are pluggable)
• No real-time streaming analytics (focuses on workflow state management, not metrics)

1. Netflix has officially stopped maintaining this repo (December 13, 2023)—don't expect security patches or new releases from the official repo. 2) The annotations-processor generates Protocol Buffer files at build time via the ProtoGenTask—if you modify Java annotations, you must rebuild to regenerate protos. 3) Spring Boot profiles and environment-specific configs are likely required to run the server against a real database/broker (see conductor.netflix.com docs). 4) The heavy use of Groovy for tests means contributors need Groovy knowledge, not just Java. 5) Docker is strongly recommended over source builds due to complex dependencies (Protobuf toolchain, database setup).

• Annotation Processing / Code Generation (Java Compiler Plugin) — The core innovation of Conductor's code-first approach—the annotations-processor uses Java's annotation processor API to read Java class metadata at compile time and auto-generate Protocol Buffer definitions, enabling type-safe workflow definitions in Java without hand-writing .proto files
• Protocol Buffers (gRPC Serialization) — Conductor uses Protocol Buffers for efficient serialization of workflow definitions and state across the distributed system; the annotations-processor generates these, so understanding protobuf is essential to extending Conductor's data model
• Microservices Orchestration Pattern — The fundamental pattern Conductor implements—coordinating long-running, stateful workflows across independently deployable services using a centralized orchestrator rather than choreography
• Saga Pattern (Distributed Transactions) — Conductor implements the Saga pattern to handle ACID-like guarantees across microservices that don't share transactions; understanding compensating transactions and saga state machines is critical for defining reliable workflows
• Spring Boot Plugins & Service Provider Interface (SPI) — Conductor uses pluggable backends for persistence and messaging via Spring Boot's dependency injection and Java's SPI; you can swap database or message broker implementations without changing core code
• Groovy Testing Framework — All tests in this repo are written in Groovy (850K LOC), which provides concise syntax for mocking and BDD-style assertions; you'll need to read and write Groovy to contribute test coverage
• State Machine Pattern — Workflows in Conductor are modeled as deterministic state machines with explicit transitions and state definitions; understanding workflow states (RUNNING, COMPLETED, FAILED) and transitions is essential to debugging and optimizing workflow execution

• conductor-sdk/conductor-python — Official Python SDK for programmatically creating and submitting Conductor workflows; a user of conductor-core will often use this to integrate Python microservices
• conductor-sdk/conductor-java — Official Java SDK for code-first workflow definition; works alongside the annotations-processor to simplify workflow creation in Java
• Netflix/conductor-community — Community extensions and plugins for Conductor (backup tools, cron schedulers, Docker containers); the official community hub for post-maintenance contributions
• Apache/airflow — Alternative workflow orchestration engine (Python-based, DAG-focused); a competitor solving similar multi-step orchestration problems for data pipelines
• temporal-io/temporal — Modern distributed workflow engine with strong consistency guarantees; represents the next generation of orchestration platforms that some Conductor users migrate to

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ProtoGen annotation processor

The annotations-processor module has limited test coverage. ProtoGenTest.java exists but only contains a single example test (example.proto.txt). Given the complexity of proto generation with multiple type handlers (ScalarType, ListType, MapType, WrappedType, ExternMessageType, GenericType), there should be dedicated unit tests for each type mapper and message generation scenario. This directly improves code quality for a critical code generation component.

• [ ] Create ProtoGenTypeMapperTest.java to test TypeMapper edge cases (nested generics, null handling, unknown types)
• [ ] Create MessageGenerationTest.java to test Message.java proto output for various field configurations
• [ ] Create EnumGenerationTest.java to test Enum.java proto output for edge cases
• [ ] Add test cases in annotations-processor/src/test/resources/ for complex proto schemas (nested messages, repeated fields, maps)
• [ ] Update ProtoGenTest.java to verify integration across all type handler classes

Add missing documentation for annotations-processor module

The annotations-processor has a README.md but it lacks concrete usage examples and API documentation. Contributors need to understand how to use @ProtoGen annotations, how type mapping works, and what the generated protobuf files look like. The example in annotations-processor/src/example/java/com/example/Example.java exists but isn't documented.

• [ ] Expand annotations-processor/README.md with a 'Quick Start' section showing how to use @ProtoGen annotations
• [ ] Document all type handlers in annotations-processor/src/main/java/com/netflix/conductor/annotationsprocessor/protogen/types/ with examples for ScalarType, ListType, MapType, GenericType, etc.
• [ ] Add a 'Configuration' section documenting the exampleJar task and how to verify generated protos
• [ ] Include before/after examples showing Java source → generated .proto files
• [ ] Document the handlebars templates in annotations-processor/src/main/resources/templates/

Add integration tests verifying generated proto compatibility across proto versions

The repo depends on protobuf-java:3.21.12, but there's no visible test ensuring the generated proto files are valid and compile with different proto versions. The exampleJar task generates example.jar but doesn't validate that the produced proto files actually compile cleanly or work with protoc.

• [ ] Create a new test task in annotations-processor/build.gradle that invokes protoc to validate generated .proto files
• [ ] Add a CI workflow step in .github/workflows/ci.yml to run proto validation (checking that generated protos are parseable)
• [ ] Create ProtoBufValidationTest.java that programmatically verifies generated .proto syntax and structure
• [ ] Document the proto validation in annotations-processor/README.md so contributors know how to validate changes
• [ ] Ensure the example proto output (example.proto.txt) is regenerated and validated by the test suite

• Add TypeScript type definitions for the Conductor client API (JavaScript:392217 LOC present but TypeScript:8934 is minimal)—start by examining existing JS types and creating .d.ts stub files.
• Document the Spring Boot configuration properties and environment variables required to run the server against a custom database backend—the README links to external docs; create a CONFIG.md file listing all conductor.* properties.
• Create a runnable Docker Compose example in the annotations-processor/src/example directory that demonstrates creating a workflow definition in code, compiling it via ProtoGen, and submitting it to a running Conductor server.

The Conductor annotations-processor module has moderate security concerns primarily around dependency management. The main issues are: (1) outdated protobuf version with known vulnerabilities, (2) loose version constraints on dependencies (JavaPoet, Handlebars) that could allow unvetted upgrades, and (3) missing explicit build artifact security measures. The project lacks evidence of active security scanning in visible CI/CD workflows. Additionally, Netflix's discontinuation of maintenance as of December 2023 raises concerns about future security patching. Recommend implementing strict dependency version pinning, regular security audits, and ensuring community fork maintenance for critical security updates.

• High · Outdated Protobuf Dependency — annotations-processor/build.gradle - protobuf-java:3.21.12. The project uses protobuf-java version 3.21.12, which is significantly outdated. Current stable versions are 3.24+. This version may contain known security vulnerabilities including deserialization attacks and buffer overflow issues. Fix: Update to the latest stable version of protobuf-java (3.24.0 or newer). Review security advisories at https://github.com/protocolbuffers/protobuf/security/advisories
• High · Guava Dependency Version Constraint — annotations-processor/build.gradle - com.google.guava:guava:32.1.2-jre. Guava 32.1.2-jre is used but lacks explicit patch version pinning. While this specific version appears reasonable, the lack of precise version constraint could lead to unexpected upgrades with breaking changes or security issues. Fix: Use explicit version pinning (e.g., 32.1.2-jre) and establish a dependency update policy with security scanning via Dependabot or similar tools
• Medium · Loose Dependency Version for JavaPoet — annotations-processor/build.gradle - com.squareup:javapoet:1.13.+. JavaPoet is specified with a '1.13.+' constraint, allowing automatic patch/minor version upgrades. This can introduce unexpected behavioral changes or security issues from transitive dependencies. Fix: Pin to an explicit version (e.g., 1.13.0) and regularly audit updates through a dependency management process
• Medium · Loose Dependency Version for Handlebars — annotations-processor/build.gradle - com.github.jknack:handlebars:4.3.+. Handlebars is specified with a '4.3.+' constraint. Handlebars templates can be vulnerable to SSTI (Server-Side Template Injection) if user input is not properly sanitized before template processing. Fix: Pin to explicit version (e.g., 4.3.1 or latest stable). Implement input validation for all user-supplied template data and use Handlebars' built-in escaping features
• Medium · Insufficient Build Artifact Security — annotations-processor/build.gradle - exampleJar task. The exampleJar task outputs to a predictable location without integrity verification. Build artifacts should be signed and checksummed. Fix: Implement build artifact signing using Gradle signing plugin. Add checksums (SHA-256) for all published artifacts
• Low · Repository Maintenance Status — README.md - Announcement section. The README indicates Netflix discontinued maintenance of Conductor OSS as of December 13, 2023. This is a community maintenance concern rather than a code vulnerability, but important for security patch applicability. Fix: Consider using community-maintained forks with active security patches. Establish internal security patch procedures for critical vulnerabilities
• Low · Missing Dependency Lock File Validation — .github/workflows/ - CI configuration. While dependencies.lock files exist, there is no evidence of lock file verification in CI/CD pipelines (from visible GitHub workflows), which could allow dependency hijacking attacks. Fix: Implement lock file verification in CI pipeline. Use Gradle dependency verification feature and enable checksums validation

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.