---
name: build
description: Guided Codify-ceremony runbook for building a new Organization Model System end to end in a tenant project — shell, ontology, resources, topology, knowledge node, and verify.
allowed-tools: Read, Glob, Grep, Bash
---

# /om build (Tenant)

Intent-driven runbook for authoring a complete Organization Model System in this tenant project.
The **primary entry is intent**: `/om` routes free-text build intent here via `promptSignals` and
the 5-bucket classifier whenever you describe a system you want to build. Manual `/om build` is a
supported secondary entry.

Every write runs through the Codify ceremony (snapshot → propose → confirm → write → validate →
rollback). See the "Write Power" section in `SKILL.md` for the ceremony steps.

**Tenant authoring files** (split layout):

- `core/config/organization-model/systems.ts` — System entries and system-owned resources
- `core/config/organization-model/navigation.ts` — sidebar wiring
- `core/config/knowledge/nodes/` — knowledge node MDX files

---

## Phase 0 — Capture Intent

Before writing anything, extract:

1. **System name and dotted path** (`parent.child` format, e.g. `sales.crm`).
2. **Kind**: `product`, `operational`, `platform`, or `diagnostic`.
3. **What it does** — one sentence. This becomes the `description`.
4. **What it owns** — objects, actions, catalogs, events (these become `system.ontology` entries).
5. **What it calls or reacts to** — other systems, triggers, human checkpoints.
6. **Whether it needs a UI route** — yes/no determines whether `system.ui` is authored.
7. **Whether it adopts a platform API interface** — yes/no determines whether `system.apiInterface`
   is authored (see "API Interface Readiness" in `SKILL.md`).

Run a pre-flight read to ground id choices in current model state:

```bash
pnpm elevasis-sdk om:ls /all-systems
```

---

## Phase 1 — System Shell (Codify Level-A)

Use `om:scaffold:system` (dry-run first) or the Codify Level-A ceremony to add the `SystemEntry`
to `core/config/organization-model/systems.ts`.

**Dry-run:**

```bash
pnpm elevasis-sdk om:scaffold:system --dry-run
```

Minimum fields: `id`, `order`, `label`. Optional at this stage: `description`, `kind`,
`lifecycle`, `responsibleRoleId`.

**Validate after write:**

```bash
pnpm -C operations check-types
pnpm -C operations check
```

---

## Phase 2 — Ontology (`system.ontology`)

Add owned ontology kinds inside the `ontology` field of the `SystemEntry` in `systems.ts`.

Valid scope keys: `objectTypes`, `linkTypes`, `actionTypes`, `catalogTypes`, `eventTypes`,
`interfaceTypes`, `valueTypes`, `sharedProperties`, `groups`, `endpoints`.

All ids use the canonical format: `system.path:kind/local-id`
(e.g. `sales.crm:object/deal`, `sales.crm:action/qualify-lead`).

Apply via the Codify Level-A ceremony — read, propose diff, confirm, write, validate.

**Validate after write:**

```bash
pnpm -C operations check-types
pnpm -C operations check
```

---

## Phase 3 — Resources (Codify Level-A + scaffold)

Add resource entries to `systems.ts` (or the split `resources` section if your project uses one).
Each resource carries `systemPath` (canonical system attachment) and `ontology` bindings.

Use `om:scaffold:resource` for guided creation, or Codify Level-A for manual addition.

**Dry-run:**

```bash
pnpm elevasis-sdk om:scaffold:resource --dry-run --system-path <your.system>
```

Key invariants:

- `resource.systemPath` is the canonical attachment for `getResourcesForSystem()`.
- Choose `systemPath` based on the business capability the resource operates, not its kind.
- `primaryAction` must be a member of `resource.ontology.actions`.

**Validate after write:**

```bash
pnpm -C operations check-types
pnpm -C operations check
```

---

## Phase 4 — Topology (optional)

If the system reacts to events, calls other systems, or requires human checkpoints, author
topology relationships. In a tenant project, topology lives alongside the System entries in
`systems.ts` (or a dedicated `topology` field if your project uses the split layout with a
separate topology section).

Canonical relationship kinds:

- `triggers` — event, webhook, or schedule fires a resource handler
- `uses` — this system calls another system or integration
- `approval` — a step requires human checkpoint before continuing

Cross-system API handoff requires a `uses` edge with `systemInterfaceGrant` metadata — see the
"API Interface Readiness" section in `SKILL.md`.

Apply via Codify Level-A ceremony. Validate after each topology write.

---

## Phase 5 — Knowledge Node (optional)

Author a governing knowledge node to make the system searchable via `/om` and surfaced in the
knowledge browser.

Use `om:scaffold:knowledge` for guided creation:

```bash
pnpm elevasis-sdk om:scaffold:knowledge --dry-run --system-path <your.system> --kind playbook
```

MDX frontmatter shape:

```mdx
---
id: knowledge.my-system-playbook
kind: playbook
label: My System Playbook
description: Rules and patterns for operating My System.
governs:
  - my.system
---
```

After authoring, regenerate the knowledge index:

```bash
pnpm elevasis-sdk om:generate
```

---

## Phase 6 — UI and Navigation (optional)

If the system needs a sidebar entry, author `system.ui` and add a navigation surface entry.

`system.ui` fields: `path`, `surfaces[]`, `icon`, `order`. Apply via Codify Level-A.

Navigation wiring lives in `core/config/organization-model/navigation.ts`. Add the system's
path to the relevant sidebar section. Validate after the navigation write.

---

## Phase 7 — apiInterface (API-backed systems only)

`system.apiInterface` is adopt-only in tenant projects. Only add it when the system adopts a
platform-provided API capability from the installed `@elevasis/core` / `@elevasis/sdk` version.
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 — do not invent a profile or repoint a cataloged
profile to a custom path.

Apply via Codify Level-A after confirming the readiness profile with the user:

```bash
pnpm -C operations check-types
pnpm -C operations check   # conformance gate fires here if the marker is incomplete
```

---

## Phase 8 — Full Verify

Run both validation gates once all phases are done:

```bash
pnpm -C operations check-types
pnpm -C operations check
```

If the conformance gate reports a gaps file, apply it:

```bash
pnpm elevasis-sdk om:scaffold:fill --gaps .elevasis/conformance-gaps.json --dry-run
```

---

## Quick Reference

| Phase | OM Slot                           | Authoring File                    | Ceremony                |
| ----- | --------------------------------- | --------------------------------- | ----------------------- |
| 1     | `systems` map                     | `systems.ts`                      | Scaffold or Level-A     |
| 2     | `system.ontology.<scope>`         | `systems.ts`                      | Level-A                 |
| 3     | resources + `resource.systemPath` | `systems.ts`                      | Scaffold or Level-A     |
| 4     | topology relationships            | `systems.ts` / topology section   | Level-A                 |
| 5     | `system.governedByKnowledge[]`    | `knowledge/nodes/<path>/<id>.mdx` | Scaffold or Level-A     |
| 6     | `system.ui` + navigation surfaces | `systems.ts` + `navigation.ts`    | Level-A                 |
| 7     | `system.apiInterface`             | `systems.ts`                      | Level-A (adopt-only)    |
| 8     | —                                 | —                                 | `check` + `check-types` |

---

## Cross-Links

- Codify Level-A ceremony: `.claude/skills/om/operations/codify-level-a.md`
- Scaffold (guided new entries): `.claude/skills/om/operations/scaffold.md`
- API interface readiness: "API Interface Readiness" section in `.claude/skills/om/SKILL.md`
- Platform narrative guide + worked examples: `node_modules/@elevasis/sdk/reference/guides/building-systems.md` (if present)
