@elevasis/sdk 1.15.0 → 1.16.0

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

@@ -0,0 +1,253 @@
+---
+name: knowledge
+description: |
+  TRIGGER this skill when any of the following apply:
+  - The user references organization-model entities by name or concept: identity, customers,
+    offerings, roles, goals, techStack, features, labels, knowledge nodes, governance edges,
+    mounts, playbook, outreach cadence, or any domain in the org model.
+  - The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
+    update, toggle, enable, or disable any organization-model domain or knowledge node.
+  - The user asks "what governs X?", "what does X control?", "feature governs", "what is our
+    identity set to?", "what's our timezone?", "show me all reference docs", "list my roles",
+    "where does outreach-cadence apply?", or similar.
+  - An agent is editing files matching: core/config/organization-model.ts,
+    foundations/config/organization-model.ts, packages/elevasis-core/src/organization-model.ts,
+    or packages/core/src/knowledge/**.
+  SKIP this skill when the task is purely UI layout, workflow authoring, or infrastructure
+  work with no reference to org-model or knowledge-graph entities.
+metadata:
+  pathPatterns:
+    - "core/config/organization-model.ts"
+    - "foundations/config/organization-model.ts"
+    - "packages/elevasis-core/src/organization-model.ts"
+    - "packages/core/src/knowledge/**"
+  promptSignals:
+    phrases:
+      - playbook
+      - knowledge node
+      - feature governs
+      - outreach cadence
+      - identity
+      - customer segment
+      - codify
+      - enable feature
+      - toggle feature
+      - what governs
+      - org model
+      - organization model
+      - offerings
+      - techStack
+      - roles
+      - goals
+      - labels
+      - knowledge map
+      - governance edge
+      - knowledge mount
+      - knowledge graph
+      - knowledge browser
+      - list my roles
+      - what is our
+      - show me all reference docs
+      - where does
+      - apply
+context: fork
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Knowledge
+
+Unified intent-inferring skill for all organization-model interaction. Reads org-model state
+through the `elevasis knowledge:*` CLI tooling; writes run through the codify ceremony absorbed
+from `/configure`. No verb namespace is required -- the skill classifies intent from conversation
+context and routes to the appropriate flow internally.
+
+---
+
+## When to Invoke
+
+This skill auto-invokes whenever:
+
+- Conversation references org-model entities (identity, customers, offerings, roles, goals,
+  techStack, features, labels, knowledge nodes, governance edges, mounts)
+- The user asks to read, list, find, show, query, navigate, describe, codify, add, edit,
+  update, toggle, enable, or disable any of those
+- An agent is editing files matching `core/config/organization-model.ts`,
+  `foundations/config/organization-model.ts`, `packages/elevasis-core/src/organization-model.ts`,
+  or `packages/core/src/knowledge/**`
+
+Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`, and
+`metadata.promptSignals` -- no explicit `/knowledge` prefix is required.
+
+---
+
+## Intent Classification
+
+Once invoked, classify the user's intent into one of five flows. Read natural-language input and
+pick a flow. On ambiguous input, default to **Describe** (read intent) and ask the user to
+confirm before any write. The codify ceremony has an explicit user-confirm gate -- misclassification
+cannot bypass the write gate.
+
+| Flow     | Triggers (examples)                                                                | Mechanics                                                                                                     |
+| -------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Read     | "what playbooks govern sales.crm?", "show me all reference docs", "list my roles"  | Run CLI read commands (monorepo or external); format result                                                   |
+| Navigate | "what governs this feature?", "where does outreach-cadence apply?"                 | Same CLI; pick mount axis from intent; default to `by-feature` for orientation queries                        |
+| Describe | "what is our identity set to?", "what's our timezone?"                             | Read current values from OM source; narrate                                                                   |
+| Codify   | "we're an e-commerce company", "add a customer segment", "our outreach goal is..." | Run codify ceremony: snapshot -> propose -> confirm -> write -> typecheck -> Zod parse -> rollback on failure |
+| Toggle   | "enable the lead-gen feature", "turn off SEO"                                      | Codify ceremony scoped to `features` domain; flip the boolean; same validation/rollback                       |
+
+---
+
+## Read Patterns
+
+### Monorepo (platform defaults)
+
+```bash
+pnpm exec elevasis knowledge:ls
+pnpm exec elevasis knowledge:cat <node-id>
+pnpm exec elevasis knowledge:graph --axis by-feature
+pnpm exec elevasis knowledge:graph --axis by-domain
+pnpm exec elevasis knowledge:graph --mount <mount-id>
+```
+
+### External projects (org instance)
+
+```bash
+pnpm exec elevasis-sdk knowledge:ls
+pnpm exec elevasis-sdk knowledge:cat <node-id>
+pnpm exec elevasis-sdk knowledge:graph --axis by-feature
+pnpm exec elevasis-sdk knowledge:graph --axis by-domain
+pnpm exec elevasis-sdk knowledge:graph --mount <mount-id>
+```
+
+Use `knowledge:ls` to enumerate all knowledge nodes. Use `knowledge:cat` to read a specific
+node's content. Use `knowledge:graph` to navigate the governance graph -- `by-feature` is the
+default axis for "what governs X?" queries; `by-domain` for domain-wide surveys.
+
+### `/knowledge read-folder` (chat shorthand from the Knowledge Browser)
+
+The Knowledge Browser's copy button on a top-level feature or kind group emits a single
+`/knowledge read-folder <axis>:<id>` line instead of N per-node `read` lines. Resolve it by
+listing the folder via `knowledge:ls` and reading each child:
+
+| Copy form                             | Resolution (external)                                                                        |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `/knowledge read-folder feature:<id>` | `pnpm exec elevasis-sdk knowledge:ls /by-feature/<id> --ids-only`, then `knowledge:cat` each |
+| `/knowledge read-folder kind:<kind>`  | `pnpm exec elevasis-sdk knowledge:ls /by-kind/<kind> --ids-only`, then `knowledge:cat` each  |
+
+Dotted feature ids may use either dots or slashes (`sales.crm` and `sales/crm` both work
+with `knowledge:ls`). Per-node leaves still copy as `/knowledge read <node-id>`; virtual
+sub-folders inside a feature (regex-grouped UI buckets like Campaigns/Pipeline) keep the
+N-line list since they have no stable folder id.
+
+---
+
+## Codify Ceremony
+
+Every write (Codify or Toggle intent) runs the six-step safety ceremony. This ceremony is
+preserved verbatim from `/configure`.
+
+### Step 1: Snapshot
+
+Read `foundations/config/organization-model.ts` (external) or the appropriate platform OM file
+(monorepo) into memory before any edit. This is the rollback target.
+
+### Step 2: Propose
+
+Show the diff in chat. Identify which domain and field changes. Present the proposed new value
+in context alongside the current value.
+
+### Step 3: Confirm
+
+Pause for explicit user confirmation. Do not proceed without a clear yes. Permission prompts
+also gate writes.
+
+### Step 4: Write
+
+Apply the edit using the Edit or Write tool.
+
+### Step 5: Validate
+
+Run both checks:
+
+```bash
+pnpm -C operations check-types   # TypeScript type-check
+pnpm -C operations check         # Runtime schema validation (Zod parse)
+```
+
+### Step 6: Rollback
+
+If any validation step fails, restore the file from the Step 1 snapshot and report the error.
+The rollback is mandatory -- never leave the project in a broken state.
+
+**Two-level ceremony:**
+
+- **Level A** -- config-only edits to existing schema fields in `foundations/config/organization-model.ts`.
+  Execute: `.claude/skills/knowledge/operations/codify-level-a.md`
+- **Level B** -- new Zod extension files in `foundations/config/extensions/`. Gated to explicit
+  user ask. On casual second mentions of a new type, suggest Level B and wait for confirmation
+  rather than scaffolding automatically.
+  Execute: `.claude/skills/knowledge/operations/codify-level-b.md`
+
+---
+
+## Domain References
+
+The following domain reference files document each org-model domain: schema fields, validation
+rules, examples, and how to read or edit them. Load the relevant file when the user's intent
+classification names a specific domain.
+
+- `.claude/skills/knowledge/operations/identity.md` -- identity domain
+- `.claude/skills/knowledge/operations/customers.md` -- customer segments
+- `.claude/skills/knowledge/operations/offerings.md` -- products and services
+- `.claude/skills/knowledge/operations/roles.md` -- role chart
+- `.claude/skills/knowledge/operations/goals.md` -- organizational goals
+- `.claude/skills/knowledge/operations/techStack.md` -- external integration registry
+- `.claude/skills/knowledge/operations/features.md` -- feature toggles and Level B extension gate
+- `.claude/skills/knowledge/operations/labels.md` -- inline display labels on enum entries
+
+These files are populated by Wave B2 and own the domain-specific schema reference content. The
+codify ceremony files above own the write pipeline. This SKILL.md owns intent classification
+and routing.
+
+---
+
+## Monorepo vs External
+
+### External projects (canonical scope -- full power)
+
+In external projects (`external/nirvana-marketing`, `external/ZentaraHQ`, etc.) this skill has
+full power: read + write + codify + toggle. The org-model file is
+`foundations/config/organization-model.ts` (or `core/config/organization-model.ts` for
+`external/_template`-derived projects). Extension files live in `foundations/config/extensions/`.
+
+This is the environment where Codify and Toggle intents write. All six ceremony steps apply.
+
+### Monorepo (read-only pointer for tenants; direct PR for platform)
+
+The monorepo-side skill at `.claude/skills/knowledge/SKILL.md` is a read-only pointer. For
+tenant agents reading the platform OM, it reads `packages/elevasis-core/src/organization-model.ts`
+(the workspace-resident platform OM, importable as `@repo/elevasis-core/organization-model`).
+It documents read patterns and explicitly declines write operations for tenant contexts.
+
+To modify the Elevasis runtime/platform OM, edit `packages/elevasis-core/src/organization-model.ts`
+via a standard PR in the monorepo -- this is source-controlled workspace code, not an external
+project. To modify your own tenant org-model state, work in `external/<your-project>/` where
+`/knowledge` has full write power via the codify ceremony.
+
+Cross-link: `.claude/skills/knowledge/SKILL.md` (monorepo pointer)
+
+---
+
+## Cross-Links
+
+- `/org-os` -- Organization OS architecture overview, seven layers, propagation pipeline,
+  feature/surface management. Use `/org-os` when the question is about the architecture or
+  propagation system rather than reading or editing org-model values. Cross-link:
+  `.claude/skills/org-os/SKILL.md`
+- `/configure` -- Legacy org-model editor (pre-absorption). Absorbed into this skill; all
+  Codify and Toggle intents now route here. `/configure` vocabulary still works as a domain
+  hint (e.g., "configure identity" is parsed as domain=identity, intent=Describe-or-Codify).
+
+---
+
+**Last Updated:** 2026-05-02

package/reference/claude-config/skills/{configure → knowledge}/operations/codify-level-a.md

@@ -1,100 +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.
+# 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.