1. Scope

1.1 Purpose

This document defines the canonical taxonomy, naming model, architectural boundaries, and packaging structure for Synedrix OS and all domain packs. Its purpose is to ensure business domains inherit from a shared multi-agent operating substrate rather than evolving into disconnected vertical systems.

1.2 Non-goals

This document does not specify detailed workflow implementations, prompts, model choices, UI design, or domain-level business rules. It defines the platform meta-architecture only.

2. Canonical definitions

2.1 Synedrix OS

Synedrix OS is the reusable multi-agent operating system that provides orchestration, agent lifecycle management, memory primitives, governance, tool mediation, and observability for business execution. It is domain-agnostic at its core; agents are its primary actor type, coordinated through the shared orchestration, governance and observability layers every domain pack composes on.

2.2 Domain pack

A domain pack is a modular business capability package that runs on Synedrix OS and introduces domain-specific entities, events, agents, tools, policies, workflows, and analytics vocabulary. Examples include Synedrix Trading, Synedrix Commerce, Synedrix Ops, Synedrix Finance — all treated equivalently as optional packs.

2.3 Business instance

A business instance is a deployed runtime composed of Synedrix OS plus one or more domain packs, configured for a specific company, team, or business unit.

2.4 Agent

An agent is a scoped software actor with a defined mission, authority boundary, input/output contract, tool permissions, memory scope, and escalation path.

2.5 Workflow

A workflow is an orchestrated sequence of events, tasks, agent invocations, and tool calls designed to produce a business outcome.

2.6 Capability

A capability is a reusable unit of business function such as pricing intelligence, fulfillment routing, risk evaluation, catalog enrichment, or customer support triage.

2.7 Business Instance Extension (BIE)

A Business Instance Extension is a customer-specific, non-reusable customization layer registered under a single business instance. It is not a numbered architectural layer; it is a governed overlay within Layer 12 (Business Instance). A BIE contributes, in order of preference, configuration values, tenant policy parameters evaluated by the OS Policy Guard, workflow hooks at extension points a domain pack explicitly declares, client-specific agents registered through the shared agent registry schema, and adapter/integration mappings. Every BIE is itself a registered, governed artifact — discoverable by the Registry & Capability Agent (os-agt-003), governed by Policy Guard (os-agt-002), and traced by Audit & Lineage (os-agt-008). See ADR-OS-005.

2.8 Capability Module

A Capability Module is a reusable, independently versioned, licensable sub-package of a domain pack, built once by the pack vendor and enabled independently by multiple business instances via an explicit entitlement flag. Unlike a Business Instance Extension, a Capability Module is not customer-specific — it contributes agents and workflows to the shared registry using the same schema as core domain-pack agents, and declares a dependency on a domain-pack version range (e.g. depends_on: commerce-pack >= 1.0). It is never bundled into the base pack and is never a BIE. See ADR-OS-005.

How the canonical terms relate:

flowchart TB
    BI["Business instance: Synedrix OS plus one or more domain packs, configured for a company, team or business unit"]
    OS["Synedrix OS: domain-agnostic core"]
    DP["Domain pack: entities, events, agents, tools, policies, workflows"]
    CM["Capability Module: sub-package of a domain pack, enabled by entitlement flag"]
    BIE["Business Instance Extension: customer-specific overlay within Layer 12"]
    AG["Agent"]
    WF["Workflow"]
    BI -->|"composed of"| OS
    BI -->|"composed of"| DP
    DP -->|"may declare"| CM
    BI -->|"may register one"| BIE
    DP -->|"introduces"| AG
    DP -->|"introduces"| WF
    CM -->|"contributes"| AG
    CM -->|"contributes"| WF
    WF -->|"invokes"| AG

3. Architectural layers

See Synedrix OS - Layer Taxonomy Table for the authoritative per-layer responsibilities. The OS defines 12 layers:

  • Human interface layer
  • Goal and intent layer
  • Orchestration layer
  • Agent runtime layer
  • Agent registry layer
  • Tool abstraction layer
  • Memory and data layer
  • Event layer
  • Governance and controls layer
  • Observability layer
  • Domain pack layer
  • Business instance layer

4. Packaging model

4.1 OS package

Must include orchestration runtime, workflow registry, agent registry, tool adapter framework, shared event schema, memory abstractions, policy engine, and observability framework.

Must not include any domain-specific logic, provider-specific heuristics, or vendor-specific execution rules.

4.2 Domain pack package

Must include domain entities, events, agents, workflows, policies, tool adapters, KPIs, and analytics vocabulary. A domain pack may optionally declare one or more Capability Modules — reusable sub-packages of its own agents/workflows, independently versioned and gated by instance-level entitlement (see §2.8).

Must not redefine core orchestration primitives, governance models, shared logging/tracing formats, or the shared agent registry schema.

4.3 Business instance package

Contains Synedrix OS + one or more domain packs + tenant configuration, credentials, policy overrides, approval thresholds, and environment settings.

