usage-rules.md

LLM Usage Rules for Jido Messaging

This document provides guidelines for AI assistants (Claude, Cursor, etc.) when working with this codebase.

Project Context

Jido Messaging is part of the Jido ecosystem - a framework for building intelligent agent systems. It provides messaging and notification infrastructure.

Code Generation Rules

1. Always use conventional commits - Follow type(scope): description format
2. Never add "ampcode" as contributor - Do not include ampcode in commit messages or author trailers
3. Follow existing patterns - Match the code style in existing modules
4. Write documentation first - Add @moduledoc and @doc before implementation
5. Include examples - Use iex code blocks in documentation

Quality Standards

• All public functions need @doc with examples
• All modules need @moduledoc
• All functions with multiple clauses should have @spec
• Test coverage must be >= 90%
• Code must pass mix quality

Common Patterns

Module Documentation Template

defmodule Jido.Messaging.MyModule do
  @moduledoc """
  Brief description of this module.

  ## Overview
  
  Detailed explanation of what this module does and why.
  
  ## Examples
  
      iex> Jido.Messaging.MyModule.some_function(:input)
      {:ok, :result}
  """
  
  @doc """
  Brief description of the function.
  
  ## Examples
  
      iex> some_function(:input)
      {:ok, :result}
  """
  @spec some_function(atom()) :: {:ok, atom()} | {:error, term()}
  def some_function(input) do
    # implementation
  end
end

Test Organization

• Place unit tests in test/jido_messaging/ with _test.exs suffix
• Use describe/ blocks to organize related tests
• Use setup/ blocks for fixtures
• Use assert and pattern matching for assertions

Error Handling

Use result tuples and pattern matching:

defmodule Jido.Messaging.Handler do
  def process(message) do
    with {:ok, validated} <- validate(message),
         {:ok, result} <- execute(validated) do
      {:ok, result}
    else
      {:error, reason} -> {:error, reason}
    end
  end
end

File Organization

• lib/jido_messaging.ex - Main public API
• lib/jido_messaging/application.ex - OTP supervisor
• lib/jido_messaging/ - Feature modules (one per file)
• test/jido_messaging/ - Test files mirroring lib structure

Before Committing

1. Run mix format to format code
2. Run mix quality to check all standards
3. Run mix test (core lane) to ensure fast feedback
4. Run mix test.all before merging broad runtime changes
5. Run mix coveralls.html and verify coverage >= 90%
6. Review git diff for quality

Documentation

• Write in Markdown
• Include ## Examples sections with actual iex code
• Use ## Parameters for function arguments
• Use ## Returns for return value descriptions
• Link to related modules with backticks: `Jido.Messaging.Other`

Dialyzer Tips

• Add @spec annotations to functions
• Use proper @type definitions
• Handle nil cases explicitly
• Use | nil in type specs when appropriate

Debugging

• Use Logger.debug/1 for debug output
• Never use IO.inspect/1 in production code
• Use dbg/1 only in development/tests (Credo will warn)
• Include context in log messages

Dependencies

Do not add dependencies without discussion. Current dependencies:

• jason - JSON support
• zoi - Schema validation
• credo, dialyxir, ex_doc, excoveralls - Dev tools

Testing Checklist

• Test both success and error cases
• Test edge cases (empty input, nil, etc.)
• Use descriptive test names
• Use the right lane/tag (:integration, :story, :flaky) for non-core tests
• Coverage report shows >= 90%
• No flaky tests (mark with @tag :flaky if unavoidable)