@elevasis/sdk 1.15.0 → 1.16.0

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

@@ -1,275 +1,275 @@
----
-name: setup
-description: First-time project setup — detect and replace template placeholders, install dependencies, verify build, then hand off to /configure for org-model configuration
-argument-hint: ""
----
-
-# Setup
-
-First-time project setup for projects cloned directly from the template. Handles placeholder replacement, dependency install, and build verification. After bootstrap, delegates org-model configuration to `/configure`.
-
-**Usage:** `/setup`
-
----
-
-## State Detection (Run Before Anything Else)
-
-Before collecting any information or running any steps, determine which state the project is in. Read these files:
-
-- `package.json` — look for `__PROJECT_SLUG__` in the `name` field
-- `CLAUDE.md` — look for `TEMPLATE_PROJECT_NAME` AND check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings
-- `ui/package.json` — look for `__PROJECT_SLUG__`
-- `ui/index.html` — look for `__PROJECT_NAME__`
-
-**State A — Virgin (placeholders present):** One or more of the above placeholder strings is found. Run the full bootstrap flow (Steps 1–7 below), then hand off to `/configure`.
-
+---
+name: setup
+description: First-time project setup — detect and replace template placeholders, install dependencies, verify build, then hand off to /knowledge for org-model configuration
+argument-hint: ""
+---
+
+# Setup
+
+First-time project setup for projects cloned directly from the template. Handles placeholder replacement, dependency install, and build verification. After bootstrap, delegates org-model configuration to `/knowledge`.
+
+**Usage:** `/setup`
+
+---
+
+## State Detection (Run Before Anything Else)
+
+Before collecting any information or running any steps, determine which state the project is in. Read these files:
+
+- `package.json` — look for `__PROJECT_SLUG__` in the `name` field
+- `CLAUDE.md` — look for `TEMPLATE_PROJECT_NAME` AND check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings
+- `ui/package.json` — look for `__PROJECT_SLUG__`
+- `ui/index.html` — look for `__PROJECT_NAME__`
+
+**State A — Virgin (placeholders present):** One or more of the above placeholder strings is found. Run the full bootstrap flow (Steps 1–7 below), then hand off to `/knowledge`.
+
 **State B — Already bootstrapped, org-model at defaults:** No placeholders found, but `core/config/organization-model.ts` contains only the default branding override (just `branding.organizationName`, `branding.productName`, `branding.shortName` — no identity, customers, offerings, roles, goals, or techStack overrides). Print:
-
-```
-This project is already set up. The organization model has not been configured yet.
-Running /configure to set up your organization profile...
-```
-
-Then execute `/configure` (the full layered flow) and stop.
-
+
+```
+This project is already set up. The organization model has not been configured yet.
+Running /knowledge to set up your organization profile...
+```
+
+Then execute `/knowledge` (the full layered flow) and stop.
+
 **State C — Fully configured:** No placeholders found AND `core/config/organization-model.ts` has at least one non-branding domain populated (identity, customers, offerings, roles, goals, or techStack present). Print:
