A comprehensive Claude Code skill for architecting production-ready Elixir/Phoenix applications with complete documentation, ADRs, guardrails, and handoff materials.
Elixir Architect is a Claude Code skill that acts as an expert system architect, creating comprehensive project documentation packages that enable Director and Implementor AI agents to successfully build complex Elixir/OTP systems following industry best practices.
This skill creates:
- ✅ Complete directory structure for multi-app projects
- ✅ Architecture documentation (8 comprehensive files)
- ✅ Architecture Decision Records (ADRs)
- ✅ AI collaboration guardrails (Director/Implementor roles)
- ✅ Handoff documentation with workflows
- ✅ Domain-specific adaptations (Financial, E-Commerce, SaaS)
Automatically launches Task agents to research:
- Domain-specific architecture patterns
- Ash Framework best practices
- Dave Thomas's path-based dependency approach
- OTP supervision tree patterns
- Superpowers framework for implementation planning
Generates 20+ documentation files including:
- Foundation: README.md, CLAUDE.md with AI context
- Architecture: 8 detailed architecture documents (~6,000 lines)
- Guardrails: NEVER_DO, ALWAYS_DO, role definitions, review checklist
- Decisions: ADRs with alternatives and trade-offs
- Handoff: Complete workflow for Director/Implementor collaboration
Special handling for:
- Financial Systems: Double-entry bookkeeping, money handling, audit trails
- E-Commerce: Order workflows, inventory, payment integration
- SaaS Platforms: Multi-tenancy, subscriptions, usage tracking
- Database as source of truth (no GenServers for entities)
- Functional core, imperative shell pattern
- Dave Thomas multi-app structure (path-based dependencies)
- Ash Framework for declarative domain modeling
- Oban for background job processing
- Optimistic locking for concurrency
# In Claude Code, run:
/plugin install github.com/maxim-ist/elixir-architectThe skill will be automatically available as elixir-architect.
# Clone the repository
git clone https://github.com/maxim-ist/elixir-architect.git
# Copy skill to Claude Code skills directory
mkdir -p ~/.claude/skills
cp -r elixir-architect/skills/elixir-architect ~/.claude/skills/To verify the skill is installed:
# In Claude Code
/skills listYou should see elixir-architect in the list.
# In Claude Code
/skills elixir-architectOr simply describe your need:
I need to architect a task management system using Elixir, Ash, and Oban with
complete documentation for Director and Implementor AI collaboration
Claude will automatically invoke the skill if appropriate.
The skill gathers requirements through these questions:
- Project Domain: What system are you building? (e.g., task management, e-commerce, SaaS)
- Tech Stack: Confirm Elixir + Ash + Oban + Phoenix + LiveView?
- Project Location: Where to create files? (provide absolute path)
- Structure Style: Dave Thomas path-based or umbrella app?
- Special Requirements: Multi-tenancy? Event sourcing? External integrations?
- Scale Targets: Expected load and performance requirements
- AI Collaboration: Using Director/Implementor workflow?
User: Create architecture docs for a task management system at /Users/me/projects/taskflow
Claude: [Invokes elixir-architect skill]
Skill: I'll help architect your task management system. Let me gather some details:
1. Confirm tech stack: Elixir 1.17+, Ash 3.0+, Oban 2.17+, Phoenix 1.7+?
2. Structure: Dave Thomas path-based dependencies?
3. Special requirements:
- Multi-tenancy (teams/organizations)?
- Real-time features (LiveView task boards)?
- Expected user volume and task creation rate?
4. Will you use Director/Implementor AI workflow?
[After answering questions, skill launches expert Task agents]
Skill: Researching task management patterns and state machines...
Analyzing Ash Framework resource patterns...
Studying Dave Thomas multi-app structure...
[Creates complete documentation package]
Skill: ✅ Project architecture complete!
Created 23 files at /Users/me/projects/taskflow:
- Foundation docs (README, CLAUDE.md)
- 5 guardrail documents
- 8 architecture documents
- 4 Architecture Decision Records
- Handoff documentation
Ready for Director AI to create first feature design!
The skill generates this structure at your specified location:
project_root/
├── README.md # Project overview
├── CLAUDE.md # Complete AI agent context
├── docs/
│ ├── HANDOFF.md # Director/Implementor workflow
│ ├── architecture/ # 8 comprehensive architecture docs
│ │ ├── 00_SYSTEM_OVERVIEW.md
│ │ ├── 01_DOMAIN_MODEL.md
│ │ ├── 02_DATA_LAYER.md
│ │ ├── 03_FUNCTIONAL_CORE.md
│ │ ├── 04_BOUNDARIES.md
│ │ ├── 05_LIFECYCLE.md
│ │ ├── 06_WORKERS.md
│ │ └── 07_INTEGRATION_PATTERNS.md
│ ├── design/ # Empty - Director fills during features
│ ├── plans/ # Empty - Director creates Superpowers plans
│ ├── api/ # Empty - Director documents APIs
│ ├── decisions/ # Architecture Decision Records
│ │ ├── ADR-001-framework-choice.md
│ │ ├── ADR-002-id-strategy.md
│ │ ├── ADR-003-process-architecture.md
│ │ └── [domain-specific ADRs]
│ └── guardrails/ # AI collaboration rules
│ ├── NEVER_DO.md # Critical prohibitions
│ ├── ALWAYS_DO.md # Mandatory practices
│ ├── DIRECTOR_ROLE.md # Architect AI role definition
│ ├── IMPLEMENTOR_ROLE.md # Coder AI role definition
│ └── CODE_REVIEW_CHECKLIST.md
10 critical prohibitions with code examples:
- Never use floats for money (use integer cents or Decimal)
- Never update balances without version check (optimistic locking)
- Never create GenServers for domain entities (database as source of truth)
- Never allow partial transaction commits (use Ecto.Multi)
- And 6 more with detailed rationale
22 mandatory practices across:
- Data integrity (transactions, events, audit trails)
- Testing (TDD, edge cases, property tests)
- Code quality (typespecs, documentation, formatting)
- Architecture (separation of concerns, async workers)
Each of the 8 architecture files includes:
- Complete explanations with context
- Concrete code examples (valid Elixir)
- ASCII diagrams where helpful
- Performance considerations
- Testing patterns
- Common mistakes and corrections
Each ADR documents:
- The decision made
- Context and rationale
- Alternatives considered with pros/cons
- Why alternatives were rejected
- Implementation guidelines with DO/DON'T examples
- Validation criteria
- Review schedule
Perfect for:
- Project management platforms
- Issue tracking systems
- Kanban/Scrum boards
- Team collaboration tools
- Workflow management
Special handling:
- State machine enforcement
- Priority calculations
- Dependency management
- Real-time updates (LiveView)
- Notification workflows
Perfect for:
- Double-entry ledgers
- Payment platforms
- Commission calculation systems
- Multi-currency accounts
- Audit trail requirements
Special handling:
- Money handling (never floats!)
- Balance integrity validation
- Two-phase transactions
- Optimistic locking patterns
Perfect for:
- Order management systems
- Inventory tracking
- Payment processing
- Shipping integration
- Customer accounts
Special handling:
- Order state machines
- Inventory reservation
- Payment gateway integration
- Refund workflows
Perfect for:
- Multi-tenant platforms
- Subscription billing
- Usage metering
- Feature management
- API platforms
Special handling:
- Tenant isolation strategies
- Row-level security
- Usage tracking patterns
- Plan limit enforcement
One of the unique features of this skill is creating documentation that enables a two-AI workflow:
- Creates feature designs
- Makes architectural decisions
- Writes implementation plans (Superpowers format)
- Reviews code against design
- Maintains architectural consistency
- Executes implementation plans
- Writes tests first (TDD)
- Implements features
- Reports progress and blockers
- Maintains code quality
- Director: Creates design + plan → commits
- Implementor: Executes plan (TDD) → commits
- Director: Reviews implementation → approves or requests changes
- Repeat: Until feature complete
The generated HANDOFF.md provides complete workflow documentation with message templates and communication protocols.
The skill enforces these proven principles:
- No GenServers for domain entities (Task, Project, User, etc.)
- State persists in PostgreSQL, not process memory
- Optimistic locking for concurrent updates
- Simple recovery: just query the database
- Pure business logic in
impl/layer (no side effects) - Side effects (DB, HTTP) in boundaries layer
- Easy to test, easy to reason about
- Clear separation of concerns
- Never block request path with external API calls
- Enqueue Oban jobs for notifications, webhooks, integrations
- Circuit breakers for failing services
- Idempotency keys for retry safety
- Supervision trees for fault tolerance
- GenServers for infrastructure (not entities)
- Processes isolated, failures contained
- Self-healing systems
- Write tests first (red → green → refactor)
- Unit tests for pure functions (impl/ layer)
- Integration tests for boundaries
- Property tests for invariants
The skill includes realistic performance targets in documentation:
- Task Queries: <50ms (p95), <100ms (p99)
- Task Updates: <200ms (p95), <500ms (p99)
- Throughput: 1,000+ operations/second sustained
- Test Coverage: >90% for core logic, >80% for boundaries
# ✅ ALWAYS validate transitions
def can_transition?(from_status, to_status) do
valid_transitions = %{
todo: [:in_progress, :blocked],
in_progress: [:blocked, :review, :done],
review: [:in_progress, :done]
}
to_status in Map.get(valid_transitions, from_status, [])
end# ✅ ALWAYS check version for concurrent updates
task
|> change(status: new_status)
|> optimistic_lock(:version)
|> Repo.update()# ✅ ALWAYS use Multi
Multi.new()
|> Multi.insert(:record, changeset)
|> Multi.run(:side_effect, fn _, %{record: r} -> side_effect(r) end)
|> Repo.transaction()See the examples directory for:
- Complete supervisor tree example
- GenServer infrastructure template
- Ash Resource with optimistic locking and state machines
- Oban worker with retries and notifications
- Property test for state transition validation
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-improvement) - Make your changes with tests
- Commit with clear messages (
git commit -m 'Add: improved ADR template') - Push to your fork (
git push origin feature/amazing-improvement) - Open a Pull Request
- Additional domain adaptations (Healthcare, Logistics, etc.)
- More code examples in the skill
- Integration with other Claude Code plugins
- Community-contributed architecture patterns
- Multi-language support (currently Elixir-focused)
- GraphQL API documentation templates
- LiveView component patterns
- Broadway event streaming examples
- Distributed system patterns (clustering, horde)
- Kubernetes deployment templates
- Observability and monitoring setup
- Load testing scripts and examples
- Migration from Rails/Django guides
- Multi-language support (Go, TypeScript)
- Event sourcing pattern library
- CQRS implementation templates
- Microservices architecture option
This skill works well with:
- test-driven-development - For TDD workflow
- code-review - For reviewing generated code
- git-workflow - For managing commits and branches
"The elixir-architect skill saved us weeks of architecture work. The generated documentation was so comprehensive that our team could start implementing immediately." - SaaS Startup CTO
"The Director/Implementor workflow with the guardrails made AI-assisted development actually work at scale. No more architectural drift." - Platform Engineering Lead
"Finally, architecture documentation that's actually maintained and useful! The ADRs with alternatives are gold." - Senior Elixir Engineer
A: Yes, just specify "umbrella app" when asked about structure style. The skill will adapt, though Dave Thomas path-based dependencies are recommended by default.
A: Absolutely! While financial systems get special handling (money, audit trails), the skill adapts to any domain: e-commerce, SaaS, messaging, IoT, etc.
A: No, it's optional. If you answer "no" to that question, the skill still creates complete architecture docs without the AI collaboration guardrails.
A: Yes! All documentation is Markdown, fully editable. Treat the generated files as a starting point and adapt to your needs.
A: The skill is optimized for Elixir + Ash + Oban + Phoenix but can adapt. Specify your preferences when asked, and the skill will adjust recommendations.
A: The skill sets review schedules (typically 6 months), but review ADRs whenever:
- Performance becomes a bottleneck
- Scale significantly changes
- New technologies emerge
- Team composition changes
MIT License - See LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: [Your contact email]
This skill incorporates wisdom and patterns from:
- Dave Thomas - Multi-app structure and path-based dependencies
- Saša Jurić - OTP patterns and "database as source of truth"
- José Valim - Elixir philosophy and GenStage patterns
- Zach Daniel - Ash Framework patterns and best practices
- Superpowers Framework - Implementation planning format
Current Version: 1.0.0
Release Date: 2024-01-11
Compatibility: Claude Code 1.0+
Built with ❤️ by the Elixir community
Creating production-ready architectures, one documentation package at a time.