@elevasis/sdk 1.31.0 → 1.33.0

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

@@ -0,0 +1,201 @@
+---
+name: client
+description: "Client portfolio management -- list, resolve, inspect, and maintain client records and their lineage to companies, contacts, and source deals -- via the elevasis-sdk client:* CLI."
+argument-hint: "[list | status | get | resolve | create | update | delete] [args]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Client Management
+
+`/client` is the entrypoint for all client-portfolio work in the template. It covers:
+
+- **Portfolio status** -- bare `/client` or `/client status` gives a portfolio-level overview of all clients.
+- **Lookup and resolution** -- `/client <query>` or `/client resolve <query>` resolves a name or search term to a canonical client ID.
+- **Detail and lineage** -- `/client get <id>` returns full client detail including linked companies, contacts, and source deals.
+- **CRUD surface** -- create, update, and delete client records via `elevasis-sdk client:*`.
+
+**Usage:**
+
+- `/client` / `/client status` -- Portfolio overview (see "Status Mode" below). Wraps `client:status`.
+- `/client list [--search q] [--status s] [--limit n] [--offset n]` -- Paginated client list. Wraps `client:list`.
+- `/client <query>` / `/client resolve <query>` -- Fuzzy-resolve a client by name, UUID, or search string. Wraps `client:resolve`.
+- `/client get <id>` -- Full client detail: name, status, source, linked company, contact, deals. Wraps `client:get`.
+- `/client create --name "..." [options]` -- Create a new client (confirm ceremony). Wraps `client:create`.
+- `/client update <id> [options]` -- Update client fields (confirm ceremony). Wraps `client:update`.
+- `/client delete <id>` -- Delete a client (destructive -- explicit confirmation required). Wraps `client:delete`.
+
+---
+
+## Ambient Vibe Integration
+
+`/client` is the landing point for client-scoped vibe intents. Agents arriving from the ambient layer behave identically to a direct invocation.
+
+| Vibe intent    | What vibe detected                                          | What to do here                                                                                       |
+| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Describe**   | "tell me about Acme", "what's the status of this client"    | Resolve the client name via `client:resolve`, then run `client:get <id>` and narrate detail + lineage |
+| **Query**      | "which clients are active", "list clients", "client status" | Run `client:list [--status s] [--search q]` or `client:status` and present the results                |
+| **Navigate**   | "focus on Acme", "switch to Acme", "back to Acme"           | Resolve via `client:resolve <query>`, update scope to that client, narrate the new context            |
+| **Capture**    | "add a new client", "create a client for Beta LLC"          | Draft fields from the user's message, confirm with user (Capture ceremony), then `client:create`      |
+| **Transition** | "update Acme's status", "mark Acme as active"               | Confirm the change with user (Transition ceremony), then `client:update <id> --status <new>`          |
+
+`client:create`, `client:update`, and `client:delete` MUST route through the standard Capture/Transition confirm step before executing. The destructive `client:delete` requires explicit user confirmation (show what will be deleted and ask "Are you sure?" before proceeding).
+
+---
+
+## Prerequisites
+
+**Run from the project root** (the directory containing `.elevasis`). Before issuing any other commands, run:
+
+```bash
+pnpm elevasis-sdk doctor
+```
+
+If `doctor` fails, stop immediately and surface the error -- do not retry other commands. Fix the reported issue first (missing `.env`, bad API key, wrong directory), then re-run `doctor` before proceeding.
+
+---
+
+## Invocation Contract
+
+All `elevasis-sdk` commands in this skill use the wrapper script form:
+
+```bash
+pnpm elevasis-sdk <subcommand> [flags]
+```
+
+Available from the **project root** -- the directory that contains the `.elevasis` marker file. The long form `pnpm -C operations exec elevasis-sdk <subcommand>` is equivalent.
+
+---
+
+## Status Mode (bare `/client` or `/client status`)
+
+When invoked without a subcommand or with `status`, enter **client portfolio mode**: present a high-level overview and offer next actions.
+
+```bash
+pnpm elevasis-sdk client:status --pretty
+```
+
+Present the result as a compact summary: total clients, breakdown by status, and a suggestion of what to do next (e.g. "3 active clients. Inspect one with `/client get <id>` or list all with `/client list`").
+
+---
+
+## Operations
+
+### `list [options]` -- Client List
+
+```bash
+pnpm elevasis-sdk client:list --pretty
+
+# Filter by status
+pnpm elevasis-sdk client:list --status active --pretty
+
+# Search by name
+pnpm elevasis-sdk client:list --search "Acme" --pretty
+
+# Paginate
+pnpm elevasis-sdk client:list --limit 20 --offset 0 --pretty
+```
+
+**Options:** `--status <status>`, `--search <query>`, `--limit <n>`, `--offset <n>`, `--api-url <url>`, `--pretty`
+
+Present as a compact table: name, status, source.
+
+### `resolve <query>` -- Name-to-ID Resolution
+
+Resolves a name, UUID, or search string to a canonical client record. This is the primary tool for name-to-ID translation before any `get`, `update`, or `delete` call.
+
+```bash
+pnpm elevasis-sdk client:resolve "Acme" --pretty
+```
+
+If multiple candidates match, the CLI returns candidates -- pick the right one and confirm with the user before proceeding. If zero match, surface the error and suggest `client:list --search "<query>"` to browse.
+
+### `get <id>` -- Client Detail and Lineage
+
+```bash
+pnpm elevasis-sdk client:get <id> --pretty
+```
+
+Returns full client detail: name, status, source, source deal, linked primary company, primary contact, and metadata. Narrate the lineage in plain language (e.g. "Acme Corp -- active client, sourced from deal john@acme.com, linked to Acme Corp (acq_companies)").
+
+### `create` -- Create Client (Confirm Ceremony)
+
+**Always confirm before creating.** Collect required and optional fields, draft a summary, and ask the user to confirm before executing.
+
+**Required:** `--name <name>`
+
+**Optional:** `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--primary-company-id <uuid>`, `--primary-contact-id <uuid>`, `--metadata <json>`
+
+```bash
+pnpm elevasis-sdk client:create \
+  --name "Acme Corp" \
+  --status active \
+  --source deal \
+  --source-deal-id <deal-uuid> \
+  --pretty
+```
+
+After creation, show the new client ID and suggest `/client get <id>` to verify.
+
+### `update <id>` -- Update Client (Confirm Ceremony)
+
+**Always confirm before updating.** Show the current state via `client:get <id>`, draft the proposed changes, and ask the user to confirm before executing.
+
+**Options:** `--name <name>`, `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--clear-source-deal`, `--primary-company-id <uuid>`, `--clear-primary-company`, `--primary-contact-id <uuid>`, `--clear-primary-contact`, `--metadata <json>`
+
+```bash
+pnpm elevasis-sdk client:update <id> --status active --pretty
+```
+
+To clear a linked field, use the corresponding `--clear-*` flag (e.g. `--clear-source-deal`, `--clear-primary-company`, `--clear-primary-contact`). Do NOT pass an empty string -- it is rejected. Use the clear flag instead.
+
+### `delete <id>` -- Delete Client (Destructive -- Explicit Confirmation Required)
+
+**ALWAYS confirm before deleting.** Show the client record first (via `client:get <id>`), then ask the user explicitly: "Delete client `<name>` (`<id>`)? This cannot be undone." Only proceed after an affirmative confirmation.
+
+```bash
+pnpm elevasis-sdk client:delete <id> --pretty
+```
+
+---
+
+## Client Inference
+
+When the user refers to a client by name rather than ID, resolve using these steps (in priority order):
+
+1. **Exact UUID** -- if the argument looks like a UUID, use it directly with `client:get`
+2. **`client:resolve`** -- run `client:resolve "<name>"` to fuzzy-match by name; use the returned ID
+3. **`client:list --search`** -- if `resolve` returns no match, search with `client:list --search "<name>"` and present candidates
+4. **Context from conversation** -- if a specific client was resolved earlier in this session, prefer it
+5. **Ambiguous** -- if multiple match or none match, show candidates and ask
+
+---
+
+## Natural Language Mode
+
+When args do not match any command pattern, infer intent from natural language:
+
+| User says                                         | Inferred operation                                          |
+| ------------------------------------------------- | ----------------------------------------------------------- |
+| "show me Acme"                                    | `resolve "Acme"` then `get <id>`                            |
+| "who are our active clients"                      | `list --status active --pretty`                             |
+| "client overview" / "how many clients do we have" | `status --pretty`                                           |
+| "add a new client: Beta LLC"                      | `create --name "Beta LLC"` (confirm ceremony)               |
+| "update Acme to active"                           | `resolve "Acme"` then `update <id> --status active`         |
+| "delete the Gamma client"                         | `resolve "Gamma"` then `delete <id>` (explicit confirm)     |
+| "link Acme to deal <uuid>"                        | `resolve "Acme"` then `update <id> --source-deal-id <uuid>` |
+| "remove Acme's source deal"                       | `resolve "Acme"` then `update <id> --clear-source-deal`     |
+
+---
+
+## Safety Rules
+
+1. **Always confirm create/update/delete** -- show proposed changes and ask the user before executing any write operation
+2. **Explicit confirmation for delete** -- `client:delete` is irreversible; require an affirmative "yes" before running
+3. **Organization scoping** -- all API calls are automatically org-scoped via `ELEVASIS_PLATFORM_KEY`; no `--org` flag is required
+4. **Read before write** -- when updating, show current state via `client:get` before applying changes
+5. **Use `--clear-*` flags to unlink** -- never pass empty strings to clear linked fields; use `--clear-source-deal`, `--clear-primary-company`, or `--clear-primary-contact`
+6. **Template project assumption** -- the template is a single-organization project; all `/client` operations are scoped by `ELEVASIS_PLATFORM_KEY`; there is no cross-org capability
+
+---
+
+**Last Updated:** 2026-06-03