v2.3.1

Fixed

• phoenix-liveview-essentials — Relaxed "Initialize ALL assigns in mount/3" rule to acknowledge handle_params/3 as the idiomatic place for URL-dependent assigns (pagination, filters, sorting)
• testing-essentials — Replaced strict DataCase/ConnCase rule with guidance to follow the project's existing test setup patterns (e.g. shared helpers like setup :store_test_session) instead of inlining boilerplate

Full Changelog: v2.3.0...v2.3.1

v2.3.0 — Expanded Domains

What's New

5 new skills covering Phoenix development domains beyond core LiveView/Ecto:

• security-essentials — 7 RULES: atom exhaustion, SQL injection, XSS, open redirects, sensitive logging, timing attacks, dependency auditing
• deployment-gotchas — 7 RULES: runtime.exs, release migrations, PHX_HOST/PHX_SERVER, asset deployment, secrets, health endpoints, log levels
• phoenix-channels-essentials — 6 RULES: socket authentication, topic authorization, handle_in/push/broadcast, Presence, testing
• telemetry-essentials — 6 RULES: structured logging, handler attachment, Ecto telemetry events, LiveDashboard, metadata tagging
• phoenix-json-api — 7 RULES: :api pipeline, FallbackController, pagination, URL versioning, Bearer token auth, json/2

6 new security enforcement hooks:

Hook	Type	What it catches
atom-from-user-input	Blocking	String.to_atom/1 — atom table exhaustion
unparameterized-sql-fragment	Blocking	String interpolation in Ecto fragment — SQL injection
unsafe-redirect	Blocking	Redirect to user-controlled URLs — open redirect
raw-html-warning	Warning	raw/1 usage — XSS risk
sensitive-logging	Warning	password/token/secret in Logger calls
timing-unsafe-compare	Warning	== with tokens/secrets — timing attacks

Other changes:

• SubagentStart rules expanded with Security, Channel, Telemetry, Deployment, and JSON API rule sets
• CLAUDE.md.template updated with invocation instructions for all 19 skills
• Skill count: 14 → 19 | Hook count: 21 → 27

See CHANGELOG.md for full details.

---

Install: See README.md for installation instructions.

v2.2.0 — Smart Enforcement

What's New

Hooks are now context-aware — they adapt to your project stack and include copy-pasteable fix suggestions instead of bare warnings.

New: Project Detection System

SessionStart hook runs detect_project.sh once per session, parsing mix.exs to detect:

• Phoenix version (1.7 vs 1.8+ Scope struct)
• LiveView presence (full-stack vs API-only)
• Ecto adapter (Postgres, SQLite, MySQL)
• Oban presence

Results cached to .elixir-phoenix-guide-project.json — all hooks read this to conditionally apply rules.

New: 4 PostToolUse Validation Hooks

Run after code is written, catching architectural issues:

Hook	Behavior
missing-preload	Warns on association accessors without visible preload
missing-error-clause	Warns on with statements missing else clause
raw-sql-warning	Blocks SQL injection (string interpolation in raw SQL), warns on all raw SQL
context-boundary-violation	Warns on Repo calls in LiveView modules (skips in API-only projects)

Upgraded: Auto-Fix Suggestions

All warning hooks now include copy-pasteable fix examples:

```
⚠️ Nested if/else detected.

💡 Fix: Replace with case or multi-clause function:

 case {condition_a, condition_b} do
   {true, true} -> handle_both()
   {true, false} -> handle_a_only()
   _ -> handle_default()
 end

```

Upgraded hooks: nested-if-else, inefficient-enum, string-concatenation, missing-impl, hardcoded-paths, hardcoded-sizes.

Context-Aware Hooks

Hooks now adapt based on detected project stack:

• API-only projects — LiveView hooks skip silently (missing-impl, auto-upload, context-boundary-violation)
• Phoenix 1.8+ — Warns on @current_user usage (should use @current_scope)
• Skill reminder — Notes API-only status when LiveView is absent

Component Counts

Component	Count
Skills	14
Hooks	21 (1 SessionStart + 14 PreToolUse + 5 PostToolUse + 1 SubagentStart)
Scripts	4
Agent Docs	4

Updating

```bash
/plugin

Select "Marketplaces" → "elixir-phoenix-guide" → "Update"

```

