@elevasis/sdk 1.6.0 → 1.8.0

package/reference/claude-config/skills/configure/operations/codify-level-b.md

@@ -0,0 +1,158 @@
+# Codify Pipeline: Level B (New Extension TypeScript Files)
+
+Level B is the codify pipeline for changes that require creating a new TypeScript file under
+`foundations/config/extensions/`. This pipeline is used when the user wants to add a custom
+feature, a custom entity type, or any structural addition that cannot be expressed as a simple
+field override in `foundations/config/organization-model.ts`.
+
+Level B is **only offered when the user explicitly asks** for something that requires a new file.
+Never silently escalate from Level A to Level B. If Level A is sufficient, use it.
+
+---
+
+## When Level B applies
+
+- Adding a custom feature that does not exist in the platform defaults (new `FeatureSchema` entry
+  with a custom ID, manifest wiring, and route references)
+- Adding a custom entity extension (new Zod schema extending a base entity type)
+- Any structural addition the caller's domain operation has determined cannot be expressed as a
+  field value in the existing adapter
+
+The calling operation (e.g. `features.md`) is responsible for deciding when Level B is needed
+and for confirming the intent with the user before invoking this pipeline.
+
+---
+
+## Pipeline
+
+### Step 1: Snapshot all files that will be touched
+
+Before any write, read and snapshot:
+
+1. `foundations/config/organization-model.ts` (always touched for wiring)
+2. The target extension file path (if it already exists -- confirm overwrite with user)
+
+```
+Read("foundations/config/organization-model.ts")   -- store as ROLLBACK_ADAPTER
+Read("foundations/config/extensions/{target}.ts")  -- store as ROLLBACK_EXTENSION (if exists)
+```
+
+The target extension file path follows the naming convention:
+`foundations/config/extensions/{kebab-case-feature-id}.ts`
+
+### Step 2: Scaffold the extension file
+
+Create `foundations/config/extensions/{id}.ts` using the Write tool.
+
+The file shape depends on the extension type:
+
+**Custom feature (most common Level B case):**
+
+```typescript
+/**
+ * {Feature label} feature extension.
+ * Registered in foundations/config/organization-model.ts.
+ */
+import type { OrganizationModelFeature } from '@elevasis/core/organization-model'
+
+export const {FEATURE_CONST}: OrganizationModelFeature = {
+  id: '{feature-id}',
+  label: '{Feature Label}',
+  description: '{optional description}',
+  enabled: true,
+  entityIds: [],
+  surfaceIds: [],
+  resourceIds: [],
+  capabilityIds: [],
+}
+```
+
+Replace `{FEATURE_CONST}` with the SCREAMING_SNAKE_CASE version of the feature ID
+(e.g. `CLIENT_PORTAL_FEATURE`).
+
+The caller provides the exact field values based on what the user confirmed.
+
+### Step 3: Wire the extension into the adapter
+
+Edit `foundations/config/organization-model.ts` to:
+
+1. Import the new constant from the extension file.
+2. Add it to the `features` array in the `defineOrganizationModel({...})` call.
+
+Example import addition:
+
+```typescript
+import { CLIENT_PORTAL_FEATURE } from './extensions/client-portal'
+```
+
+Example features array addition:
+
+```typescript
+features: [
+  ...existingFeatures,
+  CLIENT_PORTAL_FEATURE,
+],
+```
+
+### Step 4: TypeScript type-check
+
+```bash
+pnpm -C operations check-types
+```
+
+Capture stdout and stderr. If the command exits non-zero, proceed to Step 6 (rollback).
+
+### Step 5: Runtime schema validation
+
+```bash
+pnpm -C operations check
+```
+
+If either check fails, proceed to Step 6 (rollback).
+
+### Step 6: Rollback (on failure only)
+
+If Step 4 or Step 5 failed:
+
+1. Restore `foundations/config/organization-model.ts` from ROLLBACK_ADAPTER.
+2. If the extension file did not previously exist, delete it. If it previously existed, restore
+   from ROLLBACK_EXTENSION.
+3. Re-run `pnpm -C operations check-types` to confirm the restore is clean. If the restore
+   itself fails type-check, report both the original error and the restore state to the user --
+   do not silently leave the project in a broken state.
+4. Return the error message to the caller.
+
+### Step 7: Success signal
+
+If Steps 4 and 5 both passed, return a success signal to the caller with:
+
+- Extension file path created
+- Adapter wiring changes (import + features array entry)
+- `Type-check: PASS`
+- `Schema validation: PASS`
+
+The caller formats and presents the final report to the user.
+
+---
+
+## Caller Contract
+
+Callers must provide before invoking this pipeline:
+
+- **Extension file path:** `foundations/config/extensions/{id}.ts`
+- **Extension file content:** the full TypeScript content for the new file
+- **Adapter changes:** the exact import line and features-array addition to write into the adapter
+- **Confirmed:** the user has already said yes to the proposed change and explicitly requested
+  a new extension file
+
+This pipeline does not ask the user any questions. All confirmation and escalation decisions
+happen in the domain operation before this pipeline is invoked.
+
+---
+
+## Constraint: Extension files are Tier 3 (never synced)
+
+Files under `foundations/config/extensions/` are Tier 3 -- project-specific, never overwritten
+by `/external sync`. This means custom features and entity extensions survive template upgrades
+automatically. Do not put platform-default overrides in extension files; those belong directly in
+`foundations/config/organization-model.ts` (Tier 2, merge-aware).

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,161 @@
+# 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.
+
+## 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.
+```