Guides users through documenting business flows step-by-step in EventCatalog, including services, agents, messages, actors, and external systems. Use when user asks to "document a flow", "map a business process", "create a flow diagram", "walk through a process", "document an end-to-end flow", "map an agent workflow", or "map out how something works in my architecture".
Guides users through documenting business flows step-by-step in EventCatalog, including services, agents, messages, actors, and external systems. Use when user asks to "document a flow", "map a business process", "create a flow diagram", "walk through a process", "document an end-to-end flow", "map an agent workflow", or "map out how something works in my architecture".
license
MIT
metadata
{"author":"eventcatalog","version":"1.0.0"}
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:
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:
User Registration — the user signs up
Welcome Communication — welcome email is sent
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:
Services — Does the service they mention exist in the catalog? Search by name, ID, or similar terms.
Agents — Does the AI agent, assistant, copilot, or autonomous worker they mention exist in the catalog?
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.).
Channels — Are there channels relevant to how this message flows?
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:
ProcessPayment command is sent (matched to your existing ProcessPayment command v0.0.1)
PaymentService handles the payment (matched to your existing PaymentService v1.2.0)
FraudReviewAgent reviews fraud signals (matched to your existing FraudReviewAgent v0.0.1)
Calls Stripe (external system) to charge the card
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:
[Success path] → continues to [next section]
[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]
[Step 1 summary] → [Step 2]
[Step 2 summary] → [Step 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 references/flows.md.
Rules for generation:
Use the user's catalog directory. Ask where the flow should be saved if unclear — either flows/{FlowName}/index.mdx or domains/{Domain}/flows/{FlowName}/index.mdx depending on their catalog structure.
For matched resources (found in catalog), use the exact id and version from the catalog:
