Naming Convention Spec
Status Canonical
Date September 2026
Authority for Agent IDs · Workflow IDs · n8n display names · Layer codes · runtime-engine identifiers · document link-label conventions
Supersedes v0.6 (removes the Voice domain pack and its voi/VOI layer code)
This document is the single authoritative reference for all machine identifiers and human-readable names in Synedrix OS and its domain packs. Any identifier that appears in the agent registry, workflow registry, database, n8n, or event envelopes must conform to these rules. Where a prior document contained a conflicting example, this spec takes precedence.
1. Design goals
A naming convention for this platform must satisfy six properties:
| Property | Rationale |
|---|---|
| Layer-identifiable | OS vs domain pack is visible in the ID without a registry lookup |
| Self-describing | A human can parse meaning from the ID alone |
| Stable | The ID never changes even if the agent is renamed or reorganised |
| Sortable | Natural sort groups by domain → function → sequence |
| Collision-proof | No two agents or workflows can share an ID across any layer |
| Grep-friendly | Easy to isolate in logs, YAML, SQL, n8n execution traces |
2. Layer codes
Layer codes are the first segment of every machine identifier. They are the canonical way to distinguish platform-owned artefacts from domain-pack artefacts.
| Code (lowercase) | Code (uppercase) | Layer / domain scope | Description |
|---|---|---|---|
| os | OS | Synedrix OS | Platform-owned, cross-domain capabilities and control plane |
| art | ART | Synedrix Art | Art domain pack (creative storytelling, generation, curation) |
| trd | TRD | Synedrix Trading | Trading domain pack (markets, positions, strategies, execution) |
| com | COM | Synedrix Commerce | Commerce domain pack (catalog, pricing, orders, fulfilment) |
| fin | FIN | Synedrix Finance | Finance domain pack (invoicing, payments, GL, reconciliation) |
| ops | OPS | Synedrix Ops | Operations domain pack (incidents, tickets, runbooks, workflow ops) |
| mrd | MRD | Synedrix Mini Reachy Dev Assistant | Personal dev-workflow assistant domain pack (WIP/git awareness, dual knowledge-base advisory, Reachy Mini embodiment, voice, screen/IDE action-taking) |
Case rules
- Lowercase codes (
os,art,trd,com,fin,ops,mrd) are used in agent IDs and other kebab-case identifiers. - Uppercase codes (
OS,ART,TRD,COM,FIN,OPS,MRD) are used in workflow IDs and other SCREAMING-KEBAB identifiers.
Extension rule
New domain packs must propose a 2–4 alpha character code and add it to this table via spec versioning before any canonical IDs are minted. No domain pack may use a code already in use.
Canonical source for layer codes in consolidated references: Synedrix OS — Taxonomy Platform Spec v0.4 (§6.1.1).
3. Agent IDs
3.1 Pattern
{layer}-{archetype}-{capability-slug}-{seq}
All lowercase. Hyphen-separated. No spaces. No underscores.
| Segment | Constraint | Notes |
|---|---|---|
{layer} | Governed layer code (§2) | os, art, trd, com, fin, ops, mrd, … |
{archetype} | Governed 3-char code (§3.2) | ctl, exe, int, ifa, iop, aud |
{capability-slug} | Kebab slug of primary function | Max 32 chars; stable once registered |
{seq} | Zero-padded 3 digits | Scoped globally per layer (§3.3) |
3.2 Archetype codes
| Code | Full archetype | Description |
|---|---|---|
| ctl | Control | Orchestration, policy enforcement, routing, gating, veto, validation |
| exe | Execution | Domain action specialists that produce side effects |
| int | Intelligence | Analysis, forecasting, anomaly detection — no direct side effects |
| ifa | Interface | Human or customer-facing assistants |
| iop | Interop | A2A gateway, MCP broker, protocol adapters |
| aud | Audit | Trace synthesis, compliance review, lineage |
3.3 Sequence scoping rule
Sequence numbers (001–999) are scoped globally per layer. All agents with the same layer code share one number space regardless of archetype. This simplifies registry lookups and avoids gaps when agents in one archetype are deprecated.
3.4 OS platform — canonical agent IDs
These are the twelve OS-owned agents as canonicalised by the archetype model. Agents 001–008 were originally registered as os-agt-001–os-agt-008 (retained as legacy_id during migration). Agents 009–012 are new voice infrastructure agents and are assigned canonical IDs from first registration.
| Canonical ID | Human-readable name | Legacy ID | Archetype | Layer |
|---|---|---|---|---|
| os-ctl-orchestrator-001 | Orchestrator Agent | os-agt-001 | Control | 3 |
| os-ctl-policy-guard-001 | Policy Guard Agent | os-agt-002 | Control | 9 |
| os-ctl-registry-capability-001 | Registry and Capability Agent | os-agt-003 | Control | 5 |
| os-ctl-hitl-gateway-001 | HITL Gateway Agent | os-agt-004 | Control | 9 |
| os-int-analytics-001 | Analytics Agent | os-agt-005 | Intelligence | 10 |
| os-int-forecasting-001 | Forecasting Agent | os-agt-006 | Intelligence | 10 |
| os-int-anomaly-detection-001 | Anomaly Detection Agent | os-agt-007 | Intelligence | 10 |
| os-aud-audit-lineage-001 | Audit and Lineage Agent | os-agt-008 | Audit | 10 |
Migration note
The prior os-agt-001–os-agt-008 format used in synedrix-os-agent-registry-v0.1 is the legacy format. Canonical IDs replace these at next major version. Until migration, both forms are valid; legacy IDs are recorded as legacy_id in registry entries.
The os-agt-009–os-agt-012 block is held by the General Chat Agent and the three memory control-plane agents; their canonical IDs are listed in Agent Registry §3.2.
4. Workflow IDs
4.1 Pattern
WF-{LAYER}-{FUNCTION-SLUG}-{SEQ}
All caps for prefix segments. SCREAMING-KEBAB throughout. Hyphen-separated.
| Segment | Constraint | Notes |
|---|---|---|
WF | Literal constant | Identifies this as a workflow ID |
{LAYER} | Governed layer code, uppercase (§2) | OS, ART, TRD, MRD, … |
{FUNCTION-SLUG} | SCREAMING-KEBAB business descriptor | Max 40 chars; stable; business-readable |
{SEQ} | Zero-padded 3 digits | Scoped globally per layer |
4.2 OS platform — canonical workflow IDs
The canonical workflow IDs owned by the OS platform itself, not a domain pack.
| Canonical ID | Purpose |
|---|---|
| WF-OS-ORCHESTRATION-001 | Master orchestration routing |
| WF-OS-CAPABILITY-RESOLUTION-001 | Agent capability lookup |
| WF-OS-APPROVAL-ROUTING-001 | HITL approval dispatch |
| WF-OS-AUDIT-LINEAGE-SYNC-001 | Lineage write and Neo4j sync |
| WF-OS-EVAL-PROMOTION-GATE-001 | Agent promotion gate enforcement |
5. n8n display names
The n8n workflow display name is separate from the canonical workflow_id. It must be human-scannable in a list of workflows.
5.1 Pattern
[{LAYER}] {Layer tag} · {Business name}
| Segment | Notes |
|---|---|
[{LAYER}] | Uppercased layer code in brackets — groups domain packs |
{Layer tag} | Short layer descriptor: L1–L9 for Trading; SYS for OS |
{Business name} | Title case; concise; ~≤40 chars |
5.2 Examples
[OS] SYS · Capability Resolution[OS] SYS · Approval Routing[TRD] L1 · Master Orchestration[TRD] L3 · Technical Analyst[TRD] L5 · Risk Manager VETO[TRD] L6 · Consensus[TRD] L9 · HITL · Risk Review
5.3 Runtime engine identifiers
The runtime_engine field (Agent Runtime Policy Spec v0.4) names which execution engine runs an agent. Canonical values:
| Identifier | Meaning |
|---|---|
n8n-aiagent | Agent runs as an n8n AI Agent node (Orchestration Layer host). Default. |
langgraph | Agent runs in the LangGraph Agent Runtime (Layer 4). |
These are the only permitted values; do not invent per-domain variants. When an agent runs in LangGraph, the n8n step that invokes it follows the Execute Workflow / sub-invocation display-name convention with a · LangGraph suffix, e.g. [TRD] L2 · Consensus · LangGraph. The agent’s own agent_id and human-readable name are unchanged by the runtime engine.
6. Human-readable agent names
Human-readable agent names (for UI, documentation, and Wiki) follow the pattern from the Taxonomy Spec (§6.2), extended with a domain prefix rule.
<Capability> Agent— OS / cross-domain agents (e.g.Policy Guard Agent)Trading <Capability> Agent— Trading domain pack agents (e.g.Trading Risk Manager Agent)Commerce <Capability> Agent— Commerce domain pack agentsFinance <Capability> Agent— Finance domain pack agentsOps <Capability> Agent— Ops domain pack agents
The domain prefix uses the full domain name (Trading, Commerce, Finance, Ops), not the layer code. Names should read naturally in prose while remaining unambiguous.
6.1 Document link labels
When a Markdown link’s target is a canonical document, the link label must not repeat the version number already present in the target filename. The version lives in the path; restating it in the label creates a second copy of the same fact that goes stale on every future version bump without the label itself being touched.
- Correct:
[Synedrix OS — Vocabulary](synedrix-os-vocabulary-v0.8.md) - Incorrect:
[Synedrix OS — Vocabulary v0.7](synedrix-os-vocabulary-v0.8.md)
This rule governs descriptive title labels. It does not apply when the label is literally the target’s path or filename, typically in backticks — there the version is correctly part of what is being shown, not a restated fact, e.g. [`synedrix-os-canonical-master-v3.9.md`](synedrix-os-canonical-master-v3.9.md).
7. Governance rules
- IDs are stable. Once registered, a canonical ID never changes. If a capability is substantially redesigned it receives a new ID; the old one is deprecated.
- IDs are registered before use. No agent or workflow may appear in a running workflow with an unregistered ID.
- Legacy IDs are retained as
legacy_id. During any migration period, the prior ID is recorded in the registry entry aslegacy_idand retained until all references in built n8n instances are updated. - Layer codes are owned by this spec. Domain packs may not mint new layer codes without a version increment to this document.
- Sequence numbers are not reused. When an agent or workflow is retired, its sequence number is permanently retired with it.
9. Versioning
- Version: 0.7
- Status: Canonical
- Date: September 2026
- Supersedes: v0.6
- Related artefacts: Taxonomy Spec v1.0 · Core Principles v0.5 · Layer Taxonomy v0.7 · Agent Runtime Policy Spec v0.4 · Orchestration & Runtime Strategy v0.1 · Agent Registry v0.5
Related Documents
Canonical Reference
- Synedrix OS - Consolidated Canonical Reference — Consolidated single-file synthesis; references this spec as the authoritative naming reference.
Taxonomy and Architecture
- Synedrix OS - Taxonomy & Platform Spec — Canonical taxonomy; §6.1.1 layer code table sourced from §2 of this document.
- Synedrix OS - Layer Taxonomy Table — Authoritative layer definitions; the layer responsibilities justify the layer code assignments in §2.
Agent Specifications
- Synedrix OS - Agent Registry Spec — Registry schema; the
agent_idfield uses the pattern defined in §3.1 of this document. - Synedrix OS - Agent Registry — OS agent definitions; §3.4 canonical IDs replace the legacy
os-agt-00xformat.
Workflow Standards
- Synedrix OS - Workflow Contract Spec — Workflow standard; the
workflow_idfield uses the pattern defined in §4.1 of this document.
Vocabulary
- Synedrix OS — Vocabulary — Canonical glossary; canonical forms for all platform and agent terminology.
Synedrix OS · Naming Convention Spec · September 2026