@elevasis/sdk 1.5.5 → 1.7.0

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

@@ -0,0 +1,150 @@
+# Configure: customers
+
+Guides the user through reviewing and updating the `customers` domain of the organization model.
+
+The `customers` domain describes who the organization serves — distinct buyer archetypes modeled
+after the Value Proposition Canvas (BMC / VPC). Each segment captures jobs-to-be-done, pains,
+gains, firmographics, and a value proposition. Agents use these segments for targeting, outreach
+context, and personalization.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/customers.ts`
+
+```typescript
+CustomersDomainSchema = z.object({
+  segments: z.array(CustomerSegmentSchema).default([])
+})
+
+CustomerSegmentSchema = z.object({
+  id:           z.string().trim().min(1).max(100),             // stable ID, e.g. "segment-smb-agencies"
+  name:         z.string().trim().max(200).default(''),        // display name
+  description:  z.string().trim().max(2000).default(''),       // who this segment is
+  jobsToBeDone: z.string().trim().max(2000).default(''),       // the goal they hire you to accomplish
+  pains:        z.array(z.string().trim().max(500)).default([]),
+  gains:        z.array(z.string().trim().max(500)).default([]),
+  firmographics: FirmographicsSchema.default({}),              // industry, companySize, region
+  valueProp:    z.string().trim().max(2000).default('')         // why your offering fits this segment
+})
+
+FirmographicsSchema = z.object({
+  industry:    z.string().trim().max(200).optional(),  // e.g. "Marketing Agency"
+  companySize: z.string().trim().max(100).optional(),  // e.g. "11–50"
+  region:      z.string().trim().max(200).optional()   // e.g. "North America"
+})
+```
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `customers`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `customers.segments` array.
+Present it as a summary table:
+
+```
+Current customer segments (N):
+  1. {name} ({id}) — {description truncated to 80 chars}
+  2. ...
+  (none defined yet)
+```
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add** a new segment
+- **Edit** an existing segment (by name or number)
+- **Remove** a segment
+- **Review all** segments in detail
+
+Handle one segment at a time unless the user explicitly asks to work on multiple at once.
+
+### Step 3: Gather segment details
+
+For each segment being added or edited, work through the fields conversationally:
+
+**Core identity:**
+
+- "What's a good name for this segment? (e.g. 'SMB Marketing Agencies', 'Enterprise SaaS Companies')"
+- "Give it a stable ID I'll use as a key — lowercase with hyphens, like `segment-smb-agencies`."
+- "How would you describe who this segment is in one or two sentences?"
+
+**Jobs-to-be-done:**
+
+- "What is the main job this segment is trying to get done? The goal they hire you to accomplish —
+  describe it in their terms, not yours."
+
+**Pains and gains:**
+
+- "What are two or three frustrations or obstacles this segment runs into when trying to get that
+  job done?"
+- "What outcomes or benefits are they hoping for — beyond just fixing the pain?"
+
+**Firmographics (optional):**
+
+- "Do you want to capture firmographic filters for targeting? Things like industry vertical,
+  typical company size, and geographic region."
+
+**Value proposition:**
+
+- "How does your organization's offering uniquely address this segment's needs? One or two sentences."
+
+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 segment(s):
+
+```
+Proposed customers change:
+
+ADD segment "SMB Marketing Agencies" (segment-smb-agencies):
+  name:         "SMB Marketing Agencies"
+  description:  "Owner-operated agencies with 1–15 employees running campaign delivery for SMB clients."
+  jobsToBeDone: "Deliver consistent client results without adding headcount."
+  pains:        ["Manual campaign QA", "Client reporting takes hours", "Hard to scale without hiring"]
+  gains:        ["More client capacity without more staff", "Predictable delivery timelines"]
+  firmographics: { industry: "Marketing Agency", companySize: "1–15", region: "North America" }
+  valueProp:    "Automates the repetitive delivery and reporting work so agencies can take on more clients."
+
+Apply? (yes/no)
+```
+
+For edits to existing segments, show only the fields that changed.
+
+### Step 5: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `customers`
+block. Only the `segments` array is written — no other keys in the adapter are touched.
+
+When adding a segment, append to the array. When editing, replace the matching entry by `id`.
+When removing, filter it out.
+
+Cross-reference note: if `offerings.products[].targetSegmentIds` references a segment being
+removed, surface a warning and ask the user whether to clean up those references before writing.
+
+### Step 6: Report
+
+After successful validation:
+
+```
+Customers updated.
+  Segments: {total count} ({N added / N edited / N removed})
+  foundations/config/organization-model.ts — customers.segments updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Customers 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/features.md

