Elixir Phoenix Plugin for Claude Code

Claude Code is great. But it doesn't know that assign_new silently skips on reconnect, that :float will corrupt your money fields, or that your Oban job isn't idempotent.

This plugin does. It coordinates 20 specialist agents that plan, implement, review, and verify your Elixir/Phoenix code in parallel -- each with domain expertise, fresh context, and enforced Iron Laws that catch the bugs your tests won't.

# You describe the feature. The plugin figures out the rest.
/phx:plan Add real-time comment notifications

# 4 research agents analyze your codebase in parallel.
# A structured plan lands in .claude/plans/comment-notifications/plan.md
# Then:

/phx:work .claude/plans/comment-notifications/plan.md
# Implements task by task. Compiles after each change.
# Stops cold if code violates an Iron Law.

/phx:review
# 4 specialist agents audit in parallel:
# idioms, security, tests, compilation.
# Deduplicates findings. Flags pre-existing issues separately.

No prompt engineering. No "please check for N+1 queries." The plugin auto-loads the right domain knowledge based on what files you're editing and enforces rules that prevent the mistakes Elixir developers actually make in production.

┌─────────────────────────────────────────────────────────────────────┐
│  ⚗  Elixir/Phoenix Plugin for Claude Code                           │
│                                                                     │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐           │
│  │    20    │    38    │    92    │    18    │    22    │           │
│  │  Agents  │  Skills  │   Refs   │  Hooks   │Iron Laws │           │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘           │
│                                                                     │
│  AGENTS                          COMMANDS                           │
│  ─────────────────────           ──────────────────────────         │
│  Orchestrators (opus)            Workflow                           │
│    workflow-orchestrator           /phx:plan    /phx:work           │
│    planning-orchestrator           /phx:review  /phx:full           │
│    parallel-reviewer               /phx:compound /phx:quick         │
│    context-supervisor              /phx:brief   /phx:triage         │
│                                                                     │
│  Reviewers (sonnet)              Investigation & Debug              │
│    elixir-reviewer                 /phx:investigate /phx:trace      │
│    testing-reviewer                /ecto:n1-check   /phx:perf       │
│    security-analyzer               /ecto:constraint-debug           │
│    iron-law-judge                  /lv:assigns                      │
│                                                                     │
│  Architecture (sonnet)           Analysis & Review                  │
│    liveview-architect              /phx:audit    /phx:verify        │
│    ecto-schema-designer            /phx:techdebt /phx:boundaries    │
│    phoenix-patterns-analyst        /phx:pr-review /phx:challenge    │
│    otp-advisor                     /phx:research  /phx:document     │
│                                                                     │
│  Investigation (sonnet/haiku)    Knowledge (auto-loaded)            │
│    deep-bug-investigator           liveview-patterns  ecto-patterns │
│    call-tracer                     elixir-idioms      security      │
│    xref-analyzer                   phoenix-contexts   oban          │
│    verification-runner             testing   deploy   tidewave      │
│                                                                     │
│  Domain (sonnet)                 Hooks                              │
│    oban-specialist                 auto-format · auto-compile       │
│    deployment-validator            iron-law-verify · security-scan  │
│    hex-library-researcher          debug-stmt-detect · error-critic │
│    web-researcher                  progress-tracking · block-danger │
│                                                                     │
│  ───────────────────────────────────────────────────────────        │
│  22 Iron Laws · Tidewave MCP · plan→work→verify→review→compound     │
│  github.com/oliver-kriska/claude-elixir-phoenix                     │
└─────────────────────────────────────────────────────────────────────┘

Early Stage -- Under active development. Feedback and contributions welcome via issues.

Installation

From GitHub (recommended)

# In Claude Code, add the marketplace
/plugin marketplace add oliver-kriska/claude-elixir-phoenix

# Install the plugin
/plugin install elixir-phoenix

From Local Path (for development)

git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

# Option A: Add as local marketplace
/plugin marketplace add ./claude-elixir-phoenix
/plugin install elixir-phoenix

# Option B: Test plugin directly
claude --plugin-dir ./claude-elixir-phoenix/plugins/elixir-phoenix

Getting Started

