Skip to content
Back to search

oliver-kriska

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oliver-kriska/claude-elixir-phoenix with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oliver-kriska/claude-elixir-phoenix'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oliver-kriska-claude-elixir-phoenix/badge.svg)](/listings/oliver-kriska-claude-elixir-phoenix)

HTML

<a href="/listings/oliver-kriska-claude-elixir-phoenix"><img src="/api/listings/oliver-kriska-claude-elixir-phoenix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

From GitHub (recommended)

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

# Install the plugin
/plugin install elixir-phoenix

Requires **Claude Code 2.1.110 or newer**. The install name stays `elixir-phoenix`, while its public workflow commands remain `/phx:*` — Claude Code namespaces commands by the plugin's manifest name, not its install name. A fresh install also pulls in two small compatibility namespaces for `/ecto:*` and `/lv:*` automatically; you do not need to install them separately. After an update, run `/reload-plugins` before trying the commands in an already-open session.

Updating from v2.x

> [!WARNING] > **Do not run `claude plugin update` on its own.** v3 introduced two > compatibility plugins (`ecto`, `lv`) that v2 never declared, and > `claude plugin update` does not install dependencies a new version newly > declares. The updated plugin then fails to load entirely — you lose all 36 > `/phx:*` commands, not just `/ecto:*` and `/lv:*`. Install the two > compatibility plugins **first**, using the exact order below.

claude plugin marketplace update oliver-kriska
claude plugin install ecto@oliver-kriska
claude plugin install lv@oliver-kriska
claude plugin update elixir-phoenix@oliver-kriska

Restart Claude Code afterward. In an already-open session, `/reload-plugins` reloads the updated skills, agents, and hooks. Confirm that `/phx:help`, `/ecto:n1-check`, and `/lv:assigns` appear before continuing work.

Already updated in the wrong order?

If `claude plugin list` reports `✘ failed to load` with `Dependency "ecto@oliver-kriska" is not installed`, install the two compatibility plugins to recover — nothing is lost, and no reinstall is needed:

claude plugin install ecto@oliver-kriska
claude plugin install lv@oliver-kriska

Note that `claude plugin install elixir-phoenix@oliver-kriska` also repairs the state, but resolves only **one** missing dependency per run, so it needs two invocations here.

Commands are `/phx:*`, not `/elixir-phoenix:*`

Plugin versions before v3.0.0 shipped a manifest named `elixir-phoenix`, so their commands resolved as `/elixir-phoenix:work` even though `/phx:init` wrote `/phx:*` into `CLAUDE.md`. v3.0.0 renamed the manifest to `phx`, which is what makes `/phx:*` correct. If Claude Code reports `/phx:` commands as unknown, you are on a pre-v3 version — follow the upgrade steps above, then re-run `/phx:init --update`.

Claude Code subagent compatibility

No configuration is required. Claude Code 2.1.219+ defaults to a maximum subagent spawn depth of 3, so `/phx:full`, deep `/phx:plan`, parallel `/phx:investigate`, and `/phx:trace` can use their nested orchestrators. Claude Code 2.1.217–2.1.218 defaulted to depth 1; on those versions, or when you explicitly configure depth 1–2, the workflows keep orchestration in the main conversation and spawn leaf specialists directly. They preserve the same decisions, artifacts, verification, and review gates; only the agent topology changes.

To explicitly enable the full nested topology, start Claude Code with depth 3:

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3 claude

Depth 2 is sufficient for `/phx:trace`'s call-tracer alone. This must be set in the environment that starts Claude Code; a plugin hook cannot change its parent process environment.

> **Multi-stack tip — project-scope enable.** This plugin is opinionated for > Elixir/Phoenix. If you work across multiple language stacks, prefer enabling > it per-project rather than globally — drop this into `<project>/.claude/settings.json`: > > ```json > { "enabledPlugins": { "elixir-phoenix@oliver-kriska": true } } > ``` > > Hooks self-gate on `mix.exs` presence (v2.10.1+), so global enable is safe > — project-scoping is just a tidiness preference.

Companion plugin: `catchup`

The same marketplace also ships **`catchup`** — a framework-agnostic

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 64 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "oliver-kriska",
  3. "owner": {
  4. "name": "Oliver Kriska",
  5. "email": "oliver@kriska.dev"
  6. },
  7. "metadata": {
  8. "description": "Claude Code plugins by Oliver Kriska",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "elixir-phoenix",
  14. "description": "Elixir/Phoenix/LiveView development with specialist agents, Iron Laws, and Tidewave MCP integration",
  15. "author": {
  16. "name": "Oliver Kriska"
  17. },
  18. "source": "./plugins/elixir-phoenix",
  19. "category": "development",
  20. "tags": ["elixir", "phoenix", "liveview", "oban", "ecto"]
  21. },
  22. {
  23. "name": "ecto",
  24. "description": "Compatibility namespace for the Elixir/Phoenix plugin's /ecto:* commands",
  25. "author": {
  26. "name": "Oliver Kriska"
  27. },
  28. "source": "./plugins/ecto",
  29. "category": "development",
  30. "tags": ["elixir", "ecto", "compatibility"]
  31. },
  32. {
  33. "name": "lv",
  34. "description": "Compatibility namespace for the Elixir/Phoenix plugin's /lv:* commands",
  35. "author": {
  36. "name": "Oliver Kriska"
  37. },
  38. "source": "./plugins/lv",
  39. "category": "development",
  40. "tags": ["elixir", "phoenix", "liveview", "compatibility"]
  41. },
  42. {
  43. "name": "catchup",
  44. "description": "Async-team return-from-absence briefing — /catchup fans out to GitHub, git, Linear, and calendar, then emits one prioritized Context Brief instead of a firehose. Framework-agnostic.",
  45. "author": {
  46. "name": "Oliver Kriska"
  47. },
  48. "source": "./plugins/catchup",
  49. "category": "productivity",
  50. "tags": ["productivity", "briefing", "async-team", "github", "linear"]
  51. },
  52. {
  53. "name": "rewrite",
  54. "description": "Elixir Rewrite Architect — rewrite an app from any language or framework (Rails, Django, PHP, Node, Go, JVM, .NET, Rust, Python scripts, CLIs, workers) into Elixir the Elixir way. Analyzes features and why each mechanism exists, decides the compatibility bar, designs a Phoenix/Ecto/Oban/OTP architecture, then hands vertical slices to /phx:plan and verifies parity.",
  55. "author": {
  56. "name": "Oliver Kriska"
  57. },
  58. "source": "./plugins/rewrite",
  59. "category": "development",
  60. "tags": ["elixir", "phoenix", "rewrite", "migration", "architecture"],
  61. "dependencies": ["elixir-phoenix"]
  62. }
  63. ]
  64. }
