π«π· Version franΓ§aise
See also: ProcessTypes guide Β· Back to index
Blueprint β Adding an orchestration type to Orkeon
This document is a reproducible checklist for adding a seventh ProcessType to the framework and documenting it. It follows the path the six existing modes took β the Graph mode (a Domain engine + a YAML block) and the Autonomous mode (a dedicated IProcessStrategy entry point) are the two reference precedents β and covers the 8 steps from the Domain value object to the documentation.
A missed registration fails loudly rather than silently: ProcessType.From, the YAML parser and the scripting adapter refuse an unknown name, and both ProcessStrategyFactory and SequentialCrewOrchestrator throw NotSupportedException for a mode they do not route.
Prerequisites
Before starting, decide:
- Mode name: the
ProcessTypevalue (PascalCase, e.g.Swarm) and its YAML/scripting spelling (swarm: the YAML is matched case-insensitively, the scripting builderprocess()accepts the lowercase name only) - Entry point: reuse
IProcessStrategy.ExecuteSequentialAsync(crew, inputVariables, ct)(Graph, Consensual) or add a dedicated method (Autonomous, which needs anAgentExecutionBudget) - Configuration: none, a .NET options section (Consensual:
Orkeon:Consensus), or a crew-level YAML block (Graph:graph:) - Engine: whether the mode needs a reusable Domain engine (
StateGraph<TState>,StateMachine<TState, TEvent>) or lives entirely in its strategy - Stability: whether the public surface ships under an
[Experimental]diagnostic (Autonomous:ORKEXP002, see experimental APIs)
Step 1 β Domain: declare the mode
File: src/core/Orkeon.Domain/SharedKernel/ValueObjects/ProcessType.cs
/// <summary>Agents swarm over the task pool under a shared budget.</summary>
public static readonly ProcessType Swarm = new("Swarm");
private static readonly Dictionary<string, ProcessType> s_all = new(StringComparer.OrdinalIgnoreCase)
{ /* β¦ the six existing entries β¦, */ [nameof(Swarm)] = Swarm };
ProcessType.All, From and TryFrom read s_all: once the entry is there, YAML (YamlCrewMapper.ParseProcessType) and the scripting adapter (JsCrewConfigurationAdapter) accept the new value without further change, and their error messages list it.
Per-mode predicates. Decide the mode's answer to each of these, because they fall back to a default for a mode they do not list: ProcessType.AcceptsManagerAgent (Hierarchical and Consensual) and AcceptsManagerLlm (Hierarchical and Autonomous), which gate the manager a crew may declare; CrewPlanner.HonoursTaskAgent, HowTheCrewRuns and AgentTheModeChooses (src/core/Orkeon.Domain/Crew/CrewPlanner.cs), whose _ branch describes a sequential run; DecisionTaskRules.Check (src/core/Orkeon.Domain/Task/DecisionTaskRules.cs), which supports decision tasks and when conditions in Sequential, Parallel and Graph only; and the budget, which Crew.cs and CrewDefinitionValidator accept for Autonomous only.
Entry point. When the mode needs its own entry point, add it to IProcessStrategy (src/core/Orkeon.Domain/Crew/IProcessStrategy.cs), as ExecuteAutonomousAsync was added; every existing strategy then implements it by throwing NotSupportedException("Use <Mode>ProcessStrategy β¦").
Public API. The core projects track their public surface: add each new public member to the project's PublicAPI.Unshipped.txt (src/core/Orkeon.Domain/, src/core/Orkeon.Infrastructure/, src/core/Orkeon.Application/), or the build fails (RS0016/RS0017 are errors).
Application DTO. Nothing to add: CrewDto.ProcessType is a string, and the handlers (GetCrewHandler, CreateCrewHandler) copy the ProcessType.Value of the Domain value object, so the new name reaches the DTO as soon as step 1 is done.
Fluent Builder (optional). CrewBuilder.Process(ProcessType.Swarm) works as is; a shortcut such as .Swarm() exists only for the historical modes (Sequential(), Hierarchical(...), Parallel(), Consensual()).
Step 2 β Domain: configuration and engine (when needed)
Configuration DTO
File: src/core/Orkeon.Domain/Configuration/<Mode>Config.cs β an immutable sealed record with defaults, nullable where a value overrides a preset (GraphConfig is the model: CircuitBreakerPreset = "strict", nullable limits).
Carry it to execution time:
| Where | What to add | Graph precedent |
|---|---|---|
Configuration/CrewConfiguration.cs |
public <Mode>Config? <Mode>Config { get; init; } on CrewConfiguration (and on TaskConfiguration, same file, for a task-level block) |
CrewConfiguration.GraphConfig |
Crew/CrewCreateOptions.cs |
The same property | CrewCreateOptions.GraphConfig |
Crew/Crew.cs |
A read-only property set from the options in Crew.Create |
Crew.GraphConfig |
Crew/CrewBuilder.cs |
With<Mode>Config(...) feeding the options |
WithGraphConfig(...) |
The strategy must read the config off the crew argument at execution time, never store it on the (scoped, shared) strategy instance β concurrent crews would overwrite each other's settings.
Engine
A reusable engine goes in the Domain layer, without any external dependency (Orkeon.Domain.Graph for StateGraph<TState>, Orkeon.Domain.Common.StateMachine for the FSM). What the existing engines provide, and a new one should too:
- a termination guarantee β circuit breaker (
CircuitBreakerPolicy, presetsStrict/Default/Permissive) or budget (AgentExecutionBudget, same three presets); - observability events (
OnNodeCompleted/OnTransition,OnCircuitBroken) and a status snapshot; - cooperative cancellation (
CancellationTokenon every async member); - thread safety where the engine is shared (
lock,Interlocked); [assembly: InternalsVisibleTo]only for types the tests must reach.
Step 3 β Infrastructure: the strategy
File: src/core/Orkeon.Infrastructure/Crew/Strategies/<Mode>ProcessStrategy.cs
public sealed partial class SwarmProcessStrategy : IProcessStrategy
{
public SwarmProcessStrategy(
CrewStrategyDependencies dependencies, // tasks, agents, execution service, memory scope (+ optional domain events)
ILogger<SwarmProcessStrategy> logger,
ICrewExecutionHook? hook = null, // optional: the run's observer
TaskAgentSelector? agentSelector = null) // optional: who runs a task without agent:
{ /* β¦ */ }
public Task<CrewOutput> ExecuteSequentialAsync(Crew crew,
IReadOnlyDictionary<string, string>? inputVariables = null, CancellationToken cancellationToken = default)
{ /* the mode */ }
// The entry points the mode does not serve:
public Task<CrewOutput> ExecuteHierarchicalAsync(/* β¦ */)
=> throw new NotSupportedException("Use HierarchicalProcessStrategy for hierarchical orchestration.");
// β¦ ExecuteParallelAsync, ExecuteAutonomousAsync likewise
}
Reuse the shared building blocks of Crew/Strategies/ and Crew/ β several are internal, which is why strategies live in Orkeon.Infrastructure:
| Building block | Use |
|---|---|
CrewStrategyDependencies |
The four collaborators every strategy takes (task/agent repositories, IAgentExecutionService, IMemoryScope), plus an optional fifth, DomainEvents (IDomainEventDispatcher?) |
CrewTaskSequencer.ResolveAsync |
Task order: the plan's, else the stable topological sort on dependencies |
TaskAgentSelector |
Agent choice: declared agent:, else OrkeonApplicationOptions.AgentSelectionStrategy |
CrewHookDispatcher |
ICrewExecutionHook calls β send the terminal event (CrewCompletedAsync / CrewFailedAsync) on every exit, setup and cancellation included |
TokenUsageTally |
Token telemetry into the CrewOutput metadata (never a fabricated zero) |
AgentDelegationToolsProvider |
Delegation tools for agents with allowDelegation: true (Sequential, Graph) |
LlmUsageScope.Begin(...) |
Meter extra LLM calls the mode makes itself (a manager, a judge) under the right operation |
Report the outcome honestly: CrewOutput.CreateFailure(...) when the mode's own contract failed (the runner exits non-zero on it), with the outputs and the token usage produced so far.
Step 4 β Infrastructure: registration and routing
Three places, all in Orkeon.Infrastructure:
| File | Change |
|---|---|
DependencyInjection/InfrastructureExtensions.cs |
services.AddScoped<SwarmProcessStrategy>(); in AddOrkeonRepositoriesAndStrategies β or a public AddOrkeon<Mode>() extension (options binding, voting strategiesβ¦) called from AddOrkeonFeatureModules, like AddOrkeonConsensus() |
Crew/Strategies/ProcessStrategyFactory.cs |
"Swarm" => _serviceProvider.GetRequiredService<SwarmProcessStrategy>(), |
Orchestration/SequentialCrewOrchestrator.cs |
A case in ExecuteDomainStrategyAsync calling the chosen entry point ("Swarm" => await processStrategy.ExecuteSequentialAsync(crew, stringVariables, cancellationToken)β¦) |
An options section follows the Orkeon:* convention (services.AddOptions<SwarmOptions>().BindConfiguration("Orkeon:Swarm")) and is listed in configuration.
Step 5 β YAML: the configuration block
process: swarm needs nothing more (step 1). A crew-level block follows the graph: path; a task-level block follows the task deliverable: path β mapped in MapTasks, then applied to the task by CrewFactory: a block read and never applied is a bug, and a crew that writes a key no model carries is refused at load (CrewYamlKeyCheck), so the model of this step must exist before the block is written.
Models β src/core/Orkeon.Infrastructure/Configuration/Yaml/YamlConfigModels.cs. The models carry no [YamlMember] attributes: keys resolve by convention (camelCase, with a snake_case fallback). Add a public class and the property on the models that need it:
public class SwarmYamlConfig
{
public int? MaxAgents { get; set; } // maxAgents: or max_agents:
}
// On CrewYamlConfig (single-file crew) AND CrewSettingsYamlConfig (multi-file crew.yaml):
public SwarmYamlConfig? SwarmConfig { get; set; } // key: swarmConfig
// On TaskYamlConfig for a task-level block.
Mapping β Configuration/Yaml/YamlCrewMapper.cs: a private Map<Mode>Config(...) returning the Domain DTO (or null), a property on CrewMappingSettings, and the assignment in BuildConfiguration (crew level) or MapTasks (task level).
Loader β Configuration/YamlCrewDefinitionLoader.cs fills CrewMappingSettings in both paths: from CrewSettingsYamlConfig (multi-file) and from CrewYamlConfig (single-file). Forgetting one path makes the block work in one layout only.
Factory β Configuration/CrewFactory.cs: if (config.SwarmConfig is not null) builder.WithSwarmConfig(config.SwarmConfig);, next to WithGraphConfig.
Validation β load-time rules (a value out of range, a combination the mode refuses) go in Configuration/Yaml/CrewDefinitionValidator.cs, so a wrong file fails at load, not mid-run.
Step 6 β Scripting DSL
| File | Change |
|---|---|
src/scripting/Orkeon.Scripting/Builders/JsCrewBuilder.cs |
Add the name to AllowedProcesses (the builder refuses any other) |
src/scripting/Orkeon.Scripting/Typings/crew.d.ts |
Add it to the Process union |
src/scripting/Orkeon.Scripting/Adapters/JsCrewConfigurationAdapter.cs |
Nothing for the name (ProcessType.TryFrom); map the mode's config when the DSL exposes it, or list it in CollectIgnoredFeatures |
src/scripting/Orkeon.Scripting.Cli/Commands/UseCases/UseCasesCommand.cs |
The --process help text of orkeon usecases list |
The procedural script shape (await crew.run()) ignores the process; only the declarative shape (globalThis.crew = crew) runs the strategy β see Scripting.
Step 7 β Tests
xUnit with native assertions and hand-written doubles (Mock* / Fake* / Stub* in a Doubles/ folder β no mocking library).
| Test | Where | Precedent |
|---|---|---|
The value object (count of All β pinned at 6 today β, From, TryFrom, case-insensitivity) |
tests/core/Orkeon.Domain.Tests/ValueObjects/ProcessTypeTests.cs |
β |
| The engine, if any | tests/core/Orkeon.Domain.Tests/<Area>/ |
Graph/StateGraphTests.cs, Common/StateMachine/* |
| The strategy: happy path, empty crew, failures, cancellation, hook terminal event on every exit, token metadata, unsupported entry points | tests/core/Orkeon.Infrastructure.Tests/Strategies/<Mode>ProcessStrategy/ |
GraphProcessStrategy/GraphProcessStrategyTests.cs |
| Factory routing | Strategies/ProcessStrategyFactory/ProcessStrategyFactoryTests.cs |
β |
| Orchestrator dispatch to the right entry point | Orchestration/CovAutonomous_SequentialCrewOrchestratorTests.cs |
KickoffAsync_Graph_DispatchesViaSequential |
YAML: process: parsing and the config block in both layouts |
Configuration/YamlCrewDefinition/YamlCrewDefinitionTests.cs (iterates ProcessType.All), Configuration/CircuitBreakerPolicyFactoryGraphTests.cs |
β |
| Scripting | tests/scripting/Orkeon.Scripting.Tests/ (builder accepts the name, adapter maps it) |
β |
dotnet test tests/core/Orkeon.Domain.Tests/Orkeon.Domain.Tests.csproj --filter "FullyQualifiedName~ProcessType"
dotnet test tests/core/Orkeon.Infrastructure.Tests/Orkeon.Infrastructure.Tests.csproj --filter "FullyQualifiedName~Swarm"
The test runner is Microsoft.Testing.Platform: a --filter that matches no test in a project is an error, so filter each project on names it contains.
Step 8 β Example and documentation
Example
Folder: examples/<NN-category>/<NNN-name>/ with a config.yaml (or a main.ork.ts) and a README.md (goal, diagram, annotated YAML, how to run). Start from 102-graph-orchestration. The YAML root is flat β no crew: wrapper β and agents: / tasks: are mappings keyed by id:
name: "swarm-demo"
goal: "β¦"
process: swarm
swarmConfig: # refused at load until SwarmYamlConfig carries it
maxAgents: 5
agents:
scout: # mapping keyed by agent id β never a sequence
role: "β¦"
goal: "β¦"
tasks:
explore: # the id IS the key (TaskYamlConfig has no id: field)
description: "β¦"
expectedOutput: "β¦"
A new numbered example changes the example count that the docs state and scripts/check-doc-claims.py verifies; list it in examples/INDEX.md.
Documentation
| Page | Change |
|---|---|
docs/orchestration/<mode>.md (new) |
Overview, architecture (classes per layer), execution flow, configuration and resolution, termination guarantees, observability, YAML and C# usage, example, tests β the Graph and Autonomous pages are the models |
docs/orchestration/process-types.md |
The value list, the architecture diagram, the matrix column, a dedicated section, the decision tree, the cost table |
docs/architecture/yaml-schema.md |
The process: values and the new block |
docs/reference/configuration.md |
A new options section, if any |
docs/INDEX.md, docs/toc.yml |
The new page |
CHANGELOG.md, CLAUDE.md |
The feature, and every "6 modes" statement |
Every page has its French mirror under docs/fr/ (same path), updated in the same change β a CI gate checks the parity. Placeholders in prose go inside code spans (<Mode>), never bare. Then run:
python3 scripts/check-doc-claims.py
Final checklist
| Criterion | Expected | Verified |
|---|---|---|
| Declared | ProcessType entry, All count |
[ ] |
| Mode-aware | AcceptsManagerAgent, AcceptsManagerLlm, CrewPlanner helpers, DecisionTaskRules.Check, budget rule decided for the new mode |
[ ] |
| Routed | Strategy registered, ProcessStrategyFactory case, SequentialCrewOrchestrator case |
[ ] |
| Terminates | Circuit breaker, budget, or a bounded loop β and cancellation honoured | [ ] |
| Observable | Hook terminal event on every exit, token metadata, structured logs | [ ] |
| Honest outcome | CreateFailure when the mode's contract fails |
[ ] |
| Configurable | Per-crew config read off the crew, both YAML layouts, load-time validation | [ ] |
| Scriptable | AllowedProcesses, crew.d.ts, orkeon usecases |
[ ] |
| Tested | Domain, strategy, factory, orchestrator, YAML, mapping, scripting | [ ] |
| Documented | Mode page + FR mirror, process-types, yaml-schema, INDEX/toc, CHANGELOG, check-doc-claims.py green |
[ ] |
| Example | Working config.yaml with README, listed in examples/INDEX.md |
[ ] |