Source 9b09ba947c588783a3601a43

---
name: workspace-builder
description: Build a CRM workspace from scratch — describe your business and get boards, columns, and pipeline stages created in monday. Use when someone says "set up my CRM", "build me a CRM", "create CRM boards for me", "I need a new sales pipeline", "help me get started in monday", "I don't know how to set up my pipeline", or "build me a CRM from scratch". Do not use for questions about an existing board — those belong to daily-briefing or data-cleanup.
argument-hint: "[optional: business description, e.g. 'window coverings, B2C, ~50 leads/month']"
user-invocable: true
allowed-tools: [Read, WebFetch, AskUserQuestion, mcp__monday__get_user_context, mcp__monday__list_workspaces, mcp__monday__workspace_info, mcp__monday__search, mcp__monday__create_workspace, mcp__monday__create_board, mcp__monday__create_group, mcp__monday__create_column, mcp__monday__create_item, mcp__monday__create_doc, mcp__monday__get_board_info, mcp__monday__all_monday_api]
# all_monday_api scope: group rename (update_group), group delete (delete_group — confirmed Default mode only), status label config, number unit config. No other mutations.
---

# Workspace Builder

Sets up a CRM workspace conversationally — turning "I don't know how to start" into a working board on day 1. Replaces the manual template-pick → column-rename → column-add → group-rename loop that gates 442 median days between CRM install and first MCP execution. **This is the single highest-leverage retention skill in the catalog.**

Flow: **Trigger → Discover → Propose → Confirm → Build (α) → Seed (β, opt-in) → Handoff**.

## Input
- Optional: business description via argument.
- Optional: user pre-declared mode (Default / Silent / Proactive). Add "silently" or "skip confirmations" to your request to run in Silent mode. Silent mode builds without per-step confirmations.

## Output
- **α (default):** One board (or set of boards) created in the user's chosen workspace. Boards carry the user's chosen names (no plugin prefix). Groups + columns scaffolded per the proposed structure. A `CRM Setup — <Mon DD>` doc summarizes what was created and what's next, with `Generated by Claude · <ISO timestamp>` + `<!-- claude-skill-id: workspace-builder -->` in the body.
- **β (Seed mode, opt-in):** 5–10 example items per board so the user can see the shape with data, not just empty columns. Each example item carries `Source = Claude` on a status column (auto-create the column with user confirm if missing) — no `[Example]` prefix on names.
- **Proactive extension:** Out of scope for v0.1 (automation creation requires `create_automation_rule`, not yet shipped). The setup doc includes a deep-link to the in-product Automation Recipes UI for that step.

## Knowledge
- monday CRM entity board catalog + relationships (§ monday CRM Entity Boards).
- Industry → board-shape map (§ Step 3).
- Column-type repertoire (§ Step 4).
- Shared artifact conventions (§ Shared patterns).
- GraphQL mutations for group operations: `references/monday-graphql-mutations.md`.

## Tools (MCP)
- `get_user_context` — resolve user + existing workspaces.
- `list_workspaces` / `workspace_info` — find a target workspace.
- `search` — confirm we aren't duplicating an existing CRM board.
- `create_workspace` — only if the user explicitly wants a new workspace.
- `create_board` — the core write.
- `create_group` — pipeline stages as groups (or as status labels — see Step 4).
- `create_column` — typed columns per the proposed schema.
- `create_item` — β seed items.
- `create_doc` — publish the setup summary doc.
- `all_monday_api` — group rename/delete mutations + column settings (status labels, number units) not exposed by wrapped tools. See `references/monday-graphql-mutations.md` for exact payloads.

## Cross-skill handoffs
- **From none (entry point):** First-run user, in-product CTA route, or explicit ask.
- **To daily-briefing:** Once the board has at least 5 items with a stage column populated, suggest `/monday-crm:daily-briefing` to start the daily-ops loop.
- **To data-cleanup:** After 30 days of use, suggest `/monday-crm:data-cleanup` for a fill-rate audit.

---

## monday CRM Entity Boards

monday CRM is built around five canonical entity board types. When proposing a workspace structure, use these as building blocks — don't invent custom schemas. Use the user's own terminology for board and column names, but match the underlying column types and group structure.