README.md · README · 1,192 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Elixir Phoenix Plugin for Claude Code
  2. [![Docs: phxagents.dev](https://img.shields.io/badge/docs-phxagents.dev-6e40c9)](https://phxagents.dev)
  3. [![Security: scanned with SkillSpector](https://img.shields.io/badge/security-scanned%20with%20SkillSpector-2ea44f)](SECURITY.md)
  4. **Docs: [phxagents.dev](https://phxagents.dev)** -- [install guides per runtime](https://phxagents.dev/install/),
  5. the [runtime compatibility matrix](https://phxagents.dev/compatibility/), all
  6. [26 Iron Laws](https://phxagents.dev/iron-laws/), and a browsable
  7. [skill and agent catalog](https://phxagents.dev/catalog/).
  8. **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.**
  9. This plugin does. It coordinates **26 specialist agents** that plan, implement,
  10. review, and verify your Elixir/Phoenix code in parallel -- each with domain
  11. expertise, fresh context, and enforced [Iron Laws](#iron-laws-non-negotiable-rules)
  12. that catch the bugs your tests won't.
  13. **Using Amp?** Install the generated edition for the same 51 Elixir, Phoenix,
  14. LiveView, Ecto, Oban, testing, and security skills, plus 40 deterministic
  15. workflow wrappers, five read-only specialist agents, parallel review/investigation, and
  16. native edit/verification guards, and the native PR watch lifecycle
  17. plugin. See [Use with Amp](#use-with-amp) for the
  18. important differences from the full Claude Code plugin, or the
  19. [Amp install guide](https://phxagents.dev/install/amp/) on phxagents.dev.
  20. **Using Codex?** Install the native generated skills plugin for all 51 skills,
  21. including `$elixir-phoenix:phx-investigate` and
  22. `$elixir-phoenix:phx-review` workflows. See
  23. [Use with Codex](#use-with-codex) or the
  24. [Codex install guide](https://phxagents.dev/install/codex/); a trust-gated
  25. destructive-command safeguard is included, while custom agents are intentionally
  26. not included and Tidewave MCP registration remains external.
  27. **Using Pi?** Install the native generated skills package for all 51 skills,
  28. including Pi-compatible `/skill:phx-investigate` and `/skill:phx-review`
  29. workflows. See [Use with Pi](#use-with-pi) or the
  30. [Pi install guide](https://phxagents.dev/install/pi/); extensions, prompt
  31. templates, MCP, and custom agents are intentionally not included yet. Tidewave
  32. can be used when the Pi host exposes it independently.
  33. **Using OpenCode?** Install the generated skills-only target for all 51 skills,
  34. including `phx-investigate` and `phx-review`. In the tested OpenCode 1.17.2 setup,
  35. they are also available as `/phx-investigate` and `/phx-review`; the skill tool
  36. is the portable explicit interface. See [Use with OpenCode](#use-with-opencode), the
  37. [OpenCode guide](docs/opencode.md), or the
  38. [OpenCode install guide](https://phxagents.dev/install/opencode/).
  39. **Using DeepSeek Harness (dsh)?** Install the generated skills-only target for
  40. all 51 skills. A `/phx-investigate` or `/phx-review` token anywhere in your
  41. message loads the skill deterministically, and dsh reads your `CLAUDE.md`
  42. natively. See [Use with DeepSeek Harness](#use-with-deepseek-harness), the
  43. [dsh guide](docs/dsh.md), or the
  44. [dsh install guide](https://phxagents.dev/install/dsh/); hooks and custom
  45. agents are intentionally not included, and Tidewave MCP registration is
  46. external.
  47. Compare native invocation, installation, and deliberately deferred capabilities
  48. in the canonical [runtime support matrix](docs/runtime-support.md). Generated
  49. skills support does not imply full Claude Code feature parity.
  50. ```bash
  51. # You describe the feature. The plugin figures out the rest.
  52. /phx:plan Add real-time comment notifications
  53. # 4 research agents analyze your codebase in parallel.
  54. # A structured plan lands in .claude/plans/comment-notifications/plan.md
  55. # Then:
  56. /phx:work .claude/plans/comment-notifications/plan.md
  57. # Implements task by task. Compiles after each change.
  58. # Stops cold if code violates an Iron Law.
  59. /phx:review
  60. # 4 specialist agents audit in parallel:
  61. # idioms, security, tests, compilation.
  62. # Deduplicates findings. Flags pre-existing issues separately.
  63. ```
  64. No prompt engineering. No "please check for N+1 queries." The plugin auto-loads
  65. the right domain knowledge based on what files you're editing and enforces rules
  66. that prevent the mistakes Elixir developers actually make in production.
  67. ```
  68. ┌─────────────────────────────────────────────────────────────────────┐
  69. │ ⚗ Elixir/Phoenix Plugin for Claude Code │
  70. │ │
  71. │ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
  72. │ │ 26 │ 51 │ 140 │ 30 │ 26 │ │
  73. │ │ Agents │ Skills │ Refs │Hook Regs │Iron Laws │ │
  74. │ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
  75. │ │
  76. │ AGENTS COMMANDS │
  77. │ ───────────────────── ────────────────────────── │
  78. │ Orchestrators (opus) Workflow │
  79. │ workflow-orchestrator /phx:plan /phx:work │
  80. │ planning-orchestrator /phx:review /phx:full │
  81. │ parallel-reviewer /phx:compound /phx:quick │
  82. │ context-supervisor /phx:brief /phx:triage │
  83. │ │
  84. │ Reviewers (sonnet) Investigation & Debug │
  85. │ elixir-reviewer /phx:investigate /phx:trace │
  86. │ testing-reviewer /ecto:n1-check /phx:perf │
  87. │ security-analyzer (opus) /ecto:constraint-debug │
  88. │ iron-law-judge /lv:assigns │
  89. │ │
  90. │ Architecture (sonnet) Analysis & Review │
  91. │ liveview-architect /phx:audit /phx:verify │
  92. │ ecto-schema-designer /phx:techdebt /phx:boundaries │
  93. │ phoenix-patterns-analyst /phx:pr-review /phx:challenge │
  94. │ otp-advisor /phx:research /phx:document │
  95. │ │
  96. │ Investigation (sonnet) Knowledge (auto-loaded) │
  97. │ deep-bug-investigator liveview-patterns ecto-patterns │
  98. │ call-tracer elixir-idioms security │
  99. │ xref-analyzer phoenix-contexts oban │
  100. │ verification-runner testing deploy tidewave │
  101. │ │
  102. │ Domain (sonnet) Hooks │
  103. │ oban-specialist auto-format · auto-compile │
  104. │ deployment-validator iron-law-verify · security-scan │
  105. │ hex-library-researcher debug-stmt-detect · error-critic │
  106. │ web-researcher progress-tracking · block-danger │
  107. │ │
  108. │ ─────────────────────────────────────────────────────────── │
  109. │ 26 Iron Laws · Tidewave-aware · plan→work→verify→review→compound │
  110. │ github.com/oliver-kriska/claude-elixir-phoenix │
  111. └─────────────────────────────────────────────────────────────────────┘
  112. ```
  113. > **v3.0.0** -- all 51 canonical skill trees have generated distributions
  114. > for Amp, Codex, Pi, OpenCode, and DeepSeek Harness. Nine core workflows are fully adapted: the
  115. > six flagship lifecycle workflows plus `phx-trace`, `phx-audit`, and
  116. > `phx-research`. The remaining projections preserve domain knowledge but may
  117. > require the runtime to translate Claude-specific orchestration. Claude Code
  118. > remains the full canonical plugin; hooks, agents, MCP, instructions, and
  119. > workflow portability intentionally vary by runtime. See the
  120. > [support matrix](docs/runtime-support.md) before assuming feature parity.
  121. > [Issues](https://github.com/oliver-kriska/claude-elixir-phoenix/issues) welcome.
  122. ## Installation
  123. ### Claude Code
  124. #### From GitHub (recommended)
  125. ```bash
  126. # In Claude Code, add the marketplace
  127. /plugin marketplace add oliver-kriska/claude-elixir-phoenix
  128. # Install the plugin
  129. /plugin install elixir-phoenix
  130. ```
  131. Requires **Claude Code 2.1.110 or newer**. The install name stays
  132. `elixir-phoenix`, while its public workflow commands remain `/phx:*` — Claude
  133. Code namespaces commands by the plugin's manifest name, not its install name.
  134. A fresh install also pulls in two small compatibility namespaces for `/ecto:*`
  135. and `/lv:*` automatically; you do not need to install them separately. After an
  136. update, run `/reload-plugins` before trying the commands in an already-open
  137. session.
  138. #### Updating from v2.x
  139. > [!WARNING]
  140. > **Do not run `claude plugin update` on its own.** v3 introduced two
  141. > compatibility plugins (`ecto`, `lv`) that v2 never declared, and
  142. > `claude plugin update` does not install dependencies a new version newly
  143. > declares. The updated plugin then fails to load entirely — you lose all 36
  144. > `/phx:*` commands, not just `/ecto:*` and `/lv:*`. Install the two
  145. > compatibility plugins **first**, using the exact order below.
  146. ```bash
  147. claude plugin marketplace update oliver-kriska
  148. claude plugin install ecto@oliver-kriska
  149. claude plugin install lv@oliver-kriska
  150. claude plugin update elixir-phoenix@oliver-kriska
  151. ```
  152. Restart Claude Code afterward. In an already-open session, `/reload-plugins`
  153. reloads the updated skills, agents, and hooks. Confirm that `/phx:help`,
  154. `/ecto:n1-check`, and `/lv:assigns` appear before continuing work.
  155. ##### Already updated in the wrong order?
  156. If `claude plugin list` reports `✘ failed to load` with
  157. `Dependency "ecto@oliver-kriska" is not installed`, install the two
  158. compatibility plugins to recover — nothing is lost, and no reinstall is needed:
  159. ```bash
  160. claude plugin install ecto@oliver-kriska
  161. claude plugin install lv@oliver-kriska
  162. ```
  163. Note that `claude plugin install elixir-phoenix@oliver-kriska` also repairs the
  164. state, but resolves only **one** missing dependency per run, so it needs two
  165. invocations here.
  166. #### Commands are `/phx:*`, not `/elixir-phoenix:*`
  167. Plugin versions before v3.0.0 shipped a manifest named `elixir-phoenix`, so
  168. their commands resolved as `/elixir-phoenix:work` even though `/phx:init` wrote
  169. `/phx:*` into `CLAUDE.md`. v3.0.0 renamed the manifest to `phx`, which is what
  170. makes `/phx:*` correct. If Claude Code reports `/phx:` commands as unknown,
  171. you are on a pre-v3 version — follow the upgrade steps above, then re-run
  172. `/phx:init --update`.
  173. #### Claude Code subagent compatibility
  174. No configuration is required. Claude Code 2.1.219+ defaults to a maximum
  175. subagent spawn depth of 3, so `/phx:full`, deep `/phx:plan`, parallel
  176. `/phx:investigate`, and `/phx:trace` can use their nested orchestrators. Claude
  177. Code 2.1.217–2.1.218 defaulted to depth 1; on those versions, or when you
  178. explicitly configure depth 1–2, the workflows keep orchestration in the main
  179. conversation and spawn leaf specialists directly. They preserve the same
  180. decisions, artifacts, verification, and review gates; only the agent topology
  181. changes.
  182. To explicitly enable the full nested topology, start Claude Code with depth 3:
  183. ```bash
  184. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3 claude
  185. ```
  186. Depth 2 is sufficient for `/phx:trace`'s call-tracer alone. This must be set in
  187. the environment that starts Claude Code; a plugin hook cannot change its parent
  188. process environment.
  189. > **Multi-stack tip — project-scope enable.** This plugin is opinionated for
  190. > Elixir/Phoenix. If you work across multiple language stacks, prefer enabling
  191. > it per-project rather than globally — drop this into `<project>/.claude/settings.json`:
  192. >
  193. > ```json
  194. > { "enabledPlugins": { "elixir-phoenix@oliver-kriska": true } }
  195. > ```
  196. >
  197. > Hooks self-gate on `mix.exs` presence (v2.10.1+), so global enable is safe
  198. > — project-scoping is just a tidiness preference.
  199. #### Companion plugin: `catchup`
  200. The same marketplace also ships **`catchup`** — a framework-agnostic
  201. `/catchup` return-from-absence briefing (PRs, reviews, git, Linear,
  202. calendar → one prioritized Context Brief, including which upstream
  203. changes touch *your* in-flight files). Independent plugin, separate
  204. manifest, install only if you want it:
  205. ```bash
  206. /plugin install catchup@oliver-kriska
  207. ```
  208. See `plugins/catchup/README.md`. Not coupled to Elixir/Phoenix.
  209. #### Companion plugin: `rewrite` (experimental)
  210. **`rewrite`** (Elixir Rewrite Architect) plans a rewrite of an existing app
  211. from any language into idiomatic Elixir: features as goals, why each legacy
  212. mechanism exists, a compatibility bar before any design, then vertical slices
  213. handed to `/phx:plan` and checked by `/rewrite:verify`. Stack packs for Rails,
  214. Django, Laravel/PHP, Node, Go and JVM/.NET; a generic method for the rest. It
  215. depends on `elixir-phoenix`. Version 0.1.0, tested on small apps only:
  216. ```bash
  217. /plugin install rewrite@oliver-kriska
  218. ```
  219. See `plugins/rewrite/README.md`.
  220. #### From Local Path (for development)
  221. ```bash
  222. git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
  223. # Option A: Add as local marketplace
  224. /plugin marketplace add ./claude-elixir-phoenix
  225. /plugin install elixir-phoenix
  226. # Option B: Test the plugin and its command namespaces directly
  227. claude \
  228. --plugin-dir ./claude-elixir-phoenix/plugins/elixir-phoenix \
  229. --plugin-dir ./claude-elixir-phoenix/plugins/ecto \
  230. --plugin-dir ./claude-elixir-phoenix/plugins/lv
  231. ```
  232. Keep all three `--plugin-dir` arguments when testing public command
  233. compatibility. The main directory provides `/phx:*`; the `ecto` and `lv`
  234. directories provide the legacy `/ecto:*` and `/lv:*` aliases.
  235. ### Use with Amp
  236. Amp supports two profiles from the same generated snapshot:
  237. - **Hosted-native:** publish the skills and plugin independently to Amp personal
  238. or workspace repositories. Use Amp's native `skill: invoke` command. The
  239. plugin still provides specialists, parallel analysis, and edit lock, but its
  240. filesystem wrappers cannot load hosted-only skills and native `phx-full` does
  241. not arm the plugin verification gate.
  242. - **Paired-full:** install matching skills and plugin locally. This preserves all
  243. 40 `phx:*`/`ecto:*`/`lv:*` wrappers and the wrapper-activated `phx-full` gate.
  244. Project-local paired installation is recommended for reproducible full behavior:
  245. ```bash
  246. cd /path/to/your-phoenix-project
  247. # Install the 51 skills into this project
  248. amp skill add \
  249. https://github.com/oliver-kriska/amp-elixir-phoenix/tree/stable/skills \
  250. --target "$PWD/.agents/skills"
  251. # Add deterministic workflows, read-only agents, and native guards
  252. mkdir -p .amp/plugins
  253. plugin=".amp/plugins/elixir-phoenix.ts"
  254. temporary="$(mktemp "${plugin}.XXXXXX")"
  255. curl --fail --silent --show-error --location \
  256. https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/elixir-phoenix.ts \
  257. --output "$temporary" && mv "$temporary" "$plugin"
  258. ```
  259. Open Amp's command palette with `Ctrl+O`, run `skill: invoke`, choose
  260. `phx-investigate`, and send the bug details. This native path resolves the
  261. effective skill whether it is local, built-in, personal hosted, or workspace
  262. hosted. With paired-full, the familiar `phx: investigate`, `phx: review`,
  263. `ecto: n1-check`, and `lv: assigns` wrappers are also available; they inject the
  264. matching local skill for one turn. `phx: full` activates the plugin verification
  265. gate only through that wrapper, not through native `skill: invoke`.
  266. `amp skill add --global` means **machine-local**, under
  267. `~/.config/agents/skills/`; it is not personal hosted/account-wide. Personal
  268. hosted artifacts are managed through Amp's Personal Settings or personal Git
  269. repositories and work across machines and orbs. See the complete [Amp guide](docs/amp.md)
  270. for hosted publication, source precedence, wrapper limits, updates, fallback
  271. installation, specialists, safety boundaries, and verification.
  272. `phx-watch-pr` additionally needs the separate `phx-watch-pr.ts` plugin.
  273. Install it into the project where the worker Orb opens and watches PRs:
  274. ```bash
  275. mkdir -p .amp/plugins
  276. plugin=".amp/plugins/phx-watch-pr.ts"
  277. temporary="$(mktemp "${plugin}.XXXXXX")"
  278. curl --fail --silent --show-error --location \
  279. https://raw.githubusercontent.com/oliver-kriska/amp-elixir-phoenix/stable/plugins/phx-watch-pr.ts \
  280. --output "$temporary" && mv "$temporary" "$plugin"
  281. ```
  282. It holds a bounded Orb keep-alive lease, filters deployment-like checks out of
  283. readiness, persists reload-safe state, and wakes the same worker thread only for
  284. failed/cancelled required CI, unresolved feedback, and terminal outcomes. With
  285. `--fix`, actionable feedback and branch-owned CI failures are repaired in one
  286. serialized same-thread workflow. It never blindly reruns shared CI, merges, or
  287. deploys.
  288. ### Use with Codex
  289. Codex installs the generated target as a native skills plugin. Registration and
  290. installation are separate steps:
  291. ```bash
  292. codex plugin marketplace add oliver-kriska/claude-elixir-phoenix --ref main
  293. codex plugin add elixir-phoenix@oliver-kriska
  294. codex plugin list
  295. ```
  296. Start a fresh Codex session, then invoke workflows explicitly with
  297. `$elixir-phoenix:phx-investigate` or `$elixir-phoenix:phx-review`, browse them
  298. with `/skills`, or let Codex select a relevant skill from its description. Codex
  299. namespaces plugin skills; unqualified `$phx-investigate` is not an explicit
  300. alias. This edition also ships one synchronous native hook that blocks destructive
  301. Ecto resets/drops, unguarded force pushes, and accidental `MIX_ENV=prod mix`
  302. commands. Codex requires users to review and trust plugin hooks before they run;
  303. the skills work without it. Custom agents, plugin-root instructions, the remaining
  304. Claude hooks remain deferred; Tidewave MCP registration is external. See the
  305. complete [Codex guide](docs/codex.md) for updates, uninstall, isolation,
  306. troubleshooting, tested version, and capability details.
  307. ### Use with Pi
  308. Install the repository as a Pi package globally, or add `-l` to scope it to the
  309. current project:
  310. ```bash
  311. pi install git:github.com/oliver-kriska/claude-elixir-phoenix
  312. pi list
  313. ```
  314. Start a fresh Pi session, then invoke workflows explicitly with
  315. `/skill:phx-investigate` or `/skill:phx-review`. Pi can also select a skill from
  316. its description automatically. This edition ships skills and their complete
  317. bundled resources only—not extensions, prompt templates, custom agents,
  318. or package-root instructions. Tidewave MCP registration is external. See the
  319. complete [Pi guide](docs/pi.md) for project-local installation, updates,
  320. uninstall, isolation, troubleshooting, tested version, and capability details.
  321. ### Use with OpenCode
  322. OpenCode 1.17.2 discovers the generated skills recursively. Install a sparse
  323. checkout into one project (recommended) or the global OpenCode config root:
  324. ```bash
  325. git clone --filter=blob:none --sparse https://github.com/oliver-kriska/claude-elixir-phoenix.git .opencode/skills/elixir-phoenix
  326. git -C .opencode/skills/elixir-phoenix sparse-checkout set targets/opencode
  327. ```
  328. Start a fresh session and explicitly say “Use the skill tool to load the
  329. phx-investigate skill, then …”. In the tested OpenCode 1.17.2 setup,
  330. `/phx-investigate` and `/phx-review` also work when they do not collide with
  331. existing commands, but the skill tool is the documented portable interface. OpenCode
  332. selects the model implicitly. This target contains skills and complete bundled
  333. resources only—not hooks or custom agents. Tidewave MCP registration is
  334. external. Investigation, review, plan, work, PR-review, and full-lifecycle
  335. workflows are explicitly adapted; some other skills may still describe optional
  336. Claude-specific orchestration APIs. See the
  337. [OpenCode installation and support guide](docs/opencode.md) for global setup,
  338. updates, uninstall, feature-branch review, discovery debugging, and limitations.
  339. ### Use with DeepSeek Harness
  340. DeepSeek Harness scans a fixed set of skill roots and does **not** recurse, so
  341. point its provider at the generated directory rather than nesting a checkout:
  342. ```bash
  343. cd /path/to/your-phoenix-project
  344. git clone --filter=blob:none --sparse https://github.com/oliver-kriska/claude-elixir-phoenix.git .dsh/vendor/elixir-phoenix
  345. git -C .dsh/vendor/elixir-phoenix sparse-checkout set targets/dsh
  346. ```
  347. Then add `customSkillDirs: [<abs-path>/.dsh/vendor/elixir-phoenix/targets/dsh/skills]`
  348. to the `skill-filesystem` row in your profile's `cordis.patch.yml`, or simply copy
  349. `targets/dsh/skills/.` into `.agents/skills/`.
  350. Use a `/phx-investigate` or `/phx-review` token anywhere in a message — dsh's
  351. pre-step boundary injects the full skill body deterministically — or ask the
  352. model to load the skill through its `skill` tool. dsh reads `CLAUDE.md` natively,
  353. so `/phx:init` output applies with no porting. This target contains skills and
  354. complete bundled resources only: not hooks, custom agents, or MCP. Custom agents
  355. are not applicable rather than deferred, because dsh has no markdown agent
  356. registry. Tested against dsh `0.1.1-rc.2`, which is a developer preview with
  357. breaking changes expected. See the [dsh guide](docs/dsh.md) for both install
  358. options, discovery roots, and the full capability boundary.
  359. ## Getting Started
  360. The remainder of this README describes the full Claude Code plugin and uses
  361. Claude Code `/phx:*`, `/ecto:*`, and `/lv:*` syntax. For generated runtimes,
  362. translate invocations using the runtime guide: Amp natively uses
  363. `skill: invoke` and paired-full also provides generated entries such as
  364. `phx: investigate`; Codex uses
  365. `$elixir-phoenix:<skill>`, Pi uses `/skill:<name>`, OpenCode uses its skill
  366. tool, and dsh uses a `/phx-<skill>` token or its skill tool. Generated editions do not install Claude Code's complete custom agent,
  367. lifecycle-hook, permission, or MCP configuration.
  368. New to the plugin? Run the interactive tutorial:
  369. ```bash
  370. /phx:intro
  371. ```
  372. It walks through the workflow, commands, and features in 6 short sections (~5 min).
  373. Skip to any section with `/phx:intro --section N`.
  374. ## Quick Examples
  375. ```bash
  376. # Just describe what you need — the plugin detects complexity and suggests the right approach
  377. > Fix the N+1 query in the user dashboard
  378. # Plan a feature with parallel research agents, then execute
  379. /phx:plan Add email notifications for new comments
  380. /phx:work .claude/plans/email-notifications/plan.md
  381. # Full autonomous mode — plan, implement, review, capture learnings
  382. /phx:full Add user profile avatars with S3 upload
  383. # 4-agent parallel code review (idioms, security, tests, compilation)
  384. /phx:review
  385. # Quick implementation — skip ceremony, just code
  386. /phx:quick Add pagination to the users list
  387. # Structured bug investigation with 4 parallel tracks
  388. /phx:investigate Timeout errors in the checkout LiveView
  389. # Project health audit across 5 categories
  390. /phx:audit
  391. ```
  392. The plugin auto-loads domain knowledge based on what files you're editing
  393. (LiveView patterns for `*_live.ex`, Ecto patterns for schemas, security rules for auth code)
  394. and enforces [Iron Laws](#iron-laws-non-negotiable-rules) that prevent common Elixir/Phoenix mistakes.
  395. ## How It Works
  396. ### The Lifecycle
  397. The plugin implements a **Brainstorm, Plan, Work, Verify, Review, Compound** lifecycle. Each phase produces artifacts in a namespaced directory:
  398. ```
  399. /phx:brainstorm → /phx:plan → /phx:work → /phx:verify → /phx:review → /phx:compound
  400. │ │ │ │ │ │
  401. ↓ ↓ ↓ ↓ ↓ ↓
  402. interview.md plans/{slug}/ (in namespace) (in namespace) (in namespace) solutions/
  403. ```
  404. - **Plan** -- Research agents analyze your codebase in parallel, then synthesize a structured implementation plan
  405. - **Work** -- Execute the plan task-by-task with quick compile checks after each change
  406. - **Verify** -- Full verification loop (compile, format, credo, test) before review
  407. - **Review** -- Four specialist agents audit your code in parallel (idioms, security, tests, static analysis)
  408. - **Compound** -- Capture what you learned as reusable knowledge for future sessions
  409. ### Key Concepts
  410. - **Filesystem is the state machine.** Each phase reads from the previous phase's output. No hidden state.
  411. - **Plan namespaces.** Each plan owns all its artifacts in `.claude/plans/{slug}/` -- plan, research, reviews, progress, scratchpad.
  412. - **Plan checkboxes track progress.** `[x]` = done, `[ ]` = pending. `/phx:work` finds the first unchecked task and continues.
  413. - **One plan = one work unit.** Large features get split into multiple plans. Each is self-contained.
  414. - **Agents are automatic.** The plugin spawns specialist agents behind the scenes. You don't manage them directly.
  415. ### Plan Namespaces
  416. Every plan gets its own directory with all related artifacts:
  417. ```
  418. .claude/
  419. ├── plans/{slug}/ # Everything for ONE plan
  420. │ ├── plan.md # The plan itself (checkboxes = state)
  421. │ ├── research/ # Research agent output
  422. │ ├── reviews/ # Review findings (individual tracks)
  423. │ ├── summaries/ # Compressed multi-agent output
  424. │ ├── progress.md # Session progress log
  425. │ └── scratchpad.md # Auto-written decisions, dead-ends, handoffs
  426. ├── reviews/ # Ad-hoc reviews (no plan context)
  427. └── solutions/ # Compound knowledge (reusable across plans)
  428. ```
  429. No more scattered files across `.claude/planning/`, `.claude/progress/`, `.claude/reviews/`. One plan, one directory, everything together.
  430. ## Architecture
  431. ### Agent Hierarchy
  432. The plugin uses 26 agents organized into 3 tiers:
  433. ```
  434. ┌──────────────────────────────┐
  435. │ Orchestrators (opus model) │
  436. │ Coordinate phases, spawn │
  437. │ specialists, manage flow │
  438. └──────────┬───────────────────┘
  439. │
  440. ┌──────────────────────┼──────────────────────┐
  441. │ │ │
  442. ▼ ▼ ▼
  443. ┌───────────────┐ ┌───────────────────┐ ┌────────────────────┐
  444. │ workflow- │ │ planning- │ │ parallel- │
  445. │ orchestrator │ │ orchestrator │ │ reviewer │
  446. │ (full cycle) │ │ (research phase) │ │ (review phase) │
  447. └───────────────┘ └───────────────────┘ └────────────────────┘
  448. │ │
  449. ┌──────────┼──────────┐ ┌──────┼──────┐
  450. ▼ ▼ ▼ ▼ ▼ ▼
  451. ┌──────────┐ ┌────────┐ ┌──────┐ ... 4 specialist
  452. │ liveview │ │ ecto │ │ web │ review agents
  453. │ architect│ │ schema │ │ rsch │
  454. └──────────┘ └────────┘ └──────┘
  455. │
  456. ┌──────────┴──────────┐
  457. ▼ ▼
  458. ┌────────────┐ ┌──────────────┐
  459. │ context- │ │ Orchestrator │
  460. │ supervisor │ ───► │ reads ONLY │
  461. │ (sonnet) │ │ the summary │
  462. └────────────┘ └──────────────┘
  463. ```
  464. **Orchestrators** (opus, medium effort) -- Primary workflow coordinators, security-critical analysis.
  465. **Specialists** (sonnet) -- Domain experts, secondary orchestrators, judgment-heavy tasks. `sonnet` resolves to Sonnet 5.5 (1M context, half Opus 5.5's price).
  466. ### The Context Supervisor Pattern
  467. When an orchestrator spawns 4-8 research agents, their combined output can exceed 50k tokens -- flooding the parent's context window. The **context-supervisor** solves this using an OTP-inspired pattern:
  468. ```
  469. ┌────────────────────────────────────────────────────┐
  470. │ Orchestrator (thin coordinator, ~10k context) │
  471. │ Only reads: summaries/consolidated.md │
  472. └──────────────────┬─────────────────────────────────┘
  473. │ spawns AFTER workers finish
  474. ┌──────────────────▼─────────────────────────────────┐
  475. │ context-supervisor (sonnet, fresh 1M context) │
  476. │ Reads: all worker output files │
  477. │ Applies: compression strategy based on size │
  478. │ Validates: every input file represented │
  479. │ Writes: summaries/consolidated.md │
  480. └──────────────────┬─────────────────────────────────┘
  481. │ reads from
  482. ┌─────────────┼─────────────┐
  483. ▼ ▼ ▼
  484. worker 1 worker 2 worker N
  485. research/ research/ research/
  486. patterns.md security.md liveview.md
  487. ```
  488. **How compression works:**
  489. | Total Output | Strategy | Compression | What's Kept |
  490. | --------------- | ---------- | ----------- | ------------------------------ |
  491. | Under 8k tokens | Index | ~100% | Full content with file list |
  492. | 8k - 30k tokens | Compress | ~40% | Key findings, decisions, risks |
  493. | Over 30k tokens | Aggressive | ~20% | Only critical items |
  494. The supervisor also **deduplicates** -- if two agents flag the same issue
  495. (e.g., both the security analyzer and code reviewer find a missing
  496. authorization check), it merges them into one finding with both sources cited.
  497. **Used by:** planning-orchestrator (research synthesis), parallel-reviewer (review deduplication), audit skill (cross-category analysis).
  498. ### How Planning Works
  499. When you run `/phx:plan Add real-time notifications`:
  500. ```
  501. 1. planning-orchestrator analyzes your request
  502. │
  503. 2. Spawns specialists IN PARALLEL based on feature needs:
  504. ├── phoenix-patterns-analyst (always -- scans your codebase)
  505. ├── liveview-architect (if UI/real-time feature)
  506. ├── ecto-schema-designer (if database changes needed)
  507. ├── security-analyzer (if auth/user data involved)
  508. ├── oban-specialist (if background jobs needed)
  509. ├── web-researcher (if unfamiliar technology)
  510. └── ... up to 8 agents
  511. │
  512. 3. Each agent writes to plans/{slug}/research/{topic}.md
  513. │
  514. 4. context-supervisor compresses all research into one summary
  515. │
  516. 5. Orchestrator reads the summary + synthesizes the plan
  517. │
  518. 6. Output: plans/{slug}/plan.md with [P1-T1] checkboxes
  519. ```
  520. ### How Review Works
  521. When you run `/phx:review`:
  522. ```
  523. 1. parallel-reviewer collects your git diff
  524. │
  525. 2. Delegates to 4 EXISTING specialist agents:
  526. ├── elixir-reviewer → Idioms, patterns, error handling
  527. ├── security-analyzer → SQL injection, XSS, auth gaps
  528. ├── testing-reviewer → Test coverage, factory patterns
  529. └── verification-runner → mix compile, format, credo, test
  530. │
  531. 3. Each writes to plans/{slug}/reviews/{track}.md
  532. │
  533. 4. context-supervisor deduplicates + consolidates
  534. │
  535. 5. Output: plans/{slug}/summaries/review-consolidated.md
  536. ```
  537. ### Hooks — the deterministic layer
  538. Skills and agents are instructions a model may or may not follow. **Hooks are
  539. shell scripts that always run.** The plugin ships 23 of them across 10 lifecycle
  540. events:
  541. - **Block destructive commands** — `mix ecto.reset/drop`, force pushes,
  542. `MIX_ENV=prod` tasks other than release builds, and `pkill -f beam`-style
  543. pattern kills are denied before they execute (also inside a script the
  544. command runs), with a safer alternative attached
  545. - **Verify Iron Laws on every edit** — the lines you just wrote are scanned for
  546. `:float` money fields, `String.to_atom` on user input, `raw/1` with a
  547. variable, implicit cross joins, unsupervised `start_link`
  548. - **Inject context where models can't reach it** — all 26 Iron Laws into every
  549. spawned subagent; `/phx:` routing suggestions on PR URLs and stack traces
  550. - **Keep the plan workflow coherent** — hard-stop after planning, re-inject
  551. phase rules and scratchpad dead ends across compaction
  552. - **Break debugging loops** — repeated `mix` failures escalate from hints to a
  553. structured critic that consolidates the error history
  554. Everything Elixir-specific self-gates on `mix.exs`, so the plugin is inert in
  555. your non-Elixir repos. Hooks fail open — a broken hook means the guard is off,
  556. never that the session is unusable.
  557. **→ [HOOKS.md](HOOKS.md)** for the full list, the lifecycle diagram, and
  558. per-hook deep dives.
  559. ## Usage Guide
  560. ### Quick tasks (bug fixes, small changes)
  561. Just describe what you need. The plugin auto-detects complexity and suggests the right approach:
  562. ```
  563. > Fix the N+1 query in the dashboard
  564. Claude: This is a simple fix (score: 2). I'll handle it directly.
  565. ```
  566. Or use `/phx:quick` to skip ceremony:
  567. ```
  568. /phx:quick Add pagination to the users list
  569. ```
  570. ### Medium tasks (new features, refactors)
  571. Use `/phx:plan` to create an implementation plan, then `/phx:work` to execute it:
  572. ```
  573. /phx:plan Add email notifications for new comments
  574. ```
  575. The plugin will:
  576. 1. Spawn research agents to analyze your codebase patterns
  577. 2. Show a completeness check (every requirement mapped to a task)
  578. 3. Ask you how to proceed (start implementation, review plan, adjust)
  579. When starting implementation, the plugin recommends a **fresh session** for plans with 5+ tasks. The plan file is self-contained, so no context from the planning session is needed:
  580. ```
  581. # In a new Claude Code session:
  582. /phx:work .claude/plans/email-notifications/plan.md
  583. ```
  584. ### Large tasks (new domains, security features)
  585. Use deep research planning:
  586. ```
  587. /phx:plan Add OAuth login with Google and GitHub --depth deep
  588. ```
  589. This spawns 4+ parallel research agents, then produces a detailed plan.
  590. For security-sensitive features, the plugin will ask clarifying questions
  591. before proceeding. Or use `/phx:full` for fully autonomous development.
  592. ### Fixing review issues
  593. After implementing, run a review:
  594. ```
  595. /phx:review
  596. ```
  597. Four parallel agents check your code (idioms, tests, security, compilation). If blockers are found, the plugin asks whether to replan or fix directly:
  598. ```
  599. Review found 2 blockers:
  600. 1. Missing authorization in handle_event -- security risk
  601. 2. N+1 query in list_comments -- performance issue
  602. Options:
  603. - Replan fixes (/phx:plan --existing)
  604. - Fix directly (/phx:work)
  605. - Handle myself
  606. ```
  607. ### Project health checks
  608. Run a comprehensive audit with 5 parallel specialist agents:
  609. ```
  610. /phx:audit # Full audit
  611. /phx:audit --quick # 2-3 minute pulse check
  612. /phx:audit --focus=security # Deep dive single area
  613. /phx:audit --since HEAD~10 # Audit recent changes only
  614. ```
  615. The audit scores your project across 5 categories (architecture, performance, security, tests, dependencies) and produces an actionable report.
  616. ### Full autonomous mode
  617. For hands-off development:
  618. ```
  619. /phx:full Add user profile avatars with S3 upload
  620. ```
  621. Runs the complete cycle: plan (with research), work, verify, review. After review fixes, re-verifies before cycling back. Captures learnings on completion.
  622. ## Workflow Tips
  623. ### Context management
  624. - `/phx:plan` creates a **self-contained plan file** with all implementation details
  625. - For 5+ task plans, start `/phx:work` in a **fresh session** to maximize context space
  626. - For small plans (2-4 tasks), continuing in the same session is fine
  627. ### Resuming work
  628. Plan checkboxes are the state. If a session ends mid-work:
  629. ```
  630. # Just run /phx:work on the same plan -- it finds the first [ ] and continues
  631. /phx:work .claude/plans/my-feature/plan.md
  632. ```
  633. ### Splitting large features
  634. When a feature has 10+ tasks across different domains, the plugin offers to split into multiple plan files:
  635. ```
  636. Created 3 plans (14 total tasks):
  637. 1. .claude/plans/auth/plan.md (5 tasks -- login, register, reset)
  638. 2. .claude/plans/profiles/plan.md (4 tasks -- avatar, bio, settings)
  639. 3. .claude/plans/admin/plan.md (5 tasks -- dashboard, roles)
  640. Recommended order: 1 -> 2 -> 3
  641. ```
  642. Execute each plan separately with `/phx:work`.
  643. ### Learning from mistakes
  644. After fixing a bug or receiving a correction:
  645. ```
  646. /phx:learn-from-fix Fixed N+1 query -- always preload associations in context functions
  647. /phx:learn-from-fix --library ical --scope personal ICal.to_ics output needs CRLF line endings
  648. ```
  649. This stores verified general lessons in personal `~/.claude/CLAUDE.md`, project
  650. instructions, or project-keyed memory.
  651. The library route creates or safely updates native background knowledge at
  652. `~/.claude/skills/hex-<package>/SKILL.md` (personal) or
  653. `.claude/skills/hex-<package>/SKILL.md` (project). Claude selects it from its
  654. description; dependency presence alone does not guarantee activation. Cached
  655. plugin files are never modified.
  656. ## Iron Laws (Non-Negotiable Rules)
  657. The plugin enforces critical rules and **stops with an explanation** if code would violate them:
  658. **LiveView:** No database queries in disconnected mount. Use streams for lists >100 items. Check `connected?/1` before PubSub subscribe.
  659. **Ecto:** Never use `:float` for money. Always pin values with `^` in queries. Separate queries for `has_many`, JOIN for `belongs_to`.
  660. **Oban:** Jobs must be idempotent. Args use string keys. Never store structs in args.
  661. **Security:** No `String.to_atom` with user input. Authorize in every LiveView
  662. `handle_event`. Treat forms, hooks, and `phx-value-*` as user-controlled. IDs
  663. rendered in HTML or event payloads are public identifiers, not proof of access.
  664. Never use `raw/1` with untrusted content.
  665. **Deployment:** Keep core release secrets required, but gate credentials for
  666. optional services behind the feature that enables them. `runtime.exs` also runs
  667. when an `eval`-based migration boots the release, so unconditional S3 or Redis
  668. requirements can break unrelated migrations.
  669. **OTP:** No process without a runtime reason. Supervise all long-lived processes.
  670. **Elixir:** Declare `@external_resource` for compile-time files. Wrap third-party library APIs behind project-owned modules. Never use `assign_new` for values refreshed every mount.
  671. **Code style:** Comments aren't commit messages — a change's reasoning goes in the commit/PR, not the code. No issue-reference tags inline (`# ENA-1234`).
  672. ## Commands Reference
  673. ### Workflow
  674. | Command | Description |
  675. | ----------------------- | ------------------------------------------------------------ |
  676. | `/phx:full <feature>` | Full autonomous cycle (plan, work, verify, review, compound); `--codex` adds a cross-model review track |
  677. | `/phx:brainstorm <topic>` | Adaptive requirements gathering before planning |
  678. | `/phx:plan <input>` | Create implementation plan with specialist agents |
  679. | `/phx:plan --existing` | Enhance existing plan with deeper research |
  680. | `/phx:work <plan-file>` | Execute plan tasks with verification |
  681. | `/phx:review [focus]` | Multi-agent code review (4 parallel agents) |
  682. | `/phx:compound` | Capture solved problem as reusable knowledge |
  683. | `/phx:triage` | Interactive triage of review findings |
  684. | `/phx:document` | Generate @moduledoc, @doc, README, ADRs |
  685. | `/phx:learn-from-fix [--library <pkg> --scope personal\|project] <lesson>` | Capture verified general or package lessons |
  686. | `/phx:brief <plan>` | Interactive plan walkthrough |
  687. | `/phx:perf` | Performance analysis with specialist agents |
  688. | `/phx:pr-review` | Address PR review threads — fetch, fix, reply, resolve |
  689. | `/phx:watch-pr <PR#>` | Background-watch a PR for reviews + CI; `--codex` adds a Codex cloud review loop |
  690. | `/phx:codex-loop` | Fix until Codex CLI review is clean (optional, needs codex) |
  691. ### Utility
  692. | Command | Description |
  693. | ------------------------ | ---------------------------------------------------------- |
  694. | `/phx:intro` | Interactive plugin tutorial (6 sections, ~5 min) |
  695. | `/phx:init` | Initialize plugin in a project (auto-activation rules) |
  696. | `/phx:help` | Interactive command advisor — recommends the right command |
  697. | `/phx:quick <task>` | Fast implementation, skip ceremony |
  698. | `/phx:investigate <bug>` | Systematic bug debugging (4 parallel investigation tracks) |
  699. | `/phx:research <topic>` | Research Elixir topics on the web |
  700. | `/phx:verify` | Run full verification (compile, format, credo, test — plus dialyzer when configured) |
  701. | `/phx:permissions` | Scan sessions, recommend safe Bash permissions |
  702. | `/phx:trace <function>` | Build call trees to trace function flow |
  703. | `/phx:boundaries` | Analyze Phoenix context boundaries with mix xref |
  704. | `/phx:examples` | Practical examples and pattern walkthroughs |
  705. | `/phx:recall <question>` | Recall prior work — solution docs, git history, sessions |
  706. | `/ecto:constraint-debug` | Debug Ecto constraint violations |
  707. ### Analysis
  708. | Command | Description |
  709. | -------------------- | ------------------------------------------------- |
  710. | `/ecto:n1-check` | Detect N+1 query patterns |
  711. | `/lv:assigns <file>` | Audit LiveView assigns for memory issues |
  712. | `/phx:techdebt` | Find technical debt and refactoring opportunities |
  713. | `/phx:audit` | Full project health audit with 5 parallel agents |
  714. | `/phx:challenge` | Rigorous review mode ("grill me") |
  715. ### Security & dependencies
  716. | Command | Description |
  717. | ---------------------------- | ---------------------------------------------------- |
  718. | `/phx:deps-update` | Bump outdated Hex deps — changelogs, coupled groups, grouped PRs |
  719. | `/phx:deps-audit [--base R]` | Hex supply-chain audit (8 rules + CVE + differential) |
  720. | `/phx:deps-vet <pkg> <ver>` | Manage the `hex_vet.exs` audit ledger (cargo-vet style) |
  721. ## Agents (26)
  722. | Agent | Model | Memory | Role |
  723. | ---------------------------- | ------ | ------- | -------------------------------------------- |
  724. | **workflow-orchestrator** | opus | project | Full cycle coordination (plan, work, review) |
  725. | **planning-orchestrator** | opus | project | Parallel research agent coordination |
  726. | **parallel-reviewer** | opus | -- | 4-agent parallel code review |
  727. | **deep-bug-investigator** | opus | -- | 4-track parallel bug investigation |
  728. | **call-tracer** | sonnet | -- | Parallel call tree tracing |
  729. | **security-analyzer** | opus | -- | OWASP vulnerability scanning |
  730. | **context-supervisor** | sonnet | -- | Multi-agent output compression |
  731. | **verification-runner** | sonnet | -- | mix compile, format, credo, test |
  732. | **iron-law-judge** | sonnet | -- | Pattern-based Iron Law detection |
  733. | **xref-analyzer** | sonnet | -- | Module dependency analysis |
  734. | **hex-library-researcher** | sonnet | -- | Hex.pm library evaluation |
  735. | **liveview-architect** | sonnet | -- | Component structure, streams, async patterns |
  736. | **ecto-schema-designer** | sonnet | -- | Migrations, data models, query patterns |
  737. | **phoenix-patterns-analyst** | sonnet | project | Codebase pattern discovery |
  738. | **elixir-reviewer** | sonnet | -- | Code idioms, patterns, conventions |
  739. | **testing-reviewer** | sonnet | -- | ExUnit, Mox, LiveView test patterns |
  740. | **oban-specialist** | sonnet | -- | Worker idempotency, error handling |
  741. | **otp-advisor** | sonnet | -- | GenServer, Supervisor, process design |
  742. | **deployment-validator** | sonnet | -- | Docker, Kubernetes, Fly.io config |
  743. | **web-researcher** | sonnet | -- | ElixirForum, HexDocs, GitHub research |
  744. | **ash-resource-designer** | sonnet | -- | Ash resource design (the "Ash Way") |
  745. | **ash-policy-reviewer** | sonnet | -- | Ash policy authorization audit |
  746. | **ash-query-optimizer** | sonnet | -- | Ash N+1 loads, aggregates vs load |
  747. | **requirements-verifier** | sonnet | -- | Implementation vs task-requirement check |
  748. | **hex-deps-triager** | sonnet | -- | Hex supply-chain audit finding triage |
  749. | **codex-reviewer** | sonnet | -- | Codex CLI bridge — cross-model review (opt.) |
  750. Agents with `project` memory build up knowledge across sessions
  751. in `.claude/agent-memory/<agent-name>/`. Orchestrators remember
  752. architectural decisions; pattern analysts skip redundant discovery.
  753. ## Reference Skills (Auto-Loaded)
  754. These load automatically based on file context -- no commands needed:
  755. | Skill | Triggers On |
  756. | ---------------------- | ------------------------------------------- |
  757. | `elixir-idioms` | OTP/BEAM code, GenServer, Supervisor, Task |
  758. | `phoenix-contexts` | Context modules, router, plugs, controllers |
  759. | `liveview-patterns` | `*_live.ex`, mount, handle_event, streams |
  760. | `ecto-patterns` | Schemas, migrations, Repo calls, changesets |
  761. | `testing` | `*_test.exs`, factories, test support |
  762. | `oban` | Oban workers, perform/1, queue config |
  763. | `security` | Auth, event trust, CSRF/CSP, input validation |
  764. | `deploy` | Dockerfile, runtime config, releases |
  765. | `tidewave-integration` | Runtime debugging, live process inspection |
  766. | `intent-detection` | First message routing to /phx: commands |
  767. | `compound-docs` | Solution documentation lookups |
  768. ## Tidewave MCP Integration
  769. When your Phoenix app runs with
  770. [Tidewave](https://github.com/tidewave-ai/tidewave_phoenix), the plugin detects
  771. the local server and prefers its runtime tools. Add Tidewave to the application:
  772. ```elixir
  773. # Add to mix.exs
  774. {:tidewave, "~> 0.6", only: :dev}
  775. # Add to endpoint.ex (in dev block)
  776. plug Tidewave
  777. ```
  778. Then register the running endpoint with Claude Code, replacing `$PORT` with the
  779. Phoenix port:
  780. ```bash
  781. claude mcp add --transport http tidewave \
  782. http://localhost:$PORT/tidewave/mcp
  783. ```
  784. Use `/mcp` to verify the connection. The plugin does not silently register a
  785. fixed-port MCP endpoint. Once connected, Tidewave can execute Elixir code, run
  786. SQL queries, get documentation for exact dependency versions, introspect Ecto
  787. schemas, and read application logs.
  788. ## Requirements
  789. - Claude Code CLI
  790. - Elixir/Phoenix project
  791. ### Optional
  792. - **Tidewave** for runtime debugging
  793. - **[ccrider](https://github.com/neilberkman/ccrider)** for session analysis (see Contributing)
  794. - **Ralph Wiggum Loop** for autonomous iteration across context resets
  795. - **[OpenAI Codex](https://developers.openai.com/codex)** as an external reviewer:
  796. `/phx:review --codex`, `/phx:full --codex`, and `/phx:codex-loop` use the
  797. local codex CLI; `/phx:watch-pr --codex` uses the Codex GitHub connector.
  798. Install the shared Elixir review rubric into AGENTS.md via `/phx:init`. Users
  799. without codex are unaffected — all codex behavior is flag-gated
  800. ## Security
  801. This plugin runs skills, agents, and hooks inside Claude Code with your tool
  802. permissions, so it ships a verifiable security posture:
  803. - **Independently scanned** with [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector)
  804. (static analysis, **zero covert-egress findings**): **66 / 77 components SAFE**, 7 CAUTION,
  805. 4 DO_NOT_INSTALL raw. The four DO_NOT_INSTALL components are documented false
  806. positives with reviewed baselines, so **after baselines 0 remain and the scan
  807. gate passes** (the 7 CAUTION-tier components stay documented). A static scanner
  808. flags the *safety-enforcing* and *security-auditing* skills precisely because
  809. they name dangerous patterns in order to forbid or detect them (e.g. the line
  810. literally reads `NEVER bypass security checks for speed`).
  811. - **No telemetry or covert egress**; workflows can make visible, user-authorized
  812. GitHub, Hex, web-search, or configured MCP calls through the host runtime.
  813. Review agents are read-only by default (source edits disallowed), and the
  814. Bash hooks are auditable in `plugins/elixir-phoenix/hooks/` — every one of
  815. them is documented in **[HOOKS.md](HOOKS.md)**.
  816. Full report, line-by-line triage, and a reproduce-it-yourself command live in
  817. **[SECURITY.md](SECURITY.md)**. Re-run the scan anytime with `make security`.
  818. ## Contributing
  819. PRs welcome! See [CLAUDE.md](CLAUDE.md) for full conventions.
  820. ### Quality Gate
  821. Every PR must pass the CI quality gate (lint + test + eval). Run locally before pushing:
  822. ```bash
  823. make help # Show all available commands
  824. make eval # Quick: lint + score changed skills/agents only
  825. make eval-all # Full structural: all 51 skills + all 26 agents
  826. make eval-fix # Auto-fix lint + show failures + suggest autoresearch
  827. make test # Pytest suites for the eval framework and port tooling
  828. make generated-skills-sync # Regenerate and verify all four runtime targets
  829. make ci # Full CI: lint + test + validate + eval + security (same as GitHub Actions)
  830. ```
  831. The eval framework scores skills across **8 dimensions** and agents across **5 dimensions**.
  832. Skills must score >= 0.95 to pass. Run `make eval-all` for details.
  833. ### Development Rules
  834. - **Skills**: ~100 lines SKILL.md + `references/` for details. Must include Iron Laws, "Use when..." in description.
  835. - **Agents**: under 300 lines, `disallowedTools: Write, Edit, NotebookEdit` for reviewers, no `permissionMode` (plugin agents ignore it).
  836. - **All markdown** passes `npm run lint`
  837. - **New skills/agents** must pass `npm run eval` before merging
  838. - **Autoresearch**: Run `npm run eval:fix` to auto-detect and fix quality issues
  839. ### Autoresearch (Self-Improvement Loop)
  840. The plugin includes an internal eval framework (`lab/eval/`) that scores all skills and agents. When quality drops, the autoresearch loop can fix it:
  841. ```bash
  842. # Score everything, show failures, get auto-fix command
  843. npm run eval:fix
  844. # Or run the autoresearch loop directly (targets weakest skill, fixes one issue per iteration)
  845. claude -p 'Run autoresearch...' --allowedTools 'Edit,Read,Write,Bash,Glob,Grep'
  846. ```
  847. The eval framework uses 24 deterministic Python matchers plus a separate,
  848. fresh Haiku behavioral gate. `make eval-full` requires every skill to reach 75%
  849. trigger accuracy; ignored local result caches never affect structural CI. See
  850. `lab/eval/` for details.
  851. ### Analyze your sessions to improve the plugin
  852. The plugin includes session analysis tools that help identify improvement opportunities.
  853. If you use this plugin (or work on Elixir/Phoenix projects with Claude Code),
  854. you can analyze your own sessions to find patterns that the plugin should handle better.
  855. **Setup:**
  856. 1. Clone this repo: `git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git`
  857. 2. Install [ccrider MCP](https://github.com/neilberkman/ccrider): `claude mcp add ccrider -- npx @neilberkman/ccrider`
  858. **Available tools** (dev-only, not shipped with the plugin):
  859. ```bash
  860. # Tier 1: Discover sessions and compute deterministic metrics
  861. /session-scan
  862. /session-scan --project myapp
  863. # Tier 2: Qualitative analysis of high-signal sessions
  864. /session-deep-dive
  865. /session-deep-dive --date 2026-03-01
  866. # Trends: Windowed aggregates (7d/30d/all) from metrics ledger
  867. /session-trends
  868. /session-trends --compare baseline
  869. /session-trends --html out.html # HTML report with ASCII bar charts
  870. # Pure context-window stats (max tokens, ctx %, compaction rate) across raw JSONL
  871. python3 .claude/skills/session-scan/references/compute-metrics.py \
  872. --scan-jsonl ~/.claude/projects/<project-id>/ \
  873. --since 2026-04-01 --html ctx-stats.html
  874. # Skill effectiveness monitoring (requires session-scan data)
  875. /skill-monitor # Dashboard: all skills
  876. /skill-monitor --improve # Generate improvement recommendations
  877. ```
  878. ### What session analysis finds
  879. - **Friction points** -- where you got stuck, repeated commands, abandoned approaches
  880. - **Workflow patterns** -- how you work (planning vs diving in, tool usage)
  881. - **Plugin improvement opportunities** -- missing automation, skills, or Iron Laws
  882. Each analysis report includes a **Plugin Improvement Opportunities** section that identifies:
  883. - Manual workflows that could be automated by a new skill or hook
  884. - Code patterns that caused bugs but the plugin doesn't catch (Iron Law candidates)
  885. - Missing skills or agents for common tasks
  886. - Auto-loading gaps where skills should trigger but don't
  887. Share these findings in issues or PRs to help make the plugin better for everyone.
  888. ## Roadmap
  889. - **elixir-inspector** (in progress) -- Separate plugin for 6-layer codebase analysis.
  890. Generates Credo checks, skills, CI steps, and review prompts from your project patterns.
  891. See the [open PR](https://github.com/oliver-kriska/claude-elixir-phoenix/pulls).
  892. - **Tier 2/3 behavioral eval** -- Instruction-following tests and full A/B skill comparison (with-skill vs without-skill outcome quality).
  893. - **Runtime eval integration** -- Connect session metrics to the eval framework for measuring real-world skill effectiveness.
  894. ## Sources and Inspiration
  895. This plugin was built with insights from these articles, repositories, and tools:
  896. ### Repositories and Tools
  897. - <https://github.com/tidewave-ai/tidewave_phoenix>
  898. - <https://github.com/neilberkman/ccrider>
  899. - <https://github.com/nicobailon/visual-explainer>
  900. - <https://github.com/VoltAgent/awesome-claude-code-subagents>
  901. - <https://github.com/shanraisshan/claude-code-best-practice>
  902. - <https://github.com/anthropics/claude-code>
  903. - <https://github.com/anthropics/claude-plugins-official>
  904. - <https://github.com/anthropics/skills>
  905. - <https://github.com/rjs/shaping-skills>
  906. - <https://github.com/earendil-works/pi/blob/main/scripts/session-context-stats.mjs>
  907. (badlogic — token usage / context % metrics, per-model + per-day breakdown,
  908. and ASCII-bar HTML report layout borrowed for `compute-metrics.py --scan-jsonl`
  909. and `/session-trends --html`)
  910. - <https://github.com/affaan-m/everything-claude-code>
  911. - <https://github.com/blader/theorist>
  912. - <https://github.com/tmchow/tmc-marketplace> (iterative-engineering plugin)
  913. - <https://github.com/SamJHudson01/Carmack-Council> (persona-grounded expert council review)
  914. - <https://github.com/obra/superpowers> (verification discipline, CSO patterns)
  915. - <https://github.com/boshu2/agentops>
  916. ### Articles
  917. - <https://www.codecon.sk/search-is-not-magic-with-postgresql>
  918. - <https://peterullrich.com/complete-guide-to-full-text-search-with-postgres-and-ecto>
  919. - <https://peterullrich.com/efficient-name-search-with-postgres-and-ecto>
  920. - <https://elixirmerge.com/p/exploring-postgresql-search-techniques-with-elixir-and-ecto>
  921. - <https://tidewave.ai/blog/the-future-of-coding-agents-is-vertical-integration>
  922. - <https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents>
  923. - <https://openai.com/index/harness-engineering/>
  924. - <https://www.ignorance.ai/p/the-emerging-harness-engineering>
  925. - <https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html>
  926. - <https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents>
  927. - <https://boristane.com/blog/how-i-use-claude-code/>
  928. - <https://mitchellh.com/writing/my-ai-adoption-journey>
  929. - <https://www.thepragmaticcto.com/p/no-vibes-allowed-context-engineering>
  930. - <https://basecamp.com/shapeup>
  931. - <https://pragprog.com/titles/jwpaieng/a-common-sense-guide-to-ai-engineering/>
  932. - <https://allanmacgregor.com/posts/setting-up-tidewave-beam-introspection>
  933. - <https://theengineeringmanager.substack.com/p/councils-of-agents>
  934. - <https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling>
  935. - <https://arxiv.org/abs/2603.03329> (AutoHarness: improving LLM agents by automatically synthesizing a code harness)
  936. - <https://x.com/heynavtoor>
  937. ## License
  938. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.