agentleFS
genex-gamesgenex-games/genex-desktop/.agents/skills/add-event-type/SKILL.md

add-event-type

Skill874 starsChanged 6 days agoMITView on GitHub

Add a new persisted event (custom event_type in the append-only log) or a transient UI event, with its producer, readers and tests. Use when the core, harness or a run needs to record or announce something new.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If a later session, the chat transcript, Studio activity or a run review must show it, it is persisted.

    line 15
  2. Very specific:

    Keep EventData in src/shared/event-log.ts unchanged.

    line 20
  3. Very specific:

    Read it where it shows up: src/shared/studio-activity.ts (STUDIO_RECORD_EVENTS), src/shared/chat-activity.ts, src/shared/run-review.ts, …

    line 37
  4. Distinctive:

    Never rewrite or delete old events to migrate.

    line 44

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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 an event type

Two kinds exist. Pick one before writing code.

KindSurvives restartProducerTransport
Persistedyes; the log is the agent's whole statecore append, harness events.appendstudio:events pull
Transient UInocore emit, harness ctx.notify / ui.notifystudio:event push

If a later session, the chat transcript, Studio activity or a run review must show it, it is persisted. Progress ticks, status lines and "refresh now" hints are transient.

Persisted: a custom event

  1. Keep EventData in src/shared/event-log.ts unchanged. New events are { type: "custom", event_type: "snake_case_name", payload }. Add a new top-level type only for a new substrate primitive (and update normalizeEvent in src/substrate/event-store.ts).
  2. Contract first, in src/shared/custom-events.ts: add a PascalCase key with its exact wire value to CustomEvent (CUSTOM_EVENT_TYPES is derived), and, when the app reads it, its payload to CustomEventMap (a map key the registry lacks fails the typecheck). Every field is optional: old logs and self-edited harness code can emit partial payloads. Reuse a payload type that already lives in src/shared (AssetDeliveredPayload, PluginToolStartedPayload, …).
  3. Produce it (NewEvent below stands for the key you add; use the seed HostMethod from src/harness-seed/loop/host-methods.ts for harness calls):
    • core: await this.append([customEventData(CustomEvent.NewEvent, payload)], threadId) in src/main/studio-core.ts (or the module that owns the behaviour);
    • harness: await ctx.call(HostMethod.EventsAppend, {batch:[...]}) (typed by HarnessHostApi in src/shared/harness-api.ts), as in src/harness-seed/tools/self-tools.ts. Harness-seed is shipped product payload: edit it as product code, and add an incident row (the harness-incident-fix skill).
  4. Read it where it shows up: src/shared/studio-activity.ts (STUDIO_RECORD_EVENTS), src/shared/chat-activity.ts, src/shared/run-review.ts, src/renderer/chat-entries.ts, src/renderer/run-graph.ts, src/renderer/build-progress.ts. Read the payload with customEvent(event, CustomEvent.NewEvent) / customPayload(data, [CustomEvent.NewEvent]) (null for any other event, {} for a missing payload), delegatedPayload for delegated.<engine>, or customRecord for any custom event; no data.payload as. Grep event_type === to find every consumer of a similar event, and keep the names consistent with them.
  5. Never rewrite or delete old events to migrate; readers accept both shapes.

Transient: a UI event

  • Contract first: add the exact wire name and payload to UiEventMap, and a PascalCase key to UiEvent in src/shared/ui-events.ts; UI_EVENT_TYPES is derived (named like run.finished or preview.frame). Fields the harness writes stay optional: it is edited at runtime and main forwards its notifications unchanged.
  • Core: this.emit(UiEvent.NewEvent, payload), typed by the map; main's pushUiEvent in src/main/index.ts (also typed) forwards it as studio:event (a push channel of src/shared/ipc-channels.ts).
  • Harness: keep the matching wire name in a seed-owned as const vocabulary beside its producer, then call ctx.notify(SeedUiEvent.NewEvent, payload). The example name stands for that vocabulary; there is no shared seed UiEvent export. Never import app source into the editable seed. Keep the seed/app contract covered by its contract tests.
  • Renderer: window.studio.onEvent(event => { if (event.type === UiEvent.NewEvent) … }) narrows the payload; isUiEventIn(event, "area.") narrows a family. No event.payload as.
  • tests/conformance/ui-events.test.ts fails when a produced name is missing from the map, or a key is no longer produced.
  • Nothing may depend on a transient event having been seen; the next pull must be able to rebuild the state.

Tests (red first)

  • tests/conformance/custom-events.test.ts scans src as data and fails when the code writes or reads a custom event name missing from CUSTOM_EVENT_TYPES, or the registry keeps a name nothing uses.
  • Reader: feed synthetic EventEnvelopes (including an old/partial payload) to the pure reader, as tests/conformance/studio-activity.test.ts and chat-history.test.ts do.
  • Producer: drive the behaviour through tests/helpers/core-lite.ts and read the log back with core.store.listEvents(threadId); for harness producers use startRig and customEvents from tests/helpers/studio-rig.ts.
  • Log invariants: tests/conformance/event-store.test.ts when touching the store itself.
npm test -- tests/conformance/studio-activity.test.ts tests/conformance/<producer>.test.ts

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.