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/elsa-workflows/elsa-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 today
• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits

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

What it runs against: a local clone of elsa-workflows/elsa-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 elsa-workflows/elsa-core | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "elsa-workflows/elsa-core(\\.git)?\\b" \\
  && ok "origin remote is elsa-workflows/elsa-core" \\
  || miss "origin remote is not elsa-workflows/elsa-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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/copilot-instructions.md" \\
  && ok ".github/copilot-instructions.md" \\
  || miss "missing critical file: .github/copilot-instructions.md"
test -f ".specify/memory/constitution.md" \\
  && ok ".specify/memory/constitution.md" \\
  || miss "missing critical file: .specify/memory/constitution.md"
test -f ".nuke/build.schema.json" \\
  && ok ".nuke/build.schema.json" \\
  || miss "missing critical file: .nuke/build.schema.json"
test -f ".github/workflows/packages.yml" \\
  && ok ".github/workflows/packages.yml" \\
  || miss "missing critical file: .github/workflows/packages.yml"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"

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

Elsa is a .NET workflow engine and orchestration library that enables users to define, execute, and visually design workflows within any .NET application. It supports multiple workflow definition formats—C# code, JSON, and a web-based visual designer—and runs on .NET 6+. The core problem it solves is providing a flexible, composable, low-code automation platform for complex business processes without requiring users to hand-code every integration. Monorepo structure: core workflow engine lives in the root C# projects (6.2M C# LOC), with agent skills under .agents/ and .claude/ directories (skill definitions in markdown + references for GitLab API and GraphQL), and Docker/shell tooling for deployment. Visual designer and server likely in unpacked but not shown in top 60 files; real execution happens in the core C# assemblies referenced by consuming .NET applications.

.NET backend developers and architects who need to build long-running business process automation (order processing, approvals, notifications) and want the flexibility of a pluggable activity system. Also targets business analysts and domain experts who want to design workflows visually without writing C#. Contributors include both the maintainer team and community members building custom activities and integrations.

Actively developed but in prerelease (Elsa 3.x). The project has significant community engagement (Discord: 814605913783795763, StackOverflow tag, Gurubase presence) and CI/CD pipelines (GitHub Actions for packages.yml badge shown), indicating ongoing investment. However, the 3.x branch is marked prerelease on NuGet, so production adoption of v3 is limited while v2 (branch 2.x) is stable.

Prerelease status (v3) means breaking changes are still possible; the maintainers explicitly direct users to branch 2.x for production workloads. Heavy C# dependency chain typical of .NET projects; no visible package count or security audit data in metadata. Single-author commit patterns are possible but not confirmed from file list alone. Docker image versioning is semver-based, suggesting discipline.

Active v3 development with prerelease packages being published to NuGet and Docker Hub (image tag: elsaworkflows/elsa-v3). Agent skills are being defined (speckit-* skill family suggests spec-driven development tooling). The presence of .agents/ and .claude/ directories suggests recent integration with AI code assistance tooling for development workflow.

Clone and build: git clone https://github.com/elsa-workflows/elsa-core.git && cd elsa-core. Check for .NET SDK version in .editorconfig or global.json (not shown but standard for .NET projects). Run dotnet build to compile. For the Designer/Server, docker run -p 3000:3000 elsaworkflows/elsa-v3:latest or build from Dockerfile in repo root.

Daily commands: dotnet build from root; dotnet run in the appropriate project (likely src/server or similar, not fully visible in file list). For Docker: docker build -t elsa:local . && docker run -it -p 3000:3000 -p 8080:8080 elsa:local. Check README for exact port and env var requirements.

• .github/copilot-instructions.md — Core guidance for AI-assisted development and architectural patterns used throughout the project.
• .specify/memory/constitution.md — Project constitution defining core principles, design philosophy, and decision-making framework for all contributors.
• .nuke/build.schema.json — Build system configuration that defines how the entire .NET workflow engine is compiled, tested, and packaged.
• .github/workflows/packages.yml — CI/CD pipeline that orchestrates building, testing, and publishing NuGet packages—the primary delivery mechanism.
• .editorconfig — Enforces code style and formatting standards across all C# source files to maintain consistency.
• .github/pull_request_template.md — Standardized PR template that guides contributors through required checks, documentation, and testing expectations.
• .gitignore — Defines which files and directories are excluded from version control for a .NET monorepo workspace.

