Claude Code Integration
Petal Pro v4 ships with first-class Claude Code support. Sub-agents, skills, recipes, and scoped CLAUDE.md files are all pre-configured — you get an AI-aware codebase out of the box.
Sub-Agents
Sub-agents are specialized Claude Code agents that automatically activate based on context. They live in .claude/agents/ and are invoked by Claude Code when relevant.
| Agent | Description |
|---|---|
schema-architect |
Designs database schemas following Petal Pro conventions (UUID v7 PKs, proper indexes, on_delete strategies) |
test-runner |
Runs tests, interprets failures, and suggests fixes |
elixir-reviewer |
Reviews Elixir code for correctness, conventions, and common pitfalls |
heex-reviewer |
Reviews HEEx templates for proper interpolation, component usage, and accessibility |
ui-ux-reviewer |
Reviews UI/UX for design quality, usability, and consistency with the app’s design system |
You don’t invoke these directly — Claude Code activates the appropriate agent automatically.
Skills
Skills are slash commands for scaffolding new code. They enforce project conventions so generated code is consistent with the rest of the codebase. Run them from Claude Code with an optional argument describing what you want.
Scaffolding
| Command | Description |
|---|---|
/new-liveview |
Scaffolds a new LiveView page — layout wrapping, imports, assign patterns, handle_params/handle_event structure |
/new-context |
Scaffolds a new Phoenix context module — CRUD patterns, filters, error handling, logging |
/new-email |
Creates a new transactional email template with inline styling and the deliver/render pipeline |
/new-oban-worker |
Scaffolds an Oban background worker — queue config, retry strategy, logging, error handling |
/schema-migration |
Guides schema and migration changes — UUID v7 PKs, indexes, Ecto schema patterns |
Feature Addition
| Command | Description |
|---|---|
/add-org-feature |
Scaffolds a new org-scoped resource end-to-end: schema with org_id, context, migration, LiveView pages, routes, GDPR updates |
/add-notification |
Adds a new notification type end-to-end: schema, context function, email template, component renderer |
/add-admin-page |
Scaffolds an admin section page with DataTable, Flop pagination, sorting, and filtering |
/add-api-endpoint |
Adds a new REST API endpoint with OpenAPI specs, bearer auth, JSON views, and tests |
/add-billing-feature |
Guides through billing additions: new plans, subscription gates, webhook handlers, Stripe calls |
/add-route |
Safely adds routes to the router — enforces live_session grouping, pipeline selection, scope conventions |
Utilities
| Command | Description |
|---|---|
/ci |
Simulates the full GitHub Actions CI pipeline locally and fixes failures |
/gdpr-compliance |
Ensures new user-associated schemas are included in data export and deletion workflows |
/liveview-js |
Guides use of Phoenix.LiveView.JS for client-side UI state (show/hide, toggles, tabs) instead of server round-trips |
Recipes
Recipes are slash commands for larger-scale customizations — removing features, switching architecture, adding integrations. See the Recipes page for the full list.
CLAUDE.md Files
The project ships with scoped CLAUDE.md files at multiple levels. Claude Code reads these automatically when working in each directory, giving it the right context without you having to explain it every time.
| File | Scope |
|---|---|
CLAUDE.md (root) |
Project overview, feature table, dev scripts, architectural patterns, config keys |
lib/CLAUDE.md |
Elixir conventions, Ecto guidelines, Mix guidelines |
lib/petal_pro/CLAUDE.md |
Business logic patterns, multi-tenancy, auth, billing, background jobs |
lib/petal_pro_web/CLAUDE.md |
Web layer conventions, LiveView patterns, layout system |
assets/CLAUDE.md |
JS/CSS conventions, Tailwind v4 setup, Alpine.js patterns |
test/CLAUDE.md |
Testing conventions, Mimic mocking, factory patterns |
How to Use
Installation
npm install -g @anthropic-ai/claude-codeStarting a session
cd your-petal-pro-project
claudeClaude Code picks up all the CLAUDE.md context files automatically.
Running a skill
Type the slash command with an optional description of what you want:
/new-liveview A settings page for managing notification preferences/add-org-feature Projects — users can create and manage projects within their orgRunning a recipe
/recipes:remove-billingUsing sub-agents
Sub-agents activate automatically — when you ask Claude Code to review a template it will invoke heex-reviewer, when you ask it to design a schema it will use schema-architect. You don’t need to call them explicitly.
Asking Claude Code to work on a task
The workflow commands handle the full development cycle:
/task:plan Add a feedback widget to the dashboard
This interviews you about the feature and generates a structured task file in .claude/tasks/. Then:
/task:do feedback_widgetThis implements it step by step, with the sub-agents reviewing as it goes. Then:
/ciThis runs the full CI pipeline locally (format, compile warnings, tests, credo, sobelow) and fixes what fails. When it is green:
/git:commit
This runs mix format and commits in logical chunks with conventional messages.