Ash Kindle

Use mix.exs, config/config.exs, and the project file structure to answer these.

If no project exists yet

If the directory has no mix.exs, offer to create a new Phoenix project:

1. Install the Phoenix generator: mix archive.install hex phx_new --force
2. Create the project: yes | mix phx.new . --app <app_name>
   • The yes | prefix is needed to auto-confirm the existing directory prompt
3. Ask about structure (single app recommended — can migrate to umbrella later)
4. Then proceed with the rest of the setup

Step 2: Ask or Accept Defaults

Present the user with what you'll set up:

I'll configure the following AI dev tooling for your Ash/Phoenix project:

1. usage_rules — CLAUDE.md generation + doc search from deps
2. Tidewave — dev MCP server for runtime introspection (eval, logs, schemas)
3. Domain MCP — dev-only MCP server exposing your Ash domain tools (requires Ash domains with resources)
4. Ash AI — usage rules and MCP tooling for Ash resources
5. CLAUDE.md — project instructions (Ash First, MCP Usage, Feedback Loop, Logging)
6. Claude Code skills — auto-generated from usage_rules config
7. logging-best-practices — external skill for wide events pattern
8. Browser testing — optional GIF-recorded browser walkthrough skill (requires Claude-in-Chrome)
9. Dev environment — optional setup for devenv, flake, or devbox with PostgreSQL

Want to customize any of these, or are defaults fine?

If the user says defaults are fine, proceed with all defaults from defaults.md. Default for Domain MCP: yes if Ash domains with resources are detected, no otherwise. Default for Browser testing: no (opt-in only). Default for Dev environment: skip if no config file detected, otherwise default to detected tool.

If the user wants to customize, ask about each piece one at a time:

• Which usage_rules to include (:elixir, :otp, :phoenix, others?)
• Which skills to build (default: ash-framework; suggest others based on detected deps)
• Whether to set up domain MCP (and which domain to wire first)
• Whether to set up browser testing
• Which dev environment tool to use (devenv, flake, or devbox)
• Any additional CLAUDE.md sections

Step 3: Install Dependencies

Known issue: plug dependency conflict

When tidewave (only: :dev) and ash_ai (which brings in ash_json_api) are both present, there is a :only env conflict on the plug dependency. You must add an explicit plug dependency to resolve this:

{:plug, "~> 1.19"}

For umbrella projects (root mix.exs):

# Add to deps in root mix.exs
{:plug, "~> 1.19"},
{:usage_rules, "~> 1.2", only: :dev, runtime: false}

Note: The plug dep may not be needed in umbrella projects if tidewave and ash_ai live in separate child apps. Only add it if mix deps.get reports an :only option conflict on plug.

For the web app (or single app) mix.exs:

# Add to deps
{:tidewave, "~> 0.5", only: :dev}

For the core app (or single app) mix.exs:

# Add to deps
{:ash_ai, "~> 0.5"}

For single app projects, all deps in one mix.exs:

{:plug, "~> 1.19"},
{:ash, "~> 3.0"},
{:ash_phoenix, "~> 2.0"},
{:ash_postgres, "~> 2.0"},
{:ash_ai, "~> 0.5"},
{:usage_rules, "~> 1.2", only: :dev, runtime: false},
{:tidewave, "~> 0.5", only: :dev}

Then run:

mix deps.get

Step 4: Configure usage_rules

Add the usage_rules() function and reference it in the project config. See defaults.md for the default configuration. Adapt based on:

• Umbrella vs single app: In umbrella, usage_rules goes in root mix.exs
• Detected deps: If Oban, Req, LangChain etc. are present, suggest additional skill builds
• Skills location: Always .claude/skills

In the project/0 function, add:

# listeners required for usage_rules to auto-regenerate on code changes