---
name: om
description: |
  TRIGGER this skill when any of the following apply:
  - The user references organization-model entities by name or concept: identity, customers,
    offerings, roles, goals, techStack, systems, actions, labels, knowledge nodes, governance edges,
    mounts, playbook, outreach cadence, or any domain in the org model.
  - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
    update, toggle, enable, or disable any organization-model domain or knowledge node.
  - The user asks "what governs X?", "what does X control?", "system governs", "what is our
    identity set to?", "what's our timezone?", "show me all reference docs", "list my roles",
    "where does outreach-cadence apply?", or similar.
  - An agent is editing files matching: core/config/organization-model.ts,
    core/config/organization-model/**, or core/config/knowledge/**.
  SKIP this skill when the task is purely UI layout, workflow authoring, or infrastructure
  work with no reference to org-model or knowledge-graph entities.

  /knowledge is preserved as a permanent alias for muscle memory; both names route here.
metadata:
  pathPatterns:
    - "core/config/organization-model.ts"
    - "core/config/organization-model/**"
    - "core/config/knowledge/**"
    - "core/config/extensions/**"
  promptSignals:
    phrases:
      - playbook
      - knowledge node
      - system governs
      - outreach cadence
      - identity
      - customer segment
      - codify
      - enable system
      - toggle system
      - what governs
      - org model
      - organization model
      - offerings
      - techStack
      - roles
      - goals
      - labels
      - knowledge map
      - governance edge
      - knowledge mount
      - knowledge graph
      - knowledge browser
      - ontology
      - apiInterface
      - interface readiness
      - by-ontology
      - list my roles
      - what is our
      - show me all reference docs
      - where does
      - apply
      - build a system
      - design a system
      - create a system that
      - system architecture
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# OM (Organization Model)

Unified intent-inferring skill for all organization-model interaction in this tenant project.
Reads OM state through the `elevasis-sdk om:*` CLI surface (or the legacy `knowledge:*` aliases
that still work); writes run through the Codify/Toggle ceremony. No verb namespace is required --
the skill classifies intent from conversation context and routes internally.

The slash command was renamed from `/knowledge` to `/om`; `/knowledge` is preserved as a permanent
alias. Both invocations land here.

---

## When to Invoke

This skill auto-invokes whenever:

- Conversation references org-model entities (identity, customers, offerings, roles, goals,
  techStack, systems, actions, labels, knowledge nodes, governance edges, mounts)
- The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
  update, toggle, enable, or disable any of those
- An agent is editing files matching `core/config/organization-model.ts`,
  `core/config/organization-model/**`, `core/config/extensions/**`, or
  `core/config/knowledge/**`

Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`, and
`metadata.promptSignals` -- no explicit prefix is required.

---

## Operations

| Operation | Description                                                                                                              | Execute                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `build`   | Codify-ceremony runbook for building a System end to end (shell → ontology → resources → topology → knowledge → verify). | `.claude/skills/om/operations/build.md` |

---

## 5-Bucket Decision Tree

If the user expresses intent to **build, design, or architect a system** -- phrased as "build a
system", "design a system", "create a system that does X", "I want a system for Y", "system
architecture for Z", or any free-text describing a system they want to construct rather than
query -- route to `/om build` **before** the buckets below. Read
`.claude/skills/om/operations/build.md` and follow its ordered phases. This is the primary
entry; the user does not need to type `/om build` explicitly.

Once invoked for read/write intents (not build), classify the user's input into ONE of these
buckets and dispatch the matching primitive. When two buckets fit, prefer the higher one (more
specific → more general).

| #   | Bucket                         | Trigger                                                                                           | Dispatch                                                                        |
| --- | ------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 1   | Named knowledge/role/policy id | User names `knowledge.<id>`, `role.<id>`, `policy.<id>` directly                                  | `om:cat <id>` for body, `om:describe <id>` for neighborhood                     |
| 2   | Named system                   | User names a system path (`sales.crm`, `sales.lead-gen`)                                          | `om:describe <id>`                                                              |
| 3   | Named ontology id              | Id contains `:object/`, `:action/`, `:event/`, `:catalog/`, `:interface/`, `:link/`, `:endpoint/` | `om:describe <id>` (or `om:ls /by-ontology/<id> --ids-only` then `om:cat` each) |
| 4   | Kind keyword                   | "playbooks", "strategies", "all references", "list policies"                                      | `om:ls /by-kind/<kind> --ids-only` then `om:cat` each                           |
| 5   | Free-text discovery            | Anything else ("lead gen", "outreach", "what governs X?")                                         | `om:search "<query>"` then drill into top hit with `om:describe`                |

On ambiguous input, default to **bucket 5 (search)** and surface the top hits. Codify and Toggle
intents are write paths -- see "Write Power" below.

---

## CLI Surface

All commands run with `pnpm elevasis-sdk <cmd>` from the tenant project root (uses the root script
alias). Alternatively, use `pnpm -C operations exec elevasis-sdk <cmd>` from the monorepo root.
Do NOT use `pnpm exec elevasis-sdk <cmd>` at the project root -- `@elevasis/sdk` is a dependency of
`operations/` only; the binary is not found from the project root without the alias.

| Command            | Alias                | Purpose                                                                                                                                                                                                             |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `om:search <q>`    | `knowledge:search`   | Universal keyword search across all 6 OM surfaces                                                                                                                                                                   |
| `om:describe <id>` | `knowledge:describe` | Structured neighborhood view; kind auto-detected from id shape; also resolves `item:<domain>:<id>` and bare `<prefix>:<uuid>` domain-item forms                                                                     |
| `om:cat <id>`      | `knowledge:cat`      | Raw MDX body of a knowledge node                                                                                                                                                                                    |
| `om:ls <path>`     | `knowledge:ls`       | List by mount path. Enumeration: `/all-systems`, `/all-resources`, `/all-roles`. Scoped: `/by-system/`, `/by-kind/`, `/by-ontology/`, `/by-owner/`, `/by-domain/`, `/by-item/`, `/graph/<id>/{governs,governed-by}` |
| `om:graph <id>`    | `knowledge:graph`    | Show outgoing + incoming graph edges                                                                                                                                                                                |
| `om:skills <id>`   | `knowledge:skills`   | Show callable invocations on graph neighbors                                                                                                                                                                        |
| `om:generate`      | `knowledge:generate` | Regenerate `_generated/nodes.ts` from MDX sources                                                                                                                                                                   |

Common flags: `--json`, `--ids-only`, `--limit <n>`, `--kinds <list>`.

---

## Read Patterns (Tenant Project)

### Free-text discovery (default for natural-language queries)

```bash
pnpm elevasis-sdk om:search "lead gen"
pnpm elevasis-sdk om:search outreach --kinds knowledge --limit 5
pnpm elevasis-sdk om:search apollo --ids-only
```

### Neighborhood view for any OM node

```bash
pnpm elevasis-sdk om:describe sales.crm
pnpm elevasis-sdk om:describe knowledge.outreach-playbook
pnpm elevasis-sdk om:describe sales.crm:object/deal
```

### Domain-item profile (clients, roles, policies, customers, offerings, goals)

Use `om:describe item:<domain>:<id>` to read a rich domain-item profile -- identity, branding,
location, and governing knowledge. The bare `<prefix>:<uuid>` form (e.g. `client:<uuid>`) is
accepted as a back-compat alias and resolves identically.

```bash
pnpm elevasis-sdk om:describe item:clients:<uuid>     # full ClientProfile + location + governing knowledge
pnpm elevasis-sdk om:describe item:roles:<id>
pnpm elevasis-sdk om:describe item:policies:<id>
pnpm elevasis-sdk om:describe item:customers:<id>
pnpm elevasis-sdk om:describe item:offerings:<id>
pnpm elevasis-sdk om:describe item:goals:<id>
```

Do not confuse this with `client:get <uuid>` (the portfolio/DB surface for status, lineage, and
deals). `om:describe item:clients:<uuid>` returns the org-model `ClientProfile`; `client:get`
returns a sparse DB record. They share the same `id` and can be cross-linked by it.

### Read a single knowledge node body

```bash
pnpm elevasis-sdk om:cat knowledge.outreach-playbook
```

### Top-level enumeration (drill-down entry point)

Start here when an agent needs to discover what this tenant's custom OM contains before
building on it -- list everything in a domain, then narrow with `om:describe` / `om:cat`:

```bash
pnpm elevasis-sdk om:ls /all-systems              # every System (path + label)
pnpm elevasis-sdk om:ls /all-resources            # every resource (id, kind, title)
pnpm elevasis-sdk om:ls /all-roles                # every role (id, title)
pnpm elevasis-sdk om:ls /all-systems --ids-only   # pipe paths into om:describe
```

These resolve against this tenant's resolved model -- they enumerate the project's own custom
OM, not the platform's. Use `--json` for the wrapped envelope or `--ids-only` for piping.

### Scoped mount-path listings

```bash
pnpm elevasis-sdk om:ls /by-system/sales.crm
pnpm elevasis-sdk om:ls /by-kind/playbook --ids-only
pnpm elevasis-sdk om:ls /by-ontology/sales.crm:object/deal --ids-only
pnpm elevasis-sdk om:ls /by-owner/role.ops-lead --ids-only
pnpm elevasis-sdk om:ls /by-domain/clients                    # enumerate all client domain items
pnpm elevasis-sdk om:ls /by-item/clients/<uuid>               # single item record (same as om:describe item:clients:<uuid>)
pnpm elevasis-sdk om:graph knowledge.outreach-playbook
```

When a query clearly names an ontology id such as `sales.crm:object/deal`, route through
`/by-ontology/<id>` automatically. When the query names a graph node id such as
`ontology:sales.crm:object/deal`, strip the `ontology:` graph prefix for the
`/by-ontology/<id>` path.

### `/om read-folder` (chat shorthand from the Knowledge Browser)

The Knowledge Browser's copy button on a top-level system, kind group, or domain-item node
emits a single `/om read-folder <axis>:<id>` line (or the legacy `/knowledge read-folder ...`
form) instead of N per-node `read` lines. Resolve it by the table below:

| Copy form                            | Resolution                                                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `/om read-folder system:<id>`        | `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`, then `om:cat` each                                                   |
| `/om read-folder kind:<kind>`        | `pnpm elevasis-sdk om:ls /by-kind/<kind> --ids-only`, then `om:cat` each                                                   |
| `/om read-folder owner:<id>`         | `pnpm elevasis-sdk om:ls /by-owner/<id> --ids-only`, then `om:cat` each                                                    |
| `/om read-folder ontology:<id>`      | `pnpm elevasis-sdk om:ls /by-ontology/<id> --ids-only`, then `om:cat` each                                                 |
| `/om read-folder item:<domain>:<id>` | `pnpm elevasis-sdk om:describe item:<domain>:<id>` -- returns profile + location + governing knowledge                     |
| `/om read-folder graph:<id>`         | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids                                   |
| `/om read-folder group:<id>`         | browser overview reference only; resolve by visible children -- `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`       |
| `/om read-folder domain:<domain>`    | browser overview reference only; resolve by enumerating domain -- `pnpm elevasis-sdk om:ls /by-domain/<domain> --ids-only` |
| `/om read-folder folder:<id>`        | browser overview reference only; treat as `domain:<id>` and enumerate with `/by-domain/<id>`                               |

**Legacy bridge -- `graph:client:<uuid>` and other `graph:<prefix>:<uuid>` domain-item forms:**
Older Knowledge Browser builds emitted `graph:client:<uuid>` for client items. This is a
graph-neighborhood shorthand, not a profile read. When you receive such a reference:

1. Resolve the graph neighborhood: `pnpm elevasis-sdk om:graph client:<uuid>` (may return empty or only `contains` edges -- that is expected; no `ClientProfile` is accessible this way).
2. For the rich profile, pivot to: `pnpm elevasis-sdk om:describe item:clients:<uuid>`.

In short: `graph:client:<uuid>` points to the graph node; `item:clients:<uuid>` resolves the
full org-model profile. Always use `item:` for profile reads going forward.

Dotted system ids may use either dots or slashes (`sales.crm` and `sales/crm` both work).
Legacy `feature:<id>` copy lines from older browser builds are compatibility aliases for
`system:<id>`; resolve through `/by-system/`. Per-node leaves still copy as
`/om read <node-id>` (or `/knowledge read <node-id>`).

`read-folder system:<id>` is the baseline knowledge read, not a mandatory full-system snapshot.
Start by loading governing knowledge nodes; broaden into adjacent OM context only when the
current task makes it relevant.

---

## Organization Model Navigation Guide

Use this map whenever the task asks what something is, where it lives, what governs it, or
what adjacent context may matter:

| Question                           | Start here                                                                                                                        | Then inspect                                                                                                                         |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| What Systems exist?                | `om:ls /all-systems`                                                                                                              | System IDs, parentage, lifecycle, UI metadata, and content                                                                           |
| What resources exist?              | `om:ls /all-resources`                                                                                                            | resource ids, kinds, owning System refs                                                                                              |
| What roles exist?                  | `om:ls /all-roles`                                                                                                                | role ids, titles, responsibilities                                                                                                   |
| What governs a System?             | `om:describe <system-id>` or `om:ls /by-system/<id>`                                                                              | system entry, governed knowledge, roles, policies, graph `governs` edges                                                             |
| What resources belong to a System? | the id-keyed `organizationModel.resources` map and `getResourcesForSystem(model, systemPath)`                                     | use `{ includeDescendants: true }` only for parent-scope rollups                                                                     |
| What can a System do?              | system action refs and the actions domain                                                                                         | `action.resourceId`, invocation metadata, affected entities, policies                                                                |
| What data does it own?             | entities domain                                                                                                                   | owning System refs, state catalogs, entity links, emitted/projected events                                                           |
| Is a platform API interface ready? | the System's `apiInterface` marker and `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md` | matching convention-locked System path, cataloged `readinessProfile`, derived resource ontology bindings, and scoped topology grants |
| What UI surface exposes it?        | `navigation.sidebar` plus `SystemModule` manifests                                                                                | route files, surface targets, route-prefix modules, guards                                                                           |
| What knowledge applies?            | `om:ls /by-system/<id>` plus graph edges                                                                                          | `om:cat`, `om:graph`, `/graph/<id>/governed-by`                                                                                      |

Do not treat any one read as a complete system snapshot. The OM is a set of related domain maps;
follow the relationship that matches the work. Prefer structured helpers from
`@elevasis/core/organization-model` over ad hoc string scanning when code access is available.

---

## System Taxonomy and Resource Placement

Use Systems for durable organizational capability boundaries, not implementation categories.

A System is appropriate only when it owns at least one of:

- Business or platform capability semantics
- System-local ontology/config
- Accountable roles or governance
- Resources that operate that capability
- Knowledge or policies that govern that capability

Do not create Systems for:

- Resource kinds such as `workflows`, `agents`, `scripts`, or `triggers`
- Shell or navigation groups such as `operations`, `monitoring`, `settings`, or `knowledge`
- Catch-all buckets such as `automation`, `misc`, `runtime`, or `tools`
- Individual UI pages or logs such as `command queue`, `task scheduler`, or `execution logs`
- One-off implementations that should be Resources

Resources still require `systemPath`. Choose the System by the capability the Resource supports,
not by its implementation type.

Placement examples:

- Scaffold/runtime smoke test `echo` -> `platform.diagnostics`
- Shared notification workflow -> `platform.notifications`
- Lead-gen workflow -> `sales.lead-gen`
- CRM or deal workflow -> `sales.crm`
- Project status workflow -> `projects`
- External integration credential/sync resource -> the business or platform System it serves, not
  `integrations` unless an actual integration-platform subsystem exists

Before adding a System:

1. Run `pnpm elevasis-sdk om:ls /all-systems`.
2. Run `pnpm elevasis-sdk om:describe <candidate-parent-or-owner>`.
3. If the proposed System name is a resource kind, shell group, or catch-all, do not create it;
   attach or create a Resource under the real owning System.
4. Create a new System only when no existing System owns the capability and the new System has
   durable ontology/config/governance meaning.

Current template placement convention:

- Platform cross-cutting subsystems live under `platform.*`.
- `platform.diagnostics` owns scaffold diagnostic resources.
- `platform.notifications` owns notification delivery.
- Tenant business workflows belong to the business System they operate, such as `sales.lead-gen`
  or `projects`.

---

## API Interface Readiness

`system.apiInterface` is adopt-only in tenant projects. It declares intent to adopt a platform-provided API capability from the installed `@elevasis/core` / `@elevasis/sdk` version; it is not a tenant extension point.

Use only readiness profiles listed in `node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`. The profile also fixes the required System path, such as `sales.lead-gen` or `sales.crm`. Do not invent a profile, and do not repoint a cataloged profile to a custom System path.

Readiness is derived, not hand-authored. After the marker is present, the validator checks ontology object/catalog types, scoped resources and their `resource.ontology` bindings, and any required scoped topology `uses` grants. Lead-gen to CRM handoff is represented as a scoped topology relationship under the cross-System boundary invariant, not as an authored bridge object.

Custom Systems should not carry `apiInterface`. Build custom behavior through `System.ontology`, `System.config`, resources, catalogs, topology, navigation, and workflows/operations. Runtime business logic belongs in workflows and agents registered by `operations/src/index.ts`; the tenant project does not add platform API routes.

Do not confuse ontology `interface` records with `system.apiInterface`. Ontology ids such as `<system>:interface/<local-id>` describe semantic model records under `System.ontology`; `system.apiInterface` is a flat System-level marker for closed platform API readiness.

---

## Shared Layering Preview

When opening a domain that uses a closed stage, status, or catalog vocabulary -- especially
prospecting, CRM, outreach, or another pipeline-like domain -- read the scaffold-shipped primer:

```bash
node_modules/@elevasis/sdk/reference/spine/spine-primer.md
```

Use it to emit a short domain layering preview before the normal read, describe, or codify flow:

1. **Catalog:** which `organizationModel.<domain>` catalog owns the keys, labels, descriptions,
   ordering, and entity ownership.
2. **Runtime state:** where record progress is stored as sparse state keyed by those catalog
   members.
3. **Producers:** which workflow resources, templates, or factories write entity-tagged results
   for those keys.
4. **Consumers:** which dashboards, queues, reports, filters, or API reads render or aggregate the
   same keys.

For vibe-coder sessions, translate this into plain language: "business profile", "saved progress",
"workflow resources", and "dashboard or reports". For technical sessions, it is acceptable to name
the catalog, state map, producer, and consumer surfaces directly.

---

## Write Power (Codify + Toggle Ceremony)

This tenant skill owns the full Codify and Toggle write surface. Every write runs the six-step
safety ceremony preserved verbatim from the legacy `/configure` flow.

### Step 1: Snapshot

Determine the target file for the domain being edited (see the domain reference file for
"Where it lives" guidance). Read that file into memory before any edit. This is the rollback
target. For unsplit projects the target is `core/config/organization-model.ts`; for split projects
use the appropriate sub-file (`profile.ts`, `systems.ts`, or `navigation.ts` under
`core/config/organization-model/`).

### Step 2: Propose

Show the diff in chat. Identify which domain and field changes. Present the proposed new value
in context alongside the current value.

For stage, status, or catalog vocabulary edits, include the shared-layer impact preview before
asking for confirmation. Name the affected catalog key, whether existing sparse runtime state may
contain the old key, which producers/templates reference it, and which consumers render or filter
by it.

### Step 3: Confirm

Pause for explicit user confirmation. Do not proceed without a clear yes. Permission prompts also
gate writes.

### Step 4: Write

Apply the edit using the Edit or Write tool.

### Step 5: Validate

Run both checks:

```bash
pnpm -C operations check-types   # TypeScript type-check
pnpm -C operations check         # Runtime schema validation (Zod parse)
```

### Step 6: Rollback

If any validation step fails, restore the file from the Step 1 snapshot and report the error.
The rollback is mandatory -- never leave the project in a broken state.

**Two-level ceremony:**

- **Level A** -- config-only edits to existing schema fields in a single config file under
  `core/config/` (the entry `organization-model.ts` for unsplit projects, or the appropriate
  sub-file for split projects — see the domain reference for the correct target).
  Execute: `.claude/skills/om/operations/codify-level-a.md`
- **Level B** -- new Zod extension files in `core/config/extensions/`. Gated to explicit user
  ask. On casual second mentions of a new type, suggest Level B and wait for confirmation rather
  than scaffolding automatically.
  Execute: `.claude/skills/om/operations/codify-level-b.md`

---

## Domain References

The following domain reference files document each org-model domain: schema fields, validation
rules, examples, and how to read or edit them. Load the relevant file when the user's intent
classification names a specific domain.

- `.claude/skills/om/operations/identity.md` -- identity domain
- `.claude/skills/om/operations/customers.md` -- customer segments
- `.claude/skills/om/operations/offerings.md` -- products and services
- `.claude/skills/om/operations/roles.md` -- role chart
- `.claude/skills/om/operations/goals.md` -- organizational goals
- `.claude/skills/om/operations/techStack.md` -- external integration registry
- `.claude/skills/om/operations/features.md` -- legacy compatibility notes for feature wording
- `.claude/skills/om/operations/labels.md` -- inline display labels on enum entries

---

## When NOT to Use This Skill

- Pure UI layout (no OM, no org-model entities, no knowledge graph)
- Workflow authoring or infrastructure work that doesn't reference org-model entities
- Status checks / ops questions about deployed resources -- those route through `/elevasis`
- Project/task management -- those route through `/project`

---

## Cross-Links

- `/configure` -- legacy org-model editor (pre-absorption). Absorbed into this skill; all Codify
  and Toggle intents now route here. `/configure` vocabulary still works as a domain hint
  (e.g. "configure identity" is parsed as domain=identity, intent=Describe-or-Codify).
- `node_modules/@elevasis/sdk/reference/spine/spine-primer.md` -- scaffold-shipped layering primer
  for stage/status/catalog vocabularies that coordinate business-profile entries, runtime progress,
  producers, and consumers in tenant projects.

---

**Last Updated:** 2026-06-06
