Standards-based AI rules for Elixir/BEAM development

ai-rules is a reusable operating layer for AI-assisted Elixir/BEAM development. It gives coding agents a subscription-free, tool-agnostic set of rules, roles, skills, patterns, templates, and workflow configs so they can plan, build, and review projects consistently across OpenCode, Claude, Cursor, and local or MCP-based tooling.

This project is provided as-is and without any warranty. The authors are not responsible for any damages or losses resulting from the use of this project. This repository has evolved through several iterations across multiple models and tools. Some documents may still reflect older assumptions and are being consolidated toward the positioning described above.

Create a subscription-free, standards-based starting point for Elixir/BEAM projects that works with:

• OpenCode (primary tool) - Multi-session agentic development
• Compatible tools (Claude Code, Cursor)
• Local LLMs (Ollama, LM Studio, MLX for Apple Silicon)
• MCP support (Serena)

Key Principles:

• Tool-agnostic: Guidelines work across OpenCode, Claude, Cursor
• Subscription-free: All tools (mgrep, Serena) are open-source and free
• Multi-session: Separate plan, build, and review workflows
• Flexible LLMs: Support for local + API providers
• Elixir/BEAM focused: OTP patterns, Domain Resource Action, TDD

.
├── ai-rules/               # This repo (symlink in generated projects)
├── .opencode/              # Plan/Build/Review configs
├── config/                 # Environment config only (no business logic)
├── lib/
│   ├── [app]/              # Elixir runtime entry + supervision
│   │   ├── application.ex  # Top-level supervisor
│   │   ├── registry/       # Registry + DynamicSupervisor
│   │   └── support/        # Pure helpers (no IO/side effects)
│   └── [app]_ash/          # Ash Domain Resource Action (Elixir‑Scribe style)
│       ├── domains/        # Domain boundaries
│       │   └── accounts/
│       │       ├── resources/      # Ash Resources (schema + validations)
│       │       ├── actions/        # Ash Actions (single responsibility)
│       │       ├── policies/       # Authorization per resource
│       │       └── notifiers/      # Side-effect handlers (email, pubsub)
│       └── apis/            # Ash APIs that expose resources per domain
├── lib/[app]_web/          # Phoenix LiveView (thin controllers, state in Ash)
│   ├── endpoint.ex
│   ├── router.ex
│   ├── live/               # LiveViews / components
│   └── controllers/        # Minimal glue, delegate to Ash actions
├── priv/repo/              # Migrations & seeds
├── test/                   # Mirrors lib/ for easy grep & coverage
│   ├── support/            # DataCase/ConnCase factories
│   ├── ash/                # Resource/action tests (unit, property-based)
│   └── web/                # LiveView/Controller integration tests
├── flake.nix               # Nix devshell (phoenix_ash/universal/nerves)
└── project_requirements.md # Project + model/tool choices

Why this layout?

• Single Responsibility: Ash resources/actions/policies separated; controllers stay thin.
• Searchable: Domains/resources/actions live under predictable paths for mgrep/rg.
• Testable: test/ mirrors lib/ so coverage tools and agents find pairs quickly.

• BEAMAI (roles/beamai.md): Senior BEAM/Phoenix/Ash/Nerves/Nix expert with concise professional tone; use as default voice unless overridden by a role.

• See docs/quickstart-agents.md for mode commands, directory map, and preflight checks.

# Clone or symlink ai-rules into your project
cd my_new_project
ln -s ~/path/to/ai-rules ai-rules

# Initialize project
bash ai-rules/scripts/init_project.sh my_app

# Start plan session (Terminal 1)
opencode --config .opencode/opencode.plan.json

# Start build session (Terminal 2)
opencode --config .opencode/opencode.build.json

• Multi-Session: Plan, build, review workflows
• MCP Support: Serena MCP integration
• mgrep Integration: Native semantic search
• Local LLMs: Ollama, LM Studio, MLX for Apple Silicon

• Claude: Full agent, skills, commands support
• Cursor: .cursorrules-based prompting

• Arcana (optional): Local document retrieval sidecar for all agents (not OpenCode-only)
• Setup/search scripts: scripts/arcana_setup.sh, scripts/arcana_ingest_ai_rules_docs.sh, scripts/arcana_search_ai_rules_docs.sh
• Guide: docs/arcana-sidecar.md

Optional Claude bridge (opt-in)

• See tools/claude/ for hooks/skills/templates tuned for Claude Code/Desktop.
• User-copyable versions live in templates/claude/; nothing is auto-enabled for OpenCode.

Reference snippets

• Elixir idioms and small code examples: /Users/elay14/projects/2026/ai-rules/elixir_examples.md

• OTP Patterns: GenServer, Supervisor, Application, Registry
• Domain Resource Action: Organizes business logic into domains, resources, and actions
• TDD Workflow: Red-Green-Refactor cycle
• Code Quality: Credo, Dialyzer, formatting, type specs

This project follows a strict Git workflow defined in git_rules.md:

