phx-init
Initialize plugin in a project — install Iron Laws, auto-activation rules,
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phx-init
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Plugin Initialization
Install the Elixir/Phoenix plugin's behavioral instructions into the project's CLAUDE.md.
Usage
phx-init # First-time installation
phx-init --update # Update existing installation with latest rules
Iron Laws
- NEVER overwrite content outside plugin markers — User-written CLAUDE.md rules must be preserved verbatim
- Always detect stack before generating — Never assume Phoenix/Ecto versions
- Always validate after installation — Verify markers present and stack correct
Workflow
Step 1: Check Existing CLAUDE.md
Use Glob to check if CLAUDE.md exists. Then use Grep to check for existing ELIXIR-PHOENIX-PLUGIN:START marker in CLAUDE.md.
Step 2: Detect Project Stack
Scan the project to customize the injected instructions:
Read mix.exs and use Grep to extract:
- Phoenix version: search for
phoenix.*"~>inmix.exs - Ecto version: search for
ecto.*"~>inmix.exs - Oban: search for
"oban"and"oban_pro"inmix.exs - Frameworks: search for
"ash","surface"inmix.exs - Tidewave: search for
"tidewave"inmix.exs - Project size: use Glob to count
lib/**/*.exfiles
Step 3: Handle Installation Modes
Mode A: Fresh Install (no CLAUDE.md or no markers)
- Create/append to CLAUDE.md
- Insert full behavioral instructions between markers
- Include only relevant sections based on detected stack
Mode B: Update (--update flag or markers exist)
- Find content between
<!-- ELIXIR-PHOENIX-PLUGIN:START -->and<!-- ELIXIR-PHOENIX-PLUGIN:END --> - Replace with latest behavioral instructions
- Preserve everything outside the markers
In both modes, CLAUDE.md content outside the plugin markers — user-written rules, project conventions, other plugin sections — stays verbatim (Iron Law 1)
Step 4: Generate Content
Write the following structure to CLAUDE.md:
<!-- ELIXIR-PHOENIX-PLUGIN:START -->
<!-- Last updated: {date} | Plugin version: 1.0 | Stack: Phoenix {version}, Ecto {version}, {optional: Oban, Tidewave} -->
# Elixir/Phoenix Plugin - Auto-Activation Rules
{Include all sections from the Content Template below, filtered by detected stack}
<!-- ELIXIR-PHOENIX-PLUGIN:END -->
Step 4b: Offer Codex Review Guidelines (optional)
If command -v codex succeeds (or the user asks): offer to install a
managed ## Review guidelines block into the project's AGENTS.md —
honored by BOTH codex exec review locally and the Codex cloud PR
reviewer. Follow the install rules and exact block in
references/codex-review-guidelines.md: markers
ELIXIR-PHOENIX-REVIEW-GUIDELINES:START/END, upsert in place on
--update, never touch content outside markers, and STOP to ask if an
unmanaged ## Review guidelines section already exists. When codex is
absent and not requested, skip silently — never mention codex to users
who don't have it.
Step 5: Output Summary
✅ Elixir/Phoenix plugin initialized
Detected stack:
- Phoenix {version}
- Ecto {version}
- {Oban standard | Oban Pro | not detected}
- {Tidewave ✓ | Tidewave not detected}
- {Ash Framework detected - Ecto patterns disabled | not detected}
Added to CLAUDE.md:
- Auto-activation rules (complexity detection, interview mode)
- Agent trigger patterns ({n} agents available)
- Reference auto-loading ({n} reference docs)
- Iron Laws enforcement ({n} laws)
- Verification rules
{- Codex review guidelines → AGENTS.md (only if installed in Step 4b)}
Run phx-init --update after plugin updates.
Run phx-audit for a full project health check.
Content Template
The exact content to inject is in references/injectable-template.md.
Key structure:
- Routing table — which
phx-*command fits which kind of request - Iron Laws — STOP behavior on violations
- Conditional Sections — Include based on detected stack:
{OBAN_SECTION}— If Oban detected (not Pro){OBAN_PRO_SECTION}— If Oban Pro detected{ASH_SECTION}— If Ash Framework detected{TIDEWAVE_SECTION}— If Tidewave detected
- Verification — Mandatory after code changes
- Quick Reference — Skill routing table
Placeholder substitution:
| Placeholder | Source |
|---|---|
{DATE} |
Current date |
{PHOENIX_VERSION} |
From mix.exs |
{ECTO_VERSION} |
From mix.exs |
{OPTIONAL_STACK} |
Detected optional deps |
See references/injectable-template.md for full template with all placeholders and conditional sections.
Validation
After running phx-init:
- Check CLAUDE.md contains markers
- Verify detected stack matches actual project
- New session should:
- Auto-detect complexity when given tasks
- Stop on Iron Law violations
- Offer relevant workflows based on task
Error Handling
| Scenario | Action |
|---|---|
| CLAUDE.md read-only | Error: "Cannot modify CLAUDE.md - check permissions" |
| Markers corrupted | Warn, offer to remove and reinstall |
| Unknown Phoenix version | Use conservative defaults (all features enabled) |
| Not an Elixir project | Error: "No mix.exs found - is this an Elixir project?" |
Relationship to Other Commands
| Command | When to Use |
|---|---|
phx-init |
First time, or after plugin updates |
phx-audit |
Periodic project health check |
phx-verify |
After code changes |
Files (claude-elixir-phoenix)
-
references
-
codex-review-guidelines.md 3.6 KB
Loading… -
injectable-template.md 6.3 KB
Loading…
-
-
SKILL.md 5.5 KB
--- name: phx-init description: Initialize plugin in a project — install Iron Laws, auto-activation rules, and reference auto-loading into CLAUDE.md. Use when setting up or updating the plugin. --- # Plugin Initialization Install the Elixir/Phoenix plugin's behavioral instructions into the project's CLAUDE.md. ## Usage ``` phx-init # First-time installation phx-init --update # Update existing installation with latest rules ``` ## Iron Laws 1. **NEVER overwrite content outside plugin markers** — User-written CLAUDE.md rules must be preserved verbatim 2. **Always detect stack before generating** — Never assume Phoenix/Ecto versions 3. **Always validate after installation** — Verify markers present and stack correct ## Workflow ### Step 1: Check Existing CLAUDE.md Use Glob to check if `CLAUDE.md` exists. Then use Grep to check for existing `ELIXIR-PHOENIX-PLUGIN:START` marker in `CLAUDE.md`. ### Step 2: Detect Project Stack Scan the project to customize the injected instructions: Read `mix.exs` and use Grep to extract: - Phoenix version: search for `phoenix.*"~>` in `mix.exs` - Ecto version: search for `ecto.*"~>` in `mix.exs` - Oban: search for `"oban"` and `"oban_pro"` in `mix.exs` - Frameworks: search for `"ash"`, `"surface"` in `mix.exs` - Tidewave: search for `"tidewave"` in `mix.exs` - Project size: use Glob to count `lib/**/*.ex` files ### Step 3: Handle Installation Modes **Mode A: Fresh Install** (no CLAUDE.md or no markers) 1. Create/append to CLAUDE.md 2. Insert full behavioral instructions between markers 3. Include only relevant sections based on detected stack **Mode B: Update** (`--update` flag or markers exist) 1. Find content between `<!-- ELIXIR-PHOENIX-PLUGIN:START -->` and `<!-- ELIXIR-PHOENIX-PLUGIN:END -->` 2. Replace with latest behavioral instructions 3. Preserve everything outside the markers In both modes, CLAUDE.md content outside the plugin markers — user-written rules, project conventions, other plugin sections — stays verbatim (Iron Law 1) ### Step 4: Generate Content Write the following structure to CLAUDE.md: ```markdown <!-- ELIXIR-PHOENIX-PLUGIN:START --> <!-- Last updated: {date} | Plugin version: 1.0 | Stack: Phoenix {version}, Ecto {version}, {optional: Oban, Tidewave} --> # Elixir/Phoenix Plugin - Auto-Activation Rules {Include all sections from the Content Template below, filtered by detected stack} <!-- ELIXIR-PHOENIX-PLUGIN:END --> ``` ### Step 4b: Offer Codex Review Guidelines (optional) If `command -v codex` succeeds (or the user asks): offer to install a managed `## Review guidelines` block into the project's `AGENTS.md` — honored by BOTH `codex exec review` locally and the Codex cloud PR reviewer. Follow the install rules and exact block in `references/codex-review-guidelines.md`: markers `ELIXIR-PHOENIX-REVIEW-GUIDELINES:START/END`, upsert in place on `--update`, never touch content outside markers, and STOP to ask if an unmanaged `## Review guidelines` section already exists. When codex is absent and not requested, skip silently — never mention codex to users who don't have it. ### Step 5: Output Summary ``` ✅ Elixir/Phoenix plugin initialized Detected stack: - Phoenix {version} - Ecto {version} - {Oban standard | Oban Pro | not detected} - {Tidewave ✓ | Tidewave not detected} - {Ash Framework detected - Ecto patterns disabled | not detected} Added to CLAUDE.md: - Auto-activation rules (complexity detection, interview mode) - Agent trigger patterns ({n} agents available) - Reference auto-loading ({n} reference docs) - Iron Laws enforcement ({n} laws) - Verification rules {- Codex review guidelines → AGENTS.md (only if installed in Step 4b)} Run phx-init --update after plugin updates. Run phx-audit for a full project health check. ``` ## Content Template The exact content to inject is in `references/injectable-template.md`. **Key structure:** 1. **Routing table** — which `phx-*` command fits which kind of request 2. **Iron Laws** — STOP behavior on violations 3. **Conditional Sections** — Include based on detected stack: - `{OBAN_SECTION}` — If Oban detected (not Pro) - `{OBAN_PRO_SECTION}` — If Oban Pro detected - `{ASH_SECTION}` — If Ash Framework detected - `{TIDEWAVE_SECTION}` — If Tidewave detected 4. **Verification** — Mandatory after code changes 5. **Quick Reference** — Skill routing table **Placeholder substitution:** | Placeholder | Source | |-------------|--------| | `{DATE}` | Current date | | `{PHOENIX_VERSION}` | From mix.exs | | `{ECTO_VERSION}` | From mix.exs | | `{OPTIONAL_STACK}` | Detected optional deps | See `references/injectable-template.md` for full template with all placeholders and conditional sections. ## Validation After running `phx-init`: 1. Check CLAUDE.md contains markers 2. Verify detected stack matches actual project 3. New session should: - Auto-detect complexity when given tasks - Stop on Iron Law violations - Offer relevant workflows based on task ## Error Handling | Scenario | Action | |----------|--------| | CLAUDE.md read-only | Error: "Cannot modify CLAUDE.md - check permissions" | | Markers corrupted | Warn, offer to remove and reinstall | | Unknown Phoenix version | Use conservative defaults (all features enabled) | | Not an Elixir project | Error: "No mix.exs found - is this an Elixir project?" | ## Relationship to Other Commands | Command | When to Use | |---------|-------------| | `phx-init` | First time, or after plugin updates | | `phx-audit` | Periodic project health check | | `phx-verify` | After code changes |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.