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/danielgerlag/workflow-core 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 the board

• Last commit 1d ago
• 9 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{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 danielgerlag/workflow-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/danielgerlag/workflow-core.

What it runs against: a local clone of danielgerlag/workflow-core — 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 danielgerlag/workflow-core | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of danielgerlag/workflow-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/danielgerlag/workflow-core.git
#   cd workflow-core
#
# 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 danielgerlag/workflow-core and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/danielgerlag/workflow-core"
  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).

Workflow Core is a lightweight, embeddable .NET Standard workflow engine that executes long-running processes with multiple stateful tasks. It provides a fluent C# API and JSON/YAML DSL for defining workflows, with pluggable persistence (SQL Server, MongoDB, PostgreSQL, etc.) and concurrency providers to enable multi-node cluster deployments. Key capability: manage complex business processes (user onboarding, saga transactions, approval chains) without external servers. Monolithic .NET solution (WorkflowCore.sln) with core engine as the main library targeting .NET Standard, plus modular persistence providers (SQL, MongoDB, PostgreSQL) and concurrency plugins. Docs in /docs/ cover activities, control structures, error handling, and extensions. Recent additions include Azure AI Foundry and Elasticsearch integration docs, suggesting extension ecosystem.

.NET developers building backend systems that need to orchestrate multi-step processes with durable state—specifically microservices teams, enterprise integration specialists, and SaaS platforms requiring workflow automation without deploying a separate orchestration service.

Production-ready and actively maintained. The project has 40+ release notes spanning from v1.2.8 to v3.6.0, indicating maturity and iterative improvement. CI/CD is set up via GitHub Actions (.github/workflows/dotnet.yml) and AppVeyor. Recent releases (3.4.0, 3.6.0) suggest active development, though commit frequency is not visible from the file list alone.

Low-to-moderate risk. The codebase is primarily C# (1.3M LOC) with minimal external dependencies visible (only Dockerfile and TSQL for optional infrastructure). Single-maintainer apparent (danielgerlag), which is typical of this project type. Breaking changes have occurred (v2.0.0 and v3.0.0 release notes exist), so upgrading requires attention. No test file listing provided in top 60, which is a gap worth investigating.

Project maintains active release cadence with recent versions 3.4.0 and 3.6.0. New integrations are being added: docs/azure-ai-foundry.md and docs/elastic-search.md indicate recent feature expansion. A related stand-alone project, Conductor, was announced as a server-based alternative using Workflow Core internally. The GitHub Actions workflow is configured for .NET builds.

git clone https://github.com/danielgerlag/workflow-core.git && cd workflow-core && dotnet build WorkflowCore.sln && dotnet test (verify test projects exist in solution). Review docs/getting-started.md for first steps. No npm/package.json; this is pure .NET.

Daily commands: dotnet build WorkflowCore.sln (compile) → dotnet test (run test suite, if tests exist in solution) → integration via NuGet: Install-Package WorkflowCore then instantiate IWorkflowHost and register your workflow IWorkflow implementations. See README examples for fluent API usage.

• WorkflowCore.sln: Root project file; defines all assemblies, dependencies, and build configuration for the entire workflow engine
• docs/getting-started.md: Entry point for new developers; covers workflow definition, execution setup, and basic API usage
• docs/activities.md: Defines how to create custom step types (IStepBody implementations) which is the primary extension point
• docs/control-structures.md: Documents conditional logic, loops, parallel execution, and error handling patterns available in workflow definitions
• docs/persistence.md: Explains pluggable storage layer architecture; critical for understanding multi-node deployments and state durability
• docs/extensions.md: Lists available persistence and concurrency provider plugins and how to implement custom providers
• .github/workflows/dotnet.yml: CI/CD pipeline; shows how builds and tests are automated, useful for understanding test expectations and release process

For new step types: implement IStepBody in a new .cs file (examples: CreateUser, SendConfirmationEmail). For persistence providers: implement IWorkflowStore in src/providers/. For DSL enhancements: modify WorkflowCore.DSL parsing logic. For control structures: extend IWorkflowBuilder in core engine. Start with docs/activities.md and docs/extensions.md for patterns.

