elsa-core/AGENTS.md

# AGENTS.md

Guidance for AI coding agents working in this repository.

## Project Overview

- Elsa Core is a .NET solution centered on `Elsa.sln`.
- Production code lives under `src/`.
- Tests live under `test/`, grouped by `unit`, `integration`, `component`, and `performance`.
- Build automation is implemented with NUKE in `build/Build.cs` and exposed through `build.sh`, `build.ps1`, and `build.cmd`.

## Working Rules

- Keep changes focused on the requested task. Do not mix unrelated cleanup, formatting, or dependency updates into functional changes.
- Preserve existing public APIs unless the task explicitly requires an API change.
- Update tests when behavior changes and add tests for new behavior where practical.
- Update documentation when changing externally visible behavior, configuration, APIs, or developer workflows.
- Do not delete generated-looking, artifact, or IDE files unless the task explicitly asks for cleanup.
- If the worktree contains unrelated user changes, leave them untouched.

## Agent Operating Principles

- Do not assume, hide confusion, or flatten uncertainty; surface questions, constraints, and tradeoffs explicitly.
- Write the minimum code that solves the defined problem; do not add speculative abstractions, features, or cleanup.
- Touch only the files and behavior required for the task; clean up only issues introduced by your own changes.
- Define success criteria before implementation, then iterate until the criteria are verified or clearly state what could not be verified.

## Build And Test Commands

- Build the default target: `./build.sh`
- Run NUKE test target: `./build.sh Test`
- Build with dotnet directly: `dotnet build Elsa.sln`
- Run all tests directly: `dotnet test Elsa.sln`
- Run a specific test project: `dotnet test test/unit/Elsa.Workflows.Core.UnitTests/Elsa.Workflows.Core.UnitTests.csproj`
- Run ElsaScript DSL integration tests: `./run-dsl-tests.sh`

Prefer targeted `dotnet test <project>` commands while iterating, then run a broader build or test command when the change affects shared infrastructure or cross-module behavior.

## Code Style

- C# uses `LangVersion` `latest`, nullable reference types, and implicit usings from `Directory.Build.props`.
- Projects under `src/` target `net8.0`, `net9.0`, and `net10.0` through `src/Directory.Build.props`.
- Follow `.editorconfig`: 4-space indentation for C#, file-scoped namespaces, braces required, `var` preferred, usings outside namespaces, and sorted system directives.
- Prefer clear domain names over abbreviations. Keep types small and responsibilities explicit.
- Avoid suppressing warnings unless compatibility or framework constraints make the warning unavoidable; explain the reason near the suppression.

## Repository Structure

- `src/apps/`: runnable app hosts and sample packages.
- `src/clients/`: client libraries.
- `src/common/`: shared infrastructure and testing support.
- `src/extensions/`: extension packages.
- `src/modules/`: Elsa modules and feature packages.
- `test/unit/`: unit tests.
- `test/integration/`: integration tests.
- `test/component/`: component tests.
- `test/performance/`: performance tests.
- `build/`: NUKE build project.
- `doc/`, `design/`, and `specs/`: documentation, design assets, and feature specifications.

## Testing Guidance

- Place tests near the relevant existing test project rather than creating a new project by default.
- Use the existing shared testing helpers under `src/common/Elsa.Testing.Shared*` when they fit the scenario.
- For regressions, add a failing test that demonstrates the bug before or alongside the fix.
- For multi-targeting issues, consider whether the test must run against all target frameworks or only the affected one.

## Dependency And Package Guidance

- Central package versions are managed in `Directory.Packages.props`; do not add ad hoc versions to individual project files unless the repository already uses that pattern for the package.
- Keep target framework changes centralized in `src/Directory.Build.props` unless a project has a specific reason to differ.
- Be cautious with package upgrades because this repository targets multiple frameworks and modules.

## Review Checklist

Before handing off changes, verify the following when applicable:

