Rails-AI requires the Superpowers plugin to function.

Before starting ANY work, verify Superpowers is installed by attempting to use a Superpowers skill. If you see an error like "skill not found" or "plugin not available":

⚠️ WARNING: Superpowers plugin not installed!

Rails-AI cannot function without Superpowers. Please install it:

/plugin marketplace add obra/superpowers
/plugin install superpowers

Then restart Claude Code.

Why this matters: Rails-AI provides WHAT to build (Rails domain knowledge). Superpowers provides HOW to build it (TDD, debugging, planning, code review). Without Superpowers, you cannot follow the mandatory workflows.

If Superpowers is installed, proceed normally.

MANDATORY: Use Superpowers Foundation First

Rails-AI builds on Superpowers. You MUST use the foundation before doing ANY work.

FIRST ACTION when starting any Rails work:

1. Use superpowers:using-superpowers skill (Skill tool)
2. This establishes mandatory skill-usage protocol
3. Then use relevant rails-ai domain skills (see table below)

Why use superpowers:using-superpowers?

• Enforces checking for skills BEFORE any task
• Establishes discipline of using skills with Skill tool
• Prevents rationalizing away skill usage
• Provides proven workflow framework

Without using superpowers:using-superpowers first:

• You will skip using skills when you should
• You will rationalize that tasks are "too simple" for skills
• You will operate without the proven process framework

Rails-AI Skill-to-Task Mapping

Superpowers handles skill-usage enforcement. This table tells you WHICH Rails skills to use:

Each Rails-AI skill contains:

• Required gems and dependencies
• TEAM_RULES.md enforcement for that domain
• Rails 8+ patterns and conventions
• Security requirements
• Code examples and anti-patterns

Planning Rails Features

CRITICAL: Load domain skills BEFORE brainstorming or planning.

You can't give expert advice on Rails features if you haven't loaded the relevant domain knowledge. The brainstorming skill is process-agnostic — it doesn't know Rails patterns, TEAM_RULES, or which gems to use. You need to load that context first.

Planning workflow:

1. Load relevant rails-ai domain skills (see table below)
2. Read the codebase to understand what exists
3. THEN use superpowers:brainstorming to refine the idea
4. THEN use superpowers:writing-plans to create implementation plan

Which skills to load for common features:

