@elevasis/sdk 1.5.2 → 1.5.4

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

@@ -0,0 +1,66 @@
+---
+name: dsp
+description: Dispatch subagents in parallel for implementation tasks
+---
+
+# DSP -- Dispatch Subagents in Parallel
+
+Parallel agent dispatch for implementation tasks. Orchestrate, then delegate to subagents.
+
+**Usage:** `/dsp <instructions>`
+
+## Rules
+
+1. **Always dispatch, never self-execute** -- the purpose is to offload work to subagents
+2. **Parallel within waves** -- all agents in a wave dispatched in a SINGLE message
+3. **Read docs first** -- always read `docs/index.md` before planning to understand project structure
+
+## Process
+
+### Step 1: Understand Context
+
+1. Read `docs/index.md` for project structure and navigation
+2. Read relevant architecture/feature docs based on the task domain
+3. If the task touches code, explore the relevant `src/` directories
+
+### Step 2: Analyze Complexity
+
+**Single-Wave** -- all tasks independent, dispatch everything at once
+**Multi-Wave** -- tasks have dependencies, execute waves sequentially
+
+### Step 3: Plan
+
+For each unit of work, identify:
+
+- What files/areas are affected
+- What context the subagent needs
+- Whether it depends on another task's output
+
+Print the plan:
+
+```
+DSP Plan: N waves, M tasks
+Wave 1: [description] -- N tasks
+Wave 2: [description] -- N tasks (if multi-wave)
+Dispatching Wave 1...
+```
+
+### Step 4: Dispatch
+
+Use the Agent tool with `subagent_type="general-purpose"` and `model="sonnet"`.
+
+Each agent prompt must include:
+
+- The specific task to accomplish
+- Relevant file paths and context
+- Instruction to use backslash paths for file operations on Windows
+
+### Step 5: Aggregate Results
+
+```
+DSP Results: [description]
+
+Tasks completed: X/Y
+Files modified: [list]
+Next steps: [if any]
+```

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

