@elevasis/sdk 1.5.5 → 1.7.0

package/reference/claude-config/skills/configure/operations/labels.md

@@ -0,0 +1,128 @@
+# Configure: labels
+
+Guides the user through editing inline display labels on enum entries in the organization model.
+
+Labels are the `label` field carried by status entries, stage entries, and other enum-like
+elements in the model. They control what users see in the UI and what agents say when narrating
+state. Editing a label does not change the entry's `id` or `semanticClass` -- only the
+human-readable display string.
+
+This operation is Level A only (config-only edits to `foundations/config/organization-model.ts`).
+No new TypeScript files are created.
+
+## What has labels
+
+The following model elements carry inline `label` fields that are editable here:
+
+**Statuses (sales domain -- deal pipeline stages):**
+Located in `foundations/config/organization-model.ts` under `sales.statuses` or in the platform
+defaults at `packages/core/src/organization-model/domains/sales.ts`.
+
+Each status entry shape (example):
+
+```typescript
+{ id: 'new', label: 'New Lead', semanticClass: 'active', color: 'blue' }
+```
+
+**Statuses (prospecting domain -- lead lifecycle stages):**
+Located under `prospecting.statuses` or in `packages/core/src/organization-model/domains/prospecting.ts`.
+
+**Statuses (projects domain -- project and task stages):**
+Located under `projects.statuses` or in `packages/core/src/organization-model/domains/projects.ts`.
+
+**Features (`label` field):**
+The display label on a feature entry (e.g. changing "CRM" to "Sales Pipeline"). Editing this
+changes sidebar nav text and any agent narration that references the feature by label.
+
+**Navigation surfaces (`label` field):**
+Surface entries in the `navigation.surfaces` array each carry a `label`. Editing changes
+breadcrumb text and nav item display.
+
+The `id` and `semanticClass` of any entry must never be changed here -- those are structural
+anchors. Only `label` (and optionally `color` or `icon`) are in scope for this operation.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Ask the user which domain's labels they want to edit:
+
+- Deal pipeline stages (sales)
+- Lead lifecycle stages (prospecting)
+- Project/task stages (projects)
+- Feature names
+- Navigation surface names
+
+Read `foundations/config/organization-model.ts` and the relevant platform defaults file for the
+selected domain. Present all current label values for that domain:
+
+```
+Current labels -- sales (deal pipeline stages):
+  new              "New Lead"
+  contacted        "Contacted"
+  qualified        "Qualified"
+  proposal         "Proposal Sent"
+  negotiation      "In Negotiation"
+  closed_won       "Closed Won"
+  closed_lost      "Closed Lost"
+```
+
+### Step 2: Gather changes
+
+Ask which labels the user wants to change. Work one at a time or accept a list:
+
+- "Which label do you want to rename? (by current label or ID)"
+- "What should it say instead?"
+
+Validate:
+
+- Max 120 characters
+- Non-empty
+- No change to the `id` or `semanticClass`
+
+If the user wants to change a `color` or `icon` alongside the label, accept that too.
+
+### Step 3: Confirm before writing
+
+Present a diff:
+
+```
+Proposed label changes -- sales:
+  new:          "New Lead" -> "Inbound Lead"
+  proposal:     "Proposal Sent" -> "Proposal Out"
+  negotiation:  (unchanged)
+
+Apply? (yes/no)
+```
+
+### Step 4: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md`.
+
+The write targets only the affected entries in the selected domain array. Entries not being
+changed are left exactly as they are. The `id` and `semanticClass` of every entry must remain
+unchanged in the output.
+
+### Step 5: Report
+
+After successful validation:
+
+```
+Labels updated.
+  Domain: {domain name}
+  Changed: {list of id: "old" -> "new"}
+  foundations/config/organization-model.ts -- {domain}.statuses updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Labels update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts -- restored to previous state
+  No changes persisted.
+```

package/reference/claude-config/skills/configure/operations/offerings.md

