flow-wizard

What this skill does

# Flow Documentation Wizard

An interactive, conversational skill that guides users through documenting business flows in EventCatalog — step by step, section by section — while cross-referencing their existing catalog resources.

## Instructions

### Step 1: Locate the User's Catalog

Before anything else, you need to find the user's EventCatalog project so you can cross-reference existing resources.

Ask: **"Do you have an EventCatalog project I can look at? If so, where is it?"**

- If they provide a path, verify it's an EventCatalog project by checking for `eventcatalog.config.js` or known directories (`services/`, `agents/`, `events/`, `domains/`, `flows/`).
- If they have the EventCatalog MCP server connected, use `getResources` to discover what's in the catalog.
- If they don't have one, that's fine — you'll document steps as plain text descriptions without resource references. Let them know they can still create a useful flow and add resource links later.

Once located, scan the catalog to build an inventory of existing resources:
- Read existing services, agents, events, commands, queries, domains, channels, and flows
- Note their IDs, names, and versions — you'll use these to suggest matches as the user walks through their flow

### Step 2: Ask What Flow They Want to Document

Ask: **"What flow would you like to document? Describe the end-to-end process you're trying to capture."**

Let the user describe the flow in their own words. Examples:
- "User signs up, gets a welcome email, and is added to our CRM"
- "Order is placed, payment is processed, inventory is reserved, and the order is shipped"
- "A customer submits a support ticket, it gets triaged, assigned to an agent, and resolved"
- "A support agent receives an order event, looks up order context, and updates the support case"

From their description, break the flow into **sections** (high-level stages). Present these sections back to the user for confirmation:

**Example response:**
> Based on your description, I can see roughly these sections:
> 1. **User Registration** — the user signs up
> 2. **Welcome Communication** — welcome email is sent
> 3. **CRM Integration** — user is added to the CRM
>
> Does that look right? We'll walk through each one in detail. Feel free to add, remove, or reorder sections.

Wait for confirmation before proceeding.

### Step 3: Walk Through Each Section

Go through each section **one at a time**. For each section, ask the user to describe what happens. The user leads the conversation — you follow.

For each section, ask something like:

**"Let's start with [Section Name]. What happens here? Who or what triggers it, and what happens as a result?"**

As the user describes what happens, you need to:

#### A. Identify the Step Type

From their description, determine which flow step type(s) this section involves:

- **Actor** — a person or role does something (e.g., "the user clicks sign up", "the admin approves")
- **Service** — a service in their architecture processes something (e.g., "our auth service handles registration")
- **Agent** — an AI agent reasons, invokes tools, or automates part of the process (e.g., "the refund agent reviews the case")
- **Message** — an event, command, or query is exchanged (e.g., "a UserRegistered event is fired")
- **External System** — a third-party system is involved (e.g., "we call Stripe for payment", "Twilio sends the SMS")

A single section may produce multiple steps (e.g., a user action triggers a command, which is handled by a service, which emits an event).

#### B. Cross-Reference the Catalog

For each step the user describes, search their EventCatalog (if available) for matching resources:

1. **Services** — Does the service they mention exist in the catalog? Search by name, ID, or similar terms.
2. **Agents** — Does the AI agent, assistant, copilot, or autonomous worker they mention exist in the catalog?
3. **Events/Commands/Queries** — Does the message they describe match something already documented? Look for exact matches and close matches (e.g., user says "order created event" → search for `OrderCreated`, `OrderPlaced`, etc.).
4. **Channels** — Are there channels relevant to how this message flows?
5. **Domains** — Does this step fall within a documented domain?

**If you find a match**, tell the user:

> I found a **[resource type]** called `[ResourceName]` (version `[version]`) in your catalog that looks like it matches. Would you like to reference it in this step?

If they say yes, use the resource's actual `id` and `version` in the flow step.

**If you find multiple possible matches**, present them and let the user choose:

> I found a few resources that might match what you're describing:
> - `OrderCreated` (event, v1.0.0) — "Emitted when a new order is placed"
> - `OrderPlaced` (event, v0.0.1) — "Published when checkout completes"
>
> Which one fits, or is this something new?

**If you find no match**, that's perfectly fine. Document it as a descriptive step:
- If it sounds like a service, use `service` type with a suggested ID and note it's not yet in the catalog
- If it sounds like an AI agent, use `agent` type with a suggested ID and note it's not yet in the catalog
- If it sounds like a message, use `message` type with a suggested ID
- If it's a person/role, use `actor` type
- If it's a third-party tool/API, use `externalSystem` type

Let the user know: **"I didn't find this in your catalog. I'll document it as [step type] for now. You can create the full resource later if you'd like."**

#### C. Confirm Each Section Before Moving On

After processing a section, summarize what you've captured for that section and ask the user to confirm before moving to the next one.

**Example:**
> Here's what I've captured for **Payment Processing**:
>
> 1. `ProcessPayment` command is sent (matched to your existing `ProcessPayment` command v0.0.1)
> 2. `PaymentService` handles the payment (matched to your existing `PaymentService` v1.2.0)
> 3. `FraudReviewAgent` reviews fraud signals (matched to your existing `FraudReviewAgent` v0.0.1)
> 4. Calls **Stripe** (external system) to charge the card
> 5. `PaymentProcessed` event is emitted (not in your catalog yet — I'll use a placeholder)
>
> Does that look right? Anything to add or change?

### Step 4: Handle Branching and Edge Cases

As you walk through sections, watch for:

- **Branching paths** — "If payment succeeds, we continue; if it fails, we notify the user"
  - Ask: **"It sounds like there's a decision point here. What are the possible paths?"**
  - Document these as `next_steps` (plural) with labels for each branch

- **Loops** — "The service retries if the external call fails"
  - Document as a step that references back to an earlier step via `next_step`

- **Error/failure paths** — "If validation fails, we send back an error"
  - These are terminal steps or branch to a notification/error handling step

- **Parallel paths** — "While payment processes, we also reserve inventory"
  - Document as separate branches from a common step using `next_steps`

When you detect branching, explicitly confirm the paths with the user:

> **"It sounds like there's a fork here. After [step], these things could happen:**
> 1. [Success path] → continues to [next section]
> 2. [Failure path] → [what happens]
>
> **Is that right? Are there other outcomes?"**

### Step 5: Build the Flow Summary

After walking through all sections, present a complete summary of the flow before generating the file:

> **Here's the complete flow: [Flow Name]**
>
> 1. [Step 1 summary] → [Step 2]
> 2. [Step 2 summary] → [Step 3]
> 3. [Step 3 summary] → branches to [Step 4a] or [Step 4b]
> ...
>
> **Resources matched from your catalog:** [list of matched resources]
> **New resources (not yet in catalog):** [list of unmatched items]
>
> Ready to generate the flow file?

### Step 6: Generate the Flow File

Once the user confirms, generate the flow `index.mdx` file following the format in `referenc