elixir-phoenix-guide

Elixir Phoenix Guide for Claude Code

Version: 2.4.0 | Changelog

An essential development guide for Claude Code that ensures idiomatic Elixir and Phoenix LiveView code. This plugin includes enforced skills, plugin-native hooks, automated code quality analysis, and reference documentation that actively guide and validate your Elixir development workflow.

v2.4.0 Released! Hooks now ship and run entirely inside the plugin — no settings.json merging, no script installation. See CHANGELOG.md for details.

What's Included

Skills (19 essential files)

Consolidated domain expertise with enforced patterns:

• elixir-essentials - Core Elixir patterns: pattern matching, pipes, with statements, error handling
• phoenix-liveview-essentials - Complete LiveView guide: lifecycle, events, rendering phases, state management
• ecto-essentials - Database operations: schemas, changesets, queries, migrations, associations
• phoenix-uploads - File uploads and static file serving workflow
• testing-essentials - Testing patterns: DataCase/ConnCase setup, fixtures, LiveView tests, TDD workflow
• otp-essentials - OTP patterns: GenServer, Supervisor, Task, Agent, DynamicSupervisor, Registry, ETS
• oban-essentials - Background jobs: workers, queues, idempotency, unique jobs, cron, testing with Oban.Testing
• code-quality - Automated code quality detection: duplication, complexity, unused functions
• phoenix-liveview-auth - LiveView authentication: on_mount, current_scope, import conflicts, session handling
• ecto-changeset-patterns - Advanced changesets: separate per operation, cast_assoc pitfalls, composition
• phoenix-auth-customization - Extending phx.gen.auth: custom fields, migrations, fixture updates
• phoenix-pubsub-patterns - Real-time updates: subscriptions, broadcasting from contexts, topic naming
• phoenix-authorization-patterns - Access control: server-side authz, ownership, policy modules, scoped queries
• ecto-nested-associations - Nested data: cast_assoc, cast_embed, Ecto.Multi, cascades, FK indexes
• security-essentials - Security enforcement: atom exhaustion, SQL injection, XSS, open redirects, timing attacks
• deployment-gotchas - Deployment pitfalls: runtime.exs, release migrations, PHX_HOST, health checks, secrets
• phoenix-channels-essentials - Channels: socket auth, topic authorization, Presence, handle_in patterns
• telemetry-essentials - Observability: structured logging, :telemetry, Ecto events, LiveDashboard, metrics
• phoenix-json-api - JSON APIs: :api pipeline, FallbackController, pagination, versioning, Bearer auth

Each skill includes a RULES section with 6-11 non-negotiable patterns that must be followed.

Note on auto_suggest metadata: Skills include auto_suggest: true and file_patterns metadata for future Claude Code enhancements. These fields are not currently active in the Claude Code runtime but are included for forward compatibility.

Hooks (ship inside the plugin)

Hooks live in hooks/hooks.json and activate automatically when the plugin is installed — no settings.json editing, no script copying:

Event	Check
SessionStart	Detects Phoenix/LiveView/Ecto/Oban and caches project facts (in the plugin data dir, never your repo)
PreToolUse (Bash)	Blocks mix ecto.reset and git push --force (suggests --force-with-lease)
PostToolUse (Write/Edit on .ex/.exs/.heex)	Security (String.to_atom, SQL-injection fragments, open redirects, raw/1, secrets in logs, timing-unsafe ==, IO.inspect/dbg debug calls), Phoenix deprecations (form_for, live_redirect/live_patch, @current_user under 1.8 scopes), missing @impl true, migration FK/on_delete safety

Feedback works through exit code 2 with the reason on stderr — Claude reads that and fixes the issue. Exit 0 means no findings; there is no separate "warning" tier. See INSTALL-HOOKS.md for the full write-up, manual install (without the plugin manager), and how to write your own hooks.

Analysis Scripts (3 scripts)

Automated code quality analysis tools, run on demand from a checkout (they are not installed anywhere by the plugin manager or install.sh):

• code_quality.exs - AST-based Elixir analysis: duplication detection, ABC complexity, unused function detection (elixir scripts/code_quality.exs scan lib/)
• detect_project.sh - Project stack detection used by the SessionStart hook
• run_analysis.sh - Full project analysis runner

Reference Documentation (4 files)

Detailed reference material in docs/reference/ for complex tasks:

• project-structure.md - Directory layout and context boundaries
• liveview-checklist.md - Step-by-step LiveView development checklist
• ecto-conventions.md - Comprehensive Ecto patterns and best practices
• testing-guide.md - Testing patterns for contexts, LiveViews, and schemas