• Build & Package (NUKE, GitHub Actions) (NUKE, GitHub Actions, MSBuild, .NET SDK) — Compiles C# source, runs test suite, validates code quality (EditorConfig), generates NuGet packages, publishes to nuget.org
  • Failure mode: Failed compilation, test failures, or NuGet publish errors block merges; manual intervention required
• Code Review & Quality (Claude AI, PR templates) — undefined

Add a New AI-Driven Skill

1. Create skill definition directory with SKILL.md file describing the capability and parameters (.agents/skills/{skill-name}/SKILL.md)
2. Register skill in the appropriate agent configuration (e.g., speckit, greploop, or claude) (.github/agents/{agent-name}.agent.md)
3. Create prompt template for the skill to guide AI behavior (.github/prompts/{skill-name}.prompt.md)
4. Add skill to manifest for your integration platform (SpecKit or Claude) (.specify/integrations/{platform}.manifest.json)

Add a New GitHub Actions Workflow

1. Create workflow YAML file defining triggers, jobs, and steps (.github/workflows/{workflow-name}.yml)
2. Reference NUKE build targets if the workflow compiles or builds code (.nuke/build.schema.json)
3. Update copilot instructions if the workflow impacts contributor process (.github/copilot-instructions.md)

Enforce New Code Standards

1. Add or update code style rules to apply across languages and projects (.editorconfig)
2. Update pull request template to document required checks (.github/pull_request_template.md)
3. Add corresponding checks in PR validation workflow (.github/workflows/pr.yml)
4. Document standard in project constitution if it's architectural (.specify/memory/constitution.md)

Update Build or Deployment Process

1. Modify NUKE build targets or parameters (.nuke/parameters.json)
2. Update package build and publish workflow if it affects NuGet distribution (.github/workflows/packages.yml)
3. Register new tools if required for local development (.config/dotnet-tools.json)

• .NET / C# — Core language for Elsa Workflows engine; provides strong typing, async/await patterns, and rich ecosystem for enterprise workflow automation
• GitHub Actions — Native CI/CD for GitHub-hosted monorepo; enables automated testing, code review, and NuGet package publishing with minimal external dependencies
• NUKE Build System — .NET-native build orchestration language; provides type-safe build definitions and integration with the .NET toolchain without external DSLs
• Claude AI / SpecKit Agents — Automate code analysis, documentation, implementation, and release workflows; reduce manual review burden for large monorepo
• EditorConfig + .gitignore — Enforce consistent code style and toolchain across all contributors without enforcing a single IDE or environment

• AI-driven code review and automation (Claude, SpecKit agents)

  • Why: Large monorepo (600 files) with complex workflow engine requires intelligent triage and documentation to reduce reviewer burden
  • Consequence: Increased dependency on LLM quality and uptime; may require human override for nuanced architectural decisions

• Centralized GitHub Actions CI/CD vs. distributed build agents

  • Why: GitHub-native workflow ensures all contributors use same build environment and simplifies secret/credential management
  • Consequence: GitHub Actions rate limits and concurrency constraints; longer feedback loop for high-volume PR activity

• Monorepo structure (single elsa-core repo with 600 files)

  • Why: Atomic versioning and coordinated releases for all workflow components; easier cross-component refactoring
  • Consequence: Larger clone size; CI/CD pipeline must build entire project even for small changes unless highly optimized

• NUKE build system over MSBuild directly

  • Why: Type-safe, version-controlled build logic; enables complex orchestration (parallelize, conditional targets, caching)
  • Consequence: Additional learning curve for contributors unfamiliar with NUKE; another abstraction layer over MSBuild

• Real-time workflow execution monitoring (pre-built dashboard UI)
• Visual workflow designer (BPMN/graphical editor in core)
• Multi-tenancy/SaaS hosting (core engine is single-tenant library)
• Cloud provider lock-in—framework remains cloud-agnostic

