add-scenario
Skill3 starsChanged 4 months agoMITView on GitHub
Add a scenario (animated flow) to the Cosmos map. Use when the user says "add a scenario", "add a flow", "show what happens when X", or names a user action whose path through the system should play on the map. Traces the real flow from source across repos, then writes Scenario + Step entries (and any missing services/topics) into src/scenarios/.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-serviceSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
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".
- Very specific: line 10
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 …
- Distinctive: line 28
Ask the user if any are missing:
- Very specific: line 87
Add to the SCENARIOS array (grouped by domain):
- Very specific: line 101
If the domain doesn't exist yet, add it to DOMAINS first:
- Distinctive: line 171
Mark parallel steps: when services genuinely fire together (e.g.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
| File | Why |
src/scenarios/scenarios.ts | Scenario entry (and Domain entry if new) |
src/scenarios/steps/<domain>.ts | Step entries for the flow |
src/scenarios/data.ts | Barrel — only if you add a new steps file |
src/scenarios/services.ts / topics.ts | Any missing services/topics |
src/scenarios/types.ts | Only if you need a new Tech variant |
Step 1 — Gather the three inputs
Ask the user if any are missing:
- Domain — which domain does this flow belong to? Check
DOMAINSinsrc/scenarios/scenarios.ts(the demo ships withshopping,fulfillment,engagement). If it doesn't fit, confirm a new domain name — you'll add aDomainentry too. - User-facing trigger — what action starts the flow? ("customer clicks Buy", "webhook lands", "cron fires")
- 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:
| Field | Description |
from | service id (must match SERVICES[].id or TOPICS[].id) |
to | service id |
via | topic id — only for Kafka hops; from → topic → to renders as 2 edges |
through | intermediate hub id — only for 3-hop broadcast: producer → topic → hub → browser |
type | 'http' | 'ws' | 'kafka' | 'internal' |
label | short noun phrase for the timeline chip (≤35 chars) |
title | sentence-case side-panel header |
plain | 1–3 sentence narrative for the panel |
payload | optional headers + body + response sample |
parallel | optional true if this fires alongside the previous step |
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 (seeadd-serviceskill) - 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
type | When to use | Edge rendering |
'http' | REST/HTTP call | amber edge |
'ws' | WebSocket message | cyan edge |
'kafka' | Kafka publish/consume | add via: 'topic-id'; renders 2 orange edges |
'internal' | In-process logic, no network | dashed grey edge (self-loop if from === to) |
Special patterns
Kafka with intermediary:
{ phase: 6, from: 'orders', to: 'shipping',
via: 'orders.created', type: 'kafka', ... }
// Renders: orders → [topic node] → shipping3-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-servicesParallel 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.tsauto-splitsHeaders:/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 scenarioHard rules:
- ❌ Never run
tscwithout--noEmit/-b— stray.jsfiles shadow.tsxin Vite. - ❌ Never reuse a
phaseId. Steps are filtered by phase — collision = wrong steps play. - ❌
from/to/viaids must exactly matchSERVICES[].idorTOPICS[].id. Typos silently break edges. - ❌
phase:on every step must equal the scenario'sphaseId. 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/viaid doesn't matchSERVICES/TOPICS - Wrong steps playing? → Two steps with the same
phasefrom 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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

