workspace-builder

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).

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

• Industry → board-shape map (§ Step 3).
• Column-type repertoire (§ Step 4).
• Shared artifact conventions (§ Shared patterns).

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 — escape hatch for column settings (status labels, number units) not exposed by wrapped tools.

Cross-skill handoffs

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

---

Step 0: Connector check

Goal: Fail fast if the monday MCP connection is missing.

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 it from https://monday.com/mcp, then run this skill again."
   • Stop.
3. If connector works, cache user.id, user.name, default workspace.

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

---

Step 1: Detect mode

• Default — confirm every create_* call before executing.
• Silent — skip confirmations but stay on α scope (no β seed items).
• 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 — let the user describe their 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.

1. If the argument carried a business description, parse it directly. Skip the prompt entirely.
2. Else ask one open AskUserQuestion-style 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."
3. Only if the user's description is genuinely under-specified for a column-set decision (e.g., they mention deal size but not the currency, or volume isn't parseable), ask one clarifying follow-up. Examples:
   • 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. 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."

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.

1. From get_user_context, list workspaces the user can write to.
2. If the user has exactly one writable workspace → use it (skip ask).
3. If multiple → AskUserQuestion with workspace names + option "create a new one".
4. If "create a new one" → create_workspace({ name: "<user input or default 'CRM'>", kind: "open" }) after confirming.
5. 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, (c) Cancel and pick a different workspace?"
   • 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.

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 default "Group Title" / "New Group" entries. Either:
   • Rename the first default group to the first proposed group via all_monday_api (change_simple_column_value doesn't apply to groups; use the group mutation), then create_group for the rest, OR
   • Delete defaults via all_monday_api mutation delete_group and create_group cleanly. (Default mode confirms before delete.)
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 confirms before each call; Silent runs through; Proactive (a) runs through, (b) confirms each, (c) skips seed step.

Confirm-before-write (Default mode)

Before the first create_board call, print a single batched confirm: "I'll create board(s) with columns total in workspace <workspace>. Proceed? (yes / no / show plan again)."

Per-call confirmation only kicks in for delete operations (group deletes) — never for creates inside a confirmed plan. Spamming the user with N confirms defeats the skill.

---

Step 6: Seed β (opt-in)

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

Only runs if mode = Proactive (option a) OR user explicitly opted in at Step 5 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.

create_doc in the user's workspace, title CRM Setup — <Mon DD>, <YYYY>. Body:

# 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:morning-briefing`.
3. **Set up automations.** Open the Automation Center on each board to wire status changes, due-date reminders, and lead routing — these aren't part of this skill yet (coming in v0.2).
4. **Audit hygiene later.** After 30 days, run `/monday-crm:board-diagnosis` 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).

Idempotency: before creating, search same-day docs by title + the <!-- claude-skill-id: workspace-builder --> comment. If found, append-only update (never overwrite earlier content; this protects against repeat runs blowing away an earlier session's record).

---

Step 8: Handoff to morning-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:morning-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>.
• 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).
• 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 user-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.

---

Error handling reference

Failure	Behavior
Connector not installed	Step 0 stops; print install link.
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; never overwrite.
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.