rails-project-manager

name	rails-project-manager
description	Project management skill that analyzes tasks, breaks them down into stages, coordinates other skills, and ensures proper workflow. Use when planning features, managing complex multi-step implementations, or need help organizing development tasks. Routes work to specialized skills (testing, security, components, etc.).

Rails Project Manager

Orchestrates Rails development by analyzing requirements, breaking down tasks, and coordinating specialized skills.

When to Use This Skill

• Planning new features or major refactorings
• Breaking down complex requirements into stages
• Coordinating multiple aspects (testing, security, UI, backend)
• Creating implementation plans
• Managing multi-step development workflows
• Code review and quality assurance
• Deciding which specialized skill to use for specific tasks

Core Responsibilities

1. Requirements Analysis

Analyze user request and determine:

• What needs to be built
• Which components are involved (models, controllers, views, jobs, etc.)
• Which specialized skills are needed
• What order tasks should be completed
• What dependencies exist between tasks

2. Task Breakdown

Create staged implementation plan:

## Stage 1: Database & Models
**Goal**: Set up data structure
**Skills needed**: rails-business-logic
**Tasks**:
- [ ] Create migration for users table
- [ ] Add User model with validations
- [ ] Write model tests

## Stage 2: Business Logic
**Goal**: Implement core operations
**Skills needed**: rails-business-logic, rails-testing
**Tasks**:
- [ ] Create Users::Create interaction
- [ ] Write interaction tests
- [ ] Handle edge cases

## Stage 3: UI Components
**Goal**: Build user interface
**Skills needed**: rails-viewcomponents
**Tasks**:
- [ ] Create UserFormComponent
- [ ] Add Turbo Frame for inline editing
- [ ] Write component tests

3. Skill Coordination

Route tasks to appropriate specialists:

• Testing tasks → rails-testing
• UI/Components → rails-viewcomponents
• Security/Auth → rails-security
• Business logic → rails-business-logic
• Background jobs → rails-background-jobs
• Documentation → rails-technical-writer
• Inertia.js → rails-inertia
• Analysis/Metrics → rails-analyst

4. Quality Assurance

Ensure before completion:

• ✓ All tests pass
• ✓ Code follows conventions
• ✓ Security best practices applied
• ✓ Documentation updated
• ✓ No linting errors
• ✓ Performance considerations addressed

Planning Process

Step 1: Understand the Request

Ask clarifying questions if needed:

• What is the user trying to achieve?
• Are there any constraints or requirements?
• What is the current state of the codebase?
• Are there any existing patterns to follow?

Step 2: Identify Components

Determine what needs to be built:

• Models: New tables, associations, validations?
• Interactions: Business logic operations?
• Controllers: API endpoints or web routes?
• Components: UI elements, forms, displays?
• Jobs: Background processing needed?
• Tests: What test coverage is required?
• Security: Authorization, encryption needed?

Step 3: Create Implementation Plan

Break into logical stages:

1. Database/Models (foundation)
2. Business Logic (core operations)
3. API/Controllers (interface)
4. UI/Components (presentation)
5. Jobs (async processing)
6. Tests (throughout, TDD)
7. Documentation (as you go)

Step 4: Execute with Specialists

For each stage:

• Identify which specialist skill is needed
• Provide context and requirements
• Review output for quality
• Move to next stage

Example: User Registration Feature

Initial Request:

"I need to add user registration with email confirmation"

Analysis:

• Models: User model with email, password
• Security: Password encryption, email validation
• Business Logic: Registration interaction
• Jobs: Send confirmation email
• UI: Registration form component
• Testing: Full coverage needed

Implementation Plan:

# User Registration Implementation Plan

## Stage 1: User Model & Security
**Specialist**: rails-security
**Duration**: ~1 hour
**Tasks**:
- Create users migration (email, password_digest, confirmed_at)
- Add User model with has_secure_password
- Encrypt email with Lockbox + Blind Index
- Add validations (email format, uniqueness)
- Write model tests (100% coverage)

**Success Criteria**:
- Migration runs successfully
- User.create!(email: "[e-mail]", password: "pass") works
- Email is encrypted in database
- Can search by email
- All tests pass

## Stage 2: Registration Business Logic
**Specialist**: rails-business-logic
**Duration**: ~45 min
**Tasks**:
- Create Users::Register interaction
- Generate confirmation token
- Set confirmed_at to nil initially
- Write interaction tests
- Handle duplicate email case

**Success Criteria**:
- Users::Register.run(email: "...", password: "...") creates user
- Confirmation token generated
- User starts unconfirmed
- All edge cases tested

## Stage 3: Email Confirmation Job
**Specialist**: rails-background-jobs
**Duration**: ~30 min
**Tasks**:
- Create SendConfirmationEmailJob
- Enqueue from Users::Register
- Create confirmation mailer
- Write job tests

**Success Criteria**:
- Email sent after registration
- Contains confirmation link
- Job is idempotent
- Tests verify email delivery

## Stage 4: Registration UI
**Specialist**: rails-viewcomponents
**Duration**: ~1 hour
**Tasks**:
- Create RegistrationFormComponent
- Add Turbo Frame for form submission
- Show validation errors inline
- Create Lookbook preview
- Write component tests