Full Changelog: v2.1.0...v2.2.0

v2.1.0 — Additional Skills & Polish

What's New

6 New Skills (8 → 14 total)

Skill	Rules	Purpose
phoenix-liveview-auth	7	on_mount auth, current_scope, import conflicts, session handling
ecto-changeset-patterns	7	Separate changesets, cast_assoc pitfalls, composition, transforms
phoenix-auth-customization	6	Extending phx.gen.auth with custom fields, fixtures, confirmation
phoenix-pubsub-patterns	6	Subscriptions, broadcasting from contexts, topic naming
phoenix-authorization-patterns	6	Server-side authz, ownership, policy modules, scoped queries
ecto-nested-associations	6	cast_assoc, Ecto.Multi, cascades, FK indexes

1 New Hook (14 → 15 total)

• migration-safety — Warns on missing FK indexes, missing on_delete strategies, unsafe column removals, NOT NULL without defaults

Updated

• SubagentStart hook — Injects condensed rules from all 14 skills into every spawned subagent
• CLAUDE.md.template — Updated with all 14 skill references and migration-safety hook

Impact

• Battle-tested skills based on real-world debugging sessions (30-90 min pain points each)
• Comprehensive coverage of Phoenix authentication, authorization, and data patterns
• Migration safety catches common deployment-breaking issues before they're committed

Totals

Component	Count
Skills	14
Hooks	15
Analysis Scripts	3
Agent Docs	4

See CHANGELOG.md for full details.

v2.0.0 — Automation: Code Quality Detection

What's New

Major version bump introducing automated code quality analysis that goes beyond skill/hook guidance.

New: Code Quality Detection System

PostToolUse hook runs automatically after every file write:

• Code Duplication Detection — AST-based analysis finds functions duplicated across modules (>70% trigram similarity)
• ABC Complexity Analysis — flags functions exceeding complexity threshold of 30 (Assignments + Branches + Conditions)
• Unused Private Function Detection — finds defp functions never called within their module
• Template Duplication Detection — catches HEEx templates sharing >40% identical markup

New: code-quality Skill (8th skill)

7 non-negotiable rules covering duplication extraction, complexity limits, dead code removal, and refactoring guidance.

New: Analysis Scripts

• code_quality.exs — AST-based Elixir analysis engine (single file or full project scan)
• detect_template_duplication.sh — HEEx template comparison
• run_analysis.sh — Full project analysis runner for CI/CD integration

On-Demand Analysis

# Scan entire project
bash ~/.claude/scripts/elixir-phoenix-guide/run_analysis.sh

# Single file
elixir ~/.claude/scripts/elixir-phoenix-guide/code_quality.exs all lib/my_module.ex

# Full project scan
elixir ~/.claude/scripts/elixir-phoenix-guide/code_quality.exs scan lib/

Component Counts

Component	Count
Skills	8
Hooks	14 (13 PreToolUse + 1 PostToolUse)
Analysis Scripts	3
Agent Docs	4

Updating

/plugin
# Select "Marketplaces" → "elixir-phoenix-guide" → "Update"

Full Changelog: v1.4.0...v2.0.0

v1.4.0: Competitive Parity

What's New

New Skills (2)

• otp-essentials — 7 RULES covering GenServer, Supervisor, Task, Agent, DynamicSupervisor, Registry, ETS, and common OTP anti-patterns
• oban-essentials — 7 RULES covering workers, queues, idempotency, unique jobs, cron scheduling, testing with Oban.Testing, and error handling

New Hooks (3)

• dangerous-operations-blocker (Bash, exit 2) — blocks mix ecto.reset, git push --force, and MIX_ENV=prod commands
• debug-statement-detector (Write/Edit, exit 1) — warns on IO.inspect, dbg(), IO.puts outside test files
• security-audit-reminder (Write/Edit, exit 0) — nudges mix deps.audit / hex.audit / sobelow when mix.exs is modified

Subagent Enforcement

• SubagentStart hook — injects condensed rules from all 7 skills into every spawned subagent, ensuring code written by subagents follows the same standards

Totals

• Skills: 5 → 7
• Hooks: 10 → 13
• Subagent enforcement: new

See CHANGELOG.md for full details.

