elixir-phoenix-guide

Elixir Phoenix Guide for Claude Code

Version: 1.3.2 | Changelog

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

v1.3.2 Released! Testing essentials refinements — setup chaining, timestamp testing, async safety, improved skeletons. See CHANGELOG.md for details.

What's Included

Skills (5 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

Each skill includes a RULES section with 7-8 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 (10 shell commands in settings.json)

Active enforcement rules that catch anti-patterns in real-time:

Blocking (exit 2 - prevents action):

• missing-impl - Blocks callbacks without @impl true
• hardcoded-paths - Blocks hardcoded file paths
• hardcoded-sizes - Blocks hardcoded file size limits
• static-paths-validator - Blocks file references not in static_paths()
• deprecated-components - Blocks deprecated Phoenix components (.flash_group, form_for, live_redirect) 1 Warnings (exit 1 - shows warning, allows action):
• nested-if-else - Warns about nested if/else, suggests pattern matching
• inefficient-enum - Warns about multiple Enum operations
• string-concatenation - Warns about string concatenation in loops
• auto-upload-warning - Warns when auto_upload: true is detected

Agent Documentation (4 files)

Detailed reference material 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

Project Template

• CLAUDE.md.template - Project-specific instructions template

Installation

Note: Official marketplace publication is in progress. Once available, installation will be even simpler through the official Claude Code marketplace.

Installing for the First Time

In a Claude Code session, use the interactive plugin manager:

# Step 1: Add the marketplace (first time only)
/plugin marketplace add j-morgan6/elixir-phoenix-guide

# Step 2: Open the interactive plugin manager
/plugin

# This opens an interactive menu where you can:
# - Select the elixir-phoenix-guide marketplace
# - Install the elixir-phoenix-guide plugin
# - Choose scope (user = all projects, project = current only)
# - Verify you have version 1.3.2 or higher

Updating to Latest Version

If you already have the plugin installed:

# Open the interactive plugin manager
/plugin

# Select "Marketplaces" → "elixir-phoenix-guide" → "Update"
# Then update the plugin from the menu
# Verify version shows 1.3.2 or higher

Latest Updates (v1.3.2):

• Setup chaining guidance for reusable test contexts
• Timestamp testing patterns to prevent flaky tests
• Refined async: true rule with safe/unsafe categorization
• Improved context test skeleton with result binding and error assertions

See CHANGELOG.md for full release notes and version history.

Usage

Once installed, Claude Code will automatically:

1. Load skills based on code context - providing intelligent suggestions for Elixir patterns
2. Enforce hooks in real-time - catching anti-patterns as you write code
3. Reference agent docs when needed - accessing detailed information for complex tasks
4. Follow CLAUDE.md (if present) - respecting project-specific conventions

Example Interactions

Before (without optimization):

def process(user) do
  if user.status == :active do
    if user.role == :admin do
      :allowed
    else
      :denied
    end
  else
    :inactive
  end
end

After (with hooks and skills):

• Hook warns about nested if/else
• Skill suggests pattern matching
• Claude generates:

def process(%{status: :active, role: :admin}), do: :allowed
def process(%{status: :active}), do: :denied
def process(_), do: :inactive

Testing the Setup