Status: Active
Date: March 23, 2026
Owners: OSHUN Product, OSHUN Engineering, OSHUN Platform, OSHUN Safety
Related:
docs/releases/v1/reports/subsystem-ownership-matrix.mddocs/releases/v1/specs/program-charter.mddocs/releases/v1/specs/web-app-admin-v1-prd.mddocs/releases/v1/specs/todos.md
1. Purpose and Authority#
This guide operationalizes the OSHUN V1 ownership matrix.
Use it when the question is not "who owns this capability?" but "which subsystem should this feature, flow, or incident invoke right now?"
This guide is authoritative for day-to-day routing decisions as long as it remains consistent with:
docs/releases/v1/reports/subsystem-ownership-matrix.mddocs/releases/v1/specs/program-charter.mddocs/releases/v1/specs/web-app-admin-v1-prd.md
If a scenario seems to require multiple subsystems, compose them through the shell, BFF, and explicit adapters. Do not collapse ownership to make the flow feel simpler.
2. Fast Routing Table#
| If the need is... | Call... | Why |
|---|---|---|
| route composition, shared UX, continuity UI, admin/operator surfaces | OSHUN Shell | the shell owns composition, routing, adapters, and shared presentation |
| identity, entitlements, shared search infra, notifications infra, audit, observability, privacy, experimentation | Shared Platform Services | these are shared infrastructure concerns, not peer customer domains |
| centering, rituals, transitions, sleep, presence | Tara | Tara owns the contemplative customer-facing experience |
| habits, goals, reflection, daily structure | Arete | Arete owns disciplined embodiment experiences |
| grounded claims, briefings, evidence inspection | Veritas + Sophia | Veritas owns the experience; Sophia owns grounding and citations |
| passages, study, compare, annotation, scholarship | Nisaba + Sophia | Nisaba owns the study experience; Sophia owns grounding support |
| sky awareness, celestial events, cosmological orientation | Nyx | Nyx owns wonder and astronomy experiences |
| durable assistant identity, memory, conversation history, memory consent | Iris | Iris owns assistant continuity and memory state |
| live text/voice/avatar runtime, conferencing, turn-taking | Psyche | Psyche owns real-time multimodal orchestration |
| contemplative tone, teacher logic, persona safety | Lilith | Lilith owns contemplative persona policy and safeguards |
| retrieval, citations, evidence packs, notebooks, research evaluation | Sophia | Sophia is the grounding and research-integrity substrate |
| model/workflow selection, generation policy, provenance, release gates | Isis | Isis is the generation control plane |
3. Decision Flow#
- Is the problem about product composition, routing, shared UI presentation, or admin/operator surface behavior? Call OSHUN Shell first.
- Is the problem about a shared infrastructure concern such as identity, entitlements, search infra, notifications infra, audit, privacy, or observability? Call Shared Platform Services first.
- Is the user-facing value primarily one of the five customer domains? Call the corresponding domain owner first: Tara, Arete, Veritas, Nyx, or Nisaba.
- Does the flow need durable assistant memory, consent-aware recall, or persistent conversation continuity? Add Iris.
- Does the flow need live text/voice/avatar orchestration, conferencing, or low-latency embodiment? Add Psyche.
- Does the flow need contemplative tone, teacher behavior, or domain-specific spiritual safety policy? Add Lilith.
- Does the flow need evidence, citations, retrieval, source-aware synthesis, notebooks, or research evaluation? Add Sophia.
- Does the flow need model selection, workflow selection, generation policy, provenance, staging/promotion, or release-gated media execution? Add Isis.
- If more than one step above applies, compose the responsible subsystems through explicit adapters and keep ownership split intact.
4. Common Scenarios#
| Scenario | Call... | Do Not Call First... | Reason |
|---|---|---|---|
| text assistant turn with continuity but no live voice and no evidence need | OSHUN Shell + Iris | Psyche, Sophia, Isis | this is a memory-backed assistant flow, not a real-time or grounded-generation flow |
| live voiced Tara guide or avatar-led contemplative session | OSHUN Shell + Iris + Psyche + Lilith | Sophia unless grounded evidence is required | the flow needs memory, embodiment, and contemplative policy |
| evidence-backed claim explanation in Veritas | OSHUN Shell + Veritas + Sophia | Lilith or Isis as primary owners | Veritas owns the experience, Sophia owns grounding |
| Nisaba study/compare/annotation flow | OSHUN Shell + Nisaba + Sophia | Veritas as primary owner unless the goal is claim briefing | the study surface is Nisaba, but grounding still belongs to Sophia |
| cross-domain search result rendering | OSHUN Shell + Shared Platform Services + Sophia where grounding is required | treating each domain as an independent search owner | search infra is shared; grounded evidence remains Sophia-owned |
| notification preferences and delivery controls | OSHUN Shell + Shared Platform Services | domain surfaces owning the global preference model | notification infra is shared, while the shell owns the surfaced UX |
| memory review, delete, export, or consent change | OSHUN Shell + Iris | Psyche | this is durable memory and consent state, not live runtime |
| model-backed image/audio/video/avatar generation | OSHUN Shell or domain surface + Isis | direct provider runtime | Isis owns workflow, model, provenance, and release governance |
| imported Civitai model or workflow intake | Isis | ad hoc direct provider usage | Civitai assets must normalize into Isis-owned records |
5. Anti-Patterns#
- Do not call Sophia for every assistant turn just because the response feels "smart." Call Sophia only when grounding, citations, retrieval, or source-aware synthesis are actually required.
- Do not use Psyche as a durable memory or consent store.
- Do not use Lilith as the shell router or generic orchestration layer.
- Do not let domains or shell code bypass Isis and talk directly to generation providers as the runtime of record.
- Do not move domain business logic into the shell for convenience.
- Do not treat Shared Platform Services as a customer-facing peer domain.
6. Escalation Rule#
If this guide still leaves a call-routing decision ambiguous:
- use
docs/releases/v1/reports/subsystem-ownership-matrix.mdto identify the system-of-record owner - use the charter and PRD to confirm the intended dependency edge
- update this guide, the matrix, and the governing docs together before implementation proceeds