Always include rails-ai:testing — TDD is non-negotiable (TEAM_RULES #4).

Why this order matters:

• Domain skills give you Rails patterns and constraints
• Reading code shows you what's already there
• Brainstorming with this context produces better designs
• Plans written with domain knowledge specify the right skills for workers

Superpowers Reference

Superpowers provides universal workflows. Here's when to use each in Rails development:

Planning & Design

Implementation

Quality & Review

Debugging & Testing

Defense & Security

Agents

Commands (Shortcuts)

Rails-specific usage:

• Always load rails-ai domain skills BEFORE superpowers workflows
• rails-ai:debugging wraps superpowers:systematic-debugging with Rails context
• rails-ai:testing enforces TDD via superpowers:test-driven-development

How Rails-AI Works

Rails-AI is a two-layer system built on Superpowers:

┌─────────────────────────────────────────────┐
│ LAYER 1: Superpowers (Universal Process)   │
│ • brainstorming - Refine ideas              │
│ • writing-plans - Create plans              │
│ • test-driven-development - TDD cycle       │
│ • systematic-debugging - Investigation      │
│ • subagent-driven-development - Execution   │
│ • dispatching-parallel-agents - Coordination│
│ • requesting-code-review - Quality gates    │
│ • finishing-a-development-branch - Complete │
│ • receiving-code-review - Handle feedback   │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ LAYER 2: Rails-AI (Domain Expertise)       │
│ • 12 Rails domain skills                   │
│ • TEAM_RULES.md enforcement                 │
│ • Rails 8+ patterns and conventions         │
└─────────────────────────────────────────────┘

Key Principle:

• Superpowers = HOW to work (process framework)
• Rails-AI = WHAT you're building (domain knowledge)
• The architect loads both as needed

Architecture Evolution

Previous architecture (complex):

• 5 agents (architect, developer, security, devops, uat)
• Ambiguous delegation chains
• Overlap between agent roles and workflows

Current architecture (simple):

• 1 slash command (/rails-ai:architect) - coordinator
• Superpowers workflows handle process (HOW)
• Rails-AI skills provide domain expertise (WHAT)
• General-purpose workers implement features
• Clean separation of concerns

How It Works

User request → /rails-ai:architect → Uses skills → Dispatches workers → Reviews

Example: "Add user authentication"

1. Coordinator uses superpowers:brainstorming

   • Uses rails-ai:models + rails-ai:security for context
   • Refines design with user

2. Coordinator uses superpowers:writing-plans

   • Creates implementation plan
   • Specifies which skills workers should use per task

3. Coordinator uses superpowers:subagent-driven-development

   • Dispatches general-purpose workers for each task: • Worker 1: User model → uses rails-ai:models + rails-ai:testing • Worker 2: Sessions controller → uses rails-ai:controllers + rails-ai:testing • Worker 3: Login views → uses rails-ai:views + rails-ai:styling
   • Reviews each worker's output

4. Coordinator uses superpowers:finishing-a-development-branch

   • Verifies TEAM_RULES.md compliance
   • Creates PR or merges

Result: Clean feature with tests, following all conventions

Available Rails-AI Skills

12 Domain-Based Skills (Consolidated):

1. rails-ai:views - Partials, helpers, forms, accessibility (WCAG 2.1 AA)
2. rails-ai:hotwire - Turbo Drive, Turbo Frames, Turbo Streams, Turbo Morph, Stimulus controllers
3. rails-ai:styling - Tailwind CSS utility-first framework, DaisyUI component library, theming
4. rails-ai:controllers - RESTful actions, nested resources, skinny controllers, concerns, strong parameters
5. rails-ai:models - ActiveRecord patterns, validations, associations, callbacks, query objects, form objects
6. rails-ai:testing - TDD with Minitest, fixtures, mocking, test helpers
7. rails-ai:security - XSS, SQL injection, CSRF, strong parameters, file uploads, command injection
8. rails-ai:project-setup - Environment config, credentials, initializers, Docker, RuboCop
9. rails-ai:jobs - SolidQueue, SolidCache, SolidCable background processing (TEAM RULE #1: NO Redis/Sidekiq)
10. rails-ai:mailers - ActionMailer email templates, delivery, attachments, testing with letter_opener
11. rails-ai:debugging - Rails debugging tools (logs, console, byebug) + superpowers:systematic-debugging
12. rails-ai:using-rails-ai - This guide - how rails-ai integrates with superpowers workflows

TEAM_RULES.md Enforcement

6 Critical Rules (REJECT violations):

1. ❌ NEVER Sidekiq/Redis → ✅ SolidQueue/SolidCache
2. ❌ NEVER RSpec → ✅ Minitest only
3. ❌ NEVER custom routes → ✅ RESTful resources
4. ❌ NEVER skip TDD → ✅ RED-GREEN-REFACTOR
5. ❌ NEVER merge without bin/ci → ✅ All quality gates pass
6. ❌ NEVER WebMock bypass → ✅ Mock all HTTP in tests

See rules/TEAM_RULES.md for all 20 rules.

Getting Started

Primary interface: /rails-ai:architect command

The simplest way to use Rails-AI is the /rails-ai:architect convenience command:

/rails-ai:architect add user authentication
/rails-ai:architect fix failing test in user_test.rb
/rails-ai:architect plan payment processing feature
/rails-ai:architect refactor UserController

This command acts as the Rails architect coordinator, which:

• Analyzes requests
• Uses superpowers workflows (for process)
• Uses rails-ai skills (for domain expertise)
• Dispatches general-purpose workers to implement features
• Reviews work and enforces TEAM_RULES.md

Example:

User: "/rails-ai:architect Add email validation to User model"

Architect (coordinator):
1. Determines this is model work requiring TDD
2. Loads superpowers:test-driven-development for process
3. Loads rails-ai:testing for Minitest patterns
4. Loads rails-ai:models for validation patterns
5. Dispatches general-purpose worker with those skills loaded
6. Worker follows TDD cycle: write test → RED → implement → GREEN → refactor
7. Reviews worker output and verifies TEAM_RULES.md compliance

Learn More

Superpowers skills: Use superpowers:using-superpowers for full introduction Rails-AI rules: See rules/TEAM_RULES.md