---
description: Platform workflows, agents, resource definitions, and deployment for the operations/ surface
paths:
  - operations/**
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# Operations

**Status:** Stable

## Overview

The `operations/` directory contains platform resources and deployment metadata that deploy to the Elevasis platform. It is a standalone TypeScript project with its own `package.json`, `tsconfig.json`, and dependencies.

**Discovering deployed resources:** Read `operations/src/index.ts` for deployment assembly and `core/config/organization-model.ts` for the OM Resources descriptor catalog. Run `pnpm elevasis-sdk project:list --pretty` against the live DB for the deployed surface.

## Echo Workflow (Starter Example)

**Location:** `operations/src/example/echo.ts`

The echo workflow accepts a message string and returns it unchanged. Its purpose is the wiring, not the logic: input and output schemas are defined in `core/types/index.ts` and imported by both the workflow and the frontend.

```
core/types/index.ts             -- defines echoInputSchema, echoOutputSchema
operations/src/example/echo.ts  -- imports schemas for workflow contract
ui/src/routes/                  -- imports schemas for form validation and display
```

The workflow is registered in `operations/src/index.ts` as part of the `example` group and deployed with `pnpm -C operations deploy`.

## Adding a New Workflow

1. **Define the descriptor in `core/config/organization-model.ts`** -- Add the OM Resource descriptor under the id-keyed `resources` map so identity, System membership, owner role, and governance status are authored once.

2. **Model the semantic surface** -- Add durable business nouns, verbs, catalogs, links, events, and surfaces to the owning System's `ontology`; bind executable Resources through `resource.ontology.actions` and optional `resource.ontology.primaryAction`; add system-local defaults/settings to `System.config`; add explanatory or governing material to `knowledge`; and keep transient DTOs and handler internals out of the OM. Top-level `entities`, top-level `actions`, and `System.content` are compatibility mirrors only when current published consumers still need them.

3. **Define the contract in `core/types/`** -- Add Zod schemas and inferred types to `core/types/index.ts` (or a new file under `core/types/`). Use `core/types/entities.ts` when workflows operate on project-specific entity contracts.

4. **Implement the workflow in `operations/src/`** -- Create a new directory under `operations/src/` for the feature. Import the descriptor, derive runtime `resourceId`, `type`, `name`, and `description` from it, export the workflow from its `index.ts`, and register it in `operations/src/index.ts`.

   Workflow-side signing and platform adapter error bucketing should use the worker SDK surface: import `generateHmacToken` and `classifyPlatformToolError` from `@elevasis/sdk/worker`. Keep provider-specific timeout messages, error codes, and message snippets in tenant code, then pass them into the generic classifier.

5. **Add the UI in `ui/src/routes/`** -- Create a new route file. Use TanStack Query to call the workflow execution endpoint. Import schemas from `@core/types` for validation and type inference. Read OM resources, ontology, knowledge, and graph data where possible instead of creating page-local semantic registries.

6. **Update rules when the pattern persists** -- If the workflow introduces a reusable adapter pattern, checkpoint/schedule convention, domain vocabulary, or workflow family behavior that future agents must follow, update this rule or add a scoped rule under `.claude/rules/` in the same change.

7. **Deploy and verify:**

```bash
pnpm -C operations check        # validate resource definitions
pnpm -C operations deploy       # deploy to dev
```

## Resource Registry

`operations/src/index.ts` default-exports a `DeploymentSpec` with `version`, `organizationModel`, `workflows`, `agents`, and optional deployment mechanics such as `triggers`, `integrations`, `relationships`, `humanCheckpoints`, and `externalResources`. Durable operational wiring belongs in `organizationModel.topology.relationships`; deployment mechanics, credentials, provider webhook details, and per-run state stay outside the OM. Each feature group exports `workflows` and `agents` arrays from its own `index.ts`, spread into the top-level spec. `DeploymentSpec` assembles deployable behavior; it should not be treated as a second resource identity catalog.

When you need breadth first, read:

- `operations/src/README.md` for the source boundary and drill-down guidance
- `core/config/organization-model.ts` for descriptor identity and governance metadata
- `operations/src/index.ts` for deployment assembly
- `pnpm elevasis-sdk project:list --pretty` for the live deployed surface

## Commands

| Command                          | Purpose                       |
| -------------------------------- | ----------------------------- |
| `pnpm -C operations check`       | Validate resource definitions |
| `pnpm -C operations check-types` | TypeScript type-check         |
| `pnpm -C operations deploy`      | Deploy to dev                 |
| `pnpm -C operations deploy:prod` | Deploy to production          |

Always run `check` before `deploy`.

## Rule Updates

When developing resources, workflows, agents, integrations, checkpoints, schedules, or recurring operational conventions, keep `.claude/rules/` current.

- Update `operations.md` for package-wide operations invariants.
- Add a scoped rule for domain-specific workflow families whose conventions should autoload for future edits.
- Do not bury durable operational rules only in task notes or chat context.