No explicit test directory in top 60 file list—verify test projects exist in .sln before assuming coverage. Persistence providers are optional: in-memory default may not persist across restarts (dev trap). External events (WaitFor pattern) require external trigger mechanism not built into core. Multi-node clustering requires distributed locking provider setup, not automatic. DSL (JSON/YAML) requires separate WorkflowCore.DSL NuGet package, not included in core. Docker support exists but requires SQL/persistence backend configuration.

• Fluent Builder Pattern — Workflow Core's primary API uses fluent builders (builder.StartWith<Task1>().Then<Task2>()) for readable, chainable workflow definitions; understanding this pattern is essential for authoring workflows and extensions
• Pluggable Persistence Layer — The engine abstracts storage via IWorkflowStore interface; you must understand this to swap persistence providers, scale to multi-node, or debug state durability issues
• Saga Pattern (Distributed Transactions) — Workflow Core explicitly supports sagas for coordinating multi-step transactions with rollback compensation; core to building resilient microservices without 2PC
• Step-based State Machine — Workflows are modeled as directed acyclic graphs (DAGs) of steps with state; each step is a state machine node, critical for understanding execution semantics and error handling
• External Event Triggering (WaitFor Pattern) — Workflows can pause at WaitFor() calls waiting for external events (e.g., user confirmation, webhook); you need this pattern to integrate with async user interactions and event sources
• Distributed Locking for Concurrency — Multi-node deployments require a concurrency provider (distributed lock) to prevent duplicate execution; this is non-obvious and essential for production clusters
• Workflow DSL (Domain-Specific Language) — Workflow Core supports declarative JSON/YAML definitions via WorkflowCore.DSL, allowing non-developers to define workflows; essential for low-code scenarios but separate from fluent API

• danielgerlag/conductor — Official stand-alone server that wraps Workflow Core internally, offering REST API and UI for workflow management—the next step for teams needing a central orchestration service
• temporalio/temporal — Industry alternative: Temporal is a mature, distributed workflow orchestration engine (Go-based) solving the same problem at scale for complex, long-running processes
• dapr/dapr — Complementary distributed application runtime; includes workflow execution via Dapr Workflow API, useful if you're building .NET microservices requiring orchestration alongside pub/sub and secrets
• Azure/DurableFunctions — Cloud-native alternative: Azure Durable Functions provides serverless workflow orchestration in .NET, tightly integrated with Azure—compare when deploying to Microsoft cloud

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 documentation for WorkflowCore.DSL module

The DSL (Domain Specific Language) module exists in src/WorkflowCore.DSL with IDefinitionLoader and ITypeResolver interfaces, but there is no dedicated documentation file explaining how to use these features. The docs/ folder has extensive guides (activities.md, control-structures.md, etc.) but no docs/dsl.md or docs/definition-loader.md explaining JSON/YAML workflow definitions or custom type resolution.

• [ ] Create docs/dsl.md documenting IDefinitionLoader interface and DefinitionSource model
• [ ] Add examples showing how to load workflow definitions from JSON/YAML using the DSL module
• [ ] Document ITypeResolver and explain custom type resolution for workflow definitions
• [ ] Reference the new doc from docs/index.md and mkdocs.yml
• [ ] Link to this documentation from docs/json-yaml.md which currently exists but may lack DSL implementation details

Expand GitHub Actions CI to test multiple .NET versions and platforms

The .github/workflows/dotnet.yml exists but the file structure suggests it may lack comprehensive coverage. Given that this is a .NET Standard library targeting multiple frameworks, the CI should explicitly test against multiple .NET versions (e.g., .NET 6.0, 7.0, 8.0+) and potentially Linux/Windows platforms to ensure broad compatibility across the ecosystem.

• [ ] Review current .github/workflows/dotnet.yml for existing matrix configuration
• [ ] Add or expand matrix strategy to test against multiple .NET versions (6.0, 7.0, 8.0, 9.0)
• [ ] Add separate job or matrix entry for Windows and Linux test runs
• [ ] Include code coverage reporting to track test coverage across versions
• [ ] Update README.md with a badge showing tested .NET versions

