Project layout
A project in the Open Engineering Language is a folder of small source files, each with one job. Agents, subagents, nodes (business steps), edges (typed two-way connections), configuration, hooks and skills are first-class building blocks, each in its own named file, so a project's structure reads at a glance.
A complete project
support/
main.oel # main support(): the program's entry point
pack.oel # packages; may be empty
metadata.oel # the project's name and settings
src/
application.config.oel
validation.reuse.oel
normalize.global.oel
agents/support.agent.oel
nodes/summarize.node.oel
nodes/verify.node.oel
edges/summary_to_verify.edge.oel
auth.hook.oel
prompts/summarize.md
oel init support creates the three root files. Every other folder and file is your choice.
The three root files
| File | Holds |
|---|---|
main.oel | main support(), the program's entry point, named after the application. Exactly one, at the project root. |
pack.oel | The manifest: the packages this folder and the folders below it use. Required at the root, even when it lists none. |
metadata.oel | The project's name, description and settings. The name, here support, names main and the program that oel build writes; an entry named main is refused. A package project names its package here instead, and its main takes the package name's last segment. |
One component per file
Every other source file but a language file (below) is named <name>.<role>.oel. It declares exactly one component of that role, and the component carries the file's name: summarize.node.oel declares node summarize(…).
| File | Declares | Holds |
|---|---|---|
<name>.agent.oel | agent <name>(…) | An agent: a workflow with its nodes, edges, starting points and completion. |
<name>.subagent.oel | subagent <name>(…) | A subagent: a short-lived agent that an agent spawns at run time, which does one task, returns a typed result to the agent that spawned it and ends. |
<name>.node.oel | node <name>(…) | A node: one business step, deterministic or model-driven. |
<name>.edge.oel | edge <name>(…) | An edge: a typed, two-way channel between two components, a value one way and its reply back. |
<name>.config.oel | config <name>(…) | Typed configuration with defaults, locked into a snapshot for each run. |
<name>.hook.oel | hook <name>(…) | A hook: authorization, auditing or cleanup attached before or after a component, function or statement. |
<name>.skill.oel | skill <name>(…) | A skill that an agent or subagent loads; see Skills. |
<name>.global.oel | global <name>(…) | A global function, visible in its folder and every folder below it. |
<name>.reuse.oel | reuse <name>(…) | A reusable function, available to a file that imports it by path. |
<name>.routes.oel | routes <name>(…) | HTTP routes, a file role that the server/http package adds. |
A name is an identifier: letters, digits and _, not starting with a digit, and not a keyword. Names are case-sensitive, and a file whose component name does not match its file name fails the check.
Functions in other languages
Your application can hold private functions written in other languages, with typed signatures in the Open Engineering Language, built and run with your own toolchains, pinned by version. A function with a file of its own is in a language file, <name>.<lang>.oel, such as profile.python.oel, which declares python profile(…); a component's file holds them beside its helpers in the Open Engineering Language as fn python …. A file name never holds both a language and a role. Functions in other languages describes both forms.
Sharing functions
Sharing follows three rules, and the check enforces each of them:
- Helper functions (
fn) stay private to the component that declares them and its extension files. - Global functions are visible, without an import, in their own folder and every folder below it.
normalize.global.oelinsrc/is callable from every file undersrc/. - Reusable functions are available only to a file that imports them by path, in its header, from its own folder or a folder above it.
# src/nodes/summarize.node.oel
import "../validation.reuse.oel";
node summarize(request: Str<4000>) -> Str<1000> {
config {
id: "summarize"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "summarize"; };
ports: [{ id: "request"; direction: "input"; schema_type: "String<4000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 4000; join: "all"; },
{ id: "summary"; direction: "output"; schema_type: "String<1000>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 1000; join: "all"; }];
limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
}
let checked: Str<4000> = normalize(validation(request));
return write_summary(checked);
}
fn write_summary(request: Str<4000>) -> Str<1000> {
# A private helper: only this node can call it. This placeholder returns an empty summary.
return "";
}
validation and normalize are written like this:
# src/validation.reuse.oel
reuse validation(request: Str<4000>) -> Str<4000> {
return request;
}
# src/normalize.global.oel
global normalize(request: Str<4000>) -> Str<4000> {
return request;
}
When two shared functions have the same name, the one in the nearest folder wins. A file never calls a shared function from a sibling folder or from a folder below it.
Extension files
When a component needs more private helpers than fit in its file, you move them to extension files in the same folder: support.agent.extended.oel, then support.agent.extended.2.oel and up. An extension file holds only private helpers, in the Open Engineering Language or in another language, and they belong to that one component. main.oel uses main.extended.oel, and a language file such as profile.python.oel uses profile.python.extended.oel, which holds only functions in its language.
Every source file has a fixed size limit, so files stay small and reviewable. Limits gives the exact limit.
Packages in a project
pack.oeldeclares the packages a folder and the folders below it use. The root manifest is required, and any folder can add its own, so one part of a project can add a package without affecting the rest. The nearest manifest that declares a package wins.pack.lockis generated beside eachpack.oel. It records the exact versions, origins and fingerprints your builds use, so builds repeat, even offline. You never edit it by hand..package/is generated beside each manifest that lists packages, and holds the installed packages. It is not part of your source: you never edit it.
A file names the parts of a package it uses in its header, for example refer server/http select get;, and every export it selects must be used. Using packages describes manifests, folder scopes and the lock file in full, and Private packages the packages you build and host yourself.
Prompts and other files
prompts/ is the usual place for system prompts kept as files, one per prompt. It is a convention, not a rule: a node names its prompt file by path, wherever the file is in the project.