rails-agent-skills

---
name: rails-agent-skills
description: >
license: MIT
---

# Rails Agent Skills

This skill coordinates disciplined Rails development by sequencing atomic skills for each task. It defines what to run, in what order, and how to validate each step.

**Core principle:** Atomic, task-specific instructions that turn AI coding assistants into reliable Rails collaborators through TDD and idiomatic patterns.

## Activating Atomic Skills

To activate an atomic skill, read its corresponding Markdown file from the skills bundle and follow its instructions as the operative prompt for that step. If a skill file is unavailable, use the inline fallback guidance in the Skill Catalog below rather than halting entirely — note any gaps in output and proceed with best-effort idiomatic Rails conventions.

## HARD-GATES

### 1. Context First (Pre-flight)

1. Do not perform any implementation or review action without first running `load-context`.
2. Synchronize with the host application's schema, routes, and established patterns before producing any output.

### 2. Tests Gate Implementation

1. Implementation code cannot be written until a test exists for the target behaviour.
2. The test must be executed via `bundle exec rspec <spec_file>` before implementation begins.
3. The test must fail for the correct reason (feature missing, not a syntax error) before proceeding.

## Core Process

1. **Context Initialization (CRITICAL):** Activate `load-context`. Confirm schema, routes, and patterns are loaded before any other step.
2. **Discovery:** Identify which atomic skills from the catalog match the current task.
3. **Execution Loop:**
   - **Plan:** Activate `plan-tests`. Output: a list of pending test cases with descriptions.
   - **Act:** Activate `write-tests`. Run `bundle exec rspec <spec_file>` — confirm output shows red (failure for the right reason). Then activate `implement`. Run `bundle exec rspec <spec_file>` — confirm green. Then activate `apply-code-conventions`.
   - **Polish:** Activate `write-yard-docs` and `code-review`.
4. **Validation:** After each atomic skill completes, verify its declared `Output Style` checklist before proceeding to the next step. If a step produces unexpected failures, re-run `load-context` before retrying.

## Worked Example: Adding a Service Object with Tests

```
Step 1 — load-context
  Input:  project root directory
  Action: Read schema.rb, routes.rb, and existing service objects
  Output: Confirmed patterns (e.g., services inherit ApplicationService, use call)

Step 2 — plan-tests
  Input:  "Create an OrderFulfillmentService"
  Output: [
    "returns success when inventory is available",
    "returns failure when inventory is insufficient",
    "enqueues FulfillmentJob on success"
  ]

Step 3 — write-tests
  Input:  test plan above
  Output: spec/services/order_fulfillment_service_spec.rb (written, not passing)
  Validate: bundle exec rspec spec/services/order_fulfillment_service_spec.rb
            → Expect: 3 examples, 3 failures (NameError or similar — feature missing)

Step 4 — implement
  Input:  failing spec
  Output: app/services/order_fulfillment_service.rb
  Validate: bundle exec rspec spec/services/order_fulfillment_service_spec.rb
            → Expect: 3 examples, 0 failures

Step 5 — apply-code-conventions + write-yard-docs + code-review
  Output: Linted file with YARD docs and review comments resolved
```

## Skill Catalog

| Category | Skill | Fallback Guidance (if file unavailable) |
|----------|-------|------------------------------------------|
| **Context** | `load-context` | Read `schema.rb`, `routes.rb`, and a sample service/model; note conventions manually |
| **Testing** | `plan-tests` | List expected behaviours as RSpec `it` descriptions before writing code |
| **Testing** | `write-tests` | Write RSpec examples using `described_class`, `let`, `expect`, `have_received` idioms |
| **Testing** | `test-service`, `triage-bug` | Follow standard RSpec unit-test patterns; isolate dependencies with doubles |
| **DDD** | `define-domain-language`, `model-domain`, `review-domain-boundaries` | Apply standard DDD vocabulary; group by bounded context |
| **Quality** | `code-review`, `security-check`, `apply-code-conventions`, `refactor-code` | Apply Rails best practices, Brakeman findings, and RuboCop rules inline |
| **API/Infra** | `implement-graphql`, `integrate-api-client`, `implement-background-job`, `review-migration` | Follow graphql-ruby conventions, ActiveJob patterns, and strong-migration rules |
| **Engines** | `create-engine`, `test-engine`, `release-engine`, `document-engine` | Use `rails plugin new --mountable`; isolate specs under `spec/` inside the engine root |
| **Patterns** | `create-service-object`, `write-yard-docs` | Inherit `ApplicationService`, expose `.call`, document with `@param`/`@return` YARD tags |
| **Setup** | `setup-environment` | Verify Ruby version, `bundle install`, and `bin/rails db:setup` |

*The complete list of all 28 local atomic skills and 9 personas is defined in `directory.json` at the project root. This repository also depends on `igmarin/ruby-core-skills` for 15 additional core skills (Process, Code Quality, Orchestration, DDD, and Ruby patterns).*

## Integration

- **`directory.json`** (project root): Canonical registry of all 28 local atomic skills and 9 personas — names, file paths, and metadata. This is the source of truth for skill discovery.
- **`docs/reference/skill-catalog.md`**: Human-readable reference with usage notes for each skill; useful for manual lookup when `directory.json` is unavailable.
- **`skill-router`**: Orchestration layer that maps incoming tasks to the correct atomic skill sequence; invoked automatically when this entry-point skill is activated.

## Core Dependencies

This repository depends on `igmarin/ruby-core-skills` for foundational DDD and Ruby pattern skills. The following 15 core skills are auto-detected and available when this plugin is installed alongside `ruby-core-skills`:

**DDD Skills (3):**
- `define-domain-language` — Domain terms glossary
- `review-domain-boundaries` — Review bounded contexts and language leakage
- `model-domain` — Map DDD to Rails (models, services, value objects)

**Ruby Pattern Skills (4):**
- `create-service-object` — `.call` pattern, response contract, YARD
- `integrate-api-client` — Layered architecture for external APIs
- `implement-calculator-pattern` — Variant-based calculators
- `write-yard-docs` — Inline documentation with YARD

**Process Skills (5):**
- `tdd-process` — TDD discipline and workflow
- `refactor-process` — Refactor preserving behavior
- `review-process` — Systematic code review
- `security-review-process` — Security audit workflow
- `test-planning-process` — Test planning and selection

**Code Quality Skills (2):**
- `triage-bug` — Bug diagnosis and reproduction
- `respond-to-review` — Respond to review feedback

**Orchestration Skills (1):**
- `skill-router` — Routes to correct specialized skill

---