4.4 Business Instance Extension package

May include configuration values, tenant policy parameters, declared workflow hooks, customer-specific agents (owner = the business instance), and adapter mappings, always scoped to exactly one business instance package. Must not redefine OS policy, must not widen a domain pack’s declared configurable surface beyond named extension points, and must not be reused across instances — see Business Instance.

5. Responsibility boundaries

5.1 Rule of inclusion

If a capability can be reused by multiple domains without domain knowledge, it belongs in Synedrix OS. If it requires domain entities, domain tools, or domain policies, it belongs in a domain pack. If it is a threshold, credential, or environment-specific setting, it belongs in a business instance.

See Synedrix OS - Responsibility Matrix for the authoritative capability-by-capability split.

6. Naming conventions

6.1 Platform naming

Synedrix OS = core platform Synedrix <Domain> = domain pack (e.g. Synedrix Trading, Synedrix Commerce, Synedrix Ops) Synedrix <Client/Unit> Runtime = deployed business instance

6.1.1 Layer codes

Layer codes provide a compact, machine-friendly prefix for agents, workflows, and other identifiers while remaining self-describing at a glance.

Code (lowercase)Code (uppercase)Layer / domain scopeDescription
osOSSynedrix OSPlatform-owned, cross-domain capabilities and control plane
artARTSynedrix ArtArt domain pack (creative storytelling, generation, curation)
trdTRDSynedrix TradingTrading domain pack (markets, positions, strategies, execution)
comCOMSynedrix CommerceCommerce domain pack (catalog, pricing, orders, fulfillment)
finFINSynedrix FinanceFinance domain pack (invoicing, payments, GL, reconciliation)
opsOPSSynedrix OpsOperations domain pack (incidents, tickets, runbooks, workflow ops)
mrdMRDSynedrix Mini Reachy Dev AssistantPersonal dev-workflow assistant domain pack (WIP/git awareness, dual knowledge-base advisory, Reachy Mini embodiment, voice, screen/IDE action-taking)

6.1.2 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 SCREAMING-KEBAB identifiers.
  • 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.

6.2 Agent naming

6.2.1 Machine identifier (agent_id)

Pattern: {layer}-{archetype}-{capability-slug}-{seq}

All lowercase, hyphen-separated.

SegmentValues
{layer}Governed layer code from §6.1.1
{archetype}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

Examples: os-ctl-orchestrator-001, os-ctl-policy-guard-001, trd-exe-bull-strategist-001, trd-ctl-risk-manager-001

6.2.2 Human-readable name

<Capability> Agent for OS / cross-domain agents. Trading <Capability> Agent for Trading domain-pack agents (the pattern generalizes: <Domain> <Capability> Agent for any domain pack).

For the full archetype code table, canonical OS agent IDs, and canonical per-pack agent IDs (e.g. Trading), see Synedrix OS — Naming Convention Spec.

6.3 Workflow naming

6.3.1 Machine identifier (workflow_id)

Pattern: WF-{LAYER}-{FUNCTION-SLUG}-{SEQ}

SCREAMING-KEBAB, hyphen-separated.

SegmentValues
WFLiteral constant
{LAYER}Governed layer code, uppercase, from §6.1.1
{FUNCTION-SLUG}SCREAMING-KEBAB business descriptor (max 40 chars, stable)
{SEQ}Zero-padded 3 digits, scoped globally per layer

Examples: WF-OS-ORCHESTRATION-001, WF-TRD-MASTER-ORCHESTRATION-001, WF-TRD-RISK-MANAGER-VETO-001

6.3.2 n8n display name

Pattern: [{LAYER}] {Layer tag} · {Business name}

The [LAYER] prefix sorts domain packs together in the n8n workflow list.

Examples: [OS] SYS · Capability Resolution, [TRD] L1 · Master Orchestration, [TRD] L5 · Risk Manager VETO

For the full canonical workflow ID tables and the complete legacy-to-canonical migration map, see Synedrix OS — Naming Convention Spec.

7. Agent taxonomy

7.1 Control agents (cross-domain)

Orchestrator Agent, Policy Guard Agent, Registry & Capability Agent, HITL Gateway Agent.

7.2 Domain agents (pack-specific)

Defined by each domain pack. A domain pack’s agents use family: domain and owner: <domain-pack-id> (e.g. owner: trading for Trading pack agents).

7.3 Intelligence agents (cross-cutting)

Analytics Agent, Forecasting Agent, Anomaly Detection Agent.

7.4 Customer-facing agents

Appear only in relevant packs: Support Agent, CRM/Retention Agent, Review/Reputation Agent.

8. Memory types

Memory has two orthogonal axes. The tier is what kind of memory a record is; the substrate is the store it is written to or projected into. Neither may be inferred from the other. Memory Fabric Spec §3 is authoritative; this table is its summary.