@@ -0,0 +1,159 @@
+# Configure: offerings
+
+Guides the user through reviewing and updating the `offerings` domain of the organization model.
+
+The `offerings` domain describes what the organization sells or delivers — a catalog of products
+and services modeled after Business Model Canvas "Value Propositions". Agents use offerings for
+quoting, proposal generation, and scope-of-work reasoning.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/offerings.ts`
+
+```typescript
+OfferingsDomainSchema = z.object({
+  products: z.array(ProductSchema).default([])
+})
+
+ProductSchema = z.object({
+  id:               z.string().trim().min(1).max(100),       // stable ID, e.g. "product-starter-plan"
+  name:             z.string().trim().max(200).default(''),  // display name
+  description:      z.string().trim().max(2000).default(''), // what it delivers
+  pricingModel:     PricingModelSchema.default('custom'),    // 'one-time' | 'subscription' | 'usage-based' | 'custom'
+  price:            z.number().min(0).default(0),            // base price amount (≥ 0)
+  currency:         z.string().trim().max(10).default('USD'),// ISO 4217, e.g. "USD", "EUR"
+  targetSegmentIds: z.array(z.string()).default([]),         // must ref customers.segments[].id
+  deliveryFeatureId: z.string().optional()                   // optional ref to features[].id
+})
+```
+
+`pricingModel` values:
+
+- `one-time` — single purchase (setup fee, project fee)
+- `subscription` — recurring (monthly/annual SaaS, retainer)
+- `usage-based` — metered by consumption (API calls, seats)
+- `custom` — negotiated or bespoke pricing
+
+Cross-reference constraints enforced at parse time:
+
+- `targetSegmentIds` entries must exist in `customers.segments[].id`
+- `deliveryFeatureId` (when present) must exist in `features[].id`
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `offerings`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `offerings.products` array.
+Also extract `customers.segments` (for cross-reference display) and `features` (for
+`deliveryFeatureId` reference).
+
+Present a summary:
+
+```
+Current offerings (N):
+  1. {name} ({id}) — {pricingModel} — {price} {currency}
+     Targets: {segment names or "(none)"}
+  (none defined yet)
+```
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add** a new product/service
+- **Edit** an existing product (by name or number)
+- **Remove** a product
+- **Review all** in detail
+
+### Step 3: Gather product details
+
+For each product being added or edited:
+
+**Core identity:**
+
+- "What's the name of this offering? (e.g. 'Starter Plan', 'Full-Service Retainer', 'One-Time Audit')"
+- "Give it a stable ID — lowercase with hyphens, like `product-starter-plan`."
+- "Describe what this product/service delivers in one or two sentences."
+
+**Pricing:**
+
+- "How is this priced? Options: one-time payment, subscription (recurring), usage-based (metered),
+  or custom/negotiated."
+- "What's the base price? (Enter 0 if pricing is fully custom or not yet set.)"
+- "What currency? (Default: USD)"
+
+**Targeting:**
+
+- "Which customer segments does this offering target?"
+  Show the available segments by name. The user can select by name; translate to IDs.
+  If no segments are defined yet, note this and suggest configuring customers first.
+
+**Platform delivery (optional):**
+
+- "Is there a platform feature responsible for delivering this offering? (e.g. the CRM feature,
+  the Projects feature)" Show available feature IDs. This field is optional.
+
+If a field already has a value, show it and ask "Keep this or update it?"
+
+### Step 4: Confirm before writing
+
+Present a diff for the affected product(s):
+
+```
+Proposed offerings change:
+
+ADD product "Full-Service Retainer" (product-full-service-retainer):
+  name:             "Full-Service Retainer"
+  description:      "End-to-end campaign delivery, reporting, and optimization for SMB clients."
+  pricingModel:     "subscription"
+  price:            2500
+  currency:         "USD"
+  targetSegmentIds: ["segment-smb-agencies"]
+  deliveryFeatureId: (not set)
+
+Apply? (yes/no)
+```
+
+### Step 5: Cross-reference validation
+
+Before writing, verify:
+
+1. Every `targetSegmentIds` entry exists in the current `customers.segments[].id` array in the
+   adapter. If any are missing, surface the discrepancy and ask whether to add the missing segment
+   first or proceed without the reference.
+2. If `deliveryFeatureId` is provided, verify it exists in `features[].id`. If not found, surface
+   a warning and offer to omit the field.
+
+### Step 6: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `offerings`
+block. Only the `products` array is written — no other keys in the adapter are touched.
+
+When adding a product, append to the array. When editing, replace by `id`. When removing, filter
+out and also surface any `targetSegmentIds` in other products referencing the removed ID.
+
+### Step 7: Report
+
+After successful validation:
+
+```
+Offerings updated.
+  Products: {total count} ({N added / N edited / N removed})
+  foundations/config/organization-model.ts — offerings.products updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Offerings update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts — restored to previous state
+  No changes persisted.
+```

package/reference/claude-config/skills/configure/operations/roles.md

@@ -0,0 +1,153 @@
+# Configure: roles
+
+Guides the user through reviewing and updating the `roles` domain of the organization model.
+
+The `roles` domain describes who does what inside the organization — a role chart inspired by the
+EOS Accountability Chart but using plain-language field names throughout. Agents use this domain
+for HITL routing, escalation logic, and approval-rights reasoning.
+
+Field names are developer-facing; user-facing prompts should say "role", "responsibilities",
+"reports to", and "held by". Do not say "seat", "accountability", or "EOS".
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/roles.ts`
+
+```typescript
+RolesDomainSchema = z.object({
+  roles: z.array(RoleSchema).default([])
+})
+
+RoleSchema = z.object({
+  id:               z.string().trim().min(1).max(100),              // stable ID, e.g. "role-ceo"
+  title:            z.string().trim().min(1).max(200),              // display title, e.g. "CEO"
+  responsibilities: z.array(z.string().trim().max(500)).default([]),// what this role owns
+  reportsToId:      z.string().trim().min(1).max(100).optional(),   // must ref another roles[].id
+  heldBy:           z.string().trim().max(200).optional()           // name or email, free-form
+})
+```
+
+Cross-reference constraint: `reportsToId` (when present) must resolve to another `roles[].id` in
+the same collection. Enforced at parse time by `OrganizationModelSchema.superRefine()`. Cycle
+detection is not enforced (known limitation).
+
+Absence of `reportsToId` indicates a top-level role (no reporting line).
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `roles`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `roles.roles` array.
+Present it as a role chart summary:
+
+```
+Current roles (N):
+  {title} ({id})
+    Held by: {heldBy or "(unassigned)"}
+    Reports to: {reportsToId resolved to title, or "(top-level)"}
+    Responsibilities: {count or "(none listed)"}
+  (none defined yet)
+```
+
+If the array is empty, note that an empty roles chart means no HITL routing or escalation rules
+are available yet.
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add** a new role
+- **Edit** an existing role (by title or number)
+- **Remove** a role
+- **Review all** in detail (show full responsibilities lists)
+
+### Step 3: Gather role details
+
+For each role being added or edited:
+
+**Core identity:**
+
+- "What's the title of this role? (e.g. 'CEO', 'Head of Client Success', 'Operations Lead')"
+- "Give it a stable ID — lowercase with hyphens, like `role-ceo` or `role-head-of-client-success`."
+
+**Reporting line:**
+
+- "Does this role report to another role? If so, which one?"
+  Show the existing roles by title. Translate selection to ID. If none, it becomes a top-level role.
+
+**Responsibilities:**
+
+- "What are the main things this role is accountable for? List them one at a time — I'll capture
+  each as a separate responsibility."
+
+**Who holds it (optional):**
+
+- "Who currently holds this role? A name or email address works — or leave it blank if it's
+  unassigned."
+
+If a field already has a value, show it and ask "Keep this or update it?"
+
+### Step 4: Confirm before writing
+
+Present a diff for the affected role(s):
+
+```
+Proposed roles change:
+
+ADD role "CEO" (role-ceo):
+  title:            "CEO"
+  responsibilities: ["Set company direction", "Final approval on deals >$10K", "Manage investor relations"]
+  reportsToId:      (none — top-level)
+  heldBy:           "Alice Johnson"
+
+ADD role "Head of Client Success" (role-head-of-client-success):
+  title:            "Head of Client Success"
+  responsibilities: ["Own client health scores", "Lead QBRs", "Handle escalations"]
+  reportsToId:      "role-ceo"
+  heldBy:           (unassigned)
+
+Apply? (yes/no)
+```
+
+### Step 5: Cross-reference validation
+
+Before writing, verify:
+
+1. Every `reportsToId` in the proposed changes resolves to an ID that will exist after the write
+   (either already present in the array or being added in this batch).
+2. If a role being removed has other roles that `reportsToId` to it, surface those orphaned
+   references and ask whether to clear the reporting lines before proceeding.
+
+### Step 6: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `roles` block.
+Only the `roles` array is written — no other keys in the adapter are touched.
+
+When adding, append in declaration order (top-level roles first, then reporting roles). When
+editing, replace by `id`. When removing, filter out.
+
+### Step 7: Report
+
+After successful validation:
+
+```
+Roles updated.
+  Roles: {total count} ({N added / N edited / N removed})
+  foundations/config/organization-model.ts — roles.roles updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Roles update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts — restored to previous state
+  No changes persisted.
+```