-
-```
-This project is already configured. To update your organization profile, run /configure.
-To re-verify the build, run the checks below.
-```
-
-Offer to run the verification checks (Steps 6b–6e) if the user wants them. Do not re-ask any questions. Do not re-run placeholder replacement. Stop after verification.
-
----
-
-## Full Bootstrap Flow (State A Only)
-
-### Step 1: Collect Project Info
-
-Ask the user for three values:
-
-1. **Slug** — lowercase, hyphens only (e.g., `acme-dashboard`). Default to the basename of the current working directory.
-2. **Human-readable name** — used in titles, docs, and CLAUDE.md (e.g., `Acme Dashboard`).
-3. **Short description** — one sentence, used in `package.json` and CLAUDE.md (e.g., `Client dashboard for Acme Corp.`).
-
-Confirm the values before proceeding:
-
-```
-Configuring project with:
-  Slug:        <slug>
-  Name:        <name>
-  Description: <description>
-  Date:        <YYYY-MM-DD>
-
-Proceed? (yes/no)
-```
-
-### Step 2: Get to Know the User and Client
-
-Transition naturally after confirming the project values: "Now let me learn a bit about you and the client so I can be more helpful going forward."
-
-**About the user (ask conversationally, one at a time):**
-
-1. **Name** -- "What's your first name?"
-2. **Role** -- "What's your role?" (e.g., founder, developer, project lead)
-3. **Technical level** -- "How comfortable are you with technical stuff? No wrong answer -- just helps me know how to explain things."
-4. **Communication style** -- "When I explain things or write docs, do you prefer short and to-the-point, or more detailed with context?"
-
-Use their name naturally from this point on.
-
-**About the client/company this project is for:**
-
-5. **Company name** -- "Who's this project for? What's the company name?"
-6. **What they do** -- "What does {company} do? Just a sentence or two."
-7. **Industry** -- "What industry or space are they in?"
-8. **Key context** -- "Anything else that would help me understand the project context? Key stakeholders, business goals, important constraints -- whatever comes to mind. (Totally fine to skip, we can add this as we go.)"
-
-React to what they share, ask natural follow-ups if something is interesting or unclear. Don't make it feel like a form.
-
-After gathering, confirm:
-
-```
-Got it! Here's what I captured:
-
-User: {name} ({role}, {technical level}, prefers {style})
-
-Client: {company}
-  {what they do}
-  Industry: {industry}
-  {any additional context}
-
-Look good?
-```
-
-### Step 3: Replace Placeholders
-
-Search ALL files in the project matching these extensions: `.ts`, `.tsx`, `.js`, `.mjs`, `.json`, `.md`, `.mdx`, `.html`, `.yaml`, `.yml`, `.css`, `.env.example`
-
-Exclude these directories and files: `node_modules/`, `dist/`, `.tanstack/`, `pnpm-lock.yaml`
-
-For each matching file, replace all occurrences of:
-
-| Placeholder                    | Replace with            |
-| ------------------------------ | ----------------------- |
-| `__PROJECT_NAME__`             | human-readable name     |
-| `__PROJECT_SLUG__`             | slug                    |
-| `__PROJECT_DESCRIPTION__`      | description             |
-| `__DATE__`                     | today's date YYYY-MM-DD |
-| `TEMPLATE_PROJECT_NAME`        | human-readable name     |
-| `TEMPLATE_PROJECT_DESCRIPTION` | description             |
-
-Use the Read tool to read each file, then the Edit tool (with `replace_all: true`) or Write tool to apply the replacements. Read each file before writing.
-
-After all replacements, re-scan the four key files from State Detection to verify zero placeholders remain. If any are still present, report them by file and fix immediately.
-
-### Step 4: Populate CLAUDE.md Knowledge Sections
-
-**Idempotency check (MANDATORY before writing):** Read `CLAUDE.md` and check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings. Only write if they are still placeholders. If either section is already filled in (user or a previous run already populated it), skip that section entirely — do not overwrite.
-
-**`{CLIENT_CONTEXT}`** -- replace with a single line (only if still a placeholder):
-
-```markdown
-**{company name}** — {what they do, one sentence}
-```
-
-**`{USER_PREFERENCES}`** -- replace with a table (only if still a placeholder):
-
-```markdown
-| Name   | Role   | Technical Level | Communication |
-| ------ | ------ | --------------- | ------------- |
-| {name} | {role} | {level}         | {preference}  |
-```
-
-If the user skipped any knowledge questions, fill in what was provided and omit what wasn't -- don't leave placeholder text behind.
-
-### Step 5: Write Client Brief to Org Model
-
+
+```
+This project is already configured. To update your organization profile, run /knowledge.
+To re-verify the build, run the checks below.
+```
+
+Offer to run the verification checks (Steps 6b–6e) if the user wants them. Do not re-ask any questions. Do not re-run placeholder replacement. Stop after verification.
+
+---
+
+## Full Bootstrap Flow (State A Only)
+
+### Step 1: Collect Project Info
+
+Ask the user for three values:
+
+1. **Slug** — lowercase, hyphens only (e.g., `acme-dashboard`). Default to the basename of the current working directory.
+2. **Human-readable name** — used in titles, docs, and CLAUDE.md (e.g., `Acme Dashboard`).
+3. **Short description** — one sentence, used in `package.json` and CLAUDE.md (e.g., `Client dashboard for Acme Corp.`).
+
+Confirm the values before proceeding:
+
+```
+Configuring project with:
+  Slug:        <slug>
+  Name:        <name>
+  Description: <description>
+  Date:        <YYYY-MM-DD>
+
+Proceed? (yes/no)
+```
+
+### Step 2: Get to Know the User and Client
+
+Transition naturally after confirming the project values: "Now let me learn a bit about you and the client so I can be more helpful going forward."
+
+**About the user (ask conversationally, one at a time):**
+
+1. **Name** -- "What's your first name?"
+2. **Role** -- "What's your role?" (e.g., founder, developer, project lead)
+3. **Technical level** -- "How comfortable are you with technical stuff? No wrong answer -- just helps me know how to explain things."
+4. **Communication style** -- "When I explain things or write docs, do you prefer short and to-the-point, or more detailed with context?"
+
+Use their name naturally from this point on.
+
+**About the client/company this project is for:**
+
+5. **Company name** -- "Who's this project for? What's the company name?"
+6. **What they do** -- "What does {company} do? Just a sentence or two."
+7. **Industry** -- "What industry or space are they in?"
+8. **Key context** -- "Anything else that would help me understand the project context? Key stakeholders, business goals, important constraints -- whatever comes to mind. (Totally fine to skip, we can add this as we go.)"
+
+React to what they share, ask natural follow-ups if something is interesting or unclear. Don't make it feel like a form.
+
+After gathering, confirm:
+
+```
+Got it! Here's what I captured:
+
+User: {name} ({role}, {technical level}, prefers {style})
+
+Client: {company}
+  {what they do}
+  Industry: {industry}
+  {any additional context}
+
+Look good?
+```
+
+### Step 3: Replace Placeholders
+
+Search ALL files in the project matching these extensions: `.ts`, `.tsx`, `.js`, `.mjs`, `.json`, `.md`, `.mdx`, `.html`, `.yaml`, `.yml`, `.css`, `.env.example`
+
+Exclude these directories and files: `node_modules/`, `dist/`, `.tanstack/`, `pnpm-lock.yaml`
+
+For each matching file, replace all occurrences of:
+
+| Placeholder                    | Replace with            |
+| ------------------------------ | ----------------------- |
+| `__PROJECT_NAME__`             | human-readable name     |
+| `__PROJECT_SLUG__`             | slug                    |
+| `__PROJECT_DESCRIPTION__`      | description             |
+| `__DATE__`                     | today's date YYYY-MM-DD |
+| `TEMPLATE_PROJECT_NAME`        | human-readable name     |
+| `TEMPLATE_PROJECT_DESCRIPTION` | description             |
+
+Use the Read tool to read each file, then the Edit tool (with `replace_all: true`) or Write tool to apply the replacements. Read each file before writing.
+
+After all replacements, re-scan the four key files from State Detection to verify zero placeholders remain. If any are still present, report them by file and fix immediately.
+
+### Step 4: Populate CLAUDE.md Knowledge Sections
+
+**Idempotency check (MANDATORY before writing):** Read `CLAUDE.md` and check whether `{CLIENT_CONTEXT}` and `{USER_PREFERENCES}` are still literal placeholder strings. Only write if they are still placeholders. If either section is already filled in (user or a previous run already populated it), skip that section entirely — do not overwrite.
+
+**`{CLIENT_CONTEXT}`** -- replace with a single line (only if still a placeholder):
+
+```markdown
+**{company name}** — {what they do, one sentence}
+```
+
+**`{USER_PREFERENCES}`** -- replace with a table (only if still a placeholder):
+
+```markdown
+| Name   | Role   | Technical Level | Communication |
+| ------ | ------ | --------------- | ------------- |
+| {name} | {role} | {level}         | {preference}  |
+```
+
+If the user skipped any knowledge questions, fill in what was provided and omit what wasn't -- don't leave placeholder text behind.
+
+### Step 5: Write Client Brief to Org Model
+
 **Idempotency check:** Read `core/config/organization-model.ts` and inspect `identity.clientBrief`. If the field is already a non-empty string, skip this step entirely — do not overwrite.
-
-If the field is empty or absent, compose the client brief from the information gathered in Step 2:
-
-```markdown
-**Company:** {company name}
-**Industry:** {industry}
-**Description:** {what they do}
-
-## Additional Context
-
-{any additional context shared — key stakeholders, business goals, constraints, etc. If nothing was shared, write "No additional context provided yet. Update this as the project evolves."}
-```
-
-Propose the composed content to the user before writing (read → propose → confirm → write — the same ceremony `/configure` uses):
-
-```
-Here's the client brief I'll write into identity.clientBrief:
-
----
-{composed content}
----
-
-Write this? (yes/no)
-```
-
+
+If the field is empty or absent, compose the client brief from the information gathered in Step 2:
+
+```markdown
+**Company:** {company name}
+**Industry:** {industry}
+**Description:** {what they do}
+
+## Additional Context
+
+{any additional context shared — key stakeholders, business goals, constraints, etc. If nothing was shared, write "No additional context provided yet. Update this as the project evolves."}
+```
+
+Propose the composed content to the user before writing (read → propose → confirm → write — the same ceremony `/knowledge` uses):
+
+```
+Here's the client brief I'll write into identity.clientBrief:
+
+---
+{composed content}
+---
+
+Write this? (yes/no)
+```
+
 On confirmation, use the Edit tool to replace the `clientBrief: ''` value in `core/config/organization-model.ts` with a template literal containing the composed markdown. Use a regular string (backtick or single-quoted multi-line) — ensure the closing quote and trailing comma are correct TypeScript.
-
-After the edit, run:
-
-```bash
+
+After the edit, run:
+
+```bash
 pnpm -C core test
-```
-
-If type-check fails, report the error and do not proceed to Step 6 until it is resolved.
-
-### Step 6: Install and Verify
-
-#### Step 6a: Install Dependencies
-
-```bash
-pnpm install
-```
-
-This generates the project's own `pnpm-lock.yaml`. Report success or any errors.
-
-#### Step 6b–6e: Verify Build
-
-Run all checks sequentially (stop and report on first failure, but attempt all):
-
-```bash
-pnpm -C ui check-types
-pnpm -C ui build
-pnpm -C operations check
-pnpm -C operations check-types
-```
-
-For each check, record PASS or FAIL. If a check fails, read the output and report the error clearly. Do not silently skip failures.
-
-### Step 7: Bootstrap Report
-
-```
-You're all set, {name}!
-========================
-Project: <Human Name>
-Slug:    <slug>
-Client:  <company name> (<industry>)
-
-Verification:
-  [PASS/FAIL] Type-check (ui)
-  [PASS/FAIL] Production build (ui)
-  [PASS/FAIL] Resource validation (operations)
-  [PASS/FAIL] Type-check (operations)
-```
-
-If any verification step failed, add an Errors section listing each failure with its output.
-
-### Step 8: Hand Off to /configure
-
-After a successful bootstrap, transition to the org-model configuration flow. Print:
-
-```
-Bootstrap complete. Now let's set up your organization profile.
-```
-
-Then execute `/configure` (the full layered flow, no argument). This is where identity, customers, offerings, roles, goals, and techStack are configured. Do not attempt to collect or write org-model data here — that ceremony belongs entirely to /configure.
-
-If the user wants to skip org-model setup for now, they can stop here and run `/configure` later.
-
----
-
-## Error Recovery
-
-If placeholder replacement leaves stragglers:
-
-```
-Placeholder Cleanup Required
-=============================
-Remaining: <list files and placeholders>
-Action: Re-applying replacements to affected files...
-```
-
-Fix each remaining occurrence before proceeding to Step 6a.
-
----
-
-## Idempotency Guarantees
-
-Running `/setup` more than once is safe:
-
-- **Placeholder replacement** only runs when placeholders are detected (State A). It is skipped entirely in States B and C.
-- **CLAUDE.md knowledge sections** (`{CLIENT_CONTEXT}`, `{USER_PREFERENCES}`) are checked before writing. If already replaced, the write is skipped.
-- **`identity.clientBrief`** is only written when the field is empty. A non-empty field is never overwritten by `/setup`. The write uses a read → propose → confirm ceremony before touching the file.
-- **All other org-model fields** (`core/config/organization-model.ts`) are never written by `/setup`. All other org-model edits go through `/configure`, which has its own diff-preview and confirm ceremony.
-
----
-
-## Relationship to /configure
-
-`/setup` is a thin bootstrap wrapper. It:
-
-1. Replaces scaffold placeholders (project name, slug, description)
-2. Fills lightweight CLAUDE.md knowledge sections (user and client basics, idempotent)
-3. Writes the client brief into `identity.clientBrief` in the org model (confirm-before-write, idempotent)
-4. Installs dependencies and verifies the build
-5. Hands off to `/configure` for full org-model configuration
-
-`/configure` owns all other structural org-model editing (identity fields beyond clientBrief, customers, offerings, roles, goals, techStack, features, labels). It is idempotent, confirm-before-overwrite, and includes a runtime validation gate. Re-run `/configure` any time organizational reality changes — no need to re-run `/setup`.
+```
+
+If type-check fails, report the error and do not proceed to Step 6 until it is resolved.
+
+### Step 6: Install and Verify
+
+#### Step 6a: Install Dependencies
+
+```bash
+pnpm install
+```
+
+This generates the project's own `pnpm-lock.yaml`. Report success or any errors.
+
+#### Step 6b–6e: Verify Build
+
+Run all checks sequentially (stop and report on first failure, but attempt all):
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+pnpm -C operations check
+pnpm -C operations check-types
+```
+
+For each check, record PASS or FAIL. If a check fails, read the output and report the error clearly. Do not silently skip failures.
+
+### Step 7: Bootstrap Report
+
+```
+You're all set, {name}!
+========================
+Project: <Human Name>
+Slug:    <slug>
+Client:  <company name> (<industry>)
+
+Verification:
+  [PASS/FAIL] Type-check (ui)
+  [PASS/FAIL] Production build (ui)
+  [PASS/FAIL] Resource validation (operations)
+  [PASS/FAIL] Type-check (operations)
+```
+
+If any verification step failed, add an Errors section listing each failure with its output.
+
+### Step 8: Hand Off to /knowledge
+
+After a successful bootstrap, transition to the org-model configuration flow. Print:
+
+```
+Bootstrap complete. Now let's set up your organization profile.
+```
+
+Then execute `/knowledge` (the full layered flow, no argument). This is where identity, customers, offerings, roles, goals, and techStack are configured. Do not attempt to collect or write org-model data here — that ceremony belongs entirely to /knowledge.
+
+If the user wants to skip org-model setup for now, they can stop here and run `/knowledge` later.
+
+---
+
+## Error Recovery
+
+If placeholder replacement leaves stragglers:
+
+```
+Placeholder Cleanup Required
+=============================
+Remaining: <list files and placeholders>
+Action: Re-applying replacements to affected files...
+```
+
+Fix each remaining occurrence before proceeding to Step 6a.
+
+---
+
+## Idempotency Guarantees
+
+Running `/setup` more than once is safe:
+
+- **Placeholder replacement** only runs when placeholders are detected (State A). It is skipped entirely in States B and C.
+- **CLAUDE.md knowledge sections** (`{CLIENT_CONTEXT}`, `{USER_PREFERENCES}`) are checked before writing. If already replaced, the write is skipped.
+- **`identity.clientBrief`** is only written when the field is empty. A non-empty field is never overwritten by `/setup`. The write uses a read → propose → confirm ceremony before touching the file.
+- **All other org-model fields** (`core/config/organization-model.ts`) are never written by `/setup`. All other org-model edits go through `/knowledge`, which has its own diff-preview and confirm ceremony.
+
+---
+
+## Relationship to /knowledge
+
+`/setup` is a thin bootstrap wrapper. It:
+
+1. Replaces scaffold placeholders (project name, slug, description)
+2. Fills lightweight CLAUDE.md knowledge sections (user and client basics, idempotent)
+3. Writes the client brief into `identity.clientBrief` in the org model (confirm-before-write, idempotent)
+4. Installs dependencies and verifies the build
+5. Hands off to `/knowledge` for full org-model configuration
+
+`/knowledge` owns all other structural org-model editing (identity fields beyond clientBrief, customers, offerings, roles, goals, techStack, features, labels). It is idempotent, confirm-before-overwrite, and includes a runtime validation gate. Re-run `/knowledge` any time organizational reality changes — no need to re-run `/setup`.