using-rails-ai

What this skill does

# Using Rails-AI: Rails Domain Layer on Superpowers Workflows

<EXTREMELY-IMPORTANT>
## ⚠️ DEPENDENCY CHECK: Superpowers Required

**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:**

| User Request Involves | Use These Skills |
|----------------------|-------------------|
| Models, databases, ActiveRecord | rails-ai:models |
| Controllers, routes, REST | rails-ai:controllers |
| Views, templates, forms | rails-ai:views |
| Hotwire, Turbo, Stimulus | rails-ai:hotwire |
| CSS, Tailwind, DaisyUI | rails-ai:styling |
| Tests, TDD, Minitest | rails-ai:testing |
| Security, XSS, SQL injection | rails-ai:security |
| Background jobs, caching | rails-ai:jobs |
| Email, ActionMailer | rails-ai:mailers |
| Project setup, validation, gems | rails-ai:project-setup |
| Environment config, Docker | rails-ai:project-setup |
| Debugging Rails issues | rails-ai:debugging |

**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:**

| Feature Type | Load These Skills |
|--------------|-------------------|
| Authentication/Authorization | `rails-ai:security` + `rails-ai:models` + `rails-ai:controllers` |
| User-facing forms/pages | `rails-ai:views` + `rails-ai:hotwire` + `rails-ai:styling` |
| API endpoints | `rails-ai:controllers` + `rails-ai:security` |
| Background processing | `rails-ai:jobs` + `rails-ai:models` |
| Email features | `rails-ai:mailers` + `rails-ai:jobs` + `rails-ai:views` |
| Data modeling | `rails-ai:models` + `rails-ai:testing` |
| Interactive UI | `rails-ai:hotwire` + `rails-ai:views` + `rails-ai:controllers` |
| New project setup | `rails-ai:project-setup` |

**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
| Skill | When to Use |
|-------|-------------|
| `superpowers:brainstorming` | Refining feature ideas before implementation |
| `superpowers:writing-plans` | Creating detailed implementation plans with tasks |
| `superpowers:executing-plans` | Running through a plan in controlled batches |

### Implementation
| Skill | When to Use |
|-------|-------------|
| `superpowers:test-driven-development` | Any feature or bugfix — write test first, watch fail, implement |
| `superpowers:subagent-driven-development` | Executing plans with fresh workers per task |
| `superpowers:dispatching-parallel-agents` | 3+ independent tasks that can run concurrently |
| `superpowers:using-git-worktrees` | Isolating feature work from main workspace |

### Quality & Review
| Skill | When to Use |
|-------|-------------|
| `superpowers:requesting-code-review` | Before merging — dispatches code-reviewer agent |
| `superpowers:receiving-code-review` | Processing review feedback with technical rigor |
| `superpowers:verification-before-completion` | Before claiming work is done — run tests, confirm output |
| `superpowers:finishing-a-development-branch` | Work complete, deciding merge/PR/cleanup |

### Debugging & Testing
| Skill | When to Use |
|-------|-------------|
| `superpowers:systematic-debugging` | Any bug or test failure — investigate before fixing |
| `superpowers:root-cause-tracing` | Tracing errors back through call stack |
| `superpowers:testing-anti-patterns` | Avoiding mocking mistakes, test pollution |
| `superpowers:condition-based-waiting` | Fixing flaky tests with race conditions |

### Defense & Security
| Skill | When to Use |
|-------|-------------|
| `superpowers:defense-in-depth` | Validation at multiple layers to prevent bugs |

### Agents
| Agent | When to Use |
|-------|-------------|
| `superpowers:code-reviewer` | Dispatched by requesting-code-review for PR review |

### Commands (Shortcuts)
| Command | What it Does |
|---------|--------------|
| `/superpowers:brainstorm` | Quick access to brainstorming skill |
| `/superpowers:write-plan` | Quick access to writing-plans skill |
| `/superpowers:execute-plan` | Quick access to executing-plans skill |

**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`
</EXTREMELY-IMPORTANT>

## How Rails-AI Works

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

```text
┌─────────────────────────────────────────────┐
│ 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-A