jido-signal

name	jido-signal
description	Builder-oriented guidance for the upstream `jido_signal` package. Use when Codex needs to define signal schemas, route or dispatch events, bridge Jido signals to buses or transports, or review `jido_signal` boundaries versus `jido`, `jido_messaging`, and application code.

Jido Signal

jido_signal is the upstream Hex package name.

Start Here

Use this skill when the task is about signal structure, validation, dispatch, or event boundaries.

Good triggers:

• "Define the signal shape for this workflow."
• "Bridge agent events onto PubSub, webhooks, or another bus."
• "Turn the signal docs into a runnable example."
• "Review whether this event contract belongs in jido_signal or in app code."

Read references/builder-notes.md before implementing when the task touches CloudEvents-like structure, signal versioning, or external delivery boundaries.

Primary Workflows

Define signal contracts

• Start with event intent: what happened, who emitted it, and what downstream consumers must rely on.
• Keep the public signal shape stable even if internal producers change.
• Prefer explicit type, source, subject, and data conventions over loose maps.

Build routing and dispatch flows

• Separate signal creation from transport delivery.
• Keep signal validation close to the producer boundary.
• Translate into PubSub, queues, or webhooks in adapter code, not in the signal definition itself.

Turn docs into runnable examples

• Show one producer, one signal payload, and one consumer.
• Include serialization or validation only when it changes the design.
• Demonstrate failure handling for malformed or missing fields when that is central to the example.

Review boundaries

• Keep event contracts and signaling semantics in jido_signal.
• Keep transport-specific adapters in jido-messaging or app code.
• Keep agent planning and execution control in jido.

Build Checklist

• Name the event in domain language.
• Define the minimum stable payload.
• Choose versioning or compatibility rules before publishing widely.
• Test serialization, validation, and consumer expectations.

Boundaries

• Do not use this skill to design an entire broker stack.
• Do not overload one signal type with unrelated payload shapes.
• Do not let consumer-specific fields leak back into the core signal contract.