elixir-phoenix-init

Plugin Initialization

Install the Elixir/Phoenix plugin's behavioral instructions into the project's AGENTS.md.

Usage

`elixir-phoenix-init`           # First-time installation
`elixir-phoenix-init` --update  # Update existing installation with latest rules

Iron Laws

1. NEVER overwrite content outside plugin markers — User-written AGENTS.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 AGENTS.md

Check whether AGENTS.md exists, then search it for an existing ELIXIR-PHOENIX-PLUGIN:START marker.

Step 2: Detect Project Stack

Scan the project to customize the injected instructions:

Read mix.exs and 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: count lib/**/*.ex files

Step 3: Handle Installation Modes

Mode A: Fresh Install (no AGENTS.md or no markers)

1. Create/append to AGENTS.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

CRITICAL: NEVER overwrite or delete existing AGENTS.md content outside the plugin markers — user-written rules, project conventions, and other plugin sections must be preserved verbatim

Step 4: Generate Content

Write the following structure to AGENTS.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 -->