/diff-adopt

name: diff-adopt
description: "Adopt one shared DexDiff methodology — reads a workflow description, adapts it to your role and vault, and walks you through setup. Use when the user says 'adopt this workflow', 'set me up like this doc'. Not for a full published profile by handle; use `diff-adopt-profile`."

What This Command Does

**In plain English:** Someone figured out a great way to use Dex for a specific job — like prepping for meetings, reviewing deals, or building performance evidence. This command reads their methodology and walks you through setting up a similar workflow in your vault. It adapts to your role, your tools, and your folder structure. Nothing is copied from their system — your Dex generates everything fresh, tailored to you.

**When to use it:**

• Dex suggested a workflow you might like
• You found a workflow on heydex.ai/diff
• Someone shared a methodology URL or file path with you

**How to run it:**

/diff-adopt @davekilleen/meeting-intelligence
/diff-adopt https://heydex.ai/diff/davekilleen/meeting-intelligence
/diff-adopt 04-Projects/DexDiff/beta/diffs/meeting-prep.yaml

---

Arguments

`$ARGUMENTS` - A reference to one methodology document:

• A hosted reference `@<handle>/<diff-id>` - fetch the raw methodology from the API host:

`GET https://api.heydex.ai/api/diff?author=<handle>&id=<diff-id>`

• A page URL like `https://heydex.ai/diff/<handle>/<diff-id>` - parse out the handle and diff id, then make the same API call. Never WebFetch the page itself: heydex.ai pages are a React app shell and contain no methodology text. The API lives on `api.heydex.ai`; the website host has no `/api/*` routes.
• A local path from the DexDiff draft area, usually under `DEXDIFF_DIFFS_DIR` (default `04-Projects/DexDiff/beta/diffs/meeting-prep.yaml`) (read directly)

The argument is always an explicit location — never a bare name.

Fetch failures must stop the flow with a plain explanation, never silently:

• HTTP 404 - "That workflow was not found. Check the handle and workflow id - the author may have unpublished it."
• Network failure - "Could not reach api.heydex.ai - check your connection and try again. Nothing was changed."
• The response should be a full methodology document carrying `dexdiff_schema: "2.0"`. If it is a short one-line summary instead, say so plainly: "This workflow was published in an old thin format that cannot be regenerated faithfully - ask the author to re-publish it." Do not invent the missing methodology.

If no argument or invalid input:

/diff-adopt expects a workflow reference, URL, or file path.

Examples:
  /diff-adopt @davekilleen/meeting-intelligence
  /diff-adopt https://heydex.ai/diff/davekilleen/meeting-intelligence
  /diff-adopt 04-Projects/DexDiff/beta/diffs/meeting-prep.yaml

---

The Onboarding Flow

This is a guided conversation, not a transaction. Walk the user through each phase. Be warm, clear, and educational. The user may not know what skills, hooks, or CLAUDE.md sections are — explain in plain language what each thing DOES, not what it IS.

---

Phase 1: Introduce the Job

Read the YAML file and parse it. Confirm `dexdiff_schema: "2.0"`.

Present the workflow by leading with the PROBLEM it solves and what it UNLOCKS — not technical details:

[name] — by [author.display_name], [author.role]

THE PROBLEM
[methodology.problem — full text, this is the hook]

WHAT PEOPLE SAY
"[love_letter.text]"
— [love_letter.author]

[love_letter.metrics as bullet points]

WHAT THIS UNLOCKS
After setup, you'll be able to:
  /[command-1]  — [one-line description]
  /[command-2]  — [one-line description]

Want to set this up? [Yes, let's go] [Tell me more first]

**If "Tell me more first":** Show `methodology.solution` in full, walk through each command's example output, explain the integrations that enhance it. Then ask again.

**If "Yes, let's go":** Proceed to Phase 2.

---

Phase 2: Discover Together

Scan the vault and EXPLAIN what you find to the user as you go. This is educational — the user learns about their own setup through the process.

**2a. Understand the user's role**

Check if `System/user-profile.yaml` exists and has a role. If it does, use it. If not, ask:

Quick question — what's your role? This helps me tailor the workflow to what matters most to you.

[Show roles from methodology.roles if available, otherwise free text]

Look up the matching role in `methodology.roles` to get the adaptation guidance.

**2b. Scan folders**

Let me look at your vault structure...

[For each folder in methodology.vault_structure.folders:]
  ✓ [purpose]: Found at [actual path]
  OR
  ○ [purpose]: Not found — I'll create [typical_path] (or suggest a location)

**2c. Check integrations**

Checking your connected tools...

[For each integration in methodology.integrations:]
  ✓ [name] — connected. [one-line value statement]
  OR
  ○ [name] — not connected. [what the workflow does WITHOUT it]
     (You can add this later with /integrate-mcp)

**2d. Check existing skills**

Checking for existing workflows...

[For each command in methodology.user_experience.commands:]
  ○ /[name] — you don't have this yet, I'll create it
  OR
  ⚡ /[name] — you already have this! [explain whether to skip, enhance, or replace]

**2e. Summarise the discovery**

Here's what I found:

  Your role: [role] — I'll frame everything around [adaptation summary]
  Your data: [list connected integrations]
  Missing (but optional): [list unconnected integrations]
  Your folders: [list matched folders with actual paths]
  Existing workflows: [list any that overlap]

Ready to see the plan? [Yes] [I want to adjust something]

---

Phase 3: Customise

Ask the user targeted questions about how they want the workflow to work. Only ask questions where the methodology has genuine choices — don't ask about things that have obvious defaults.

A few choices before I set things up:

[For each folder that was