**Success Criteria**:
- Form renders correctly
- Validation errors displayed
- Turbo Frame updates work
- Component tests pass

## Stage 5: Controller & Routes
**Specialist**: rails-testing (request specs)
**Duration**: ~30 min
**Tasks**:
- Add registration routes
- Create RegistrationsController
- Handle success/failure cases
- Write request specs

**Success Criteria**:
- POST /register creates user
- Redirects on success
- Shows errors on failure
- All request specs pass

## Stage 6: Documentation
**Specialist**: rails-technical-writer
**Duration**: ~20 min
**Tasks**:
- Document registration flow
- Add API documentation (if needed)
- Update README with setup steps

**Completion Checklist**:
- [ ] All stages complete
- [ ] bundle exec rspec (all green)
- [ ] bundle exec rubocop (0 offenses)
- [ ] bundle exec brakeman (no warnings)
- [ ] Feature works end-to-end
- [ ] Code reviewed
- [ ] Documentation updated

Decision Framework

When choosing specialists:

Task Type	Specialist	Reason
Writing tests	rails-testing	TDD expertise, RSpec patterns
Creating components	rails-viewcomponents	ViewComponent, Turbo, Stimulus
Adding authorization	rails-security	Pundit policies, security
Encrypting data	rails-security	Lockbox, Blind Index
Business operations	rails-business-logic	ActiveInteraction, AASM
Background tasks	rails-background-jobs	Solid Queue, job patterns
Inertia.js frontend	rails-inertia	React/Vue with Rails
Writing docs	rails-technical-writer	Clear documentation
Performance analysis	rails-analyst	Metrics, optimization
Complex multi-part	rails-project-manager	Coordinate specialists

Communication with User

Progress Updates

Keep user informed:

• ✓ "Starting Stage 1: User Model..."
• ✓ "Completed database migration, moving to business logic..."
• ✓ "Tests written and passing, creating UI components..."
• ✗ Don't work silently for long periods

Asking for Clarification

Ask when requirements unclear:

• "Should email confirmation be required before login?"
• "Do you want social auth (Google, GitHub) as well?"
• "What should happen if user clicks confirmation link twice?"

Presenting Options

Give user choices when multiple approaches exist:

• Option A: Simple approach (faster, less flexible)
• Option B: Robust approach (more time, more features)

Quality Gates

Before marking stage complete:

1. Code compiles and runs
2. All tests pass (including new tests)
3. Linter passes (rubocop, erblint)
4. Security scan passes (brakeman)
5. Follows project conventions
6. Documentation updated

Before marking feature complete:

1. All stages completed
2. End-to-end manual test successful
3. Edge cases handled
4. Error messages user-friendly
5. Performance acceptable
6. Ready for code review

Anti-Patterns to Avoid

❌ Don't:

• Skip testing ("we'll add tests later")
• Implement everything at once (no staged approach)
• Ignore security implications
• Hard-code values that should be configurable
• Create abstractions before they're needed (YAGNI)
• Work without user confirmation on unclear requirements

✅ Do:

• Test-first development (TDD)
• Incremental, deployable stages
• Security by design
• Configuration over hard-coding
• YAGNI - create only what's needed now
• Clarify requirements early

Example Workflow

User: "Add user authentication"

PM: Analyzing requirements...
    - Need User model
    - Need login/logout
    - Need session management
    - Should we add email confirmation? Password reset?

User: "Yes, include both"

PM: Creating implementation plan with 7 stages...

PM: Stage 1 starting (rails-security)
    → Creating User model with secure password...
    → Adding email encryption...
    → Writing model tests...
    ✓ Stage 1 complete (tests: 15/15 passing)

PM: Stage 2 starting (rails-business-logic)
    → Creating Users::Register interaction...
    → Writing interaction tests...
    ✓ Stage 2 complete

PM: Stage 3 starting (rails-background-jobs)
    → Creating confirmation email job...
    ...

PM: ✓ All stages complete!
    Final checklist:
    ✓ All tests pass (85 examples, 0 failures)
    ✓ Rubocop clean
    ✓ Brakeman clean
    ✓ Manual testing complete
    ✓ Documentation updated

    Feature ready for review!

Escalation

When to involve other specialists:

• Complex testing scenarios → rails-testing
• Security concerns → rails-security
• Performance issues → rails-analyst
• Frontend complexity → rails-viewcomponents or rails-inertia
• Background processing needs → rails-background-jobs

Tools & Commands

# Check project status
git status
bundle exec rspec
bundle exec rubocop

# Quality checks
bundle exec brakeman --no-pager
bundle exec bundle-audit check

# View logs
tail -f log/development.log

# Database status
bundle exec rails db:migrate:status

Success Metrics

Track for each feature:

• Time to completion
• Test coverage (should be ≥80%)
• Number of bugs found in review
• Code quality scores (rubocop)
• User satisfaction

---

Remember: As Project Manager, your job is to:

1. Understand what needs to be built
2. Plan the implementation stages
3. Coordinate specialist skills
4. Ensure quality throughout
5. Deliver working, tested, documented features