Prerelease status means NuGet versions may not resolve as expected—explicitly pin versions in .csproj if pulling from GitHub Actions artifacts. Docker image naming is specific (elsaworkflows/elsa-v3 not latest), watch for tag mismatches. Entity Framework migrations or database initialization may be required for production server startup (not shown in file list but standard for .NET workflow engines). Visual designer likely requires HTTPS in production; check environment variable setup in Dockerfile and README before deploying.

• Activity-Based Workflow Model — Core abstraction in Elsa where workflows are DAGs of pluggable 'Activity' nodes (HTTP, SendEmail, Approval, etc.); understanding this is essential to extending Elsa with custom integrations
• Workflow State Machine / Execution Context — Workflows transition through states (Running, Suspended, Completed, Faulted); Elsa persists execution context to enable resume, retry, and historical replay. This is non-trivial in distributed scenarios.
• Coroutine / Async Suspension Points — Elsa workflows can suspend at async boundaries (wait for human approval, external API response, scheduled time) and resume later without holding resources; this requires careful context serialization
• Dependency Injection (DI) Container Pattern — Elsa activities and storage providers are registered in a .NET IServiceProvider; custom activity development requires understanding constructor injection and service registration
• JSON Schema / Workflow Definition Serialization — Workflows are stored and transmitted as JSON; the schema for activities, connections, and metadata is critical for round-tripping between visual designer and persistence
• Saga Pattern (Distributed Transactions) — Long-running workflows involving multiple services must implement compensating transactions on failure; Elsa's activity model naturally supports saga-like patterns
• Event-Driven Workflow Triggering — Workflows can be triggered by external events (webhooks, Kafka messages, timers); Elsa routes events to appropriate workflow instances via bookmark/resumption patterns

• dapr/dapr — Distributed application runtime with similar workflow/orchestration patterns; both enable microservice choreography in .NET ecosystems
• Azure/azure-webjobs-sdk — Microsoft's serverless job orchestration framework; Elsa's visual designer and activity model are positioned as an open alternative to WebJobs + Functions
• Automattic/Newspack-plugin — Similar low-code workflow authoring for WordPress; demonstrates the same problem domain (non-technical users defining automation) solved in different stacks
• elsa-workflows/elsa-studio — Likely the companion web UI for the visual designer; users of elsa-core will need this repo to actually use the designer mentioned in README
• elsa-workflows/elsa-samples — Official example workflows and integration patterns; essential companion for learning real-world Elsa usage

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.

Consolidate duplicate AI agent skills across .agents and .claude directories

The repository has nearly identical skill definitions duplicated in both .agents/skills/ and .claude/skills/ directories (greploop, speckit-analyze, speckit-checklist, etc.). This creates maintenance burden and inconsistency risks. A new contributor could create a single source-of-truth skills directory, update references in .github/agents/ configuration files, and add a build/validation script to prevent future duplication.