**Always propose Deals. Add other boards only when the user's description clearly signals the need.**

### Deals — the pipeline board (always included)

Every monday CRM user starts here.

- **Groups (pipeline stages):** New · Discovery · Proposal · Negotiation · Won · Lost
- **Columns:** Stage (status, `is_done: true` on Won), Owner (people), Deal Value (numbers $), Probability (numbers %), Expected Close (date), Last Touch (date), Source (status), Notes (long_text)

### Contacts — individual people records

Add when the user mentions tracking people, contacts, or has account managers / a team managing relationships.

- **Groups:** Active · Inactive
- **Columns:** Email (email), Phone (phone), Company (text), Owner (people), Source (status), Last Activity (date), Notes (long_text)
- **Relates to:** Deals (link contact to their deal via board_relation)

### Leads — inbound / unqualified prospects

Add when the user mentions SDR, outbound, lead gen, or has a qualification step before deals.

- **Groups:** New · Contacted · Qualified · Disqualified
- **Columns:** Stage (status), Owner (people), Source (status), Email (email), Phone (phone), Company (text), Last Touch (date), Notes (long_text)
- **Relates to:** Deals (qualified leads become deals — link via board_relation)

### Accounts — companies / organizations

Add when the user mentions account management, renewals, B2B with multiple contacts per company, or CSM workflows.

- **Groups:** Active Customers · Prospects · Churned
- **Columns:** Owner (people), Industry (status), Size (numbers), ARR (numbers $), Health (status), Last Activity (date), Notes (long_text)
- **Relates to:** Contacts (people at this account), Deals (deals linked to this account)

### Activities — calls, emails, meetings log

Add when the user explicitly mentions logging activity, tracking touchpoints, or managing a high-touch sales motion with multiple interactions per deal.

- **Groups:** This Week · This Month · Archive
- **Columns:** Type (status: Call / Email / Meeting / Demo), Owner (people), Date (date), Notes (long_text)
- **Relates to:** Deals (the deal this activity belongs to), Contacts (the person involved)

---

### Board relationships

```
Leads ──qualified──▶ Deals ◀──linked──── Accounts
                       │                     │
                       └──── Contacts ────────┘
                                 │
                             Activities
```

- **Leads → Deals:** when a lead qualifies, create (or link to) a deal. board_relation on Leads pointing to Deals.
- **Contacts ↔ Deals:** contacts are participants on deals. board_relation on both sides.
- **Accounts → Contacts + Deals:** an account owns many contacts and many deals. board_relation on Contacts and Deals pointing to Accounts.
- **Activities → Deals + Contacts:** each activity is scoped to one deal and one contact. board_relation columns on Activities.

**v0.1 constraint:** `create_column` with `board_relation` type requires the target board to already exist. Build all boards first (Step 5), then add relation columns in a second pass via `all_monday_api`. Only wire relations the user explicitly asked for — don't create them by default.

---

### Persona → board set

| Signal in user's description | Boards to propose |
|---|---|
| Sales rep / AE / closing deals | **Deals** + Contacts |
| SDR / BDR / outbound / lead gen | **Leads** + Deals |
| Sales manager / team lead | **Deals** — suggest dashboards manually |
| Account manager / renewals / CSM | **Accounts** + Contacts + Deals |
| Full team / full CRM setup | Deals + Contacts + Leads + Accounts |
| Solo founder / small team | **Deals only** — keep it simple |

Never create all 5 boards by default. Blank boards are intimidating and reduce activation.

---

## Step 0: Connector check

**Goal:** Fail fast if the monday MCP connection is missing. Detect the CRM product and cache its numeric ID for workspace creation.

1. Try `mcp__monday__get_user_context`.
2. If missing/auth error/no workspace:
   - Print exactly: *"I don't see the monday connector active on this session. Install the monday connector at monday.com/mcp, then run `/monday-crm:workspace-builder` again."*
   - Stop.
