skills/elixir/SKILL.md

Elixir — Comprehensive Development Guide

Quick Reference

Item	Value
Current Version	Elixir 1.19.5 (target for all new code)
Required OTP	OTP 27+ (OTP 28 supported)
Phoenix Version	1.8.5 (latest — requires :formats on controllers)
Cortex Status	Elixir not yet installed on cortex.hydrascale.net
AI Agent Tooling	usage_rules hex package (~> 1.2) — always include
Production Framework	Ash Framework for substantial projects
Agent Framework	Jido (~> 2.1) for multi-agent systems
Paradigm	Functional, concurrent, fault-tolerant on BEAM VM

---

CRITICAL RULES — Read First

1. Target Elixir 1.19.5 — not 1.15, not 1.17. Use current idioms and features.
2. Always add usage_rules to every project: {:usage_rules, "~> 1.1", only: [:dev]}.
3. Use Ash Framework for production/substantial projects (not necessarily POCs).
4. Cortex is Elixir-first — Elixir is the primary orchestrator, with interop to Python/Rust/Zig.
5. Never use deprecated patterns from pre-1.16 code (see Part 1).
6. Phoenix 1.8 — always specify :formats on controllers, use ~p verified routes, use scopes.
7. For agentic workflows — consider GenStateMachine over GenServer (built-in timeouts, state enter, postpone). For multi-agent orchestration, use Jido.

---

Guide Structure — Load What You Need

This guide is split into focused parts. Load the part relevant to your current task:

Part 1: Core Language & OTP (elixir-part1-core.md)

Elixir 1.19 features, type system, breaking changes since 1.15, pattern matching, pipelines, with expressions, structs, protocols, behaviours, Mix project structure, testing.

Part 2: Concurrency & OTP (elixir-part2-concurrency.md)

BEAM processes, message passing, GenServer, Supervisors, DynamicSupervisor, Task, GenStateMachine (state machines for agentic workflows), Registry, ETS.

Part 3: Phoenix Framework (elixir-part3-phoenix.md)

Phoenix 1.8.5 — router/pipelines, verified routes, controllers, HEEx components, LiveView, Channels, contexts, Ecto, authentication, scopes, telemetry, security, testing, generators, deployment.

Part 4: Ecosystem & Production (elixir-part4-ecosystem.md)

Ash Framework, Jido (multi-agent systems), usage_rules, OTP releases, Docker deployment, distributed Erlang, monitoring (PromEx/Prometheus/Grafana), CI/CD, interop (Python/Rust/Zig), common libraries, cortex deployment plan, anti-patterns.

---

Common Libraries Quick Reference

Library	Purpose	Hex
Phoenix	Web framework + LiveView	{:phoenix, "~> 1.8"}
Ecto	Database wrapper + query DSL	{:ecto_sql, "~> 3.12"}
Ash	Declarative resource framework	{:ash, "~> 3.0"}
Jido	Multi-agent orchestration	{:jido, "~> 2.1"}
GenStateMachine	State machines (wraps gen_statem)	{:gen_state_machine, "~> 3.0"}
Oban	Background job processing	{:oban, "~> 2.18"}
Req	HTTP client (modern)	{:req, "~> 0.5"}
Jason	JSON encoding/decoding	{:jason, "~> 1.4"}
Swoosh	Email sending	{:swoosh, "~> 1.16"}
Mox	Mock behaviours for testing	{:mox, "~> 1.1", only: :test}
Credo	Static analysis / linting	{:credo, "~> 1.7", only: [:dev, :test]}
libcluster	Automatic BEAM node clustering	{:libcluster, "~> 3.4"}
Horde	Distributed supervisor/registry	{:horde, "~> 0.9"}
Nx	Numerical computing / tensors	{:nx, "~> 0.9"}
Broadway	Data ingestion pipelines	{:broadway, "~> 1.1"}
PromEx	Prometheus metrics for Elixir	{:prom_ex, "~> 1.9"}
usage_rules	AI agent docs from deps	{:usage_rules, "~> 1.1", only: :dev}