• [ ] Audit both .agents/skills and .claude/skills to document exact differences in each SKILL.md file
• [ ] Create a shared skills directory (e.g., .github/skills/) with canonical versions
• [ ] Update .github/agents/*.md files to reference the new shared skills location
• [ ] Add a pre-commit hook or CI validation script to ensure skills aren't duplicated across directories
• [ ] Document the new skill maintenance process in CONTRIBUTING.md

Create comprehensive .NET workflow testing utilities and example tests

The repo is a workflow engine for .NET but there's no visible test folder structure in the provided file list. A contributor could create a tests/ directory with example unit and integration tests demonstrating how to test workflows, activities, and the engine itself—both as a template for maintainers and as documentation for users building workflows.

• [ ] Create src/tests/ directory structure mirroring core components (Activities, Workflows, Host, Persistence)
• [ ] Write example unit tests for a sample activity (e.g., HttpActivity tests with mocked HttpClient)
• [ ] Write integration tests demonstrating workflow execution with in-memory storage
• [ ] Add xUnit test fixtures and helpers in a shared test utilities project
• [ ] Document testing patterns in docs/testing-workflows.md with code examples

Develop GitHub Actions workflow for multi-target .NET testing and publishing

The repo badges show NuGet and Docker publishing but the .github/workflows directory is not fully visible. A new contributor could create a comprehensive GitHub Actions workflow that tests against multiple .NET versions (net6.0, net8.0), runs code quality checks (SonarQube/CodeQL), and automates NuGet/Docker publishing on version tags—following the multi-platform nature of a .NET workflow engine.

• [ ] Create .github/workflows/test.yml to run unit/integration tests on net6.0 and net8.0
• [ ] Add code coverage reporting (e.g., Codecov integration) and fail if coverage drops
• [ ] Create .github/workflows/publish.yml triggered by version tags to publish to NuGet and Docker Hub
• [ ] Add .github/workflows/codeql.yml for security scanning on pull requests
• [ ] Document CI/CD process in CONTRIBUTING.md with example commands for local testing

• Add C# XML documentation comments to core Activity base class and IWorkflowStore interface; the file list suggests core abstractions exist but completeness of inline docs is unknown. This is low-risk and high-learning-value.
• Write integration tests for the four speckit-* skills (analyze, clarify, plan, implement) to validate SKILL.md contract; test framework likely xUnit or NUnit but test directory not shown in top 60 files.
• Document the .agents/ vs .claude/ distinction in a DEVELOPMENT.md file; both directories have identical skill structure, suggesting they serve different contexts (Claude vs generic agents) but this is not explained.

The elsa-core repository shows moderate security posture. Primary concerns include: (1) incomplete visibility into dependency files and vulnerable packages, (2) AI/Agent configuration files that require access controls, (3) GitHub Actions workflows needing security audit, and (4) missing analysis of actual .NET codebase for injection vulnerabilities. Strengths include Dependabot configuration and structured issue templates. Recommend comprehensive dependency scanning, GitHub Actions workflow audit, and review of actual C# code for injection risks and insecure patterns.

• Medium · AI Agent Configuration Files Lack Security Hardening — .agents/skills/, .claude/skills/ directories. Multiple AI agent configuration directories (.agents and .claude) contain skill definitions and reference materials that may expose operational patterns or sensitive workflow information. These files include API references (gitlab-api.md, graphql-queries.md) that could be leveraged for reconnaissance. Fix: Review and restrict access to AI agent skill definitions. Consider moving sensitive API documentation outside the repository or implementing access controls. Ensure API references don't expose authentication patterns.
• Medium · GitHub Actions Workflows Require Review — .github/workflows/ (especially docker-ca.yml, claude.yml, greploop.yml). Multiple GitHub Actions workflows are present (.github/workflows/) including docker-ca.yml, claude.yml, and others. Without reviewing the actual workflow content, there's potential for exposure of secrets, improper Docker image handling, or execution of untrusted code in CI/CD pipelines. Fix: Audit all GitHub Actions workflows for: (1) proper secret management using GitHub Secrets, (2) least-privilege permissions, (3) unpinned action versions, (4) untrusted input validation in workflow triggers.
• Medium · Missing Dependency File Analysis — Root directory and project subdirectories. The repository lacks visible package dependency files (package.json, .csproj, requirements.txt, pom.xml) in the provided structure. As a .NET workflow engine, .csproj files should be analyzed but weren't provided for review. Fix: Perform comprehensive dependency scanning using tools like OWASP Dependency-Check, Snyk, or NuGet vulnerability scanner. Ensure all NuGet packages are up-to-date and have no known CVEs. Implement automated dependency updates via Dependabot (partially configured).
• Low · Potential Sensitive Information in Configuration Files — .config/dotnet-tools.json, .editorconfig. The presence of .editorconfig, .env-related patterns, and .config/dotnet-tools.json could potentially contain sensitive configuration. Although no actual sensitive data was visible, these file types are common vectors. Fix: Ensure .env files and local configuration files are in .gitignore. Use environment variables or secure vaults (Azure Key Vault, AWS Secrets Manager) for sensitive configuration. Review .config/dotnet-tools.json for any sensitive tool configurations.
• Low · Docker Configuration Requires Verification — .github/workflows/docker-ca.yml, Dockerfile (not provided). Docker workflow exists (docker-ca.yml) and DockerHub integration is referenced in badges. Docker security practices need verification including: image scanning, base image selection, and runtime security. Fix: Implement Docker image scanning in CI/CD pipeline. Use minimal base images (Alpine, distroless). Scan for vulnerabilities using tools like Trivy or Docker Scout. Ensure containers run with non-root users and minimal capabilities.

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.