3. If connector works, cache `user.id` and `user.name`.
4. Check `account.products` (from `get_user_context`) for an entry with `kind: "crm"`. If not found, print: *"This plugin requires a monday CRM account. Your current plan doesn't include the CRM product — visit monday.com/crm to start a trial."* and stop.
5. **Get the CRM product's numeric ID** (needed for workspace creation — the `kind` string alone is not sufficient):
   ```graphql
   { account { products { id kind } } }
   ```
   via `all_monday_api`. Find the entry with `kind: "crm"` and cache its `id` as `crmProductId`. This ID is account-specific (e.g., `"1312540"`) — do not hardcode it.

> **PAUSE**: do not write any `create_*` call before Step 5, and never before Step 0 passes.

---

## Step 1: Detect mode

- **Default** — confirm the full build plan once (batch) before executing. Confirms again only for delete operations.
- **Silent** — skip confirmations, stay on α scope (no β seed items). Triggered by "silently", "skip confirmations", or similar in the user's request.
- **Proactive** — ask once: *"Proactive mode will create the board(s), groups, columns, AND seed example items. (a) Approve all, (b) Review each create call, (c) Skip seed items?"*. Cache the choice.

If undeclared, assume **Default**.

Hard safety rail regardless of mode: **no deletes (boards, columns, items), no amount-column writes, no cross-workspace moves, no overwriting an existing same-named board, no modifying columns on boards the user didn't ask us to touch, no board creates outside the user-confirmed workspace**.

---

## Step 2: Discover — learn about the user's business

**Goal:** Get enough signal to propose a board shape without forcing the user into a taxonomy. The whole skill exists to bypass the "where do I start" paralysis — surfacing internal labels like "B2B sales" or "Outbound" defeats that.

### 2a: Website enrichment (preferred)

Ask first:
*"What's your company website? I'll read it to get context on your business — or describe your business in a sentence if you'd prefer."*

- **If a URL is provided** → `WebFetch` the homepage. Extract: industry, product/service description, target customer (B2B/B2C, company size), any sales/CRM terminology used on the site (e.g., "clients", "projects", "leads", "cases"). Use this as the primary business context for Step 3 — skip the free-text question below entirely.
- **If no URL / user prefers to describe** → fall through to 2b.

If `WebFetch` fails (404, timeout, paywalled) → fall through to 2b silently, don't surface the error.

### 2b: Free-text fallback

Ask one open prompt:
*"Tell me about your business — industry, what you sell, who you sell to, roughly how many deals/leads you track. One or two sentences."*

### 2c: One clarifying follow-up (if needed)

Only if the description (from website or free-text) is genuinely under-specified for a column-set decision, ask **one** clarifying follow-up:
- Currency / deal-size unit if values are mentioned.
- Approximate pipeline volume (<50 / 50–500 / 500+) if it'll change between a single-board vs. two-board funnel.

**Hard cap: 2 questions total across 2a–2c.** Anything beyond that defeats the skill.

---

## Step 3: Map description → internal archetype → board shape (Synthesize)

**Goal:** Translate the free-text description into a concrete board proposal. Internal mapping uses an archetype taxonomy as scaffolding — the user never sees the archetype label.

### Internal archetype map (not user-visible)

| Signals in description | Internal archetype | Default board shape |
|---|---|---|
| Long sales cycle, account/stakeholder language ("contracts", "buyers", "procurement"), deal sizes >$1K | B2B sales | Single `Deals` board, pipeline as groups, rich columns |
| High volume / short cycle / consumer-facing ("orders", "customers", "products", e-commerce, retail) | B2C transactional | `Orders` + `Customers` (two boards), pipeline as status column |
| Project / hourly / engagement language ("clients", "retainers", "billable", "projects") | Services | `Engagements` + `Clients`, pipeline as groups, effort/hours columns |
| Outbound / lead-gen / top-of-funnel ("SDR", "cold outreach", "leads", "ICP") | Outbound | `Leads` + `Deals` (two-board funnel), status on Leads, groups on Deals |
| Mixed / unclear / industry-specific (recruiting, real estate, law firm, etc.) | **Custom** | Compose from primitives (see below) — don't force a fit |

### Custom mode

When the description doesn't fit cleanly, compose the board structure from primitives rather than forcing an archetype:

- **Primary entity board** (e.g., `Candidates` for recruiting, `Listings` for real estate, `Matters` for a law firm) — name reflects the user's own language.
- **Pipeline mechanism** (groups vs. status column) — pick groups for low-volume / high-touch, status column for high-volume.
- **Secondary board** if the description names two distinct entities (e.g., `Candidates` + `Roles`, `Listings` + `Buyers`).
- **Columns** chosen from the standard set (Owner, Stage, Value, Probability, Date, Source, Notes) plus 1–3 industry-specific columns inferred from the description.

### Output to user

Present a complete, named board structure as a markdown table. Use **the user's own terminology** wherever possible (if they said "matters", call the board "Matters" not "Cases"). Skip any internal archetype label.

For each proposed board:
- Board name (no plugin prefix).
- Group list with concrete labels.
- Column list with types (e.g., `Stage (status)`, `Owner (people)`, `Value (numbers, $)`, `Last touch (date)`).
- One line of rationale grounded in the user's description (not the archetype): *"You mentioned tracking listings and buyers separately, so I split them across two boards."*

**Do not include workspace name here** — workspace hasn't been resolved yet (Step 4). The batch confirm in Step 5 is where the workspace name appears.

Then ask: *"Build this as-is, change anything before building, or describe your business differently?"*

Hard rule: **no writes** until the user confirms.

---

## Step 4: Resolve target workspace

**Goal:** Land in the right workspace without cluttering Main. Prefer existing CRM workspaces over creating new ones.

1. From `get_user_context`, get the workspace list. Then call `list_workspaces` to get all writable workspaces.
2. **Identify CRM workspaces:** A workspace is likely CRM-native if its name contains "CRM" (case-insensitive) or if it was previously used for CRM boards. Surface CRM-named workspaces first in the options list.
3. If the user has exactly one writable workspace → use it (skip ask).
4. If multiple → `AskUserQuestion` with workspace names (CRM ones labeled `[CRM]`) + option "create a new one".
5. If "create a new one" → after confirming, call:
   ```
   create_workspace({ name: "<user input or default 'CRM'>", workspaceKind: "open", accountProductId: "<crmProductId>" })
   ```
   where `crmProductId` is the **numeric ID cached in Step 0** (e.g., `"1312540"`) — NOT the string `"crm"`. Passing the numeric ID ties the workspace to the monday CRM product; omitting it or passing `"crm"` creates a generic monday workspace with no product association.
6. **Idempotency:** before any `create_board`, `search` for existing boards in this workspace whose names match the proposed names (case-insensitive). If found:
   - Surface to user: *"You already have a board named `<name>`. (a) Skip this board, (b) Create alongside as `<name> 2` (I'll re-confirm the full plan before building), (c) Cancel and pick a different workspace?"*
   - Option (b) updates the plan — show the revised full plan and ask for confirmation before any writes (even in Default mode).
   - Never overwrite, never write into the existing board, never delete it.

---

## Step 5: Build α — create boards (Publish)

**Goal:** Execute the confirmed structure with idempotency, in a deterministic order.

### Confirm-before-write (Default mode)

Before the first `create_board` call, print a single batched confirm:
*"I'll create <N> board(s) with <M> columns total in workspace `<workspace>`. Want example items added after building? (yes / no) — Proceed? (yes / no / show plan again)."*

This single confirm captures both the build plan and the β opt-in. Per-call confirmation only kicks in for **delete** operations (group deletes). Spamming the user with N confirms defeats the skill.

### Build sequence

For each proposed board:

1. `create_board({ boardName: "<name>", workspaceId, boardKind: "public" | "private" })` — default `public` unless user said otherwise. Cache returned `boardId`.
2. **Replace default groups:** monday creates a default "Group Title" / "New Group" entry on every new board. Query existing groups first, then:
   - Rename the first default group to the first proposed group via `all_monday_api` using `update_group` mutation.
   - `create_group` for remaining proposed groups.
   - If renaming fails, use `delete_group` mutation via `all_monday_api` (Default mode confirms before delete) then `create_group` cleanly.
   - See `references/monday-graphql-mutations.md` for exact payloads.
