Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (84 loc) · 9.28 KB

AGENTS.md

File metadata and controls

108 lines (84 loc) · 9.28 KB

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.

For additional context about technologies to be used, project structure, shell commands, and other important information, read specs/008-weaver-ai-copilot/plan.md.

Active Technologies

  • C# latest, nullable reference types enabled, implicit usings enabled. + Microsoft.Extensions.Logging, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, existing Elsa identity/authorization features. (003-live-server-logs)
  • Bounded in-memory ring buffer for MVP; no EF Core schema changes. Provider abstraction allows external/shared log backends later. (003-live-server-logs)
  • C# latest, nullable reference types enabled, implicit usings enabled. + Microsoft.Extensions.Logging, Microsoft.Extensions.Options, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, CShells shell feature infrastructure. (004-diagnostics-structured-logs)
  • Existing bounded in-memory ring buffer; no EF Core schema changes. Provider abstraction remains available for future shared backends. (004-diagnostics-structured-logs)
  • C# latest, nullable reference types enabled, implicit usings enabled. + Existing Elsa.Diagnostics.StructuredLogs, Microsoft.Extensions.Logging, Microsoft.Extensions.Options, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, FluentMigrator runner packages, SQLite ADO.NET provider, and optionally Dapper for relational operations. (005-structured-log-persistence)
  • Bounded in-memory store by default; opt-in SQLite durable store through shared relational persistence. SQLite stores Timestamp and ReceivedAt as UTC ISO-8601 text and stores exception, scope, and property payloads as JSON text. (005-structured-log-persistence)
  • C# latest, nullable reference types enabled, implicit usings enabled. + Microsoft.Extensions.Options, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, Elsa shell feature infrastructure, and existing Elsa identity/authorization patterns. (006-diagnostics-console-logs)
  • Bounded in-memory recent buffer and bounded subscriber queues by default; no durable database schema. Providers receive redacted content only. (006-diagnostics-console-logs)
  • C# latest, nullable reference types enabled, implicit usings enabled. + Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, existing Elsa identity/authorization patterns, Elsa workflow input metadata, Microsoft.Extensions.Configuration, Microsoft.AspNetCore.DataProtection, EF Core persistence infrastructure, mediator notifications, and optional JavaScript expression integration. (007-secrets-module)
  • In-memory store for tests/development; Elsa-managed encrypted store with EF Core persistence for production; configuration-backed read-only store for deployment-managed values. No cloud vault or OS certificate store provider in v1. (007-secrets-module)
  • C# latest, nullable reference types enabled, implicit usings enabled; paired Studio Blazor/Razor module work in the Studio repository. + Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, existing identity/authorization and tenancy services, workflow definition/instance abstractions, diagnostics/log abstractions, Microsoft.Extensions.Options, Microsoft.Extensions.Logging, OpenTelemetry, System.Text.Json, SignalR or SSE streaming, GitHub Copilot SDK isolated behind Elsa.AI.Copilot, and headless Copilot CLI JSON-RPC integration. (008-weaver-ai-copilot)
  • Configurable conversation/session retention with in-memory support for development and tests; durable proposal and audit stores required for MVP using Elsa persistence provider abstractions and an EF Core provider package for production. (008-weaver-ai-copilot)

Recent Changes

  • 008-weaver-ai-copilot: Captures Weaver as a server-hosted, provider-isolated AI copilot platform with Studio chat, governed tools, proposal-only workflow mutations, audit, and extensibility.
  • 006-diagnostics-console-logs: Plans raw stdout/stderr console capture with redaction-before-provider boundaries, bounded in-memory recent/live buffers, REST backfill/source endpoints, and a SignalR live hub.
  • 005-structured-log-persistence: Plans pluggable structured log storage with in-memory default and opt-in SQLite persistence using FluentMigrator.
  • 004-diagnostics-structured-logs: Refactors the unpublished server logs module into diagnostics structured logs and preserves bounded structured ILogger capture.
  • 003-live-server-logs: Added C# latest, nullable reference types enabled, implicit usings enabled. + Microsoft.Extensions.Logging, Microsoft.AspNetCore.SignalR, Elsa feature/module infrastructure, FastEndpoints through Elsa API endpoint patterns, existing Elsa identity/authorization features.