TierOwnerScopeWrite-authoritative substrate
workingOSrun / sessionRedis; TTL-bound and never a source of truth
episodicOScross-sessionSupabase PG17, indexed in Qdrant
semanticOScross-sessionSupabase PG17, indexed in Qdrant
proceduralOScross-sessionSupabase PG17, indexed in Qdrant; versioned
profileOSsubject-scopedSupabase PG17, indexed in Qdrant; supersession-based
relationalOS / domainpersistentSupabase PG17
graphOScross-sessionSupabase PG17 for lineage; Neo4j for entities, via NAMS
temporalOSpersistentQuestDB

The former operational type is now working, and the former conversation type folds into working with its TTL and no-promotion-without-handoff rule intact — that rule is now the general case for every tier pair.

9. Domain pack contract

Each domain pack must declare:

FieldPurpose
domain_idStable machine identifier
domain_nameHuman-readable name
entity_modelCanonical business entities and relationships
event_catalogDomain-specific event types
agent_registry_entriesAgent definitions contributed by the pack
workflow_libraryWorkflows exposed by the pack
tool_adaptersExternal systems and adapters required
policy_modulesDomain-specific policy logic
analytics_modelKPIs, metrics, domain vocabulary
approval_matrixWhich actions require which level of approval
capability_modulesOptional reusable sub-packages this pack declares, each independently versioned and entitlement-gated
extension_pointsNamed hook points this pack explicitly exposes for Business Instance Extensions to attach workflow hooks to

10. Event taxonomy

See Synedrix OS - Event Taxonomy Standard for the authoritative event envelope and naming rules. The OS defines a common envelope; each domain pack defines its own event types.

11. Governance model

Every business instance must support role-based permissions, approval thresholds, audit logging, decision traceability, human override, and kill switch or pause controls.

High-impact actions (e.g., financial transactions, price changes, refunds, supplier switching, regulated messaging, policy changes) must always pass through policy validation and, where configured, human review.

12. Invariants

  • Synedrix OS remains domain-agnostic.
  • Domain packs cannot bypass OS governance.
  • No agent writes to production systems without policy-aware orchestration.
  • Every workflow is observable.
  • Every agent has explicit authority boundaries.
  • Every pack conforms to the shared registry and contract standards.
  • No memory record crosses a tier boundary without a governed memory.record.promoted event carrying its correlation_id and causation_id. Session-scoped working memory is TTL-bound and is never promoted to a durable tier without one.
  • Memory recall is an authorized tool call, never ambient context injection.
  • Only the Memory Curator (os-agt-010) commits durable memory; every other agent proposes.

13. Versioning model

Synedrix OS uses two related but distinct versioning layers:

  1. Spec/document versions (vX.Y)

    • File names and document headers use vX.Y to track canonical spec evolution.
    • X increments for breaking conceptual changes to the taxonomy or platform model.
    • Y increments for non-breaking clarifications, example updates, or added guidance.

  2. Artifact versions (SemVer)

    • Agents, workflows, domain packs, and business instances use semantic versioning (MAJOR.MINOR.PATCH) in their own version fields.
    • IDs such as trd-agt-strategy-analyst-001 or WF-TRD-MASTER-ORCHESTRATION-001 are stable identitiesand donot encode version.
    • New revisions of an agent or workflow update the version field; the ID only changes when the artifact is retired and replaced by a new identity.

  3. Pinning rule. A business instance is only affected by a new domain-pack version, a new Capability Module version, or a new Business Instance Extension (BIE) version when it explicitly updates its own pinned reference (domain_pack_version, a Capability Module entitlement/version, or the active BIE version). Publishing a new artifact version registers it; it never propagates into a running instance implicitly. This generalizes the same governed-crossing pattern used for memory tier promotion (memory.record.promoted) to instance-level artifact activation. See ADR-OS-005.

14. Versioning

  • Version: 1.0
  • Supersedes: v0.8
  • Related artifacts: Layer Taxonomy v0.7, Naming Convention Spec v0.7, Core Principles v0.5, Agent Registry Spec v0.1, Agent Registry v0.5, Workflow Contract Spec v0.4, Memory Fabric Spec v0.1, ADR-OS-005

Canonical Reference

Naming and Architecture

Core Principles and Governance

Agent Specifications

Domain Pack

  • Synedrix OS - Domain Pack Template — Domain pack authoring template built on the domain pack contract defined in §9.
  • Synedrix Trading Domain Pack — Trading domain pack; the reference implementation of a domain pack composing on Synedrix OS.

Vocabulary

Business Instance Extension and Capability Module

  • Business Instance layer page — Expands §2.7/§4.4’s Business Instance Extension definition into the full layer reference, including the non-reusability rule that separates a BIE from a Capability Module.
  • Domain Pack layer page — Where a domain pack declares extension_points and Capability Modules.
  • Synedrix OS ADR-OS-005 — Business Instance Extension and Capability Module — The decision record for §2.7, §2.8, §4.4, §9’s new rows, and §13.3.

Synedrix OS · May 2026