π«π· Version franΓ§aise
Contributing to Orkeon
First off, thank you for considering contributing to Orkeon! It's people like you that make Orkeon such a great tool.
Code of Conduct
This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
How Can I Contribute?
Reporting Bugs
Before creating bug reports, please check existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
- Use a clear and descriptive title
- Describe the exact steps which reproduce the problem
- Provide specific examples to demonstrate the steps
- Describe the behavior you observed after following the steps
- Explain which behavior you expected to see instead and why
- Include code samples and stack traces if applicable
Suggesting Enhancements
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
- Use a clear and descriptive title
- Provide a step-by-step description of the suggested enhancement
- Provide specific examples to demonstrate the steps
- Describe the current behavior and explain which behavior you expected to see instead
- Explain why this enhancement would be useful
Pull Requests
- Fork the repo and create your branch from
main - If you've added code that should be tested, add tests
- If you've changed APIs, update the documentation
- Ensure the test suite passes
- Make sure your code follows the existing code style
- Issue that pull request!
- On your first pull request, accept the Contributor License Agreement: a check posts the one sentence to reply with, and stays red until you do. Once per GitHub account; you keep your copyright, the project gets a licence it can carry to a successor entity. (The text is a template awaiting legal review β it says so on its first line β and the check documents the intended process meanwhile.)
Development Setup
# Clone your fork
git clone https://github.com/your-username/orkeon.git
cd orkeon
# Add upstream remote
git remote add upstream https://github.com/Orkeon/orkeon.git
# Install dependencies (once, and again only when a package reference changes)
dotnet restore Orkeon.sln
# Build (CI builds -c Release -warnaserror: the solution is kept at zero warnings)
dotnet build Orkeon.sln --no-restore
# Run tests (the set CI runs)
dotnet test Orkeon.sln --no-build --filter "Category!=Integration&Category!=Slow"
Why the filter, and not a bare
dotnet test Orkeon.sln:Category=Integrationcovers the Testcontainers tests, which need Docker and pull gigabytes of database images, andCategory=Slowthe long-running ones (the real ONNX models, the end-to-end runs).ci.ymlruns exactly the filtered command above, then the ONNX tests of the local-embeddings project in a step of their own, so a native-runtime failure names itself β any non-zero exit fails that step. Both categories run solution-wide in the nightlyintegration.yml; to run them locally (Docker required):dotnet test Orkeon.sln --no-build --filter "Category=Integration|Category=Slow" -- --ignore-exit-code 8β--ignore-exit-code 8because most modules hold no test of either category. The pack tests (TemplatesPackTests,LocalEmbeddingsModelOptOutTests) pack the lineup under a run version of their own (the product version with the prerelease identifiere2e-<8 hex>appended), fail a restore that resolves another version or SHA-512, and remove theirorkeon*/<run version>folders frompackageswhen they end; a folder a killed run left behind is removed once it is over 12 hours old.
To install what you built:
./scripts/install-from-source.sh(.\scripts\install-from-source.ps1on Windows, from PowerShell 7) puts theorkeonof your checkout on yourPATH, the way a release archive installs it, and names every missing prerequisite before it compiles anything β see Install from source. Run it again after agit pull.
First build touches the network once: the scripting layer bootstraps a small esbuild toolchain (
npm ciundertools/scripting-esbuild/, strictly from the committed lockfile). To skip it (CI, no-npm machines):dotnet build Orkeon.sln -p:SkipScriptingNpmInstall=trueβ the build still succeeds and esbuild is resolved fromPATHat runtime.
The tests run on Microsoft.Testing.Platform, opted in by
global.jsonβ the .NET 10 SDK refuses to run these projects through VSTest at all. Everyday commands are unchanged, but two things bite when you narrow a run: a--filterthat matches zero tests in a module is an error (exit 8), not an empty success, so a solution-wide run must never exclude a project by name; and VSTest-only flags (--collect,--logger,--blame) are rejected as unknown arguments.
Project Structure
The solution has 48 src projects across 14 zones and 34 test projects. Thirty-two
src projects are mirrored one-for-one by a test project; tests/e2e and tests/shared make
up the other two test projects. Sixteen src projects carry no test mirror by design: the five
Orkeon.Constants.* satellites and Orkeon.Rag.Onnx.Model hold constants and embedded
resources only, Orkeon.Analysis.Abstractions is exercised through Orkeon.Analysis.Tests,
and the nine src/packaging/ projects are packaging-only:
src/
βββ core/ # Orkeon.Domain, Orkeon.Application, Orkeon.Infrastructure (Clean Architecture core)
βββ tools/ # 11 tool packs: Abstractions, Analysis (RaggableTree), Code, Data, Drive,
β # Email, Embeddings.Local, EventHub, FileSystem, Rag, Web
βββ rag/ # RAG subsystem: Rag.Abstractions, Rag, Rag.Onnx, Rag.Onnx.Model
βββ analysis/ # RaggableTree engine: Analysis.Abstractions, Analysis
βββ scripting/ # Orkeon.Scripting (.ork.ts DSL) + Orkeon.Scripting.Cli (the `orkeon` tool)
βββ cli/ # Cli.Abstractions, Cli, Cli.Commands.Scripting, Cli.TerminalGui
βββ constants/ # Zero-dependency satellites of SHARED constants (ADR-009):
β # Constants.Llm, Constants.FileSystem, Constants.Configuration, Constants.Protocol, Constants.Cli
βββ hosting/ # Orkeon.Hosting (RunnerHost) + Orkeon.Host (the `orkeon-host` daemon)
β # + Orkeon.Hosting.Aspire (.NET Aspire AppHost integration, ADR-011)
βββ plugins/ # Orkeon.Plugins (runtime plugin loading)
βββ interop/ # Orkeon.Interop.AgentFramework (Microsoft Agent Framework bridge, ADR-010)
βββ generators/ # Orkeon.Generators (source generators)
βββ analyzers/ # Orkeon.Compliance.Vfs (VFS-only Roslyn analyzer)
βββ packaging/ # NuGet packaging projects: Orkeon (the framework in one nupkg), Orkeon.Tools,
β # Orkeon.Templates (`dotnet new` templates),
β # + the Rag.Onnx / Tools.Embeddings.Local / Interop.AgentFramework / Hosting.Aspire
β # / Scripting / Cli.TerminalGui wrappers depending on the Orkeon umbrella
βββ apps/ # Orkeon.ConsoleApp (orkeon-repl)
examples/ # 104 bundled examples (9 categories + showcases) β own solution
docs/ # Documentation, EN + docs/fr mirror (CI parity gate)
The full annotated tree lives in docs/getting-started/overview.md.
Coding Standards
C# Style Guide
- Use PascalCase for public members
- Use camelCase for private fields
- Prefix interfaces with 'I'
- Use meaningful variable names
- Keep methods small and focused
- Use async/await for asynchronous operations
Example:
public interface IAgentService
{
Task<Agent> CreateAgentAsync(string role, string goal);
}
public class AgentService : IAgentService
{
private readonly ILogger<AgentService> _logger;
public async Task<Agent> CreateAgentAsync(string role, string goal)
{
// Implementation
}
}
Rules the build enforces
- No direct
System.IOin framework code. Files and directories go throughIFileSystemServiceand virtual paths (/workspace/...,/output/...); theOrkeon.Compliance.Vfsanalyzer fails the build otherwise. The allowed exceptions (the VFS implementation itself, bootstrap code marked// EXCEPTION-BOOTSTRAP, system probing marked// OUT-OF-SCOPE, tests) are listed in VFS compliance. Orkeon.Domain.TaskshadowsSystem.Threading.Tasks.Task. In a file that imports both namespaces, writeSystem.Threading.Tasks.Taskin full.- A new public API is declared, see Versioning and API stability.
Comments are English, and never accented
An invariant, enforced by scripts/check-comment-accents.py in CI: every comment is in
English and carries no accented letter. A client's interface may be in French, so the trap is a
comment quoting a UI label β translate the label, do not strip its accents: a comment
citing "Modele d'IA" names something the product never displays. Name the role instead
(the model-settings tab). An accent-stripped French sentence is still French, only worse.
Only comment lines are in scope. User-facing strings keep their accents. So does typography the repository uses everywhere β em dashes, ellipses, arrows, guillemets: none of those are accented letters.
Documentation
- Add XML documentation to all public APIs
- Include examples in documentation where helpful
- Update README.md if adding new features
Bilingual documentation (required)
The documentation is maintained in English and French in parallel. Any PR that adds, renames,
or removes a file under docs/**.md (outside docs/fr/) must make the matching change to
its French mirror under docs/fr/, and any change to a root community file (README.md,
CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, and the site landing
page index.md) must update its *.fr.md mirror.
The scripts/check-docs-parity.sh script verifies this: it fails when a mirror is missing β
run it locally before opening the PR. This is a CI gate: ci.yml runs the script on
every push and pull request, so a missing mirror fails the build. The script checks file existence, not content
equivalence β keeping the two in sync is on you; if you cannot translate immediately, add a
stub mirror and flag it for translation.
Dated audit snapshots (e.g. GO/NO-GO publication reports) are governance records, not
living documentation: they live in the maintainers' private governance repository, outside
docs/, so the parity contract applies to the whole documentation tree without exception.
Adding a setting
A setting is written once, in the code that reads it. The settings catalogue, the tables of
docs/reference/configuration.md, orkeon settings and the sample file of an installation are
produced from it, and the tests fail until they are:
The property and its comment. Add the property to the options type its section is read into, with its default and an XML
<summary>: that sentence is the key's meaning everywhere it is listed. A new section is declared where it is registered (AddOrkeonSettings<T>(path),DeclareSettings).Its category. A new section gets a line in
SettingsCategories(src/constants/Orkeon.Constants.Configuration), and its heading with its two markers (<!-- settings:Its:Path -->β¦<!-- /settings -->) in the reference page and its French mirror.The French sentence. Add the key, by its path, to
docs/fr/reference/configuration.settings.json: the French table takes its meaning there.Regenerate, in this order β each step writes what the next one reads:
export UPDATE_PRODUCED_FILES=1 # 1. the catalogue: the library's file first, then the file of each binary dotnet test tests/hosting/Orkeon.Hosting.Tests --filter "FullyQualifiedName~SettingsCatalogFile" dotnet test tests/scripting/Orkeon.Scripting.Cli.Tests --filter "FullyQualifiedName~SettingsCatalogFile" dotnet test tests/hosting/Orkeon.Host.Tests --filter "FullyQualifiedName~SettingsCatalogFile" dotnet test tests/apps/Orkeon.ConsoleApp.Tests --filter "FullyQualifiedName~SettingsCatalogFile" # 2. build again: the catalogue is embedded in Orkeon.Hosting dotnet build Orkeon.sln --no-restore # 3. the tables of the reference page (EN, FR), then the sample file of an installation dotnet test tests/hosting/Orkeon.Hosting.Tests --no-build --filter "FullyQualifiedName~SettingsReferencePage" dotnet test tests/hosting/Orkeon.Hosting.Tests --no-build --filter "FullyQualifiedName~SettingsSampleFile" unset UPDATE_PRODUCED_FILES
The same tests then hold everything else to the new key: a settings file under examples/, a
json block of the documentation or a default quoted beside a key that the code no longer agrees
with fails the suite, naming the file and the key. A block that shows on purpose what a host
refuses carries <!-- settings-check:off --> on the line above its fence.
Testing
- Write unit tests for new functionality
- Maintain or improve code coverage
- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)
- Use xUnit and its native assertions only β no mocking framework (Moq, NSubstitute, FakeItEasy) and no fluent assertion library (FluentAssertions, Shouldly)
- Keep a test true under load, when several passes run at once: a test server takes its port
through
LoopbackPorts(Orkeon.Tests.Shared.Network), which starts again on another port when the probed one was taken, and listens onLoopbackPorts.Host(127.0.0.1); anHttpListeneris never closed withClose()afterStop(); a span test reads anActivityRecorder(Orkeon.Tests.Shared.Telemetry), filtered on the trace of a root it starts or on a tag only it carries; a delay the test must not reach is a hang guard (Polling.DefaultTimeout), and no unit test bounds a duration β a timestamp is checked between two readings of the clock, and two concurrent ends come in the order a rendezvous forces - A build copies the native libraries (Tree-sitter grammars, ONNX Runtime) of the machine's own
runtime only, through
OrkeonTrimForeignRuntimesin the rootDirectory.Build.targets: a test output weighs ~150 MB instead of ~1 GB, and a built worktree a few GB instead of 26. Abinthat must run on another machine is built with-p:OrkeonAllRuntimes=true - A test that awaits a script engine waits under
HangGuards.EnginePromise(Orkeon.Tests.Shared.Timing), never under Jint's implicit 10 seconds β see the threading model ofdocs/architecture/scripting.md - An integration test that starts a real program of the machine (a headless Firefox) gives it
HangGuards.ProcessStartto start, never the product's own start-up default: a cold start on a loaded runner outlasts it (#379)
[Fact]
public void ShouldTransitionFromIdleToBusy_WhenStartingTask()
{
// Arrange
var agent = new AgentBuilder().Role("Researcher").Goal("Find information").Build();
var taskId = TaskId.Create();
agent.AssignTask(taskId);
// Act
agent.StartTask(taskId);
// Assert
Assert.Equal(AgentStatus.Busy, agent.Status);
Assert.Equal(taskId, agent.CurrentTask);
}
Test doubles are hand-written, by design: a plain class named after the interface it
replaces, prefixed Mock, Fake or Stub (MockTaskRepository implements
ITaskRepository), placed in a Doubles/ (or Fakes/) folder of the consuming test
project, exposing plain fields or properties to configure answers and inspect calls.
tests/core/Orkeon.Infrastructure.Tests/Doubles/MockTaskRepository.cs is the reference.
Scripts and commits
- A
.shscript, or any script with a shebang line meant to be run directly, is committed executable (mode100755):git update-index --chmod=+x path/to/script.sh. Thefile-modes.ymlgate reads the mode from the git index β the only one a macOS/Linux clone restores β so a working tree on an NTFS mount that shows every file as executable proves nothing. - A package change also changes the NuGet lock files:
dotnet restorerewrites thepackages.lock.jsonof the projects it touches (CI restores in locked mode and fails on a stale one) β commit them with the change. - A package change β a version in
Directory.Packages.props, a package added to or removed from a project the tools, the installers or the container images ship β changes what those binaries redistribute: after the restore, runpython3 scripts/third-party-notices.pyand commitTHIRD-PARTY-NOTICES.mdwith it. CI's--checkfails until the inventory there lists the new closure, until a version a hand-written section of that file states is the shipped one, and until every shipped package resolves at least to the versionDirectory.Packages.propspins. A pin holds for direct references only: a package an application gets transitively, below its pin, needs a direct reference in a project that application builds on (Orkeon.Cli.TerminalGuiholds the onesTerminal.Guibrings to the terminal UIs). - A Dockerfile that publishes an application copies
LICENSE.mdandTHIRD-PARTY-NOTICES.mdinto the image it produces, under/usr/share/doc/orkeon/, and.dockerignorekeeps both in the build context:--checkfails otherwise. The installers copy the notices of the .NET runtime they bundle at packaging time (scripts/third-party-notices.py --runtime-notices, whichscripts/package-installers.shand its.ps1mirror call, so both need Python 3). Every release smoke then checks, on the payload it installed, that the license, the notices and thelicenses/<pack>/of each bundled runtime arrived (smoke_assert_noticesand its PowerShell twinInvoke-OrkeonNoticesAssertions, underscripts/smoke-onboarding/lib/): a packaging script, an installer or a WiX file that stops copying one fails the release. - Commit messages are in English and follow the history's
type(scope): summaryshape (feat,fix,docs,test,choreβ¦).
Areas for Contribution
The scope is frozen
Orkeon already ships 16 LLM providers (fourteen vendors and two aggregators), built-in tools, 6 memory stores, two RAG pipelines, RaggableTree, a scripting DSL, plugins, MCP and A2A β maintained by one person. Until real users ask for more, the functional surface does not grow:
- no 17th LLM provider β the OpenAI-compatible base covers any endpoint that
speaks that dialect; point
Orkeon:Llm:BaseUrlat it. The two aggregators (OpenRouter, Mammouth AI) are the first motivated exception, decided by the owner on 2026-09-18: an aggregator declares capabilities of its own, writes fields the base does not read (reasoning,usage.cost), and has to be recognised by the tooling β none of which aBaseUrlgives. The rule stands for everything else; - no new built-in tool β write yours in a
.ork.tsscript or a plugin, both are first-class and need no change here. The e-mail family (Orkeon.Tools.Email, thirteen tools) is the second motivated exception, decided by the owner on 2026-09-26: an.ork.tsscript cannot open a socket, and a plugin would not put e-mail in Orkeon itself, which is what was asked (ADR-012). The drive family (Orkeon.Tools.Drive, eleven tools for Google Drive and OneDrive) is the third, decided by the owner on 2026-10-17, for the same reason (ADR-013). The rule stands for everything else; - no new memory store, language adapter, or orchestration mode.
A pull request adding one of these will be closed with a link to this section, whatever its quality. What is welcome is everything that lowers the cost of trying Orkeon or of trusting it: bugs, tests, documentation, interoperability with what people already use (Microsoft Agent Framework, OpenTelemetry, .NET Aspire), and performance.
High Priority
- [ ] Bugs found by running the examples against a local model
- [ ] MCP interop testing against reference servers (MCP Inspector)
- [ ] Performance optimizations
- [ ] Documentation improvements (see the EN/FR parity contract above)
Good First Issues
- [ ] Add more examples (follow the example README template)
- [ ] Improve error messages
- [ ] Add XML documentation
- [ ] Fix typos in documentation
Versioning and API stability
The policy for consumers is in docs/reference/stability.md.
Orkeon follows Semantic Versioning 2.0. The public API is not a matter of opinion β it is recorded in the repository and enforced at build time:
- Every packable project carries
PublicAPI.Shipped.txt(the frozen, released surface) andPublicAPI.Unshipped.txt(additions since the last release), checked byMicrosoft.CodeAnalysis.PublicApiAnalyzers. An undeclared public API change fails the build (RS0016/RS0017are promoted to errors). - Adding a public API: declare it in
PublicAPI.Unshipped.txt(the analyzer's code fix does it for you βdotnet format analyzers --diagnostics RS0016on the project). At release time,Unshippedentries move toShipped. - A breaking change is any edit or removal of a line in
PublicAPI.Shipped.txt. It requires a major version bump, a*REMOVED*entry in the API file, and a CHANGELOG entry that says so plainly. One exception: a line whose signature carries a type of Jint, TreeSitter.DotNet or Terminal.Gui follows that library's major version and may change in a minor release that moves to a new major of it, with a CHANGELOG migration note (third-party clause). Keep such types off the public surface: plumbing that needs one isinternal. - Deprecation window: nothing public is removed without shipping
[Obsolete]for at least one minor version first, with the replacement named in the message; the removal itself lands in a major version, with a*REMOVED*line in the API file and a**[breaking]**CHANGELOG entry with a migration note. [Experimental]surfaces are outside this commitment. A2A, Autonomous orchestration, corrective RAG, the MCP integration, per-model capabilities, host HTTP security and the run history ports carry[Experimental("ORKEXP00x")]diagnostics: referencing them is a compile error you suppress explicitly, which is your opt-in to a surface that may change in any release. See docs/reference/experimental-apis.md.- Stability commitment for the 1.x line: no breaking change to a non-experimental shipped API before 2.0, the third-party clause aside. The full policy is in docs/reference/stability.md.
Release Process
- Bump
VersionPrefix/VersionSuffixinsrc/Directory.Build.propsβ the single source of truth. The publish workflow refuses av*tag that does not match it. - Cut the
[Unreleased]section ofCHANGELOG.mdinto a dated version section. - Move
PublicAPI.Unshipped.txtentries toPublicAPI.Shipped.txt. - Move the analyzer rules the same way: any entry pending in
src/analyzers/Orkeon.Compliance.Vfs/AnalyzerReleases.Unshipped.md(theORKVFS00xVFS-compliance rules) goes intoAnalyzerReleases.Shipped.mdunder a## Release <version>heading, leaving theUnshippedfile with its header only. The release-tracking analyzer parses that heading as a plainMajor.Minor.Patchnumber and rejects a prerelease suffix (RS2007): a release candidate adds nothing there, its rules go under the heading of the final version (## Release <X.Y.Z>for the<X.Y.Z>line). - Make sure CI is green on the commit you tag. Beyond the
-warnaserrorbuild and the test suites, the gates that must pass arescripts/check-docs-parity.sh,scripts/check-doc-claims.py(it also compares the hand-written copies of the NuGet lineup and runs the source half ofscripts/check-package-closure.py; its file enumeration is tested byscripts/test-check-doc-claims.py),scripts/check-comment-accents.py, the third-party notices gate (scripts/third-party-notices.py --check, its rules tested byscripts/test-third-party-notices.py), the scripting typings check (scripts/check-scripting-typings.sh), the dev-channel prune test (scripts/test-prune-dev-packages.sh), the test of the release smokes' notices check (scripts/test-smoke-notices.shand its.ps1twin), the examples gates (scripts/generate-examples-index.sh --check,scripts/lint-example-configs.py,scripts/lint-example-readmes.py,scripts/test-examples-catalog.py, the examples solution built with-warnaserror,scripts/validate-all-examples.sh), the executable-bit gate (file-modes.yml), the secret scan (secret-scan.yml), CodeQL, the dependency review and the strict docfx build β plusrag-eval.ymlandquickstart.ymlwhen their paths changed. - Run
python3 scripts/check-release-readiness.py.publish.ymlruns it on the tag and refuses a release whoseCHANGELOG.md[Unreleased]section is not empty or whosePublicAPI.Unshipped.txtfiles are not header-only; after packing, it also runsscripts/check-package-closure.pyagainst the nupkgs themselves. - Tag
v<version>and push the tag. This triggers:publish.yml(packs everything; pushes the fourteen-package v1 lineup to NuGet.org βOrkeon,Orkeon.Tools,Orkeon.Rag.Onnx,Orkeon.Rag.Onnx.Model,Orkeon.Tools.Embeddings.Local,Orkeon.Constants.Cli,Orkeon.Scripting,Orkeon.Scripting.Cli,Orkeon.Compliance.Vfs,Orkeon.Interop.AgentFramework,Orkeon.Hosting.Aspire,Orkeon.Cli.Abstractions,Orkeon.Cli.TerminalGui,Orkeon.Templates, the umbrella first because the others depend on it, through Trusted Publishing β and every packable to GitHub Packages, the packages and a CycloneDX SBOM covered by a build-provenance attestation; see the publication matrix),release.yml(the per-platform CLI packages and multi-app archives for every RID, the Windows per-user MSI and theorkeon-hostservice MSI, the macOS tarballs, the Debian package, the SBOM and theSHA256SUMS/SHA256SUMS.msichecksum files β each smoked on a real runner, then attested, before the Release is published β plus theghcr.io/orkeon/orkeoncontainer image pushed to GHCR) anddocs.yml(deploys the documentation site to GitHub Pages, at https://orkeon.github.io/orkeon/). Once the Release is published,release-verify.ymlre-runs the install smokes against the assets as downloaded from the Release page.
Between two tags, every push to main whose CI is green is also packed as
<X.Y.Z>-<pre>.dev.<run number> and pushed to GitHub Packages only β never NuGet.org β with
no attestation or SBOM; older dev builds are pruned.
Questions?
Feel free to open an issue, or start a thread in GitHub Discussions.
License
By contributing, you agree that your contributions will be licensed under the MIT License.