• Feature branch development: Create branches for all changes
• Pull requests for code review: Use PRs for review before merging
• Conventional commit messages: Standardized commit format
• Squash merging: Clean history on main branch

• Git Specialist Role (roles/git-specialist.md): Git and GitHub workflow expert
• Git Workflow Skill (skills/git-workflow/SKILL.md): Git automation and best practices

# Create feature branch
git checkout -b feature/add-git-workflow

# Commit with conventional format
git add .
git commit -m "feat: add git workflow integration"

# Push and create PR
git push -u origin feature/add-git-workflow
gh pr create --title "Add git workflow" --body "Description..."

# Merge with squash
gh pr merge --squash

# Cleanup branches
git checkout main
git pull origin main
git branch -d feature/add-git-workflow

• ai-rules: https://github.com/layeddie/ai-rules
• tensioner: https://github.com/layeddie/tensioner

For detailed Git workflow rules, see git_rules.md.

• Base config: tools/opencode/opencode.json
• Mode-specific: Plan, build, review configs
• MCP config: tools/opencode/opencode_mcp.json (Serena)

Compatible

• Structure: .claude/ folder
• Agents: Role-based agents
• Commands: Slash commands (/create-feature, /full-test)
• Skills: Technical skills

• Rules file: tools/cursor/.cursorrules with agent prompts

• Flake template: tools/nixos/flakes/universal.nix
• Integration: MLX GPU support for M2 Max

• Architect - System design, OTP supervision trees, domain boundaries
• Orchestrator - Implementation coordination, TDD workflow

• Backend Specialist - API design, business logic, Ash resources
• Frontend Specialist - LiveView UI, real-time features
• Database Architect - Ecto schemas, query optimization, N+1 prevention

• QA - Testing strategy, coverage analysis, property-based testing
• Reviewer - Code review, OTP best practices verification

• GenServer patterns - Client/server separation, named processes
• Supervisor strategies - One-for-one, one-for-all, dynamic
• Registry usage - Dynamic process naming and discovery

• N+1 prevention - Preloading strategies, missing indexes, query optimization

• TDD workflow - ExUnit, property-based testing (StreamData, PropCheck)

• Complete Phoenix web application
• Ash framework for domain modeling
• LiveView for real-time UI
• User authentication with Ash
• JSON API via Ash JSON API
• Real-time features via Phoenix PubSub

• Basic Phoenix app
• Simple router and controller structure

• OTP library with public API
• Clean module organization

• Embedded Elixir for IoT devices
• Hardware-specific configurations

• Purpose: Initialize new Elixir project with AI rules
• Functionality: Creates directory structure, symlinks ai-rules, creates configs, generates .gitignore

• Purpose: Setup OpenCode environment
• Installs mgrep, uv, Serena MCP
• Functionality: Validates all tools are available

• Purpose: Validates project setup and requirements
• Functionality: Checks LLM config, Nix setup, dependencies, and OpenCode configs

• Purpose: Starter brief for defining project goals, constraints, tool choices, architecture, and quality bar
• Sections: Project overview, technical stack, LLM/provider strategy, tool config, architecture, testing strategy

• Purpose: MCP server configuration for ai-rules workflows

• Purpose: MLX GPU optimization for Apple Silicon M2 Max
• Hardware: 64GB RAM, 50GB VRAM, up to 5 GPUs

• Supervision trees with clear hierarchies
• Domain Resource Action pattern for business logic
• TDD workflow (Red, Green, Refactor)
• Code quality (Credo, Dialyzer, formatting)

• Blocking GenServer callbacks, mixing concerns, ignoring supervision strategies

All tools (mgrep, Serena) are open-source and free.

• No subscription required to use ai-rules.
• Local LLM providers (Ollama, LM Studio, MLX) are free.
• API providers are optional and user-chosen.

• Project initialization
• Tool-specific configurations
• Role definitions
• Technical skills
• Project templates
• Multi-session workflow
• Hardware optimization

Use: ai-rules as subscription-free starting point for:

• Standardized project structure
• Multi-session development workflow
• Comprehensive agent guidelines
• Tool integration (mgrep + Serena)
• Flexible LLM support (local + API)
• Elixir/BEAM best practices

Perfect for: full-stack web applications, libraries, and embedded systems.

This repository includes ideas, patterns, and adaptation work informed by public Elixir/AI projects and docs.

• claude-code-elixir (George Guimarães): https://github.com/georgeguimaraes/claude-code-elixir
• sagents (Mark Ericksen): https://github.com/sagents-ai/sagents
• usage_rules (Ash Project): https://github.com/ash-project/usage_rules
• AgentJido ecosystem: https://github.com/agentjido

Where content is inspired or adapted, this repo prefers paraphrased integration over verbatim copying and follows upstream license terms (for example, Apache-2.0/MIT where applicable).

For local research/source inventory, see:

• /Users/elay14/projects/2026/elixir-ai/Elixir-AI-Development-Environment-Outline.md