Jidoka Usage Rules

Use these rules when generating code that depends on Jidoka.

Agent Authoring

• Prefer use Jidoka.Agent with the Spark DSL for application-authored agents.
• Keep agent, tools, and controls as the only author-facing DSL sections.
• Use plain instruction strings; do not introduce dynamic system prompt DSL.
• Use Jidoka.agent!/1 or Jidoka.Agent.Spec.new!/1 only when constructing specs directly in tests or tooling.

Runtime

• Use Jidoka.chat/3 for a simple one-turn text result.
• Use Jidoka.turn/3 when callers need the full Jidoka.Turn.Result, journal, state, events, or hibernation snapshot.
• Use Jidoka.session/2 or Jidoka.Session for durable, multi-turn flows.
• Use injected runtime capabilities in tests instead of live provider calls.

Tools And Operations

• Use Jido actions for local tools.
• Use ash_resource, browser, mcp_tools, subagent, handoff, and workflow only when those operation sources are needed.
• Mark unsafe, non-idempotent operations with idempotency: :unsafe_once.
• Attach operation controls to unsafe operations before release code reaches production.

Data Contracts

• Model persistent structures with Zoi-backed structs.
• Preserve version fields for imports, snapshots, and sessions.
• Avoid String.to_atom/1 on imported or runtime data.
• Keep provider clients, stores, process ids, and credentials out of Jidoka.Agent.Spec.

Jido Relationship

• Do not delegate the core agent loop to Jido.AI.ReAct.
• Keep Jidoka's Runic workflow spine as the owner of model/operation turns.
• Use Jido for process hosting, actions, signals, and ecosystem integrations.