agentleFS
ludeo-labsludeo-labs/cosmos-os/.claude/skills/add-scenario/SKILL.md

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/.

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
  1. Distinctive:

    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".

    line 8
  2. Very specific:

    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 …

    line 10
  3. Distinctive:

    Ask the user if any are missing:

    line 28
  4. Very specific:

    Add to the SCENARIOS array (grouped by domain):

    line 87
  5. Very specific:

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

    line 101
  6. Distinctive:

    Mark parallel steps: when services genuinely fire together (e.g.

    line 171

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

FileWhy
src/scenarios/scenarios.tsScenario entry (and Domain entry if new)
src/scenarios/steps/<domain>.tsStep entries for the flow
src/scenarios/data.tsBarrel — only if you add a new steps file
src/scenarios/services.ts / topics.tsAny missing services/topics
src/scenarios/types.tsOnly if you need a new Tech variant

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:

FieldDescription
fromservice id (must match SERVICES[].id or TOPICS[].id)
toservice id
viatopic id — only for Kafka hops; from → topic → to renders as 2 edges
throughintermediate hub id — only for 3-hop broadcast: producer → topic → hub → browser
type'http' | 'ws' | 'kafka' | 'internal'
labelshort noun phrase for the timeline chip (≤35 chars)
titlesentence-case side-panel header
plain1–3 sentence narrative for the panel
payloadoptional headers + body + response sample
paralleloptional 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 (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

typeWhen to useEdge rendering
'http'REST/HTTP callamber edge
'ws'WebSocket messagecyan edge
'kafka'Kafka publish/consumeadd via: 'topic-id'; renders 2 orange edges
'internal'In-process logic, no networkdashed 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] → 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.