@elevasis/sdk 1.22.1 → 1.24.0

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

@@ -1,345 +0,0 @@
----
-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, systems, actions, 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?", "system 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,
-    core/config/organization-model.ts, packages/elevasis-core/src/organization-model/index.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"
-    - "core/config/organization-model.ts"
-    - "packages/elevasis-core/src/organization-model/**"
-    - "packages/core/src/knowledge/**"
-  promptSignals:
-    phrases:
-      - playbook
-      - knowledge node
-      - system governs
-      - outreach cadence
-      - identity
-      - customer segment
-      - codify
-      - enable system
-      - toggle system
-      - what governs
-      - org model
-      - organization model
-      - offerings
-      - techStack
-      - roles
-      - goals
-      - labels
-      - knowledge map
-      - governance edge
-      - knowledge mount
-      - knowledge graph
-      - knowledge browser
-      - ontology
-      - by-ontology
-      - 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, systems, actions, 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`,
-  `core/config/organization-model.ts`, `packages/elevasis-core/src/organization-model/index.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 system?", "where does outreach-cadence apply?"                  | Same CLI; pick mount axis from intent; default to `by-system` 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 with shared-layer impact preview: snapshot -> propose -> confirm -> write -> typecheck -> Zod parse -> rollback on failure |
-| Toggle   | "enable the lead-gen system", "turn off SEO"                                       | Codify ceremony scoped to the `systems` domain; flip availability/routing state; same validation/rollback     |
-
----
-
-## Shared Layering Preview
-
-When opening a domain that uses a closed stage, status, or catalog vocabulary -- especially
-prospecting, CRM, outreach, or another pipeline-like domain -- read the scaffold-shipped primer:
-
-```bash
-node_modules/@elevasis/sdk/reference/spine/spine-primer.md
-```
-
-Use it to emit a short domain layering preview before the normal read, describe, or codify flow:
-
-1. **Catalog:** which `organizationModel.<domain>` catalog owns the keys, labels, descriptions,
-   ordering, and entity ownership.
-2. **Runtime state:** where record progress is stored as sparse state keyed by those catalog
-   members.
-3. **Producers:** which templates, automations, or factories write entity-tagged results for those
-   keys.
-4. **Consumers:** which dashboards, queues, reports, filters, or API reads render or aggregate the
-   same keys.
-
-For vibe-coder sessions, translate this into plain language: "business profile", "saved progress",
-"automations", and "dashboard or reports". For technical sessions, it is acceptable to name the
-catalog, state map, producer, and consumer surfaces directly. External tenants route all follow-ups
-through `/knowledge`; do not point them at monorepo-only commands.
-
----
-
-## Organization Model Navigation Guide
-
-Use this map whenever the task asks what something is, where it lives, what governs it, or
-what adjacent context may matter:
-
-| Question | Start here | Then inspect |
-| --- | --- | --- |
-| What Systems exist? | `core/config/organization-model.ts` | System IDs, parentage, lifecycle, UI metadata, and content |
-| What governs a System? | `/by-system/<id>` knowledge read | system entry, governed knowledge, roles, policies, graph `governs` edges |
-| What resources belong to a System? | the id-keyed `organizationModel.resources` map and `getResourcesForSystem(model, systemPath)` | use `{ includeDescendants: true }` only for parent-scope rollups |
-| What can a System do? | system action refs and the actions domain | `action.resourceId`, invocation metadata, affected entities, policies |
-| What data does it own? | entities domain | owning System refs, state catalogs, entity links, emitted/projected events |
-| What operational content exists? | system `content` | content helpers and scaffold migration helpers when available |
-| What UI surface exposes it? | `navigation.sidebar` plus `SystemModule` manifests | route files, surface targets, route-prefix modules, guards |
-| What knowledge applies? | knowledge domain plus graph edges | `knowledge:cat`, `knowledge:graph`, `/graph/<id>/governed-by` |
-
-Do not treat any one read as a complete system snapshot. The OM is a set of related
-domain maps; follow the relationship that matches the work. Prefer structured helpers
-from `@elevasis/core/organization-model` over ad hoc string scanning when code access is
-available.
-
----
-
-## Read Patterns
-
-### Monorepo (platform defaults)
-
-```bash
-pnpm exec elevasis knowledge:ls
-pnpm exec elevasis knowledge:cat <node-id>
-pnpm exec elevasis knowledge:ls /by-system/<system-id>
-pnpm exec elevasis knowledge:ls /by-owner/<owner-id>
-pnpm exec elevasis knowledge:ls /by-ontology/<ontology-id> --ids-only
-pnpm exec elevasis knowledge:graph <node-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:ls /by-system/<system-id>
-pnpm exec elevasis-sdk knowledge:ls /by-owner/<owner-id>
-pnpm exec elevasis-sdk knowledge:ls /by-ontology/<ontology-id> --ids-only
-pnpm exec elevasis-sdk knowledge:graph <node-id>
-```
-
-Use `knowledge:ls` to enumerate all knowledge nodes. Use `knowledge:cat` to read a specific
-node's content. Use `knowledge:ls /by-system/<system-id>` or
-`knowledge:ls /by-owner/<owner-id>` to navigate system and owner groupings. Use
-`knowledge:ls /by-ontology/<ontology-id> --ids-only` to find knowledge attached to a public
-ontology id, then `knowledge:cat` each returned node. Use `knowledge:graph <node-id>` to
-inspect incoming and outgoing graph edges for a specific node.
-
-When a `/knowledge` query clearly names an ontology id such as
-`sales.crm:object/deal`, route through `/by-ontology/<id>` automatically and read the
-returned nodes. When the query names an ontology graph node id such as
-`ontology:sales.crm:object/deal`, strip the `ontology:` graph prefix for the
-`/by-ontology/<id>` path and inspect the graph node only when the user asks for graph
-edges or adjacent context.
-
-### `/knowledge read-folder` (chat shorthand from the Knowledge Browser)
-
-The Knowledge Browser's copy button on a top-level system 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 system:<id>` | `pnpm exec elevasis-sdk knowledge:ls /by-system/<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    |
-| `/knowledge read-folder owner:<id>`  | `pnpm exec elevasis-sdk knowledge:ls /by-owner/<id> --ids-only`, then `knowledge:cat` each     |
-| `/knowledge read-folder ontology:<id>` | `pnpm exec elevasis-sdk knowledge:ls /by-ontology/<id> --ids-only`, then `knowledge:cat` each |
-| `/knowledge read-folder graph:<id>`  | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids      |
-
-Dotted system ids may use either dots or slashes (`sales.crm` and `sales/crm` both work
-with `knowledge:ls`). Legacy `feature:<id>` copy lines may still appear in older browser
-builds; treat them as compatibility aliases for `system:<id>` and resolve through `/by-system/`.
-Ontology read-folder ids are public Knowledge axes; route them through `/by-ontology/<id>`.
-Per-node leaves still copy as `/knowledge read <node-id>`. Browser group/domain/item folders
-usually copy explicit N-line read lists when they contain knowledge nodes; if they fall back to
-`group:`, `domain:`, `item:`, or `folder:` route ids, treat those as UI route breadcrumbs, not
-CLI mounts. Resolve them from visible child knowledge ids or the corresponding OM/graph context.
-
-`read-folder system:<id>` is the baseline knowledge read, not a mandatory full-system
-snapshot. Start by loading governing knowledge nodes. Broaden into adjacent Organization
-Model context only when the current task makes it relevant:
-
-- Runtime or implementation work: inspect the id-keyed `organizationModel.resources` map with
-  `getResourcesForSystem(model, id)` or `getResourcesForSystem(model, id, { includeDescendants: true })`.
-- Operational configuration: inspect the system entry, `system.content`, `getContent()`,
-  `resolveSystemContent()`, and scaffold migration helpers when applicable.
-- Governance or access work: inspect roles, policies, actions, entities, and graph edges
-  through the Organization Graph or direct `core/config/organization-model.ts` domain reads.
-- Deployment/code work: follow resource ids into `operations/src/**` only when the task
-  needs executable implementation details.
-
-There is no first-class CLI mount for "all resources/actions/entities/policies/roles by
-system" yet. Use the helpers above or scan the org model plus the relevant domain maps.
-
----
-
-## 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 `core/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.
-
-For stage, status, or catalog vocabulary edits, include the shared-layer impact preview before
-asking for confirmation. Name the affected catalog key, whether existing sparse runtime state may
-contain the old key, which producers/templates reference it, and which consumers render or filter by
-it. If the impact cannot be determined from the local project, say which surface is unknown and keep
-the write gated.
-
-### 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 `core/config/organization-model.ts`.
-  Execute: `.claude/skills/knowledge/operations/codify-level-a.md`
-- **Level B** -- new Zod extension files in `core/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` -- legacy compatibility notes for feature wording; current availability/routing work uses Systems and Actions language
-- `.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/_template`, `external/ZentaraHQ`, etc.) this skill has
-full power: read + write + codify + toggle. The org-model file is
-`core/config/organization-model.ts` (or `core/config/organization-model.ts` for
-`external/_template`-derived projects). Extension files live in `core/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/index.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 files under `packages/elevasis-core/src/organization-model/`
-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
-
-- `/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).
-- `node_modules/@elevasis/sdk/reference/spine/spine-primer.md` -- Scaffold-shipped layering
-  primer for stage/status/catalog vocabularies that coordinate business-profile entries, runtime
-  progress, producers, and consumers in tenant projects.
-
----
-
-**Last Updated:** 2026-05-02