@@ -0,0 +1,163 @@
+# Configure: features
+
+Guides the user through enabling, disabling, or adding features in the organization model.
+
+Features are the top-level capability switches in the platform. Enabling a feature makes its nav
+items and routes visible; disabling hides them without removing the feature from the model. Adding
+a new feature may require only a config edit (Level A) or a new extension TypeScript file
+(Level B), depending on whether the feature already exists in the platform defaults.
+
+This operation handles both toggling existing features and introducing custom features. For
+surface-level toggles (hiding one sub-section within an already-enabled feature), use
+`/org-os manage` instead.
+
+## Background: Level A vs Level B
+
+- **Level A (config-only edit):** The feature exists in the platform defaults
+  (`packages/core/src/organization-model/defaults.ts`). The adapter in
+  `foundations/config/organization-model.ts` overrides its `enabled` flag or adjusts metadata.
+  No new TypeScript files needed.
+
+- **Level B (new extension file):** The feature does not exist in platform defaults. A new
+  feature ID and manifest need to be declared. This requires a new TypeScript file under
+  `foundations/config/extensions/` plus wiring it into the adapter. Level B is only offered when
+  the user explicitly asks to create a custom feature.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/features.ts`
+
+```typescript
+FeatureSchema = z.object({
+  id:           ModelIdSchema,               // lowercase, e.g. "crm", "lead-gen", "seo"
+  label:        LabelSchema,                 // display label
+  description:  DescriptionSchema.optional(),
+  enabled:      z.boolean().default(true),
+  color:        ColorTokenSchema.optional(),
+  icon:         IconNameSchema.optional(),
+  entityIds:    ReferenceIdsSchema,
+  surfaceIds:   ReferenceIdsSchema,
+  resourceIds:  ReferenceIdsSchema,
+  capabilityIds: ReferenceIdsSchema
+})
+```
+
+Platform default feature IDs (from `packages/core/src/organization-model/contracts.ts`):
+`crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `seo`
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `features`
+array of `defineOrganizationModel({...})`. The `features` array replaces entirely (no element
+merge), so the adapter must redeclare all features it wants to override.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `features` array from the
+adapter. Also read `packages/core/src/organization-model/defaults.ts` to see what the platform
+defaults look like.
+
+Present a combined view:
+
+```
+Platform features (current state):
+  crm          [enabled]  -- CRM (adapter override or platform default)
+  lead-gen     [enabled]  -- Lead Generation
+  projects     [enabled]  -- Projects
+  operations   [enabled]  -- Operations
+  monitoring   [enabled]  -- Monitoring
+  settings     [enabled]  -- Settings
+  seo          [disabled] -- SEO (disabled in platform default)
+
+Custom features (adapter-only):
+  (none)
+```
+
+### Step 2: Establish intent
+
+Ask what the user wants to do:
+
+- **Enable** a disabled feature
+- **Disable** an enabled feature
+- **Add a custom feature** (Level B -- will ask for explicit confirmation)
+- **Edit metadata** on an existing feature (label, color, icon)
+
+For enable/disable: this is Level A. For custom add: escalate to Level B branch.
+
+### Step 3a: Level A -- Enable or disable
+
+For an enable or disable request:
+
+- Identify the target feature by name or ID.
+- Read the current `enabled` value.
+- Confirm the proposed change:
+
+```
+Proposed feature change:
+
+DISABLE feature "SEO" (seo):
+  enabled: true -> false
+
+This will hide the SEO nav item and gate its routes.
+Apply? (yes/no)
+```
+
+After confirmation, execute `.claude/skills/configure/operations/codify-level-a.md`.
+
+The write either adds or updates the matching entry in the `features` array of the adapter.
+Because the array replaces entirely, verify that the adapter redeclares all features that should
+remain in their current state.
+
+### Step 3b: Level B -- Add a custom feature
+
+Only proceed here when the user explicitly asks to add a new custom feature that does not exist in
+the platform defaults.
+
+State clearly: "Adding a custom feature creates a new TypeScript extension file in
+`foundations/config/extensions/`. This is a bigger change than a config toggle. Want to proceed?"
+
+If yes, gather:
+
+- "What should the feature ID be? Lowercase, hyphens only (e.g. `client-portal`)."
+- "What's the display label? (e.g. 'Client Portal')"
+- "Optional: a short description of what this feature represents."
+- "Which surfaces, entities, or resources does this feature relate to? (IDs -- leave blank to add
+  later)"
+
+Then execute `.claude/skills/configure/operations/codify-level-b.md` to scaffold the extension
+file and wire it into the adapter.
+
+### Step 4: Validation
+
+All changes -- Level A and Level B -- must pass:
+
+1. `pnpm -C operations check-types`
+2. `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` succeed on the merged result
+
+On failure, roll back and report. See `codify-level-a.md` and `codify-level-b.md` for the
+rollback procedure.
+
+### Step 5: Report
+
+After successful validation:
+
+```
+Features updated.
+  {feature label} ({id}): {old enabled} -> {new enabled}   (Level A)
+  Custom feature "{label}" ({id}): added                   (Level B, if applicable)
+  foundations/config/organization-model.ts -- features array updated
+  foundations/config/extensions/{id}.ts -- created          (Level B only)
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Features update rolled back.
+  Reason: {error message}
+  All files restored to previous state.
+  No changes persisted.
+```

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

