flow-wizard

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/, systems/, 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, systems, channels, containers (data stores), data products, 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 kind of step(s) this section involves. Each step is one of these (see references/flows.md for the exact shapes):

• 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")
• Channel — where a message travels, when it matters (e.g., "it goes onto the orders Kafka topic")
• System — a whole system takes part, internal or external (e.g., "the billing platform handles it")
• Container — a data store is read or written (e.g., "we save it to the orders database")
• Data product — an analytical data product is produced or consumed
• Sub-flow — the process hands off to another documented flow (e.g., "then the refund flow starts")
• External System — a third-party system that isn't in the catalog (e.g., "we call Stripe for payment", "Twilio sends the SMS")
• Custom — anything else worth drawing (a manual review, a UI, a scheduled job)
• Plain step — a titled box that points at nothing (e.g., "the cancellation is rejected")

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). A step can never be two things at once — "the service emits an event" is two steps.

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. Systems — Is this a documented system (including external systems with scope: external, e.g. Stripe)? Prefer a system step over externalSystem when it is.
6. Containers / data products — Is the data store or data product they mention documented?
7. 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 — but don't point at a resource that doesn't exist. A service, agent, message, channel, system, container, dataProduct or flow pointer to something missing fails the linter (refs/resource-exists, an error by default). Ask the user which they prefer:

• Create the resource first — document it with the catalog-documentation-creator skill, then point the step at it. Best for services, agents and messages that really exist.
• Describe it without a pointer — a plain titled step (id + title + summary), or a custom step with an icon. Good for things they don't want to document yet.
• If it's a person/role, use actor
• If it's a third-party tool/API that isn't in the catalog, use externalSystem

Let the user know: "I didn't find this in your catalog. I'll [create it / describe it as a plain step] for now. You can document the full resource later and point the step at it."

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 — want me to create it first, or describe it as a plain step for now?)

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 references/flows.md.

Rules for generation:

1. Use the user's catalog directory. Ask where the flow should be saved if unclear — flows/{FlowName}/index.mdx, domains/{Domain}/flows/{FlowName}/index.mdx, or under a system (systems/{System}/flows/{FlowName}/index.mdx) depending on their catalog structure. If the flow belongs to a domain or system, also add it to that domain's or system's flows frontmatter — the folder alone doesn't link them.

2. For matched resources (found in catalog), use the exact id and version from the catalog. title is optional — it defaults to the resource's name, so only set it when a different label reads better:

   - id: "payment_processing"
     service:
       id: "PaymentService"
       version: "1.2.0"
   

   Agent steps use the agent field:

   - id: "fraud_review"
     agent:
       id: "FraudReviewAgent"
       version: "0.0.1"
   

   Channel, system, container, data product and sub-flow steps use the same { id, version } shape under channel, system, container, dataProduct or flow.

3. For unmatched resources the user chose not to create yet, write a plain step (no pointer) or a custom step:

   - id: "send_welcome_email"
     title: "Send Welcome Email"
     summary: "WelcomeEmailRequested is sent (not documented yet)"
   

4. For actors, use the role or persona name:

   - id: "user_initiates_signup"
     title: "User Signs Up"
     actor:
       name: "Customer"
   

5. For external systems, include name, summary, and URL if known:

   - id: "stripe_charges_card"
     title: "Stripe Payment"
     externalSystem:
       name: "Stripe"
       summary: "Third-party payment processor"
       url: "https://stripe.com"
   

6. Connect all steps with next_step or next_steps as appropriate.

7. Terminal steps (end of flow or end of a branch) should have no next_step.

8. The body should be <NodeGraph />.

   Never add a type field to steps (it's ignored), and put any custom step metadata in x- keys — unknown keys fail the build.

9. Set version to 0.0.1 for new flows.

10. Write a meaningful summary that describes the end-to-end business process.

Step 7: Validate and Write

Before writing the file:

1. Verify all step IDs are unique within the flow
2. Verify all next_step / next_steps references point to valid step IDs, and no step has both
3. Verify every pointer matches a resource id (and version, if set) in the catalog
4. Verify no step points at two things, and there are no unknown keys (custom ones must start with x-)
5. Verify the YAML frontmatter is valid
6. Verify <NodeGraph /> is in the body

Write the file to the user's catalog directory. If the catalog has a lint script (catalogs from create-eventcatalog run eventcatalog-linter), run npm run lint and fix anything it reports.

After writing, let the user know:

• Where the file was saved
• Which resources were matched from their catalog
• Which resources are new/unmatched — suggest they can document these later using the catalog-documentation-creator skill, especially new agents
• They can view the flow visualization in EventCatalog by running their dev server, and group it by domain, system or team from the flow page (or open it grouped with <Flow id="..." lanes="team" />)

Conversation Guidelines

• The user leads. You ask questions and guide, but the user describes what happens in their own words. Don't assume or invent steps.
• One section at a time. Don't rush ahead. Confirm each section before moving on.
• Be helpful with matches. When you find catalog resources that match, proactively suggest them — but always let the user decide.
• Be honest about misses. If nothing in the catalog matches, say so plainly and document it descriptively.
• Keep it conversational. This is a guided walkthrough, not a form to fill out. Be natural and responsive.
• Suggest, don't dictate. If the user's description doesn't perfectly map to a step type, suggest what you think fits and ask if that's right.
• Handle complexity gracefully. If a flow gets complex (many branches, loops), help the user keep track by summarizing periodically.

Searching the Catalog

When searching for matching resources, use these strategies:

1. Exact ID match — search for the exact name mentioned (e.g., "OrdersService" → look for OrdersService)
2. Fuzzy match — search for variations (e.g., "orders service" → try OrdersService, OrderService, orders-service)
3. Semantic match — if the user says "the thing that handles payments", search for services with "payment" in the name or summary
4. Browse by type — if you know it's an event, search events specifically
5. Agent terms — if the user says "assistant", "copilot", "worker", "reviewer", or "agent", search agents/ before treating it as an external system

If the EventCatalog MCP server is available:

• Use getResources to list all resources
• Use getResource to get details on a specific resource
• Use findResourcesByOwner to explore resources by team

If reading the filesystem directly:

• Look in services/, agents/, events/, commands/, queries/, domains/, systems/, flows/, channels/, containers/, data-products/ directories (they can also be nested under domains and systems)
• Read index.mdx files to check id, name, version, and summary fields

Quality Checklist

Before delivering the flow file:

1. Every step has a unique id
2. Every step has a clear label — a title, or a pointer whose resource name reads well (title defaults to it)
3. Every step is at most one thing (actor, service, agent, message, channel, system, container, dataProduct, flow, custom, or externalSystem), and no step has a type field
4. All next_step and next_steps references point to valid step IDs within the flow
5. No orphaned steps (every step is reachable from the first step, except via branching)
6. Every pointer matches a resource in the catalog (no placeholders — they fail refs/resource-exists)
7. The flow has a clear start (first step) and at least one terminal step (no next_step)
8. YAML frontmatter is valid with --- delimiters
9. File is named index.mdx
10. <NodeGraph /> is in the body
11. version is a valid semver string
12. summary describes the business process meaningfully