---
name: setup
description: First-time project setup — detect and replace template placeholders, install dependencies, verify build, then hand off to /om 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 `/om`.

**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 `/om`.

**State B — Already bootstrapped, org-model at defaults:** No placeholders found, but `core/config/organization-model.ts` contains only the default display naming override (just `identity.organizationName`, `identity.productName`, `identity.shortName`, with legacy `branding.*` fallback values — no customers, offerings, roles, goals, or techStack overrides). Print:

```
This project is already set up. The organization model has not been configured yet.
Running /om to set up your organization profile...
```

Then execute `/om` (the full layered flow) and stop.

**State C — Fully configured:** No placeholders found AND `core/config/organization-model.ts` has at least one non-default business domain populated (customers, offerings, roles, goals, techStack, or identity fields beyond display naming/client brief). Print:

```
This project is already configured. To update your organization profile, run /om.
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 `/om` 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
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 /om

After a successful bootstrap, transition to the org-model configuration flow. Print:

```
Bootstrap complete. Now let's set up your organization profile.
```

Then execute `/om` (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 /om.

If the user wants to skip org-model setup for now, they can stop here and run `/om` 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 `/om`, which has its own diff-preview and confirm ceremony.

---

## Relationship to /om

`/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 `/om` for full org-model configuration

`/om` owns all other structural org-model editing (identity fields beyond clientBrief, customers, offerings, roles, goals, techStack, systems, actions, labels, and legacy feature compatibility). It is idempotent, confirm-before-overwrite, and includes a runtime validation gate. Re-run `/om` any time organizational reality changes — no need to re-run `/setup`.

---

## Capability Surface

When a user asks what skills or commands are available, do NOT answer from recollection.

- **Skill inventory:** Read `.claude/Overview.md` — it is the authoritative list of skills available in this project.
- **Live CLI capability:** Run `pnpm elevasis-sdk cli` — it outputs every command and domain currently registered in the SDK, grouped by domain.