@@ -0,0 +1,239 @@
+---
+name: elevasis
+description: Elevasis platform operations -- check, deploy, execute, inspect, and debug SDK resources
+---
+
+# Elevasis Platform Operations
+
+Manage SDK resources in the `operations/` workspace via the `elevasis-sdk` CLI.
+
+**Usage:**
+
+- `/elevasis` -- Show available operations
+- `/elevasis check` -- Validate resource definitions
+- `/elevasis deploy [--prod]` -- Deploy resources
+- `/elevasis exec <resourceId> [--input '...']` -- Execute a resource
+- `/elevasis describe <resourceId>` -- Show resource schema
+- `/elevasis logs <resourceId>` -- View recent executions
+- `/elevasis creds` -- Manage credentials
+
+## Critical Rules
+
+- **Always describe before exec** -- run `describe` first to see the exact input schema
+- **Use `-f` for complex inputs** -- write JSON to a temp file to avoid shell escaping issues
+- **Always `check` before `deploy`** -- catches schema and config errors early
+
+## Environment
+
+The CLI authenticates via `ELEVASIS_PLATFORM_KEY` in the root `.env` file. The CLI walks up directories to find `.env`, so it works from both the project root and `operations/`.
+
+For dev vs prod targeting:
+
+- Default: production (`https://api.elevasis.io`)
+- `--prod` flag: explicitly targets production (overrides `NODE_ENV=development`)
+- `ELEVASIS_API_URL` env var: override to any custom URL
+
+## Operations
+
+### Check
+
+Validate all resource definitions (schemas, contracts, config):
+
+```bash
+pnpm -C operations exec elevasis-sdk check
+```
+
+Reports: resource count, validation errors, schema serialization warnings. Exit code 0 = pass.
+
+### Deploy
+
+Bundle and deploy resources to the Elevasis platform.
+
+Before calling the SDK deploy, run both doc generators in sequence so the uploaded docs reflect the current resource state (resources first, then nav so `docs/index.md` picks up `resources.md`):
+
+```bash
+pnpm exec elevasis-sdk generate-resources
+pnpm exec elevasis-sdk generate-docs
+pnpm -C operations exec elevasis-sdk deploy [--prod]
+```
+
+Replace `[--prod]` with `--prod` when targeting production.
+
+**Version bumping flags** (written back to `src/index.ts`):
+
+- `--major` -- bump major (1.0.0 to 2.0.0) for breaking contract changes
+- `--minor` -- bump minor (1.0.0 to 1.1.0) for new features
+- `--patch` -- bump patch (1.0.0 to 1.0.1) for fixes
+
+Deploy replaces the previous active deployment. Resources become executable immediately.
+
+### Describe
+
+**Always run before executing.** Shows resource metadata, input/output schemas, and step chain:
+
+```bash
+pnpm -C operations exec elevasis-sdk describe <resourceId>
+
+# JSON output for programmatic use
+pnpm -C operations exec elevasis-sdk describe <resourceId> --json
+```
+
+Output includes: type, name, version, status, domains, input schema (required/optional fields with types), output schema, step definitions with entry point and routing.
+
+### Execute
+
+Run a deployed resource. **Always `describe` first to see the input schema.**
+
+```bash
+# Simple input (inline JSON)
+pnpm -C operations exec elevasis-sdk exec <resourceId> -i '{"key": "value"}'
+
+# Complex input (temp file -- PREFERRED for non-trivial payloads)
+# Write input to a temp file first, then reference it with -f
+pnpm -C operations exec elevasis-sdk exec <resourceId> -f .tmp-input.json
+
+# Async execution (for long-running workflows -- polls until complete)
+pnpm -C operations exec elevasis-sdk exec <resourceId> -f .tmp-input.json --async
+```
+
+**When to use `-f` (file input):**
+
+- Input contains nested objects, arrays, or special characters
+- Input has quotes that conflict with shell escaping
+- Input is reused across multiple executions
+- Any time inline `-i` causes parsing errors
+
+**Temp file pattern:**
+
+1. Write the JSON to a temp file inside the project (e.g., `operations/.tmp-input.json`)
+2. Execute with `-f .tmp-input.json`
+3. Delete the temp file after
+
+**Sync vs async:**
+
+- Sync (default): blocks until execution completes, shows result inline
+- Async (`--async`): returns execution ID immediately, polls every 3s with elapsed timer
+- Use `--async` for workflows that may exceed 30 seconds
+
+**Connection failure recovery:** If the connection drops during sync execution, the CLI automatically searches recent executions for a running one and resumes polling.
+
+### List Resources
+
+View all deployed resources:
+
+```bash
+pnpm -C operations exec elevasis-sdk resources
+
+# JSON output
+pnpm -C operations exec elevasis-sdk resources --json
+```
+
+Shows: resource ID, type (workflow/agent), name, description, status.
+
+### Execution History
+
+View past executions for a resource:
+
+```bash
+# List recent executions (default: last 50)
+pnpm -C operations exec elevasis-sdk executions <resourceId>
+
+# Filter by status
+pnpm -C operations exec elevasis-sdk executions <resourceId> --status failed --limit 10
+
+# View specific execution (full detail with logs)
+pnpm -C operations exec elevasis-sdk execution <resourceId> <executionId>
+
+# Logs only (skip metadata)
+pnpm -C operations exec elevasis-sdk execution <resourceId> <executionId> --logs-only
+
+# Include input and result data
+pnpm -C operations exec elevasis-sdk execution <resourceId> <executionId> --input --result
+```
+
+**`executions` flags:** `--limit <n>` (default 50), `--status running|completed|failed`, `--json`
+
+**`execution` flags:** `--logs-only`, `--input`, `--result`, `--json`
+
+Execution detail shows: status, start/end times, duration, input, result, error (if failed), and timestamped logs with level (ERROR/WARN/INFO/DEBUG).
+
+### Deployments
+
+View deployment history:
+
+```bash
+pnpm -C operations exec elevasis-sdk deployments
+```
+
+Shows: deployment ID, SDK version, status (active/deploying/failed/stopped), created timestamp.
+
+### Credentials
+
+Manage integration credentials (API keys, webhook secrets):
+
+```bash
+# List credentials (metadata only, secrets not exposed)
+pnpm -C operations exec elevasis-sdk creds list
+
+# Create a credential
+pnpm -C operations exec elevasis-sdk creds create --name my-api-key --type api-key --value '{"apiKey":"sk-..."}'
+
+# Update a credential value
+pnpm -C operations exec elevasis-sdk creds update my-api-key --value '{"apiKey":"new-key"}'
+
+# Rename a credential
+pnpm -C operations exec elevasis-sdk creds rename old-name --to new-name
+
+# Delete a credential
+pnpm -C operations exec elevasis-sdk creds delete my-api-key --force
+```
+
+Credential names: lowercase, digits, hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`). Types: `api-key`, `webhook-secret`.
+
+### Rename Resource
+
+Rename a resource ID across all platform tables:
+
+```bash
+# Dry run (preview only)
+pnpm -C operations exec elevasis-sdk rename old-id --to new-id
+
+# Apply rename
+pnpm -C operations exec elevasis-sdk rename old-id --to new-id --execute
+```
+
+Always dry-run first to see affected tables and row counts.
+
+### Error Resolution
+
+Mark execution errors as resolved:
+
+```bash
+# Resolve a specific error
+pnpm -C operations exec elevasis-sdk error resolve <errorId>
+
+# Resolve all errors for an execution
+pnpm -C operations exec elevasis-sdk error resolve-execution <executionId>
+```
+
+## Standard Workflow
+
+```
+1. Write/modify resources     operations/src/
+2. Type-check                 pnpm -C operations run check-types
+3. Validate                   /elevasis check
+4. Deploy                     /elevasis deploy --prod
+5. Describe                   /elevasis describe <id>
+6. Execute                    /elevasis exec <id> -f input.json
+7. Inspect logs               /elevasis logs <id>
+```
+
+## Debugging Checklist
+
+When an execution fails:
+
+1. **Get the execution ID** from the exec output or `executions <resourceId> --status failed`
+2. **Read the logs**: `execution <resourceId> <executionId> --logs-only`
+3. **Check the input**: `execution <resourceId> <executionId> --input`
+4. **Check the error**: `execution <resourceId> <executionId> --result`
+5. **Fix the handler**, redeploy, re-execute

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

@@ -0,0 +1,78 @@
+---
+name: explore
+description: Codebase exploration anchored to project documentation
+---
+
+# Explore
+
+Codebase exploration anchored to project documentation.
+
+**Usage:** `/explore [area or question]`
+
+## Process
+
+### Step 0: OS-Vocab Classification
+
+Before orienting, scan the user's query for Organization OS terminology. If any of the following appear, classify the query as **OS-relevant** and follow the OS context steps below; otherwise skip to Step 1.
+
+**OS vocabulary triggers:**
+
+- Feature layer: `feature`, `features`, `FeatureModule`, `feature key`, `feature gate`, `feature access`, `gate`, `gating`, `access`, `enable`, `disable`
+- Shell / nav: `manifest`, `shell`, `sub-shell`, `sidebar`, `nav`, `navigation`, `route`
+- Auth / guards: `guard`, `FeatureGuard`, `AdminGuard`, `ProtectedRoute`, `admin`
+- Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
+- Foundations: `foundation`, `foundations`, `@foundation/`, `adapter`
+- Platform ops: `workflow`, `agent`, `deployment`, `resource`
+
+**If OS-relevant:**
+
+1. Read `docs/reference/active-change-index.md` immediately. If the target area is flagged as under active refactor, surface the watch-area warning to the user before proceeding — include the "Load:" doc paths listed in that entry so investigation does not rely on stale scaffold prose.
+2. Build the OS context bundle to pass into Step 3:
+   - Always: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`, `docs/reference/active-change-index.md`, `docs/agent-start-here.md`
+   - Features / Shell / Gating queries: add `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+   - Workflow / Operations queries: add `docs/operations/index.md` + `docs/resources.md`
+   - Organization-model queries: add `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` + `foundations/config/README.md`
+
+**OS layer → query intent map** (guides which reference docs the investigator loads first):
+
+| Query intent                             | Primary OS layers                | Key reference                                                                            |
+| ---------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
+| "Why doesn't my feature show up?"        | Features + UI Shell Runtime      | `glossary.md` (accessFeatureKey, FEATURE_KEY_ALIASES), `feature-flags-and-gating.md`     |
+| "How do I add a nav item?"               | Features + Toolkit               | `feature-flags-and-gating.md`, `contracts.md`                                            |
+| "How does admin gating work?"            | Features + UI Shell Runtime      | `glossary.md` (AdminGuard, requiresAdmin, ProtectedRoute), `feature-flags-and-gating.md` |
+| "What runs when this workflow triggers?" | Platform Public API + Operations | `operations/index.md`, `resources.md`                                                    |
+| "Why does the foundations adapter fail?" | Foundations                      | `glossary.md` (domain vs surface, settings asymmetry), `foundations/config/README.md`    |
+
+### Step 1: Orient
+
+1. Read `docs/index.md` for the full project structure
+2. Determine which domain the user's question falls into
+
+### Step 2: Load Domain Context
+
+Read the relevant doc(s) and source directories based on the area being explored. Use the Navigation table in `CLAUDE.md` for quick reference.
+
+For OS-relevant queries, also inject the OS context bundle assembled in Step 0 into the investigator's starting context.
+
+### Step 3: Investigate
+
+For targeted questions:
+
+- Use Grep to search for specific patterns, function names, or strings
+- Use Glob to find files by pattern
+- Read specific files for detailed understanding
+
+For broad exploration:
+
+- Dispatch a `general-purpose` subagent with the domain context and exploration question
+- The subagent should read files, trace data flow, and return a structured report
+- For OS-relevant queries, pass the preloaded OS context bundle so the subagent starts with terminology already resolved
+
+### Step 4: Report
+
+Present findings with:
+
+- Direct answers to the question
+- Relevant code locations (file:function format)
+- Connections to other parts of the system
+- Suggestions for related areas to explore (if relevant)