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