@@ -0,0 +1,147 @@
+# Configure: goals
+
+Guides the user through reviewing and updating the `goals` domain of the organization model.
+
+The `goals` domain captures what the organization is working toward — time-bounded goals with
+measurable outcomes. The schema shape is OKR-inspired (objectives + key results) but all
+user-facing language must say "goals" and "measurable outcomes". Never say "OKR", "objective",
+or "key result" to the user.
+
+Agents use this domain for quarterly planning, priority routing, and understanding which outcomes
+matter most right now.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/goals.ts`
+
+```typescript
+GoalsDomainSchema = z.object({
+  objectives: z.array(ObjectiveSchema).default([])
+})
+
+ObjectiveSchema = z.object({
+  id:          z.string().trim().min(1).max(100),   // stable ID, e.g. "goal-grow-arr-q1-2026"
+  description: z.string().trim().min(1).max(1000),  // plain-language goal statement
+  periodStart: z.string().regex(ISO_DATE),          // YYYY-MM-DD — must be before periodEnd
+  periodEnd:   z.string().regex(ISO_DATE),          // YYYY-MM-DD — enforced in superRefine
+  keyResults:  z.array(KeyResultSchema).default([]) // measurable outcomes under this goal
+})
+
+KeyResultSchema = z.object({
+  id:           z.string().trim().min(1).max(100),  // e.g. "kr-revenue-q1"
+  description:  z.string().trim().min(1).max(500),  // e.g. "Increase trial-to-paid conversion"
+  targetMetric: z.string().trim().min(1).max(200),  // what is being measured, e.g. "monthly revenue"
+  currentValue: z.number().default(0),              // current tracked value
+  targetValue:  z.number().optional()               // target to hit (omit if directional)
+})
+```
+
+Cross-reference constraint: `periodEnd` must be strictly after `periodStart`. Enforced at parse
+time by `OrganizationModelSchema.superRefine()`.
+
+The field name in the schema is `objectives` (not `goals`) and the measurable-outcome array is
+`keyResults` (not `outcomes`) — these are internal field names, not user-facing vocabulary.
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `goals`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `goals.objectives` array.
+Present as a plain-language summary:
+
+```
+Current goals (N):
+  1. "{description truncated to 80 chars}" ({id})
+     Period: {periodStart} → {periodEnd}
+     Measurable outcomes: {count}
+  (no goals defined yet)
+```
+
+### Step 2: Establish intent
+
+Ask whether the user wants to:
+
+- **Add** a new goal
+- **Edit** an existing goal (by description or number)
+- **Remove** a goal
+- **Update progress** on a measurable outcome (update `currentValue`)
+
+### Step 3: Gather goal details
+
+For each goal being added or edited:
+
+**Core goal:**
+
+- "What is the organization working toward? Describe the goal in plain language — one or two sentences."
+- "Give it a stable ID — lowercase with hyphens, e.g. `goal-grow-arr-q1-2026`."
+- "What period does this goal cover? (Start date and end date — e.g. 2026-01-01 to 2026-03-31)"
+
+Validate that the end date is strictly after the start date before proceeding.
+
+**Measurable outcomes (optional but recommended):**
+
+- "Do you want to add any measurable outcomes under this goal? These help track whether you're
+  on track."
+- For each outcome: "What are you measuring? (e.g. monthly revenue, NPS score, trial-to-paid
+  conversion rate)"
+- "What's the target value? (Optional — leave blank if the outcome is directional.)"
+- "What's the current value?"
+- "Give this outcome an ID — e.g. `kr-revenue-q1`."
+
+Capture as many outcomes as the user wants. One at a time is fine.
+
+### Step 4: Confirm before writing
+
+Present a diff:
+
+```
+Proposed goals change:
+
+ADD goal "Reach $50K MRR by end of Q1 2026" (goal-arr-q1-2026):
+  period:  2026-01-01 → 2026-03-31
+  outcomes:
+    kr-mrr-q1: "Grow monthly recurring revenue"
+      metric:  "monthly recurring revenue (MRR)"
+      current: 32000
+      target:  50000
+    kr-churn-q1: "Reduce churn rate"
+      metric:  "monthly churn rate (%)"
+      current: 4.2
+      target:  2.5
+
+Apply? (yes/no)
+```
+
+### Step 5: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with the proposed `goals` block.
+Only the `objectives` array is written — no other keys in the adapter are touched.
+
+When updating progress only (updating `currentValue` on an existing outcome), make a targeted
+edit rather than rewriting the entire goals block.
+
+### Step 6: Report
+
+After successful validation:
+
+```
+Goals updated.
+  Goals: {total count} ({N added / N edited / N removed})
+  foundations/config/organization-model.ts — goals.objectives updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred:
+
+```
+Goals 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/identity.md

@@ -0,0 +1,133 @@
+# Configure: identity
+
+Guides the user through reviewing and updating the `identity` domain of the organization model.
+
+The `identity` domain captures legal identity, purpose, and operational anchors — distinct from
+`branding` (display identity: logos, product names). Editing identity fields here does not touch
+any visual or branding configuration.
+
+## Schema reference
+
+Source: `packages/core/src/organization-model/domains/identity.ts`
+
+```typescript
+IdentityDomainSchema = z.object({
+  mission:          z.string().trim().max(1000).default(''),
+  vision:           z.string().trim().max(1000).default(''),
+  legalName:        z.string().trim().max(200).default(''),
+  entityType:       z.string().trim().max(100).default(''),    // e.g. "LLC", "Corporation"
+  jurisdiction:     z.string().trim().max(200).default(''),    // e.g. "United States – Delaware"
+  industryCategory: z.string().trim().max(200).default(''),    // e.g. "Marketing Agency"
+  geographicFocus:  z.string().trim().max(200).default(''),    // e.g. "North America"
+  timeZone:         z.string().trim().max(100).default('UTC'), // IANA identifier
+  businessHours:    BusinessHoursSchema                        // per-day { open, close } in HH:MM
+})
+```
+
+`BusinessHoursSchema` is an object with optional keys `monday` through `sunday`, each holding
+`{ open: "HH:MM", close: "HH:MM" }`. An empty object `{}` means not configured.
+
+Where this lands in the adapter: `foundations/config/organization-model.ts` under the `identity`
+key of `defineOrganizationModel({...})`.
+
+---
+
+## Process
+
+### Step 1: Read current state
+
+Read `foundations/config/organization-model.ts` and extract the current `identity` block. Present
+it to the user as a plain-language summary, not a raw code dump:
+
+```
+Current identity:
+  Mission:          {value or "(not set)"}
+  Vision:           {value or "(not set)"}
+  Legal name:       {value or "(not set)"}
+  Entity type:      {value or "(not set)"}
+  Jurisdiction:     {value or "(not set)"}
+  Industry:         {value or "(not set)"}
+  Geographic focus: {value or "(not set)"}
+  Time zone:        {value}
+  Business hours:   {configured days or "not configured"}
+```
+
+### Step 2: Ask conversationally
+
+Work through the fields in natural conversation. You do not need to ask every field in a single
+message — group related ones together and react to what the user shares.
+
+**Group A — Purpose:**
+
+- "What's the organization's mission? (Why does it exist — one or two sentences.)"
+- "What's the vision? (Where is the organization headed long-term?)"
+
+**Group B — Legal identity:**
+
+- "What's the legal registered name of the organization?"
+- "What type of legal entity is it? (e.g. LLC, Corporation, Sole Proprietor, Non-profit)"
+- "What jurisdiction is it registered in? (e.g. United States – Delaware, Canada – Ontario)"
+
+**Group C — Industry and geography:**
+
+- "What industry or category best describes the organization? (e.g. Marketing Agency, SaaS, Professional Services)"
+- "Where does it primarily operate or serve? (e.g. North America, Global, Southeast Asia)"
+
+**Group D — Temporal anchors:**
+
+- "What time zone does the team primarily operate in? I'll use an IANA identifier like
+  America/Los_Angeles or Europe/London."
+- "Do you want to capture standard business hours? (e.g. Mon–Fri 09:00–17:00)"
+
+If a field already has a non-empty value, show the current value and ask whether to keep or change it.
+Never silently overwrite existing values without confirmation.
+
+### Step 3: Confirm before writing
+
+Present a diff-style summary of all proposed changes:
+
+```
+Proposed identity changes:
+  mission:          "" → "We help SMBs automate complex operations using AI."
+  vision:           (unchanged) "(not set)"
+  legalName:        "" → "Acme Operations LLC"
+  entityType:       "" → "LLC"
+  jurisdiction:     "" → "United States – Delaware"
+  industryCategory: "" → "AI Automation / Professional Services"
+  geographicFocus:  "" → "North America"
+  timeZone:         "UTC" → "America/Chicago"
+  businessHours:    {} → { monday–friday: 09:00–17:00 }
+
+Apply these changes? (yes/no)
+```
+
+If the user says no, abort without writing anything.
+
+### Step 4: Codify
+
+Execute `.claude/skills/configure/operations/codify-level-a.md` with these changes targeting the
+`identity` key inside the `defineOrganizationModel({...})` call in
+`foundations/config/organization-model.ts`.
+
+Only write the fields the user confirmed. Do not add or remove other top-level keys in the adapter.
+
+### Step 5: Report
+
+After successful validation:
+
+```
+Identity updated.
+  Fields changed: {list}
+  foundations/config/organization-model.ts — identity block updated
+  Type-check: PASS
+  Schema validation: PASS
+```
+
+If validation failed and rollback occurred, report:
+
+```
+Identity update rolled back.
+  Reason: {error message}
+  foundations/config/organization-model.ts — restored to previous state
+  No changes persisted.
+```