Add integration tests for multi-node cluster persistence scenarios

The docs/multi-node-clusters.md documentation exists and the persistence providers are pluggable, but there are no visible integration tests verifying that workflow state correctly persists and synchronizes across multiple nodes. This is critical for users deploying to production clusters.

• [ ] Create a new test project or test folder: src/WorkflowCore.Tests.MultiNode or similar
• [ ] Write integration tests that simulate multiple workflow engine instances running concurrently
• [ ] Test state consistency when one node executes a step and another queries the workflow state
• [ ] Include tests for the different persistence providers (SQL, MongoDB, etc.) with concurrent access
• [ ] Verify lock/concurrency mechanisms prevent duplicate step execution across nodes
• [ ] Document test setup in docs/multi-node-clusters.md with reproduction steps

• Add comprehensive integration test suite for all persistence providers (SQL Server, MongoDB, PostgreSQL) under a new Tests/ directory, ensuring each provider implements IWorkflowStore correctly—currently no test files visible in top 60
• Expand docs/error-handling.md with code examples for retry policies and compensation (saga rollback) patterns, mapping to real-world use cases like payment processing and reservation systems
• Implement Elasticsearch query examples in docs/elastic-search.md showing how to index workflow execution history and build a workflow audit dashboard; currently only mentions Elasticsearch without usage patterns

The Workflow Core project shows moderate security posture based on available information. As a .NET Standard library for workflow orchestration, the main security concerns are around deserialization of untrusted workflow definitions and exception handling. The lack of visible source code in this analysis limits comprehensive vulnerability detection. Key recommendations: (1) Provide dependency files for scanning, (2) Review deserialization logic in WorkflowCore.DSL, (3) Implement regular dependency vulnerability scanning in CI/CD, (4) Add security policy documentation, (5) Ensure no sensitive data leakage in exception messages, (6) Validate and sanitize all user-provided workflow definitions, (7) Consider adding security-focused integration tests.

• Medium · Insufficient static analysis coverage — Repository root - missing dependency files. The provided file structure listing and README snippet do not contain actual source code for detailed vulnerability analysis. Key files like dependency management files (*.csproj, package.json, packages.config), configuration files, and actual implementation code are not provided for review. Fix: Provide complete dependency files (.csproj, .nuspec, or lock files) for NuGet package analysis. Review should include: src/WorkflowCore/WorkflowCore.csproj and all referenced project files.
• Low · Missing security documentation — .github directory. While the project includes comprehensive documentation in the docs folder, there is no visible security policy, security.md, or vulnerability disclosure guidelines in the repository structure. Fix: Add a SECURITY.md file in the repository root with vulnerability disclosure policy and security contact information. Consider adding a security policy in .github/SECURITY.md
• Low · Potential deserialization risks in DSL module — src/WorkflowCore.DSL/Services/Deserializers.cs. The WorkflowCore.DSL module contains Deserializers.cs and handles JSON/YAML deserialization of workflow definitions. Without seeing the implementation, this is a common attack vector for deserialization vulnerabilities. Fix: Review deserialization logic to ensure: 1) Type validation is enforced, 2) Only safe types are allowed for deserialization, 3) Input validation occurs before deserialization, 4) Use safe deserialization options (TypeNameHandling = None in Newtonsoft.Json)
• Low · Exception handling exposure risk — src/WorkflowCore/Exceptions/. The Exceptions folder contains several exception classes (ActivityFailedException, CorruptPersistenceDataException, NotFoundException). Custom exceptions should not expose sensitive information through error messages. Fix: Review exception classes to ensure error messages do not expose: database details, system paths, internal state, or other sensitive debugging information in production environments.
• Low · Third-party extension dependencies not visible — src/ - all extension projects. The project supports multiple persistence providers and extensions (Elastic Search integration visible in docs). These external dependencies may have their own vulnerabilities. Fix: Maintain an up-to-date software bill of materials (SBOM). Regularly scan all NuGet dependencies using: dotnet list package --vulnerable, OWASP Dependency-Check, or Snyk.

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.