- The project or solution builds.
- Relevant unit or integration tests pass.
- Public API or behavior changes are documented.
- New code follows nullable annotations and existing style.
- No unrelated files were changed.
docs: add agent contributor guidance 2026-05-05 13:43:01 +00:00			`# AGENTS.md`

			`Guidance for AI coding agents working in this repository.`

			`## Project Overview`

			- Elsa Core is a .NET solution centered on `Elsa.sln`.
			- Production code lives under `src/`.
			- Tests live under `test/`, grouped by `unit`, `integration`, `component`, and `performance`.
			- Build automation is implemented with NUKE in `build/Build.cs` and exposed through `build.sh`, `build.ps1`, and `build.cmd`.

			`## Working Rules`

			`- Keep changes focused on the requested task. Do not mix unrelated cleanup, formatting, or dependency updates into functional changes.`
			`- Preserve existing public APIs unless the task explicitly requires an API change.`
			`- Update tests when behavior changes and add tests for new behavior where practical.`
			`- Update documentation when changing externally visible behavior, configuration, APIs, or developer workflows.`
			`- Do not delete generated-looking, artifact, or IDE files unless the task explicitly asks for cleanup.`
			`- If the worktree contains unrelated user changes, leave them untouched.`

docs: add agent operating principles to AGENTS.md and CLAUDE.md 2026-05-06 10:44:27 +00:00			`## Agent Operating Principles`

			`- Do not assume, hide confusion, or flatten uncertainty; surface questions, constraints, and tradeoffs explicitly.`
			`- Write the minimum code that solves the defined problem; do not add speculative abstractions, features, or cleanup.`
			`- Touch only the files and behavior required for the task; clean up only issues introduced by your own changes.`
			`- Define success criteria before implementation, then iterate until the criteria are verified or clearly state what could not be verified.`

docs: add agent contributor guidance 2026-05-05 13:43:01 +00:00			`## Build And Test Commands`

			- Build the default target: `./build.sh`
			- Run NUKE test target: `./build.sh Test`
			- Build with dotnet directly: `dotnet build Elsa.sln`
			- Run all tests directly: `dotnet test Elsa.sln`
			- Run a specific test project: `dotnet test test/unit/Elsa.Workflows.Core.UnitTests/Elsa.Workflows.Core.UnitTests.csproj`
			- Run ElsaScript DSL integration tests: `./run-dsl-tests.sh`

			Prefer targeted `dotnet test <project>` commands while iterating, then run a broader build or test command when the change affects shared infrastructure or cross-module behavior.

			`## Code Style`

			- C# uses `LangVersion` `latest`, nullable reference types, and implicit usings from `Directory.Build.props`.
			- Projects under `src/` target `net8.0`, `net9.0`, and `net10.0` through `src/Directory.Build.props`.
			- Follow `.editorconfig`: 4-space indentation for C#, file-scoped namespaces, braces required, `var` preferred, usings outside namespaces, and sorted system directives.
			`- Prefer clear domain names over abbreviations. Keep types small and responsibilities explicit.`
			`- Avoid suppressing warnings unless compatibility or framework constraints make the warning unavoidable; explain the reason near the suppression.`

			`## Repository Structure`

			- `src/apps/`: runnable app hosts and sample packages.
			- `src/clients/`: client libraries.
			- `src/common/`: shared infrastructure and testing support.
			- `src/extensions/`: extension packages.
			- `src/modules/`: Elsa modules and feature packages.
			- `test/unit/`: unit tests.
			- `test/integration/`: integration tests.
			- `test/component/`: component tests.
			- `test/performance/`: performance tests.
			- `build/`: NUKE build project.
			- `doc/`, `design/`, and `specs/`: documentation, design assets, and feature specifications.

			`## Testing Guidance`

			`- Place tests near the relevant existing test project rather than creating a new project by default.`
			- Use the existing shared testing helpers under `src/common/Elsa.Testing.Shared*` when they fit the scenario.
			`- For regressions, add a failing test that demonstrates the bug before or alongside the fix.`
			`- For multi-targeting issues, consider whether the test must run against all target frameworks or only the affected one.`

			`## Dependency And Package Guidance`

			- Central package versions are managed in `Directory.Packages.props`; do not add ad hoc versions to individual project files unless the repository already uses that pattern for the package.
			- Keep target framework changes centralized in `src/Directory.Build.props` unless a project has a specific reason to differ.
			`- Be cautious with package upgrades because this repository targets multiple frameworks and modules.`

			`## Review Checklist`

			`Before handing off changes, verify the following when applicable:`

			`- The project or solution builds.`
			`- Relevant unit or integration tests pass.`
			`- Public API or behavior changes are documented.`
			`- New code follows nullable annotations and existing style.`
			`- No unrelated files were changed.`