package/reference/claude-config/skills/configure/operations/techStack.md

@@ -0,0 +1,139 @@
+# Configure: techStack
+
+Guides the user through reviewing and updating the tech stack metadata on resource mapping entries
+in the organization model.
+
+Tech stack information lives as an optional `techStack` extension field on each `ResourceMapping`
+entry -- not as a standalone top-level domain. This keeps all integration metadata co-located with
+the resource mapping that represents it, while adding fields that agents need for cross-integration
+automation and system-of-record resolution.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/shared.ts`
+
+```typescript
+TechStackEntrySchema = z.object({
+  platform:         z.string().trim().min(1).max(200),
+  purpose:          z.string().trim().min(1).max(500),
+  credentialStatus: z.enum(['configured', 'pending', 'expired', 'missing']),
+  isSystemOfRecord: z.boolean().default(false)
+})
+```
+
+`credentialStatus` values:
+
+- `configured` -- credential present and valid
+- `pending` -- not yet set up
+- `expired` -- credential existed but has lapsed
+- `missing` -- expected but not present
+
+`isSystemOfRecord: true` means this integration is the authoritative data source for its domain
+(e.g. HubSpot is the system of record for contacts).
+
+`techStack` is an optional field on `ResourceMappingSchema`. It is added to individual resource
+mapping entries whose `resourceType` is `'integration'` or `'external'`.
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` inside the
+`resourceMappings` array of `defineOrganizationModel({...})`. The `techStack` field is set on the
+matching `ResourceMapping` object.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the `resourceMappings` array. Filter
+to entries that either already have a `techStack` field or have `resourceType: 'integration'` or
+`'external'`. Present as a summary:
+
+```
+Resource mappings with integration context (N):
+  {label} ({id}) -- resourceType: {type}
+    techStack: {platform} | {credentialStatus} | SoR: {yes/no}
+    (no techStack yet)
+
+Other resource mappings (M total, K without techStack):
+  {list by label}
+```
+
+If there are no resource mappings at all, note that the user should add resource mappings through
+the SDK deployment process before configuring tech stack metadata here.
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add or update** tech stack metadata on an existing resource mapping
+- **Update credential status** on an existing tech stack entry
+- **Mark or unmark** an integration as the system of record
+- **Review all** integration health
+
+For adding or updating, the user selects a resource mapping from the list.
+
+### Step 3: Gather tech stack details
+
+For each resource mapping being updated:
+
+**If no `techStack` field yet:**
+
+- "What external platform does this resource mapping represent? (e.g. 'HubSpot', 'Stripe',
+  'Notion', 'Apify')"
+- "What is this integration used for? (free-form description)"
+- "What is the current credential status? Options: configured, pending, expired, missing."
+- "Is this the system of record for its domain? (e.g. HubSpot is SoR for contacts)"
+
+**If `techStack` already exists:**
+
+Show the current values and ask which fields to update.
+
+Credential status shortcut: if the user only wants to mark a credential as configured or expired,
+skip directly to that field.
+
+### Step 4: Confirm before writing
+
+Present a diff scoped to the affected resource mapping entry:
+
+```
+Proposed techStack change:
+
+UPDATE resourceMapping "HubSpot CRM Integration" (rm-hubspot):
+  techStack:
+    platform:         "HubSpot"
+    purpose:          "CRM for contacts, companies, and deal pipeline"
+    credentialStatus: "pending" -> "configured"
+    isSystemOfRecord: false -> true
+
+Apply? (yes/no)
+```
+
+### Step 5: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed change to the
+`resourceMappings` array. Only the targeted entry (matched by `id`) is modified -- all other
+entries are left unchanged.
+
+The write edits the `techStack` field on the matching `ResourceMapping` object inside the
+`defineOrganizationModel({...})` call.
+
+### Step 6: Report
+
+After successful validation:
+
+```
+Tech stack updated.
+  Integrations: {total with techStack} ({N updated})
+  foundations/config/organization-model.ts -- resourceMappings updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Tech stack update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts -- restored to previous state
+  No changes persisted.
+```