New to the plugin? Run the interactive tutorial:

/phx:intro

It walks through the workflow, commands, and features in 6 short sections (~5 min). Skip to any section with /phx:intro --section N.

Quick Examples

# Just describe what you need — the plugin detects complexity and suggests the right approach
> Fix the N+1 query in the user dashboard

# Plan a feature with parallel research agents, then execute
/phx:plan Add email notifications for new comments
/phx:work .claude/plans/email-notifications/plan.md

# Full autonomous mode — plan, implement, review, capture learnings
/phx:full Add user profile avatars with S3 upload

# 4-agent parallel code review (idioms, security, tests, compilation)
/phx:review

# Quick implementation — skip ceremony, just code
/phx:quick Add pagination to the users list

# Structured bug investigation with 4 parallel tracks
/phx:investigate Timeout errors in the checkout LiveView

# Project health audit across 5 categories
/phx:audit

The plugin auto-loads domain knowledge based on what files you're editing (LiveView patterns for *_live.ex, Ecto patterns for schemas, security rules for auth code) and enforces Iron Laws that prevent common Elixir/Phoenix mistakes.

How It Works

The Lifecycle

The plugin implements a Plan, Work, Verify, Review, Compound lifecycle. Each phase produces artifacts in a namespaced directory:

/phx:plan → /phx:work → /phx:verify → /phx:review → /phx:compound
     │           │            │              │              │
     ↓           ↓            ↓              ↓              ↓
plans/{slug}/  (in namespace) (in namespace) (in namespace) solutions/

• Plan -- Research agents analyze your codebase in parallel, then synthesize a structured implementation plan
• Work -- Execute the plan task-by-task with quick compile checks after each change
• Verify -- Full verification loop (compile, format, credo, test) before review
• Review -- Four specialist agents audit your code in parallel (idioms, security, tests, static analysis)
• Compound -- Capture what you learned as reusable knowledge for future sessions

Key Concepts

• Filesystem is the state machine. Each phase reads from the previous phase's output. No hidden state.
• Plan namespaces. Each plan owns all its artifacts in .claude/plans/{slug}/ -- plan, research, reviews, progress, scratchpad.
• Plan checkboxes track progress. [x] = done, [ ] = pending. /phx:work finds the first unchecked task and continues.
• One plan = one work unit. Large features get split into multiple plans. Each is self-contained.
• Agents are automatic. The plugin spawns specialist agents behind the scenes. You don't manage them directly.

Plan Namespaces

Every plan gets its own directory with all related artifacts:

.claude/
├── plans/{slug}/          # Everything for ONE plan
│   ├── plan.md            # The plan itself (checkboxes = state)
│   ├── research/          # Research agent output
│   ├── reviews/           # Review findings (individual tracks)
│   ├── summaries/         # Compressed multi-agent output
│   ├── progress.md        # Session progress log
│   └── scratchpad.md      # Auto-written decisions, dead-ends, handoffs
├── reviews/               # Ad-hoc reviews (no plan context)
└── solutions/             # Compound knowledge (reusable across plans)

No more scattered files across .claude/planning/, .claude/progress/, .claude/reviews/. One plan, one directory, everything together.

Architecture

Agent Hierarchy

The plugin uses 20 agents organized into 3 tiers:

                    ┌──────────────────────────────┐
                    │  Orchestrators (opus model)  │
                    │  Coordinate phases, spawn    │
                    │  specialists, manage flow    │
                    └──────────┬───────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
        ▼                      ▼                      ▼
┌───────────────┐  ┌───────────────────┐  ┌────────────────────┐
│ workflow-     │  │ planning-         │  │ parallel-          │
│ orchestrator  │  │ orchestrator      │  │ reviewer           │
│ (full cycle)  │  │ (research phase)  │  │ (review phase)     │
└───────────────┘  └───────────────────┘  └────────────────────┘
                               │                      │
                    ┌──────────┼──────────┐    ┌──────┼──────┐
                    ▼          ▼          ▼    ▼      ▼      ▼
             ┌──────────┐ ┌────────┐ ┌──────┐ ... 4 specialist
             │ liveview │ │ ecto   │ │ web  │     review agents