oliver-kriska/claude-elixir-phoenix / targets/amp/skills/phx-intro
phx-intro
VerifiedWalk through the Elixir/Phoenix plugin commands, workflow, and features in 6 interactive sections. Use when a new user wants to learn what the plugin offers or needs a refresher on available commands.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.2 KB |
| references/tutorial-content.md | markdown | 16.4 KB |
references/tutorial-content.md
View on GitHub# Plugin Tutorial Content
Content for each section of the `phx-intro` tutorial.
Present ONE section at a time with AskUserQuestion between sections.
Present each section in full — every paragraph, table, and code block, unabridged.
## Contents
- [Section 1: Welcome](#section-1-welcome)
- [Section 2: Core Workflow Commands](#section-2-core-workflow-commands)
- [Section 3: Knowledge & Safety Net](#section-3-knowledge--safety-net)
- [Section 4: Hooks & Behavioral Rules](#section-4-hooks--behavioral-rules)
- [Section 5: Init, Review & Gaps](#section-5-init-review--gaps)
- [Section 6: Cheat Sheet & Next Steps](#section-6-cheat-sheet--next-steps)
---
## Section 1: Welcome
### What This Plugin Does
This plugin adds **specialist Elixir/Phoenix agents**, **auto-loaded knowledge**, and **Iron Laws** to Claude Code. It turns a general-purpose AI into an opinionated Elixir pair programmer.
### The Core Concept
Everything revolves around a 4-phase workflow cycle:
```text
phx-plan → phx-work → phx-verify → phx-review → phx-compound
| | | | |
v v v v v
Research & Execute Full check Parallel Capture what
plan tasks tasks compile/test code review you learned
```
Each phase reads from the previous phase's output. Plans become checkboxes. Checkboxes track progress. Reviews catch mistakes. Compound knowledge makes future work faster.
### What You Get
| Feature | What It Does |
|---------|-------------|
| 26 specialist agents | Ecto, LiveView, security, OTP, Oban, Ash, deployment experts |
| 51 skills | Commands for every phase of development |
| 26 Iron Laws | Non-negotiable rules enforced automatically |
| Auto-loaded references | Context-aware docs loaded when you edit relevant files |
| Tidewave integration | Runtime debugging when Tidewave MCP is connected |
---
## Section 2: Core Workflow Commands
### The Full Cycle
For features that need planning and review:
```bash
# 0. Brainstorm (optional) — explore requirements interactively
phx-brainstorm Add some kind of notification system
# 1. Plan — spawns research agents, outputs checkbox plan
phx-plan Add user avatars with S3 upload
# 1b. Brief (optional) — understand the plan before starting
phx-brief .claude/plans/user-avatars/plan.md
# 2. Work — executes plan, checks off tasks, runs mix compile
phx-work .claude/plans/user-avatars/plan.md
# 3. Review — parallel agents check idioms, security, tests, and
# cross-check implementation vs. requirements (auto-detected from
# branch/commits, or pass `ENA-123` / `#42` / a plan/spec path)
phx-review
# 4. Compound — capture what you learned for future reference
phx-compound Fixed S3 upload timeout with multipart streaming
```
### Shortcuts
Not everything needs the full cycle:
| Command | When to Use | Time |
|---------|------------|------|
| `phx-quick` | Bug fixes, small features (<100 lines) | ~2 min |
| `phx-full` | New features, autonomous plan-work-verify-review | ~10 min |
| `phx-investigate` | Debugging — checks obvious things first | ~3 min |
### Decision Guide
```text
Is it a bug?
Yes --> phx-investigate
No --> Do you know what you want?
No --> phx-brainstorm
Yes --> Is it < 100 lines?
Yes --> phx-quick
No --> Do you want full autonomy?
Yes --> phx-full
No --> phx-plan then phx-work
```
### Deepening an Existing Plan
Already have a plan but want to add research or refine tasks?
```bash
phx-plan --existing .claude/plans/user-avatars/plan.md
```
This spawns specialist agents to analyze your existing plan and enhance it with research findings.
---
## Section 3: Knowledge & Safety Net
### Auto-Loaded Knowledge
The plugin loads relevant reference docs based on what you're editing:
| You're editing... | Plugin loads... |
|-------------------|----------------|
| `*_live.ex` | LiveView patterns, async/streams, components |
| `*_test.exs` | ExUnit patterns, Mox, factory patterns |
| `migrations/*` | Migration patterns, safe operations |
| `*auth*`, `*session*` | Security patterns, authorization rules |
| `router.ex` | Routing patterns, plug patterns, scopes |
| `*_worker.ex` | Oban patterns, idempotency rules |
This means you don't need to explicitly load anything — open a LiveView file and the plugin already knows the patterns.
### Iron Laws (26 Rules, Always Enforced)
Iron Laws are non-negotiable rules that every agent enforces. If your code violates one, the plugin stops and explains before proceeding.
**Examples:**
| Law | Why |
|-----|-----|
| No unconditional DB queries in mount | Cache-backed branch OK for SEO |
| Use streams for lists >100 items | Regular assigns = O(n) memory per user |
| No `:float` for money | Floating point math loses precision |
| Pin values with `^` in Ecto queries | Prevents SQL injection |
| Jobs must be idempotent | Oban retries on failure |
| No `String.to_atom` with user input | Atom table exhaustion DoS |
| Authorize in EVERY `handle_event` | Mount auth alone is insufficient |
### Analysis & Verification Commands
| Command | What It Does |
|---------|-------------|
| `phx-verify` | Full check: compile, format, credo, test — plus dialyzer when the project has it configured |
| `phx-audit` | 5-agent project health audit with scores |
| `phx-deps-audit` | Audit Hex dep updates for supply-chain risk |
| `phx-deps-vet` | Record vetted Hex packages in hex_vet.exs ledger |
| `ecto-n1-check` | Detect N+1 query patterns |
| `lv-assigns` | Audit LiveView socket assigns for memory |
| `phx-boundaries` | Check Phoenix context boundary violations |
| `phx-perf` | Performance analysis (Ecto, LiveView, OTP) |
### Tidewave Integration
When Tidewave MCP is connected to your running Phoenix app:
```bash
# Get docs for your exact dependency versions
mcp__tidewave__get_docs "Ecto.Query"
# Execute code in your running app
mcp__tidewave__project_eval "MyApp.Repo.aggregate(User, :count)"
# Query your dev database directly
mcp__tidewave__execute_sql_query "SELECT count(*) FROM users"
```
The plugin automatically prefers Tidewave tools over alternatives when available.
---
## Section 4: Hooks & Behavioral Rules
The plugin uses **layered enforcement** — some things run automatically, some depend on Claude following instructions, some are on-demand. Here's what actually happens:
### Layer 1: Hooks (Automatic, Every Edit)
[Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) run shell scripts automatically after tool use. These are real automation — no instructions needed:
| Hook | Trigger | What It Does |
|------|---------|-------------|
| Dangerous ops block | Before Bash command | Blocks `mix ecto.reset/drop`, `git push --force`, non-build `MIX_ENV=prod` tasks, `pkill` of BEAM processes |
| Format check | Every `.ex`/`.exs` edit | Runs `mix format --check-formatted`, warns via stderr + exit 2 |
| Iron Law verifier | Every `.ex`/`.exs` edit | Scans code content for Iron Law violations with line numbers |
| Debug stmt warning | Every `.ex` edit | Warns about `IO.inspect`/`dbg()`/`IO.puts` in production code |
| Security reminder | Editing auth/session/password files | Outputs relevant Iron Laws via stderr + exit 2 |
| Progress logging | Every file edit | Appends to `.claude/plans/{slug}/progress.md` (async) |
| Failure hints | Bash command fails | Injects debugging hints via `additionalContext` |
| Error critic | Repeated mix failures | Escalates to structured critic analysis after 3+ failures |
| Iron Laws injection | Any subagent spawns | Injects all 26 Iron Laws into subagents via `additionalContext` |
| Compaction rules | After context compaction | Re-injects workflow rules via `SessionStart` (matcher `compact`) |
Format check **warns only** — it doesn't auto-fix (that would cause race conditions with the editor).
The compaction hook detects active workflow phases (`phx-plan`, `phx-work`, `phx-full`) and re-injects their critical rules
after context compaction. This prevents "rule amnesia" where Claude loses behavioral constraints after context is compressed.
Note: Compilation verification was moved to `phx-work` phase checkpoints for speed. The `verify-elixir.sh` hook has been removed.
### Layer 2: Iron Laws in Skills (Behavioral)
Each domain skill (ecto-patterns, liveview-patterns, security, etc.) embeds its own Iron Laws.
When Claude loads a skill, the laws become active context.
Claude is instructed to **stop and explain** before writing code that violates them.
This is behavioral — it works because the rules are in Claude's context, not because code enforces them. It's effective but not 100% guaranteed.
### Layer 3: Skill Loading by File Type (Behavioral)
Claude Code supports native `paths:` frontmatter that limits automatic skill
activation to matching files. This plugin uses it on domain skills; CLAUDE.md
also provides an explicit fallback routing table:
```text
*_live.ex → liveview-patterns (streams, async, components)
*auth*, *session* → security (authorization, XSS, atom safety)
*_worker.ex → oban (idempotency, string keys, queue config)
*_test.exs → testing (ExUnit, Mox, factories)
Any .ex file → elixir-idioms (always)
```
`paths:` is a file-path activation gate, not a dependency predicate. Matching a
path makes a skill eligible, while Claude still selects skills from their
descriptions; activation is not guaranteed merely because a dependency exists
in `mix.lock`. Running `phx-init` adds the fallback rules to the project.
---
## Section 5: Init, Review & Gaps
### Layer 4: `phx-init` (Strengthens Everything)
Running `phx-init` injects enforcement rules **directly into your project's CLAUDE.md**. This is stronger than plugin-level instructions because CLAUDE.md is always read at session start.
What it adds:
- **Routing table** — which `phx-*` command fits which kind of request, and what to ask about scope before building
- **Iron Laws with STOP protocol** — explicitly tells Claude to halt on violations
- **Verification rules** — `mix compile --warnings-as-errors && mix format` after code changes
- **Stack-specific rules** — detects Phoenix version, Oban, Ash, Tidewave from `mix.exs`
```bash
phx-init # First-time setup
phx-init --update # Update after plugin updates
```
If you're finding the plugin inconsistent, running `phx-init` is the single biggest improvement you can make.
### Layer 5: `phx-review` + Iron Law Judge (On-Demand)
The `iron-law-judge` agent does **pattern-based violation detection** — it uses Grep to search your changed files for known anti-patterns. But it only runs when you invoke `phx-review`.
What it catches with automated detection:
- `String.to_atom(` in lib code
- `field :price, :float` in schemas
- `raw(@variable)` (XSS risk)
- `Repo.` calls in LiveView mount without `connected?` guard
- Missing `^` pin in Ecto query fragments
### Layer 6: Planning Sets Structure Early
The `phx-plan` phase sets naming conventions, context boundaries, and module structure
**before any code exists**. This is where you prevent Rails-y patterns at the architecture
level — fat controllers, service objects, and ActiveRecord patterns get caught in the plan,
not in code review.
### What's NOT Automated (Yet)
Being honest about the gaps:
| Check | Status | Why |
|-------|--------|-----|
| `mix compile --warnings-as-errors` | `phx-work` checkpoints + `phx-full` VERIFYING phase | Compilation runs in workflow steps, not per-edit hooks |
| `mix credo` | `phx-full` VERIFYING phase + on-demand (`phx-verify`) | Not run per-task edit, only between phases |
| `mix test` | `phx-full` VERIFYING phase + on-demand (`phx-verify`) | Not run per-task, only between phases |
| `mix dialyzer` | On-demand (`phx-verify`) | Takes minutes, not seconds |
| Iron Law detection during coding | Behavioral only | `iron-law-judge` is review-time only |
### The Honest Summary
```text
AUTOMATIC (hooks): Format check, security reminders, progress logging, failure hints,
Iron Laws in subagents, rule re-injection after compaction
BEHAVIORAL (Claude): Iron Laws, skill loading, stop-and-explain
ON-DEMAND (commands): phx-review (iron-law-judge), phx-verify (compile/credo/dialyzer)
STRENGTHENED BY: phx-init (injects rules into project CLAUDE.md)
```
The plugin works best when all layers are active: `phx-init` for persistent rules, hooks for automatic checks, and `phx-review` to catch what the behavioral layer missed.
---
## Section 6: Cheat Sheet & Next Steps
### Command Reference
**Workflow (use in order):**
| Command | Phase |
|---------|-------|
| `phx-brainstorm <topic>` | Adaptive requirements gathering |
| `phx-plan <feature>` | Plan with research agents |
| `phx-plan --existing <file>` | Enhance existing plan |
| `phx-brief [plan file]` | Interactive plan walkthrough |
| `phx-work <plan file>` | Execute plan with verification |
| `phx-review` | Parallel agent code review |
| `phx-triage` | Interactive review finding triage |
| `phx-compound` | Capture solved problem |
**Standalone:**
| Command | Purpose |
|---------|---------|
| `phx-quick <task>` | Fast implementation, skip ceremony |
| `phx-full <feature>` | Autonomous plan-work-review cycle; `--codex` adds a cross-model review track |
| `phx-investigate <bug>` | Structured bug investigation |
| `phx-verify` | Run all quality checks |
| `phx-research <topic>` | Research with parallel workers, Tidewave-first |
| `phx-pr-review <PR#>` | Address PR review threads — fix, reply, resolve |
| `phx-watch-pr <PR#>` | Background-watch a PR for reviews + CI; `--codex` adds a Codex cloud review loop |
| `phx-codex-loop` | Fix until Codex CLI review is clean (optional — needs codex CLI) |
| `phx-deps-update` | Bump outdated Hex deps, grouped PRs |
| `phx-recall <question>` | Recall prior work from past sessions/git |
| `phx-permissions` | Scan sessions, recommend safe Bash permissions |
| `phx-help [description]` | Interactive command advisor — helps pick the right command |
**Analysis:**
| Command | Purpose |
|---------|---------|
| `phx-audit` | Full project health audit |
| `phx-deps-audit` | Hex dep update supply-chain audit |
| `phx-deps-vet` | Hex package audit ledger (`hex_vet.exs`) |
| `phx-perf` | Performance analysis |
| `ecto-n1-check` | N+1 query detection |
| `lv-assigns` | LiveView memory audit |
| `phx-boundaries` | Context boundary check |
| `phx-techdebt` | Technical debt analysis |
| `phx-trace <function>` | Call chain tracing |
| `ecto-constraint-debug` | Debug Ecto constraint errors |
**Knowledge:**
| Command | Purpose |
|---------|---------|
| `phx-examples` | Practical walkthroughs |
| `phx-learn-from-fix` | Capture a lesson from a fix |
| `phx-challenge` | Rigorous review mode |
### Playing Nicely With Claude Code Built-Ins
The plugin complements — it doesn't replace — CC's built-in features. A few that pair well with the Elixir workflow:
- **Auto mode + higher effort (`/effort xhigh`)**: run `phx-full` hands-off. Auto mode routes permission prompts through a safety classifier instead of blocking on you.
- **`/focus` (v2.1.110)**: hides intermediate tool output. Useful during long `phx-work` or `phx-full` runs when you only care about the final state.
- **Recap (v2.1.108)**: CC summarizes what happened when you return to a session.
Our scratchpad (`.claude/plans/{slug}/scratchpad.md`) still captures what recap
can't — checkbox progress, subagent findings, deliberate handoffs.
- **`/less-permission-prompts` (built-in, v2.1.111)**: generic Bash/MCP allowlist scanner. Use `phx-permissions` for Elixir-specific recommendations (credo, mix, psql, Tidewave) on top of it.
### 3 Tips for Getting the Most Out of the Plugin
1. **Start with `phx-plan` for any feature that touches multiple files.** The research agents catch architectural issues early, before you've written code that needs rewriting.
2. **Let Iron Laws stop you.** When the plugin flags a violation, read the explanation.
These rules exist because the Elixir community learned them the hard way
(atom exhaustion in prod, N+1 queries at scale, double-mount in LiveView).
3. **Use `phx-compound` after solving hard bugs.** The solution gets indexed and searchable. Next time you hit something similar, the plugin finds your past solution automatically.
### Next Steps
- Try `phx-plan` with your next feature to see the full workflow
- Run `phx-verify` to see your project's current health
- Run `phx-audit` for a comprehensive project assessment
- Check `phx-examples` for detailed walkthroughs
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |