@elevasis/sdk 1.6.0 → 1.7.0

package/reference/claude-config/rules/vibe.md

@@ -0,0 +1,210 @@
+---
+description: Ambient intent classifier -- routes natural-language input to 7 intent buckets without a slash command; Codify and Toggle delegate to /configure
+paths:
+  - "**/*"
+---
+
+# Vibe Layer
+
+Vibe is an **ambient, always-on** intent classifier. It activates automatically whenever the user speaks in plain language -- no slash command, no activation phrase, no special syntax. Every natural-language message passes through vibe classification before the agent acts.
+
+This rule applies to all sessions inside external projects. It does NOT apply in the monorepo (ambient routing is off there by default).
+
+## What Vibe Is
+
+Vibe is the translation layer between the user's natural language and the correct agent action. The user describes reality -- "we track deals by Shopify platform", "I'm stuck on this task", "what should I work on next" -- and vibe determines which of the seven intent types the message represents. The agent then routes to the right behavior without the user ever knowing the classification happened.
+
+Vibe coders (non-technical builders) are the primary audience. They build by describing. They never memorize commands, IDs, or schema. The ambient layer closes the gap between what they say and what the system can act on.
+
+## The Seven Intent Types
+
+### 1. Capture
+
+The user wants to record something new -- a task, a note, a piece of information that should persist.
+
+**Recognize by:** action verbs like "add", "create", "remember", "track", "log", "note down", "write down", combined with a thing to record.
+
+**Fixture examples:**
+
+| Input                                             | Why it's Capture                            |
+| ------------------------------------------------- | ------------------------------------------- |
+| "Add a task to follow up with the Shopify client" | Explicit "add a task" with a described item |
+| "Remember to run the campaign report on Friday"   | "Remember to" signals something to persist  |
+| "Track this conversation as a deal note"          | Explicit "track" with a described artifact  |
+
+**Agent action:** draft the capture in plain language, confirm with the user, then execute via `elevasis-sdk project:*` commands. Never write without confirmation.
+
+### 2. Query
+
+The user wants to know something about current state -- task priorities, what is pending, what is running, what failed.
+
+**Recognize by:** questions about the current list, status, or queue of things. Includes both static-model queries ("what features are on?") and runtime-entity queries ("what's pending in the queue?"). Route Query to static-model sources (org model, features config) or runtime sources (operations domain) based on the referenced entity.
+
+**Fixture examples:**
+
+| Input                                         | Why it's Query                              |
+| --------------------------------------------- | ------------------------------------------- |
+| "What should I work on next?"                 | Asking for prioritized task list            |
+| "What's pending in the HITL queue?"           | Runtime-entity query about operations state |
+| "What features are enabled for this project?" | Static-model query about features config    |
+
+**Agent action:** read the relevant source (org model, `prj_tasks`, operations domain as available) and narrate the answer in plain language. No writes.
+
+### 3. Describe
+
+The user wants the agent to explain something -- a scope, an entity, a concept within the project.
+
+**Recognize by:** "what is", "what does", "tell me about", "explain", "where am I", "what's going on", "describe", "show me" without an action intent attached.
+
+**Fixture examples:**
+
+| Input                                      | Why it's Describe                                     |
+| ------------------------------------------ | ----------------------------------------------------- |
+| "What's going on with the ZentaraHQ deal?" | Asking for a plain-language description of an entity  |
+| "Tell me about the CRM feature"            | Asking the agent to narrate what a model element does |
+| "Where am I in this project?"              | Asking for current scope narration                    |
+
+**Agent action:** read the relevant org-model label, entity, or scope. Narrate in plain language using label fields from the model -- never invent vocabulary not present in the model. Phase-1 scope covers Model, Features, and Foundations layers only.
+
+### 4. Transition
+
+The user wants to change the status of a task or entity.
+
+**Recognize by:** single-word or short-phrase state signals -- "done", "finished", "complete", "blocked", "stuck", "waiting", "in review", "cancelled" -- applied to a current task or named entity.
+
+**Fixture examples:**
+
+| Input                                         | Why it's Transition                         |
+| --------------------------------------------- | ------------------------------------------- |
+| "Done with the proposal draft"                | "Done" + named artifact = status transition |
+| "Stuck -- blocked waiting on client feedback" | "Stuck" + reason = blocked transition       |
+| "Mark the onboarding task as complete"        | Explicit status-change vocabulary           |
+
+**Agent action:** identify the task or entity being transitioned, confirm the new status with the user, then apply the transition via `elevasis-sdk project:task:save` or equivalent. Never auto-transition without confirmation if the target entity is ambiguous.
+
+### 5. Navigate
+
+The user wants to shift focus -- to a different task, project, feature, or layer of the model.
+
+**Recognize by:** focus-shift vocabulary -- "focus on", "let's look at", "switch to", "back to", "move to", "open", "go to" -- followed by a scope target.
+
+**Fixture examples:**
+
+| Input                                        | Why it's Navigate                                   |
+| -------------------------------------------- | --------------------------------------------------- |
+| "Let's focus on the onboarding flow for now" | "Focus on" + scope target                           |
+| "Switch to the Shopify integration project"  | "Switch to" = navigate to a different project scope |
+| "Back to the CRM tasks"                      | "Back to" = return to a prior scope                 |
+
+**Agent action:** update the active scope in `prj_tasks.resume_context` (current project + task pointer), then narrate the new scope in plain language so the user knows where they are.
+
+### 6. Codify
+
+The user describes organizational reality that is not yet expressed in the model -- industry type, entity kinds, custom attributes, renamed stages, domain vocabulary.
+
+**Recognize by:** declarative "we are" / "we use" / "we track" statements, repeated attribute mentions (second time the same attribute appears), or explicit "add a type / add a field / model X as Y" requests.
+
+**Fixture examples:**
+
+| Input                                                                            | Why it's Codify                                          |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| "We're an e-commerce company -- all our deals come from Shopify or Amazon"       | Declares industry + platform attributes not yet in model |
+| "We track deal stage as discovery, scoping, proposal, closed"                    | Describes custom CRM stages that should replace defaults |
+| "Add a project type called 'retainer' with monthly billing and a contract field" | Explicit request to add a new entity extension           |
+
+**Agent action:** delegate immediately to `/configure`. Do not attempt the ceremony yourself. Invoke with the relevant domain: `/configure crm` for deal/contact changes, `/configure projects` for project types, `/configure features` for feature toggles. Plain-language summary of what was detected is acceptable before delegating, but the actual draft-confirm-write ceremony belongs to `/configure`.
+
+This routing applies to both codify levels (decision #21 -- Codify ceremony delegated to `/configure`):
+
+- **Level A** (config-only edits to `organization-model.ts`, feature toggles, label renames): delegate to `/configure <domain>` immediately.
+- **Level B** (new Zod extension files in `foundations/config/extensions/`): also delegate to `/configure <domain>`; `/configure` gates Level B to explicit user asks before scaffolding a new TS file.
+
+Vibe detects the intent and delegates in both cases. It does not run either pipeline itself.
+
+Heuristics for when to propose codification (passed to `/configure` as context):
+
+- First mention of a new attribute: note to `resume_context`, do not propose yet
+- Second mention OR explicit declaration ("we're ecom"): propose extension
+- Explicit ask ("track ecom deals separately"): propose immediately with fuller scope
+- Attribute appearing across 3+ tasks: propose adding field to existing extension
+
+### 7. Toggle
+
+The user wants to enable or disable a feature.
+
+**Recognize by:** feature-control vocabulary -- "turn on", "enable", "disable", "turn off", "activate", "deactivate" -- followed by a feature name or description.
+
+**Fixture examples:**
+
+| Input                           | Why it's Toggle                               |
+| ------------------------------- | --------------------------------------------- |
+| "Turn on the lead-gen feature"  | Explicit "turn on" + feature name             |
+| "Disable monitoring for now"    | "Disable" + feature reference                 |
+| "We don't use SEO, turn it off" | Declarative + "turn it off" = feature disable |
+
+**Agent action:** delegate to `/configure features`. The ceremony (confirm + edit `foundations/config/organization-model.ts` + typecheck) belongs to `/configure`, not to the ambient rule.
+
+## Quick Reference Table
+
+| Intent     | Trigger signal                                                  | Routed to                                  |
+| ---------- | --------------------------------------------------------------- | ------------------------------------------ |
+| Capture    | "add", "remember", "track", "log" + a thing                     | Agent -- draft + confirm + `project:*` CLI |
+| Query      | "what's next", "what's pending", "what failed", "what features" | Agent -- read + narrate                    |
+| Describe   | "what is", "tell me about", "explain", "where am I"             | Agent -- narrate from org model labels     |
+| Transition | "done", "stuck", "blocked", "finished", "complete"              | Agent -- confirm + `project:task:save`     |
+| Navigate   | "focus on", "switch to", "back to", "look at"                   | Agent -- update scope + narrate            |
+| Codify     | "we are X", "we track Y", repeated attribute, "add type/field"  | Delegate to `/configure \<domain>`         |
+| Toggle     | "enable", "disable", "turn on/off" + feature                    | Delegate to `/configure features`          |
+
+## Source of Truth for Plain Language
+
+All plain-language labels come from the OrganizationModel itself -- never from hardcoded strings in this rule file. Every status, entity kind, and layer name in the model carries an inline `label` field (e.g., `{ id: 'revision_requested', label: 'changes needed', semanticClass: 'blocked' }`). When narrating state or confirming an action, read the label from the model and use it verbatim. Do not invent synonyms or fallback vocabulary.
+
+The unified manifest (delivered via `@elevasis/core/organization-model`) is the canonical vocabulary surface. Vibe classifies against it -- capabilities, features, statuses, operations entities, and resource kinds are all discoverable from the manifest without hardcoding.
+
+## Ambiguous Intent
+
+When the user's input does not clearly map to one of the seven types, ask one clarifying question. Do not guess. Do not apply a precedence rule. Do not route to the "closest" intent.
+
+Format: a single neutral question that presents the two (or three) plausible intents as options and asks which the user means.
+
+Example: "That could be a note to capture or a status update on the current task -- which did you mean?"
+
+Never ask more than one question per ambiguous input. If the user's reply is still ambiguous, ask once more, then surface the options explicitly.
+
+## Enforcement and Trust Marker
+
+Raw edits to `foundations/config/organization-model.ts` and `foundations/config/extensions/*.ts` are blocked by the `pre-edit-vibe-gate.mjs` PreToolUse hook unless the `VIBE_APPROVED=1` environment variable is set.
+
+This variable is set automatically by `/configure` after the user confirms a codify or toggle ceremony. It is subshell-scoped -- no filesystem state to clean up. Power users who invoke `/configure` directly get the marker without triggering the hook error.
+
+If you encounter the hook block outside of a `/configure` ceremony, do not attempt to bypass it. Surface the message to the user and suggest running `/configure \<domain>` to proceed through the approved ceremony.
+
+## Classifier Threshold
+
+Default threshold: `balanced`.
+
+The threshold controls how aggressively the classifier proposes codification from ambiguous signals:
+
+- `strict` -- only explicit declarations or repeat mentions trigger codify proposals
+- `balanced` -- second mention OR explicit declaration triggers; default
+- `loose` -- first strong signal triggers a proposal
+
+Override per project in `foundations/config/organization-model.ts` under `vibe.classifierThreshold`. The override is merge-aware (Tier 2 sync) and will not be overwritten by template sync operations.
+
+## Phase-1 Scope
+
+This rule covers Phase 1 of the vibe layer rollout. The layers the ambient classifier can narrate and codify in Phase 1 are:
+
+- Layer 1 (Model): narrate schema shape, propose codification edits via `/configure`
+- Layer 4 (Features): describe which features are on/off, propose enabling one via `/configure`
+- Layer 7 (Foundations): explain and edit `organization-model.ts` and `extensions/` via `/configure`
+
+Layers 2 (Public API), 3 (UI Shell Runtime), 5 (Toolkit), and 6 (Graph) require runtime read APIs that are not yet available. Do not attempt to narrate or classify against those layers in Phase 1. If the user's input clearly references one of those layers, acknowledge the scope and explain that full support arrives in a later phase.
+
+## What Vibe Is Not
+
+- Vibe is not a slash command. There is no `/vibe` invocation (decision #19 -- ambient rule, not a skill or command).
+- Vibe is not a skill. It lives in this rule file + CLAUDE.md + the PreToolUse hook -- not in `.claude/skills/`.
+- Vibe does not own the codify ceremony. `/configure` owns draft, confirm, write, and typecheck for both Level A and Level B codify pipelines (decision #21 -- Codify ceremony delegated to `/configure`). Vibe detects intent and hands off.
+- Vibe is not active in the monorepo. If working inside the monorepo (not an `external/` project), this ambient routing does not apply.

package/reference/claude-config/settings.json

@@ -4,6 +4,17 @@
     "command": "node .claude/scripts/statusline-command.js"
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-edit-vibe-gate.mjs"
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit|MultiEdit",

package/reference/claude-config/skills/configure/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: configure
+description: "Recurring organization model editor — layered QA flow across identity, customers, offerings, roles, goals, and techStack. Idempotent, confirm-before-overwrite. Codifies changes to foundations/config/organization-model.ts with runtime validation gate."
+argument-hint: "[identity|customers|offerings|roles|goals|techStack|features|labels]"
+context: fork
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Configure
+
+Recurring, safe-to-re-run org model editor for external projects. Reads the organization model as the single source of truth and guides the user through structured updates — either across all domains in a layered flow, or targeted at a single domain by argument.
+
+**Usage:**
+
+- `/configure` -- Layered flow: walks identity → customers → offerings → roles → goals → techStack in sequence
+- `/configure identity` -- Target only the identity domain
+- `/configure customers` -- Target only the customers domain
+- `/configure offerings` -- Target only the offerings domain
+- `/configure roles` -- Target only the roles domain
+- `/configure goals` -- Target only the goals domain
+- `/configure techStack` -- Target only the techStack domain (resource mapping extensions)
+- `/configure features` -- Enable, disable, or add features; Level A (defaults) or Level B (new extension TS files)
+- `/configure labels` -- Edit inline display labels on enum entries (statuses, stages, categories)
+
+**Distinction from `/org-os manage`:** `/configure` edits structural organizational reality (who the org is, who it serves, what it offers). `/org-os manage` controls feature gating (what platform capabilities are enabled). Use `/configure` for org-model content; use `/org-os manage` for feature flags.
+
+**Distinction from `/setup`:** `/setup` is for first-time bootstrap (placeholder replacement, dependency install, build verification). `/configure` is for recurring org-model updates. After first run, `/setup` delegates here.
+
+---
+
+## Goal
+
+Keep `foundations/config/organization-model.ts` accurate and validated. Every edit proposed by this skill ends with `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` confirming the merged result is valid — and a full TypeScript type-check via `pnpm -C operations check-types` to catch static errors. If validation fails, the change is rolled back.
+
+---
+
+## Pre-Flight: Read the Current Model
+
+Before any domain flow, read the current organization model adapter:
+
+```
+Read("foundations/config/organization-model.ts")
+```
+
+This is the single source of truth. All proposals must start from what is currently in this file, not from stale context.
+
+---
+
+## Mode Detection
+
+- **No argument:** run the layered flow (all domains, one at a time in the order below).
+- **Argument matches a domain name** (`identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`): run only that domain's operation.
+- **Argument is `features`:** run the features operation.
+- **Argument is `labels`:** run the labels operation.
+- **Argument is unrecognized:** ask the user which domain they meant.
+
+---
+
+## Layered Flow (Default)
+
+When run without an argument, execute operations in this order. After each domain, ask "Ready to move on to [next domain]?" and pause for confirmation. The user can stop after any domain — partial updates are valid.
+
+1. `identity` -- EXECUTE `.claude/skills/configure/operations/identity.md`
+2. `customers` -- EXECUTE `.claude/skills/configure/operations/customers.md`
+3. `offerings` -- EXECUTE `.claude/skills/configure/operations/offerings.md`
+4. `roles` -- EXECUTE `.claude/skills/configure/operations/roles.md`
+5. `goals` -- EXECUTE `.claude/skills/configure/operations/goals.md`
+6. `techStack` -- EXECUTE `.claude/skills/configure/operations/techStack.md`
+
+---
+
+## Operations
+
+| Operation        | File                                                    | Description                                                                                                      |
+| ---------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `identity`       | `.claude/skills/configure/operations/identity.md`       | Legal identity, mission, vision, industry, geography, timezone, business hours                                   |
+| `customers`      | `.claude/skills/configure/operations/customers.md`      | Customer segments with jobs-to-be-done, pains, gains, firmographics, value props                                 |
+| `offerings`      | `.claude/skills/configure/operations/offerings.md`      | Products and services with pricing model, price, currency, and segment/feature refs                              |
+| `roles`          | `.claude/skills/configure/operations/roles.md`          | Role chart with responsibilities, reporting lines, and role holders                                              |
+| `goals`          | `.claude/skills/configure/operations/goals.md`          | Organizational goals with period and measurable outcomes                                                         |
+| `techStack`      | `.claude/skills/configure/operations/techStack.md`      | External integration registry — platform, purpose, credential status, system-of-record flag                      |
+| `features`       | `.claude/skills/configure/operations/features.md`       | Enable/disable features or add new ones (Level A config edit vs Level B extension file)                          |
+| `labels`         | `.claude/skills/configure/operations/labels.md`         | Edit inline display labels on enum entries (statuses, stages, categories)                                        |
+| `codify-level-a` | `.claude/skills/configure/operations/codify-level-a.md` | Codify pipeline for config-only edits (Level A): propose, confirm, write, validate, rollback                     |
+| `codify-level-b` | `.claude/skills/configure/operations/codify-level-b.md` | Codify pipeline for new extension TS files (Level B): scaffold file, propose, confirm, write, validate, rollback |
+
+---
+
+## Validation Gate (MANDATORY)
+
+Every codify operation (Level A or B) must end with this validation sequence before reporting success:
+
+1. **TypeScript type-check:** `pnpm -C operations check-types` (catches static errors in the generated extension files)
+2. **Runtime schema parse:** confirm that the adapter calls `resolveOrganizationModel()` and `OrganizationModelSchema.parse()` is satisfied (Zod cross-refs, enum values, required fields)
+
+If either fails: roll back the file to its pre-edit state and report the error to the user. See `codify-level-a.md` and `codify-level-b.md` for the full rollback procedure.
+
+---
+
+**Last Updated:** 2026-04-20

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

@@ -0,0 +1,100 @@
+# Codify Pipeline: Level A (Config-Only Edits)
+
+Level A is the codify pipeline for changes that land exclusively in
+`foundations/config/organization-model.ts`. No new TypeScript files are created. The entire
+ceremony is: snapshot current file, propose the edit, write the edit, validate, and roll back on
+failure.
+
+This pipeline is called by domain operations (identity, customers, offerings, roles, goals,
+techStack, features, labels) after the user has confirmed the proposed change. The caller provides
+the specific field/block being changed and the proposed new value.
+
+---
+
+## Pipeline
+
+### Step 1: Snapshot
+
+Before any write, read `foundations/config/organization-model.ts` and keep the full file content
+in memory as the rollback snapshot. Do not write any file during this step.
+
+```
+Read("foundations/config/organization-model.ts")
+-- store as ROLLBACK_SNAPSHOT
+```
+
+### Step 2: Apply the edit
+
+Use the Edit tool to apply the caller's proposed change to
+`foundations/config/organization-model.ts`.
+
+Rules for the edit:
+
+- Edit only the specific field or block the caller specified. Do not reformat or restructure
+  unrelated sections.
+- Preserve all other keys in `defineOrganizationModel({...})` exactly as they are.
+- Maintain the existing code style (trailing commas, quote style, indentation) of the file.
+- If the target field does not yet exist in the adapter call, add it as a new property in the
+  appropriate position (following the declared domain order in the schema).
+
+### Step 3: TypeScript type-check
+
+Run the type-check for the operations package:
+
+```bash
+pnpm -C operations check-types
+```
+
+Capture stdout and stderr. If the command exits non-zero, proceed to Step 5 (rollback).
+
+### Step 4: Runtime schema validation
+
+Confirm that the adapter's output passes `OrganizationModelSchema.parse()`. The adapter calls
+`resolveOrganizationModel()` internally, which merges defaults with overrides and then parses the
+result. A successful `check-types` pass is strong evidence that the schema is valid, but
+cross-reference checks (segment ID refs in offerings, role reporting refs, period ordering in
+goals) are runtime-only.
+
+If the project exposes a validation script (e.g. `pnpm -C operations check`), run that too:
+
+```bash
+pnpm -C operations check
+```
+
+If either validation step fails, proceed to Step 5 (rollback).
+
+### Step 5: Rollback (on failure only)
+
+If Step 3 or Step 4 failed:
+
+1. Write the ROLLBACK_SNAPSHOT content back to `foundations/config/organization-model.ts`
+   verbatim (use the Write tool with the exact snapshot content).
+2. Confirm the file has been restored by checking that the content matches the snapshot.
+3. Return the error message to the caller.
+
+The caller is responsible for reporting the rollback to the user.
+
+### Step 6: Success signal
+
+If Steps 3 and 4 both passed, return a success signal to the caller with:
+
+- The fields changed
+- `Type-check: PASS`
+- `Schema validation: PASS`
+
+The caller formats and presents the final report.
+
+---
+
+## Caller Contract
+
+Callers must provide before invoking this pipeline:
+
+- **Target file:** always `foundations/config/organization-model.ts`
+- **Target block:** the specific domain key or sub-key being changed (e.g. `identity`,
+  `customers.segments`, `roles.roles`, `resourceMappings[id="rm-hubspot"].techStack`)
+- **Proposed value:** the new TypeScript literal to write for that block
+- **Confirmed:** the user has already said yes to the proposed change
+
+This pipeline does not ask the user any questions. All confirmation happens in the domain
+operation before this pipeline is invoked.

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).