v1.3.2 - Testing Essentials Refinements

Changes

Changed

• testing-essentials — 4 targeted refinements:
  • Setup Chaining section — guidance on composing named setup functions with setup [:func1, :func2] for reusable test context
  • Timestamp Testing section — guidance on relative timestamps instead of hardcoded dates that cause flaky tests
  • Refined async: true rule — replaced one-liner with safe/unsafe categorization (safe: pure functions, changesets, helpers; unsafe: DB contexts, LiveView, Application.put_env)
  • Improved Context Test Skeleton — result bound to variable for further assertions, error case pattern matches changeset and checks errors_on/1

Full Changelog: v1.3.1...v1.3.2

v1.3.1 - LiveView Rules + Template Refinements

Changes

Added

• phoenix-liveview-essentials — 2 new rules:
  • Rule #8: Check core_components.ex for existing components before creating custom ones
  • Rule #9: Never query the database directly from LiveViews — call context functions instead
• CLAUDE.md.template — HexDocs MCP note added to "Notes for Claude" section

Full Changelog: v1.3.0...v1.3.1

v1.3.0 - Testing Essentials

What's New

New testing-essentials skill providing proactive testing guidance for all Elixir/Phoenix test files.

Added

• testing-essentials skill — invoked before any _test.exs file:
  • 8 non-negotiable RULES covering setup, coverage, and assertion patterns
  • TDD workflow guidance (write failing test first)
  • DataCase/ConnCase setup, fixture, LiveView, context, and changeset test skeletons
  • Pointer to testing-guide.md for comprehensive examples

Changed

• testing-guide.md refactored into a deep reference companion (no duplication with skill)
• All 4 existing skills now include a ## Testing pointer to testing-essentials

Updating

/plugin
# Select "Marketplaces" → "elixir-phoenix-guide" → "Update"

v1.2.0 - Plugin Renamed to elixir-phoenix-guide

[1.2.0] - 2026-02-12

Breaking Changes

• Plugin renamed from elixir-optimization to elixir-phoenix-guide
  • Better reflects purpose: essential guide for ALL Elixir work, not just optimization
  • Update marketplace references and installation commands
  • Reinstall required for existing users

Changed

• Skills consolidated from 8 to 4 for reduced friction:

  • elixir-essentials (merged elixir-patterns + error-handling)
  • phoenix-liveview-essentials (merged phoenix-liveview + liveview-lifecycle)
  • ecto-essentials (renamed from ecto-database)
  • phoenix-uploads (merged in phoenix-static-files content)
  • Removed skill-discovery meta-skill (no longer needed)

• RULES sections added to all skills:

  • 7-8 non-negotiable rules at the top of each skill
  • Rules visible in 10 seconds, reference examples below
  • Agents internalize rules, reference examples when needed

• Skill descriptions shortened and strengthened:

  • Changed from "INVOKE BEFORE" to "MANDATORY for ALL"
  • Removed feature lists that enable rationalization
  • Single-sentence descriptions using forceful language
  • Example: "MANDATORY for ALL Elixir code changes. Invoke before writing any .ex or .exs file."

• CLAUDE.md template updated with enforcement section:

  • Mandatory rules block added to template
  • Specifies exact skill invocation requirements per file type
  • Explicit "not optional" language
  • Projects adopting template get built-in enforcement

• Reminder hook added:

  • Non-blocking (exit 0) reminder on .ex/.exs/.heex writes
  • Prompts agent to verify skill invocation
  • Gentle nudge without preventing work

Documentation

• Metadata limitations documented:
  • README now clarifies auto_suggest and file_patterns are forward-looking
  • Noted as pending Claude Code runtime support
  • False expectation claims removed from v1.1.0 changelog references

Impact

• Reduced cognitive load: 4 skills vs 8 means less choice paralysis
• Improved adoption: MANDATORY language harder to rationalize away
• Better enforcement: CLAUDE.md template + hooks + reminders create multiple touchpoints
• Clearer purpose: "guide" name indicates this applies to ALL work, not just performance tuning

Migration Notes

For existing users:

1. Uninstall elixir-optimization plugin
2. Install new elixir-phoenix-guide plugin from marketplace
3. Update project CLAUDE.md files if using template
4. Skill invocations use new names with same plugin prefix