Add Claude Code plugin marketplace with skills and documentation

.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "naymspace-backpex",
+  "owner": {
+    "name": "Naymspace"
+  },
+  "metadata": {
+    "description": "Official Backpex plugin for Claude Code"
+  },
+  "plugins": [
+    {
+      "name": "backpex",
+      "source": "./",
+      "description": "Skills and agents for building with Backpex — the Phoenix LiveView admin panel",
+      "version": "0.1.0",
+      "homepage": "https://github.com/naymspace/backpex",
+      "keywords": ["elixir", "phoenix", "liveview", "admin", "backpex"]
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "backpex",
+  "description": "Skills and agents for building with Backpex",
+  "version": "0.1.0",
+  "author": {
+    "name": "Naymspace"
+  }
+}

guides/ai_development/ai-development.md

@@ -0,0 +1,78 @@
+# Claude Code Plugin
+
+Backpex ships with a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin that gives AI assistants deep knowledge of Backpex conventions, APIs, and patterns. This means Claude can generate correct Backpex code (filters, fields, actions, and LiveResources) without you having to explain the framework from scratch.
+
+## Install the Backpex Plugin
+
+The plugin is distributed as a Claude Code marketplace directly from the Backpex repository.
+
+### Add the Marketplace
+
+Open Claude Code and run:
+
+```bash
+/plugin marketplace add naymspace/backpex
+```
+
+This registers the Backpex marketplace so you can browse and install plugins from it.
+
+### Install the Plugin
+
+```bash
+/plugin install backpex@naymspace-backpex
+```
+
+After installation, run `/reload-plugins` to activate the plugin.
+
+## What the Plugin Provides
+
+The Backpex plugin includes skills, specialized knowledge modules that Claude uses automatically when working on Backpex projects.
+
+### Create Live Resource
+
+The `create-live-resource` skill helps scaffold complete LiveResource modules. It covers `adapter_config`, required callbacks (`singular_name/0`, `plural_name/0`, `fields/0`, `layout/1`), optional callbacks like `can?/3` and `filters/0`, and router setup with `live_resources/3`.
+
+Example: "Create a LiveResource for my Product schema with name, price, and category fields"
+
+### Create Field
+
+The `create-field` skill covers all 17 built-in field types and how to create custom fields implementing `Backpex.Field`. It includes the config schema, required callbacks (`render_value/1`, `render_form/1`), common field options, and template assigns.
+
+Example: "Add a color picker field to my ProductLive resource"
+
+### Create Filter
+
+The `create-filter` skill covers all built-in filter types (Boolean, Select, MultiSelect, Range) and custom filters. It includes required callbacks, how to wire filters into `filters/0`, and options like presets and defaults.
+
+Example: "Add a published filter to PostLive"
+
+### Create Item Action
+
+The `create-item-action` skill helps create custom actions for table rows and the show page. It covers the `handle/3` vs `link/2` pattern, form fields with confirmation dialogs, and how to modify the default actions (show, edit, delete).
+
+Example: "Add an archive action that soft-deletes selected posts"
+
+### Create Resource Action
+
+The `create-resource-action` skill helps create resource-level actions like exports, imports, or invitations. It covers the required callbacks (`title/0`, `label/0`, `fields/0`, `changeset/3`, `handle/2`) and schemaless changeset patterns.
+
+Example: "Create an export action that lets users download posts as CSV"
+
+### Upgrade
+
+The `upgrade` skill assists with Backpex version upgrades. It reads the relevant upgrade guides, identifies breaking changes, and applies migrations systematically.
+
+Example: "Upgrade Backpex from 0.16 to 0.18"
+
+## Invoking Skills
+
+All skills are triggered automatically by Claude when it detects relevant work. You can also invoke them directly:
+
+```bash
+/backpex:create-live-resource
+/backpex:create-field
+/backpex:create-filter
+/backpex:create-item-action
+/backpex:create-resource-action
+/backpex:upgrade
+```

mix.exs

@@ -142,6 +142,9 @@ defmodule Backpex.MixProject do
       # Get Started
       "guides/get_started/installation.md",
 
+      # AI Assisted Development
+      "guides/ai_development/ai-development.md",
+
       # Live Resource
       "guides/live_resource/what-is-a-live-resource.md",
       "guides/live_resource/templates.md",
@@ -218,6 +221,7 @@ defmodule Backpex.MixProject do
       Introduction: ~r/README/,
       About: ~r/guides\/about\/.?/,
       "Get Started": ~r/guides\/get_started\/.?/,
+      "AI Assisted Development": ~r/guides\/ai_development\/.?/,
       "Live Resource": ~r/guides\/live_resource\/.?/,
       Fields: ~r/guides\/fields\/.?/,
       Filter: ~r/guides\/filter\/.?/,

skills/create-field/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: create-field
+description: Use when creating custom Backpex field types, implementing the Backpex.Field behaviour, or adding fields to a LiveResource's fields/0 callback.
+---
+
+# Creating Backpex Fields
+
+You are an expert at creating fields for Backpex, a Phoenix LiveView admin panel library. When the user wants to add or create a field, follow this process:
+
+1. **Determine if a built-in field works** from the list below
+2. **If custom**, generate a module implementing `Backpex.Field`
+3. **Wire it into the LiveResource** by updating the `fields/0` callback
+
+## Built-in Field Modules
+
+| Module | Use for |
+|--------|---------|
+| `Backpex.Fields.Text` | Single-line text inputs |
+| `Backpex.Fields.Textarea` | Multi-line text inputs |
+| `Backpex.Fields.Number` | Numeric values |
+| `Backpex.Fields.Boolean` | Checkboxes / toggles |
+| `Backpex.Fields.Select` | Dropdown with static options |
+| `Backpex.Fields.MultiSelect` | Multi-value dropdown |
+| `Backpex.Fields.Date` | Date picker |
+| `Backpex.Fields.DateTime` | Date and time picker |
+| `Backpex.Fields.Time` | Time picker |
+| `Backpex.Fields.Currency` | Formatted currency values |
+| `Backpex.Fields.URL` | URLs with link rendering |
+| `Backpex.Fields.Email` | Email addresses |
+| `Backpex.Fields.BelongsTo` | belongs_to associations |
+| `Backpex.Fields.HasMany` | has_many associations |
+| `Backpex.Fields.HasManyThrough` | has_many through associations |
+| `Backpex.Fields.InlineCRUD` | Inline editing of embeds_many / has_many |
+| `Backpex.Fields.Upload` | File uploads |
+
+## Common Field Options (available on all fields)
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `module` | atom | **Required.** The field module |
+| `label` | string | **Required.** Display label |
+| `searchable` | boolean | Enable search on this column |
+| `orderable` | boolean | Enable column sorting |
+| `visible` | `fn assigns -> bool` | Controls visibility on all views except index |
+| `can?` | `fn assigns -> bool` | Controls visibility on all views including index |
+| `only` | list | Restrict to specific views: `:new`, `:edit`, `:show`, `:index` |
+| `except` | list | Hide from specific views |
+| `panel` | atom | Group into a named panel |
+| `index_editable` | boolean or `fn assigns -> bool` | Enable inline editing on index |
+| `align` | `:left`, `:center`, `:right` | Column alignment on index |
+| `align_label` | `:top`, `:center`, `:bottom`, or `fn assigns -> atom` | Label alignment in forms |
+| `index_column_class` | string or `fn assigns -> string` | Extra CSS class on index column |
+| `render` | `fn assigns -> HEEx` | Override value rendering |
+| `render_form` | `fn assigns -> HEEx` | Override form rendering |
+| `help_text` | string or `fn assigns -> string` | Text below form input |
+| `default` | `fn assigns -> value` | Default value for new items |
+| `select` | `dynamic(...)` | Ecto dynamic expression for computed/virtual fields |
+| `custom_alias` | atom | Custom alias for the field in queries |
+| `translate_error` | `fn {msg, meta} -> {msg, meta}` | Custom error message formatting |
+
+## Creating a Custom Field
+
+Implement `Backpex.Field` with a `@config_schema` for field-specific options.
+
+### Required Callbacks
+
+```elixir
+@callback render_value(assigns :: map()) :: %Phoenix.LiveView.Rendered{}
+@callback render_form(assigns :: map()) :: %Phoenix.LiveView.Rendered{}
+```
+
+`render_value/1` is used on both index and show views. `render_form/1` is used on new and edit views.
+
+### Callbacks With Defaults (overridable)
+
+These are provided by `use Backpex.Field` and can be overridden as needed:
+
+```elixir
+@callback render_index_form(assigns)  # For index_editable support (only truly optional callback)
+@callback display_field(field)         # Default: returns field name
+@callback schema(field, schema)        # Default: returns the schema
+@callback association?(field)          # Default: false
+@callback assign_uploads(field, socket) # Default: returns socket unchanged
+@callback before_changeset(changeset, attrs, metadata, repo, field, assigns) # 6-arity
+@callback search_condition(schema_name :: binary(), field_name :: binary(), search_string :: binary()) # Default: ilike
+```
+
+### Key Assigns Available in Templates
+
+| Assign | Description |
+|--------|-------------|
+| `@value` | Current field value |
+| `@name` | Field key atom |
+| `@field_options` | Merged field options map |
+| `@form` | Phoenix.HTML.Form (in form renders) |
+| `@item` | The full resource item struct |
+| `@live_action` | `:index`, `:edit`, `:new`, or `:show` |
+| `@readonly` | Boolean from readonly option |
+| `@myself` | LiveComponent reference for phx-target |
+
+### Example Custom Field
+
+```elixir
+defmodule MyAppWeb.Fields.ColorPicker do
+  @config_schema [
+    palette: [
+      doc: "List of allowed hex colors.",
+      type: {:list, :string}
+    ]
+  ]
+
+  use Backpex.Field, config_schema: @config_schema
+
+  @impl Backpex.Field
+  def render_value(assigns) do
+    ~H"""
+    <div class="flex items-center gap-2">
+      <span class="inline-block h-4 w-4 rounded-full" style={"background-color: #{@value}"}></span>
+      <span>{@value}</span>
+    </div>
+    """
+  end
+
+  @impl Backpex.Field
+  def render_form(assigns) do
+    ~H"""
+    <div>
+      <Layout.field_container>
+        <:label align={Backpex.Field.align_label(@field_options, assigns, :center)}>
+          <Layout.input_label for={@form[@name]} text={@field_options[:label]} />
+        </:label>
+        <BackpexForm.input
+          type="color"
+          field={@form[@name]}
+          translate_error_fun={Backpex.Field.translate_error_fun(@field_options, assigns)}
+          help_text={Backpex.Field.help_text(@field_options, assigns)}
+          phx-debounce={Backpex.Field.debounce(@field_options, assigns)}
+        />
+      </Layout.field_container>
+    </div>
+    """
+  end
+end
+```
+
+### Using it in a LiveResource
+
+```elixir
+@impl Backpex.LiveResource
+def fields do
+  [
+    color: %{
+      module: MyAppWeb.Fields.ColorPicker,
+      label: "Color",
+      palette: ["#ff0000", "#00ff00", "#0000ff"]
+    }
+  ]
+end
+```
+
+## Declaring Fields in a LiveResource
+
+`fields/0` returns a keyword list. Each key is the Ecto schema field atom, each value is a map of options.
+
+```elixir
+@impl Backpex.LiveResource
+def fields do
+  [
+    title: %{
+      module: Backpex.Fields.Text,
+      label: "Title",
+      searchable: true
+    },
+    body: %{
+      module: Backpex.Fields.Textarea,
+      label: "Body",
+      except: [:index]
+    },
+    category: %{
+      module: Backpex.Fields.BelongsTo,
+      label: "Category",
+      display_field: :name,
+      searchable: true,
+      live_resource: MyAppWeb.CategoryLive
+    },
+    inserted_at: %{
+      module: Backpex.Fields.DateTime,
+      label: "Created At",
+      only: [:index, :show]
+    }
+  ]
+end
+```
+
+## Conventions
+
+- **File location**: `lib/my_app_web/fields/<snake_case_name>.ex`
+- **Module naming**: `MyAppWeb.Fields.<FieldName>`
+- **Always declare `@config_schema`** before `use Backpex.Field` for custom field-specific options
+- **Use `Layout.field_container`** and `Layout.input_label`  in `render_form/1` for consistent form layout
+- **Use `BackpexForm.input`** for standard input rendering with error handling