Feature Implementation Prompt

Use this prompt to implement an extracted feature into the AI SaaS Template on Steroids project.

Instructions for AI Agent

You are a feature implementation specialist for the AI SaaS Template on Steroids project. Your task is to implement an extracted feature following this project's architecture and patterns.

Critical References

Before implementing, you MUST read and follow:

AGENTS.md - Core code generation standards (SINGLE SOURCE OF TRUTH)
FILE_STRUCTURE.md - Feature-based organization patterns

Project Architecture Summary

Multi-Tenant Pattern:
User → Membership (role) → Organization → Resources

Key Rules:
- NO app/services/ folder (use namespaced model classes)
- Resources use: belongs_to :organization + belongs_to :membership
- Cross-org features use: belongs_to :user + shares_organization_with? authorization
- Personal organizations are auto-created for each user
- Authorization flows through Pundit with membership context

Implementation Workflow

Phase 1: Analysis

Read the extracted feature's ABOUT.md to understand:
- What the feature does
- Data model and relationships
- Key components and their responsibilities
- Integration points
Map to our architecture:
- Is this an organization-scoped feature? → Use Organizations:: namespace
- Is this a cross-organization feature? → Use root namespace with user associations
- Is this personal-only? → Scope to personal organization
Identify adaptations needed:
- Replace belongs_to :user with belongs_to :membership for org-scoped features
- Convert service objects to namespaced model classes
- Adapt authorization to use Pundit with membership context
- Convert RSpec to Minitest if needed
- Convert FactoryBot to fixtures if needed

Phase 2: Database

Create migrations following our patterns:

# For org-scoped features
t.references :organization, null: false, foreign_key: true
t.references :membership, foreign_key: true  # Creator
   
# For cross-org features  
t.references :user, null: false, foreign_key: true
   
# Use feature prefix for namespaced models
create_table :feature_name_models do |t|

Run migrations: bin/rails db:migrate

Phase 3: Models

Create models following AGENTS.md patterns:

# Organization-scoped
class FeatureName::Model < ApplicationRecord
  self.table_name = "feature_name_models"
     
  belongs_to :organization
  belongs_to :membership
     
  # Follow model organization order from AGENTS.md
end
   
# Cross-organization
class FeatureName::Model < ApplicationRecord
  self.table_name = "feature_name_models"
     
  belongs_to :user
     
  # Authorization via shares_organization_with?
end

Extract complex logic to namespaced classes (NOT services):

# app/models/feature_name/model/handler.rb
class FeatureName::Model::Handler
  def initialize(model)
    @model = model
  end
     
  def process
    # Complex logic here
  end
end

Add associations to Organization or User model as needed

Phase 4: Controllers

For organization-scoped features:

# app/controllers/organizations/feature_name/models_controller.rb
module Organizations
  module FeatureName
    class ModelsController < Organizations::BaseController
      # Inherits organization context and pundit_user
    end
  end
end

For cross-organization features:

# app/controllers/feature_name/models_controller.rb
module FeatureName
  class ModelsController < ApplicationController
    before_action :authenticate_user!
       
    private
       
    def pundit_user
      current_user  # Use user directly, not membership
    end
  end
end

Phase 5: Authorization (Pundit)

For organization-scoped features:

# app/policies/feature_name/model_policy.rb
module FeatureName
  class ModelPolicy < Organization::BasePolicy
    # membership context from Organization::BasePolicy
  end
end

For cross-organization features:

# app/policies/feature_name/model_policy.rb
module FeatureName
  class ModelPolicy < ApplicationPolicy
    def create?
      # Use shares_organization_with? for authorization
      record.users.all? { |u| user.shares_organization_with?(u) || u == user }
    end
  end
end

Phase 6: Views

Follow Tailwind patterns with dark mode support
Use Turbo Frames and Streams for interactivity
Use currentColor for SVG icons

Phase 7: JavaScript/Stimulus

Use kebab-case for controller names
Namespace under feature folder: app/javascript/controllers/feature_name/
Use double-dash in HTML: data-controller="feature-name--model"

Phase 8: Routes

Organization-scoped:

resources :organizations do
  scope module: :organizations do
    namespace :feature_name do
      resources :models
    end
  end
end

Cross-organization:

namespace :feature_name do
  resources :models
end

Phase 9: Tests

Use Minitest (not RSpec)
Use fixtures (not FactoryBot)
Create fixtures in test/fixtures/feature_name/

Phase 10: Verification

Run tests: bin/rails test
Check for N+1 queries (Bullet will alert)
Run rubocop: bin/rubocop
Run annotate: bundle exec annotaterb models

Feature to Implement

Extracted Feature Location

[PATH_TO_EXTRACTED_FEATURE]

Implementation Scope

Full feature
Subset: [specify]

Adaptation Notes

Organization-scoped or cross-org?
Any gems to add?
Any conflicts with existing features?

Implementation Checklist

Pre-Implementation

Read AGENTS.md thoroughly
Read FILE_STRUCTURE.md thoroughly
Read extracted feature's ABOUT.md
Identify feature scope (org-scoped vs cross-org)
Map extracted patterns to our patterns

Database Layer

Create migrations with proper associations
Run migrations
Verify schema

Model Layer

Create models following AGENTS.md order
Add enums for states (no string columns)
Add validations
Add scopes
Extract complex logic to namespaced classes
Add associations to Organization/User

Controller Layer

Create controllers in correct namespace
Keep actions under 10 lines
Use proper authorization
Support Turbo Stream responses

Authorization Layer

Create Pundit policies
Use correct base policy (Organization::BasePolicy or ApplicationPolicy)
Test all authorization scenarios

View Layer

Create views with Tailwind
Include dark mode support
Use Turbo Frames/Streams
Use currentColor for SVGs

JavaScript Layer

Create Stimulus controllers with kebab-case
Organize under feature namespace
Document controller usage

Routes

Add routes in correct scope
Verify URL helpers work

Testing

Create fixtures
Create model tests
Create controller tests
Create system tests

Final Verification

AI Agent: Begin Implementation

Once you have the extracted feature folder attached, proceed with:

Study - Read ABOUT.md, GEMS.md, SCHEMA.md from the extracted feature
Plan - Determine adaptations needed for our architecture
Ask - Request any missing context or clarification
Implement - Follow the phases above in order
Test - Run tests and verify functionality
Document - Update any relevant documentation

Adaptation Reference

Extracted Pattern	Our Pattern
`belongs_to :user` (org resource)	`belongs_to :membership`
`app/services/`	`app/models/<feature>/` namespaced class
RSpec	Minitest
FactoryBot	Fixtures
CanCanCan	Pundit
Sidekiq	Solid Queue
Redis	Solid Cache/Cable/Queue
`current_user` in policy	`membership` or `user` depending on scope

Gem Version Policy

If a gem from the extracted feature already exists in this project, use this project's version. Only add version constraints for new gems that have minimum version requirements for specific features.

Common Gotchas

Don't create app/services/ - Use namespaced model classes
Don't use belongs_to :user for org resources - Use :membership
Don't forget organization association for org-scoped resources
Don't hardcode SVG colors - Use currentColor
Don't use underscores in Stimulus names - Use kebab-case
Don't forget dark mode - Always include dark: variants

Documentation