Add Scenario

Add a scenario (flow) to the Cosmos

Use this skill when the user asks to "add a scenario", "add a flow", "show what happens when X", or "trace flow Y and add it". A scenario is a named, animated sequence of steps that plays end-to-end across services on the map.

If the service nodes involved don't exist yet, run the add-service skill first — this skill assumes all from / to / via ids already exist in SERVICES / TOPICS.

What you'll touch

Step 1 — Gather the three inputs

Ask the user if any are missing:

1. Domain — which domain does this flow belong to? Check DOMAINS in src/scenarios/scenarios.ts (the demo ships with shopping, fulfillment, engagement). If it doesn't fit, confirm a new domain name — you'll add a Domain entry too.
2. User-facing trigger — what action starts the flow? ("customer clicks Buy", "webhook lands", "cron fires")
3. Done state — what does the user see/hear when it's over? ("order confirmed banner", "email arrives", "live tracking updates")

Step 2 — Trace the real flow

Spawn an Explore agent (or grep yourself if scope is small) to map every hop end-to-end. Don't invent — read source code. For the shipped AstroMart demo there are no source repos; the demo data is illustrative. For YOUR system, this step is the whole point.

For every hop, capture:

Good Explore agent prompt:

Trace the end-to-end flow of "<ACTION>" across these repos: <paths>.
For every step report:
  STEP N · [from] → [to]
    Protocol: HTTP | WS | Kafka | Internal
    Topic (if Kafka): exact name
    Source: file:line
    What it does: 1–3 sentences
    Payload (if HTTP/Kafka): headers + body shape
List any Kafka topics not in this existing list: <TOPICS ids>.
Don't guess — grep the source. Flag unclear hops.

Step 3 — Inventory gaps

• Which services from the trace are missing from SERVICES? → add them (see add-service skill)
• Which topics from the trace are missing from TOPICS? → add them
• What is the next free phaseId? Phase ids are GLOBAL — never positional, never reused:

grep -rh 'phaseId:' src/scenarios/scenarios.ts | grep -o '[0-9]*' | sort -n | tail -1

• Does this scenario already exist with status: 'soon'? → flip it to 'ready' and assign the phaseId.

Step 4 — Add the Scenario entry

Add to the SCENARIOS array (grouped by domain):

{
  id: 'fulfillment.pack-and-ship',        // domain.kebab-slug — globally unique
  domain: 'fulfillment',                   // must match a DOMAINS[].id
  phaseId: 6,                              // next free GLOBAL phase id
  label: 'Pack & ship',                    // shown in the scenario picker
  color: 'var(--svc-emerald)',             // chip accent color
  status: 'ready',                         // 'ready' | 'soon'
  short: 'One sentence describing what the user experiences end-to-end.',
},

If the domain doesn't exist yet, add it to DOMAINS first:

{ id: 'my-domain', label: 'My Domain', glyph: '·', short: 'One-line domain summary' },

Step 5 — Add the Steps

Append to the domain's steps file (src/scenarios/steps/<domain>.ts). All steps for this scenario share phase: <phaseId>.

// ─── Phase 6 — Fulfillment · Pack & ship ────────────────────────────────
{ phase: 6, from: 'storefront', to: 'api-gateway', type: 'http',
  label: 'POST /orders', title: 'Storefront → gateway: place the order',
  plain: `One to three sentences explaining what happens and why.`,
  payload: `POST /api/v1/orders
Headers:
  Content-Type: application/json
  Authorization: Bearer <jwt>

Body:
{ "cartId": "cart_01...", "shippingAddress": { ... } }

// 201 Created
{ "orderId": "ord_01..." }` },

Step type reference

Special patterns

Kafka with intermediary:

{ phase: 6, from: 'orders', to: 'shipping',
  via: 'orders.created', type: 'kafka', ... }
// Renders: orders → [topic node] → shipping

3-hop broadcast (producer → hub → browser):

{ phase: 6, from: 'shipping', through: 'realtime-hub', to: 'storefront',
  via: 'hub-broadcasts', type: 'kafka', ... }
// Renders: shipping → [hub-broadcasts] → realtime-hub → storefront
// When the hub is expanded, the packet re-routes through its sub-services

Parallel step (fires alongside the previous step):

{ phase: 6, ..., parallel: true }

Self-loop (internal in-process step):

{ phase: 6, from: 'orders', to: 'orders', type: 'internal',
  label: 'Persist order · DB write', ... }

Tips for great steps

• Split storage hops into read + transform + write. Each pulse on the storage capsule tells the viewer something. Don't collapse "reads, transforms, writes" into one internal step.
• Add payloads for HTTP and Kafka steps whenever you know the real shape. payload-parser.ts auto-splits Headers: / Body: / response sections.
• Keep labels under ~35 chars — they're timeline chips.
• Mark parallel steps when services genuinely fire together (e.g. an email and a live push triggered by the same event).

Step 6 — Verify

npx tsc -b --noEmit    # types must pass
npm run build          # vite build must pass
npm run dev            # eyeball the new scenario

Hard rules:

• ❌ Never run tsc without --noEmit/-b — stray .js files shadow .tsx in Vite.
• ❌ Never reuse a phaseId. Steps are filtered by phase — collision = wrong steps play.
• ❌ from / to / via ids must exactly match SERVICES[].id or TOPICS[].id. Typos silently break edges.
• ❌ phase: on every step must equal the scenario's phaseId. Mismatches = silent dead steps.

Step 7 — Eyeball checklist

Open the dev server, switch to the new scenario, press play:

• Map pans + zooms to fit only the involved nodes
• Uninvolved nodes fade out (isolation effect)
• Comet packets fly along the right edges in the right order
• Step panel shows the right title + body + payload at each step
• Parallel steps fire simultaneously
• Hub expand/collapse still works (if the hub is in the flow)

Debugging mismatches:

• Edge not rendering? → from/to/via id doesn't match SERVICES/TOPICS
• Wrong steps playing? → Two steps with the same phase from different scenarios (grep -rn "phase: <N>" src/scenarios/steps/)
• Map doesn't zoom to the right set? → A service id referenced in a step isn't in SERVICES