3. For each proposed column: `create_column({ boardId, columnType: <type>, title: <title>, defaults: <settings> })`. For status columns, pass labels via `defaults`; for numbers columns, pass `unit.symbol`.
4. **Order matters for the user's mental model:** create columns left-to-right in the order proposed (Stage first, then Owner, then Value, then dates, then long_text last). monday assigns column position by creation order.
5. After each `create_*`, mirror to chat: *"Created column `Owner` (people) on `Deals`."*. Default mode runs through creates inside a confirmed plan; Silent runs through all; Proactive (b) confirms each; Proactive (c) skips seed step.

---

## Step 6: Seed β (opt-in)

**Goal:** Show the shape with data — empty boards are intimidating.

Only runs if mode = Proactive (option a) OR user opted in at the Step 5 batch confirm.

For each created board, `create_item` for 5 example items distributed across the proposed groups/stages, with realistic but obviously-fake values:
- Names like `Acme Corp — Q3 expansion`, `Beta Industries — pilot deal` (clearly fictional but no prefix pollution).
- Stage spread: 1 New, 2 mid-funnel, 1 Won, 1 Lost (or shape-appropriate).
- Owner = the running user (so every example shows up in the user's "my items" filters).
- All other columns populated to demonstrate the data model.
- **`Source = Claude` on a status column.** The board was just created in Step 5 with this column included by default — Step 6 just sets the value. If for any reason the column wasn't created, prompt once: *"Add a `Source` column so we can flag the example items? (yes / skip — keeps the items unflagged)"*.

Cap at 5 items per board, hard. The `Source = Claude` flag supports a clean cleanup loop later — user filters by source, deletes the examples manually once they have real data.

---

## Step 7: Publish setup doc (Publish)

**Goal:** Leave a navigable summary so the user knows what was created and where to go next.

**Idempotency:** before creating, search same-day docs by title + the `<!-- claude-skill-id: workspace-builder -->` marker. If found, skip creation and print:
*"A setup doc from this session already exists: `<doc url>`. The build summary has been added to chat above."*
Do not attempt to update the existing doc.

If no existing doc found, `create_doc` in the user's workspace, title `CRM Setup — <Mon DD>, <YYYY>`. Body:

```markdown
# CRM Setup — <Mon DD>

<!-- claude-skill-id: workspace-builder -->

## What was created

### Board: <Name>
- Workspace: <workspace>
- URL: <board url>
- Groups: <list>
- Columns: <list with types>

(Repeat per board.)

## Example items
<count> example items added per board, flagged `Source = Claude` on a status column. Filter by that source value to find and remove the examples once you've added real data.

## What's next

1. **Add your real deals.** Replace the examples or add fresh items.
2. **Try the morning briefing.** Once you have 5+ deals with stages set, run `/monday-crm:daily-briefing`.
3. **Set up automations.** Open the Automation Center on each board to wire status changes, due-date reminders, and lead routing.
4. **Audit hygiene later.** After 30 days, run `/monday-crm:data-cleanup` for a fill-rate audit.

---
Generated by Claude · <ISO timestamp> · re-run `/monday-crm:workspace-builder` only if you want to scaffold an additional CRM (won't touch this one).
```

---

## Step 8: Handoff to daily-briefing

If at least one board was created and the user is in Default/Proactive mode, print:
*"Want to try the morning briefing now? Once you add a few real deals it'll prioritize your day. Run `/monday-crm:daily-briefing` whenever you're ready."*

Silent mode skips this prompt.

---

## Step 9: Close the loop

- Print a one-line summary: `Created <N> board(s), <M> columns, <K> seed items. Doc: <url | "doc creation failed — see summary above">.`
- If any write failed mid-run: list the failures and offer to retry only those — never re-run the whole skill on retry (would duplicate boards if Step 4 idempotency was bypassed).

---

## Shared patterns

- **No prefix on titles.** Boards take the user's chosen names. Setup doc uses plain title + `<!-- claude-skill-id: workspace-builder -->` comment + `Generated by Claude` footer in body for findability + idempotency.
- **`Source = Claude` on every seed item** via a status column. No `[Example]` prefix.
- **Idempotency before every create** — board-name collision check, doc same-day collision check (by skill-id comment). On doc collision: skip creation, surface existing link.
- **Safety rail.** No deletes (except confirmed default-group cleanup on freshly-created boards), no amount-column writes, no cross-workspace creates, no writes outside the confirmed plan.
- **Confirm in batches, not per-call** — the whole skill exists to reduce friction; per-call confirms defeat it.
- **Type-based column choices**, not English-name-based — works on non-English monday installs.
- **Use the user's terminology** in board / group / column names, not the internal archetype names.

---

## Output template

### Setup doc (create_doc body)

```markdown
# CRM Setup — Jun 15

<!-- claude-skill-id: workspace-builder -->

## What was created

### Board: Deals
- Workspace: CRM
- URL: https://monday.com/boards/123456789
- Groups: New · Discovery · Proposal · Negotiation · Won · Lost
- Columns: Stage (status) · Owner (people) · Deal Value (numbers, $) · Probability (numbers, %) · Expected Close (date) · Last Touch (date) · Source (status) · Notes (long_text)

## Example items
5 example items added, flagged `Source = Claude` on the Source status column. Filter by that source value to find and remove the examples once you've added real data.
- Acme Corp — Q3 expansion (Discovery, $85K, Owner: Tom Ramu)
- Beta Industries — pilot (Proposal, $32K, Owner: Tom Ramu)
- Gamma Ltd — renewal (Won, $120K, Owner: Tom Ramu)
- Delta Co — trial (New, $15K, Owner: Tom Ramu)
- Epsilon Inc — churned (Lost, $28K, Owner: Tom Ramu)

## What's next
1. **Add your real deals.** Replace the examples or add fresh items.
2. **Try the daily brief.** Once you have 5+ deals with stages set, run `/monday-crm:daily-briefing`.
3. **Set up automations.** Open the Automation Center on each board to wire status changes, due-date reminders, and lead routing.
4. **Audit hygiene later.** After 30 days, run `/monday-crm:data-cleanup` for a fill-rate audit.

---
Generated by Claude · 2026-06-15T09:00:00Z · re-run `/monday-crm:workspace-builder` only if you want to scaffold an additional CRM (won't touch this one).
```

**Chat one-liner:**
```
Created 1 board, 8 columns, 5 seed items. Doc: [url].
```

---

## Error handling reference

| Failure | Behavior |
|---|---|
| Connector not installed | Step 0 stops; print install link + skill re-run command. |
| No writable workspace | Step 4 stops; print: *"You don't have write access to any workspace. Ask a workspace admin, then re-run."* |
| Board name collision | Step 4 idempotency prompt; option (b) re-confirms full plan before building. |
| `create_board` fails (perms) | Stop and surface error verbatim — don't continue creating columns into a non-existent board. |
| `create_column` fails on a column | Skip that column, log to chat, continue with the rest, list skipped in Step 9 summary. |
| `create_group` fails | Skip; the board still works with default groups; flag in summary. |
| 429 rate limit | Backoff 3x (1s, 2s, 4s); on third fail, halt and print: *"monday is rate-limiting; retry in 60s."* |
| User halts mid-build | Keep writes up to halt point; Step 7 setup doc reflects partial state. |
| Setup doc create fails | Print the doc body in chat with banner *"Couldn't publish the setup doc — copy the summary below."* |

---

## Completion criteria

- [ ] Step 0 (connector check) ran and passed.
- [ ] At least one board was created (or user explicitly cancelled at Step 3/4).
- [ ] No internal archetype label leaked into user-visible output (board/group/column names use the user's terminology).
- [ ] Every seed item carries `Source = Claude` on a status column (or the user explicitly skipped the source-column step).
- [ ] The setup doc was created (with `<!-- claude-skill-id: workspace-builder -->` + `Generated by Claude` footer) or printed to chat on failure.
- [ ] Safety rail held: no deletes outside default-group cleanup on freshly-created boards, no amount-column writes, no cross-workspace creates, no writes outside the confirmed plan.
- [ ] The chat summary lists any per-column failures.