tsykvas_rails_template 0.1.0

data/lib/generators/tsykvas_rails_template/install/bootstrap_installer.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module TsykvasRailsTemplate
+  module Generators
+    # Bootstrap install steps for InstallGenerator. Lives in its own module so
+    # the generator stays under the class-length limit and the Bootstrap-only
+    # logic is grouped together for opt-out (`--skip-bootstrap`).
+    #
+    # Expects the host to provide: `say_status`, `gem`, `create_file`,
+    # `empty_directory`, `append_to_file`, `in_root`, `destination_root`, `run`.
+    # All of those are Thor::Group / Rails::Generators::Base helpers.
+    module BootstrapInstaller
+      BOOTSTRAP_SCSS_ENTRY_PATH = "app/assets/stylesheets/application.bootstrap.scss"
+      BOOTSTRAP_SCSS_ENTRY_BODY = <<~SCSS
+        // tsykvas_rails_template — Bootstrap entrypoint compiled by dartsass-rails
+        // into app/assets/builds/application.css. Override $variables above the
+        // import to theme; add component partials below.
+        @import "bootstrap";
+      SCSS
+
+      DARTSASS_INITIALIZER_PATH = "config/initializers/dartsass.rb"
+      # `build_options` is consumed by dartsass-rails as Array#flat_map(&:split),
+      # so it MUST be an Array (a String would NoMethodError at build time).
+      # We extend dartsass-rails' own defaults (compressed + no-source-map):
+      #   --quiet-deps                   silences warnings from gem load paths
+      #                                   (Bootstrap 5.3.x's internal noise:
+      #                                   @import / red() / mix() — 311 warns)
+      #   --silence-deprecation=import   silences the lone warning on the
+      #                                   `@import "bootstrap"` in our own
+      #                                   application.bootstrap.scss
+      #                                   (Bootstrap 5.3 has no @use replacement)
+      DARTSASS_MANAGED_HEADER = "# Managed by tsykvas_rails_template:install — re-running install rewrites this file."
+      DARTSASS_INITIALIZER_BODY = <<~RUBY.freeze
+        # frozen_string_literal: true
+        #{DARTSASS_MANAGED_HEADER}
+
+        # tsykvas_rails_template — dartsass-rails build map.
+        # Keys are sources under app/assets/stylesheets, values are outputs
+        # under app/assets/builds (which Propshaft serves).
+        Rails.application.config.dartsass.builds = {
+          "application.bootstrap.scss" => "application.css"
+        }
+
+        Rails.application.config.dartsass.build_options = [
+          "--style=compressed",
+          "--no-source-map",
+          "--quiet-deps",
+          "--silence-deprecation=import"
+        ]
+      RUBY
+
+      IMPORTMAP_PINS = <<~RUBY
+        pin "bootstrap", to: "https://ga.jspm.io/npm:bootstrap@5.3.3/dist/js/bootstrap.esm.js", preload: true
+        pin "@popperjs/core", to: "https://ga.jspm.io/npm:@popperjs/core@2.11.8/lib/index.js", preload: true
+      RUBY
+
+      APPLICATION_JS_PATH = "app/javascript/application.js"
+      APPLICATION_JS_BOOTSTRAP_BLOCK = <<~JS
+
+        // Bootstrap (added by tsykvas_rails_template:install) — exposed globally
+        // so OperationsMethods' format.js modal-dismiss path can call it.
+        import * as bootstrap from "bootstrap"
+        window.bootstrap = bootstrap
+      JS
+
+      PROCFILE_DEV_PATH = "Procfile.dev"
+      PROCFILE_DEV_BODY = <<~PROC
+        web: bin/rails server
+        css: bin/rails dartsass:watch
+      PROC
+
+      private
+
+      def install_bootstrap_steps
+        add_bootstrap_gems
+        run_bundle_install_for_bootstrap
+        bundle_update_bootstrap_gems
+        write_bootstrap_scss_entry
+        ensure_assets_builds_directory
+        write_dartsass_initializer
+        pin_bootstrap_via_importmap
+        wire_application_js_bootstrap_import
+        write_procfile_dev
+        ensure_foreman_installed
+        precompile_bootstrap_css
+      end
+
+      def add_bootstrap_gems
+        add_gem_if_missing("bootstrap", "~> 5.3")
+        add_gem_if_missing("dartsass-rails")
+      end
+
+      def gemfile_includes?(name)
+        gemfile = destination_path("Gemfile")
+        return false unless File.exist?(gemfile)
+
+        File.read(gemfile).match?(/^\s*gem\s+['"]#{Regexp.escape(name)}['"]/)
+      end
+
+      def add_gem_if_missing(name, *args)
+        if gemfile_includes?(name)
+          say_status :exist, "gem '#{name}' already in Gemfile", :blue
+          return
+        end
+
+        gem(name, *args)
+      end
+
+      def run_bundle_install_for_bootstrap
+        in_root do
+          Bundler.with_unbundled_env { run "bundle install" }
+        end
+      end
+
+      # Re-runs of install on existing hosts may have older bootstrap /
+      # dartsass-rails versions locked in Gemfile.lock. `bundle install` is a
+      # no-op there. `bundle update` bumps to the latest within the Gemfile
+      # constraints (e.g. latest 5.3.x for `~> 5.3`).
+      def bundle_update_bootstrap_gems
+        in_root do
+          Bundler.with_unbundled_env { run "bundle update bootstrap dartsass-rails" }
+        end
+      end
+
+      def write_bootstrap_scss_entry
+        path = destination_path(BOOTSTRAP_SCSS_ENTRY_PATH)
+        if File.exist?(path)
+          say_status :exist, BOOTSTRAP_SCSS_ENTRY_PATH, :blue
+          return
+        end
+
+        empty_directory File.dirname(BOOTSTRAP_SCSS_ENTRY_PATH) unless File.directory?(File.dirname(path))
+        create_file BOOTSTRAP_SCSS_ENTRY_PATH, BOOTSTRAP_SCSS_ENTRY_BODY
+      end
+
+      def ensure_assets_builds_directory
+        keep = "app/assets/builds/.keep"
+        return if File.exist?(destination_path(keep))
+
+        empty_directory "app/assets/builds" unless File.directory?(destination_path("app/assets/builds"))
+        create_file keep, ""
+      end
+
+      def write_dartsass_initializer
+        path = destination_path(DARTSASS_INITIALIZER_PATH)
+        unless File.exist?(path)
+          create_file DARTSASS_INITIALIZER_PATH, DARTSASS_INITIALIZER_BODY
+          return
+        end
+
+        contents = File.read(path)
+        if contents == DARTSASS_INITIALIZER_BODY
+          say_status :exist, DARTSASS_INITIALIZER_PATH, :blue
+          return
+        end
+
+        # Re-running install rewrites the initializer to its canonical form.
+        # The "managed" header marks this file as gem-owned so users know edits
+        # don't survive — customise dartsass options elsewhere if you need to.
+        File.write(path, DARTSASS_INITIALIZER_BODY)
+        if contents.include?(DARTSASS_MANAGED_HEADER)
+          say_status :update, "#{DARTSASS_INITIALIZER_PATH} (managed)", :green
+        else
+          say_status :overwrite,
+                     "#{DARTSASS_INITIALIZER_PATH} (was hand-edited; superseded by canonical form)",
+                     :yellow
+        end
+      end
+
+      def pin_bootstrap_via_importmap
+        importmap = destination_path("config/importmap.rb")
+        return unless File.exist?(importmap)
+        return if File.read(importmap).include?(%(pin "bootstrap"))
+
+        append_to_file "config/importmap.rb",
+                       "\n# Bootstrap (added by tsykvas_rails_template:install)\n#{IMPORTMAP_PINS}"
+      end
+
+      def wire_application_js_bootstrap_import
+        path = destination_path(APPLICATION_JS_PATH)
+        return unless File.exist?(path)
+        return if File.read(path).include?('import * as bootstrap from "bootstrap"')
+
+        append_to_file APPLICATION_JS_PATH, APPLICATION_JS_BOOTSTRAP_BLOCK
+      end
+
+      def write_procfile_dev
+        path = destination_path(PROCFILE_DEV_PATH)
+        if File.exist?(path)
+          return if File.read(path).include?("dartsass:watch")
+
+          append_to_file PROCFILE_DEV_PATH, "css: bin/rails dartsass:watch\n"
+        else
+          create_file PROCFILE_DEV_PATH, PROCFILE_DEV_BODY
+        end
+      end
+
+      def precompile_bootstrap_css
+        in_root do
+          Bundler.with_unbundled_env { run "bin/rails dartsass:build" }
+        end
+      end
+
+      # Foreman is required for `bin/dev` (which reads Procfile.dev) but its
+      # README explicitly says don't add it to Gemfile — install it system-wide.
+      # Idempotent: skip when already on PATH.
+      def ensure_foreman_installed
+        if foreman_already_installed?
+          say_status :exist, "foreman already installed system-wide", :blue
+          return
+        end
+
+        in_root do
+          Bundler.with_unbundled_env { run "gem install foreman --no-document" }
+        end
+      end
+
+      def foreman_already_installed?
+        Bundler.with_unbundled_env do
+          system("gem list -i foreman > /dev/null 2>&1")
+        end
+      end
+    end
+  end
+end

data/lib/generators/tsykvas_rails_template/install/install_generator.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require_relative "bootstrap_installer"
+
+module TsykvasRailsTemplate
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include BootstrapInstaller
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Install the tsykvas_rails_template skeleton:
+          - copies app/concepts/base/{operation,component}/* into the host
+          - copies the OperationsMethods controller concern (the `endpoint` DSL)
+          - registers app/concepts in config.autoload_paths
+          - wires Pundit::Authorization + OperationsMethods into ApplicationController
+          - generates ApplicationPolicy if missing
+          - scaffolds a Home example concept (controller + operation + component
+            + HomePolicy + root route) showing the canonical one-liner pattern
+          - drops .claude/{agents,commands,docs}/* and a CLAUDE.md scaffold
+      DESC
+
+      class_option :skip_application_policy,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't generate ApplicationPolicy if it doesn't exist"
+
+      class_option :skip_autoload_paths,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't patch config/application.rb"
+
+      class_option :skip_claude,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't drop .claude/ payload or CLAUDE.md"
+
+      class_option :skip_home_example,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't scaffold the Home example concept + root route"
+
+      class_option :keep_sqlite,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't swap sqlite3 for pg in the Gemfile (default: always swap to PostgreSQL)"
+
+      class_option :skip_bootstrap,
+                   type: :boolean,
+                   default: false,
+                   desc: "Don't install bootstrap + dartsass-rails or wire the SCSS / importmap pins"
+
+      def swap_database_to_postgresql
+        return if options[:keep_sqlite]
+
+        swap_gemfile_to_pg
+        swap_database_yml_to_pg
+      end
+
+      def copy_concepts_base
+        directory "app/concepts/base", "app/concepts/base"
+      end
+
+      def copy_operations_methods_concern
+        copy_file "app/controllers/concerns/operations_methods.rb",
+                  "app/controllers/concerns/operations_methods.rb"
+      end
+
+      def add_concepts_to_autoload_paths
+        return if options[:skip_autoload_paths]
+
+        target = destination_path("config/application.rb")
+        return unless File.exist?(target)
+
+        marker = "app/concepts"
+        contents = File.read(target)
+        if contents.include?("#{marker}]") || contents.include?("#{marker}\"]")
+          say_status :exist, "config.autoload_paths already includes #{marker}", :blue
+          return
+        end
+
+        application "config.autoload_paths += %W[\#{config.root}/app/concepts]\n"
+      end
+
+      def wire_application_controller
+        target_rel = "app/controllers/application_controller.rb"
+        target_abs = destination_path(target_rel)
+        return unless File.exist?(target_abs)
+
+        contents = File.read(target_abs)
+
+        unless contents.include?("Pundit::Authorization") || contents.include?("include Pundit\n")
+          inject_into_class target_rel, "ApplicationController", "  include Pundit::Authorization\n"
+        end
+
+        return if contents.include?("OperationsMethods")
+
+        inject_into_class target_rel, "ApplicationController", "  include OperationsMethods\n"
+      end
+
+      def create_application_policy
+        return if options[:skip_application_policy]
+        return if File.exist?(destination_path("app/policies/application_policy.rb"))
+
+        empty_directory "app/policies" unless File.directory?(destination_path("app/policies"))
+        copy_file "app/policies/application_policy.rb",
+                  "app/policies/application_policy.rb"
+      end
+
+      def generate_home_example
+        return if options[:skip_home_example]
+        return if File.exist?(destination_path("app/controllers/home_controller.rb"))
+        return if File.directory?(destination_path("app/concepts/home"))
+
+        copy_file "app/controllers/home_controller.rb",
+                  "app/controllers/home_controller.rb"
+        directory "app/concepts/home", "app/concepts/home"
+
+        empty_directory "app/policies" unless File.directory?(destination_path("app/policies"))
+        return if File.exist?(destination_path("app/policies/home_policy.rb"))
+
+        copy_file "app/policies/home_policy.rb", "app/policies/home_policy.rb"
+      end
+
+      def add_root_route
+        return if options[:skip_home_example]
+
+        routes_path = destination_path("config/routes.rb")
+        return unless File.exist?(routes_path)
+        return if File.read(routes_path).match?(/^\s*root\s/)
+
+        route 'root "home#index"'
+      end
+
+      def install_bootstrap
+        return if options[:skip_bootstrap]
+
+        install_bootstrap_steps
+
+        say_status :bootstrap,
+                   "Bootstrap 5.3 + dartsass-rails wired. Run `bin/dev` for the live SCSS watcher, " \
+                   "or `bin/rails dartsass:build` once before `bin/rails server`. " \
+                   "Pass --skip-bootstrap to opt out.",
+                   :green
+      end
+
+      # Propshaft serves from `public/assets/` whenever a `.manifest.json` is
+      # there, completely bypassing live `app/assets/builds/` and
+      # `app/javascript/`. A stale dir from a prior `rails assets:precompile`
+      # silently freezes the dev environment. Clean it here — but only if
+      # `.gitignore` lists it (so we know it's a transient cache, not
+      # checked-in content). `rails new` adds `/public/assets` by default.
+      def clean_propshaft_cache
+        require "fileutils"
+
+        cache_dir = destination_path("public/assets")
+        return unless File.directory?(cache_dir)
+
+        gitignore = destination_path(".gitignore")
+        listed = File.exist?(gitignore) && File.read(gitignore).match?(%r{^/?public/assets\b})
+        unless listed
+          say_status :skip,
+                     "public/assets/ exists but is not in .gitignore — leaving alone " \
+                     "(it might be checked-in content rather than a Propshaft cache).",
+                     :yellow
+          return
+        end
+
+        FileUtils.rm_rf(cache_dir)
+        say_status :clean,
+                   "Removed stale public/assets/ (Propshaft would otherwise shadow live " \
+                   "app/assets/builds/ and app/javascript/ in dev).",
+                   :green
+      end
+
+      SHIPPED_DOCS = %w[
+        architecture
+        authentication
+        background-jobs
+        code-style
+        commands
+        companions
+        concepts-refactoring
+        database
+        deployment
+        design-system
+        documentation
+        forms
+        i18n
+        routing-and-namespaces
+        security
+        stimulus-controllers
+        testing
+        testing-examples
+        tsykvas_rails_template
+        ui-components
+      ].freeze
+
+      def copy_claude_payload
+        return if options[:skip_claude]
+
+        directory ".claude/agents", ".claude/agents"
+        directory ".claude/commands", ".claude/commands"
+        empty_directory ".claude/docs" unless File.directory?(destination_path(".claude/docs"))
+        SHIPPED_DOCS.each do |name|
+          copy_file ".claude/docs/#{name}.md", ".claude/docs/#{name}.md"
+        end
+      end
+
+      def write_claude_md
+        return if options[:skip_claude]
+
+        if File.exist?(destination_path("CLAUDE.md"))
+          say_status :skip,
+                     "CLAUDE.md already exists; not overwriting. " \
+                     "Run `/tsykvas-claude` in Claude Code to integrate the gem's " \
+                     "must-know-rules and routing table inside fence markers without " \
+                     "touching your existing content.",
+                     :yellow
+          return
+        end
+
+        template "CLAUDE.md.tt", "CLAUDE.md"
+      end
+
+      def announce_completion
+        say ""
+        say "  tsykvas_rails_template installed.", :green
+        say "    A working Home example landed at /app/concepts/home/ with"
+        say "    `root \"home#index\"` already in routes — start `bin/rails server`"
+        say "    and visit http://localhost:3000 to see it (unless you passed"
+        say "    --skip-home-example)."
+        say ""
+        say "    Next steps:"
+        say "      1. rails g tsykvas_rails_template:companions"
+        say "         (adds devise / simple_form / rspec stack / mini_magick / etc."
+        say "          and runs their :install sub-generators)"
+        say "      2. rails g tsykvas_rails_template:concept <Name> [--controller]"
+        say "         scaffolds your domain concepts."
+        say "      3. Open Claude Code and run /tsykvas-claude to refresh"
+        say "         probe-driven sections in CLAUDE.md + .claude/docs/"
+        say "         (concept folders, gem versions, branch names) when"
+        say "         your stack changes."
+        say ""
+      end
+
+      private
+
+      def destination_path(rel)
+        File.join(destination_root, rel)
+      end
+
+      def swap_gemfile_to_pg
+        gemfile = destination_path("Gemfile")
+        return unless File.exist?(gemfile)
+
+        contents = File.read(gemfile)
+        return if contents.match?(/^\s*gem\s+['"]pg['"]/)
+
+        if contents.match?(/^\s*gem\s+['"]sqlite3['"]/)
+          gsub_file "Gemfile",
+                    /^(\s*)gem\s+['"]sqlite3['"][^\n]*$/,
+                    "\\1# gem \"sqlite3\" — replaced by tsykvas_rails_template:install\n\\1gem \"pg\""
+        else
+          append_to_file "Gemfile", %(\ngem "pg"\n)
+        end
+      end
+
+      def swap_database_yml_to_pg
+        yml_path = destination_path("config/database.yml")
+        return unless File.exist?(yml_path)
+
+        contents = File.read(yml_path)
+        return unless contents.match?(/adapter:\s*sqlite3/)
+
+        # adapter: sqlite3 → adapter: postgresql (+ encoding: unicode)
+        gsub_file "config/database.yml",
+                  /^(\s*)adapter:\s*sqlite3\s*$/,
+                  "\\1adapter: postgresql\n\\1encoding: unicode"
+        # Drop sqlite-only `timeout:` lines.
+        gsub_file "config/database.yml", /^\s*timeout:\s*\d+\s*\n/, ""
+        # storage/<env>.sqlite3 → <app_name>_<env>
+        app = File.basename(destination_root).tr("-", "_")
+        gsub_file "config/database.yml",
+                  %r{database:\s*storage/(\w+)\.sqlite3},
+                  "database: #{app}_\\1"
+
+        say_status :db,
+                   "Swapped sqlite3 → pg in Gemfile + config/database.yml. " \
+                   "Run `bundle install && bin/rails db:create` after install completes. " \
+                   "Pass --keep-sqlite to skip the swap.",
+                   :yellow
+      end
+    end
+  end
+end

data/lib/generators/tsykvas_rails_template/install/templates/.claude/agents/buddy.md

@@ -0,0 +1,157 @@
+---
+name: buddy
+description: Feature planning partner. Use when brainstorming, designing, or planning a new feature. Asks probing questions, researches solutions, and produces a feature_plan.md ready for implementation.
+tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
+model: opus
+---
+
+You are a senior Rails developer and product thinker. Your role is to plan features collaboratively with the user through conversation. You NEVER implement code — you only produce a plan.
+
+## What you know
+
+You are deeply familiar with this project's architecture. Before starting, read these docs to understand how everything is built:
+
+- `.claude/docs/architecture.md` — Concepts Pattern, Operation/Component, `endpoint`, `api_endpoint`, Pundit
+- `.claude/docs/concepts-refactoring.md` — Refactoring guide and end-to-end Operation/Component examples
+- `.claude/docs/api-endpoints.md` — Building Api::V1::* endpoints with params adapters
+- `.claude/docs/ui-components.md` — `Base::Component::Base`, `Base::Component::Table`, modals, helpers
+- `.claude/docs/stimulus-controllers.md` — Stimulus conventions, listener cleanup
+- `.claude/docs/testing.md` + `.claude/docs/testing-examples.md` — RSpec patterns, the operation shared context, what NOT to test
+- `.claude/docs/code-style.md` — Ruby/Rails style, I18n keys, locales
+- `CLAUDE.md` — top-level project conventions
+
+The detailed legacy guides also live in `.cursor/rules/*.mdc` — read them when relevant.
+
+## How you work
+
+Guide the conversation through 4 phases. Don't rush — each phase matters.
+
+### Phase 1: Understand the goal
+
+Ask questions to understand WHAT and WHY:
+- What does this feature do from the user's perspective?
+- Who can access it? (account members, admins, API consumers, scan-by-token users?)
+- What's the trigger? (button click, page visit, background job, API call, barcode scan?)
+- Does it touch hardware or external services? (third-party APIs, image rendering, hardware drivers, scheduled jobs?)
+- Does the API need an endpoint too, or HTML only?
+- Are there edge cases or constraints the user already knows about?
+
+Keep asking until you have a clear picture. Don't assume — ask.
+
+### Phase 2: Technical design
+
+Now figure out HOW. Research if needed:
+- Look at existing similar features in the codebase (`app/concepts/`, `app/models/`) for reference patterns
+- For external integrations (third-party APIs, etc.), search the web for their docs and find the best integration approach
+- Read existing operations in the same domain to stay consistent
+
+Discuss with the user:
+- Database changes needed (new tables, columns, indexes, constraints, foreign keys)
+- New models or concerns; existing models to extend
+- Routes (RESTful resources? member/collection actions? API namespace?)
+- How many operations and components — name them
+- Authorization rules (who can do what — Pundit policy methods + Scope)
+- Frontend interactions (Turbo Frames? Stimulus? Modal via `remote: true`? Static page?)
+- Locale keys needed for all `config/locales/*.yml` files
+- Background jobs (SolidQueue) for slow operations: image generation, mass updates, email
+- Whether `Select2Helper` needs to be added on a model for autocomplete
+
+### Phase 3: Detail every file
+
+Go file-by-file through everything that needs to be created or modified. For each file:
+- Full path
+- What it does
+- Key logic, fields, kwargs
+
+### Phase 4: Pre-generation checklist
+
+Before writing the plan, go through this checklist WITH the user:
+
+- [ ] DB migrations — tables, columns, indexes, constraints, foreign keys
+- [ ] Models — validations, associations, enums, scopes, concerns (incl. `Select2Helper` if needed)
+- [ ] Routes — resources, nested routes, member/collection actions, API namespace
+- [ ] Operations — one per action under `app/concepts/<feature>/operation/`. For each: `authorize!` / `policy_scope` / `skip_authorize` and what it does
+- [ ] Components — kwargs, what data they display, which `Base::Component::Base` helpers they use (`header`, `modal`, `Base::Component::Table`)
+- [ ] Slim templates — layout, forms, tables, modals
+- [ ] Pundit policy — actions and `Scope#resolve`
+- [ ] Locales — keys for all `config/locales/*.yml` files, and `activerecord.attributes.<ns>/<model>.<attr>` style for model attrs
+- [ ] Stimulus controllers — if dynamic behavior needed; document-level listener cleanup planned?
+- [ ] API: controller, base + per-action params adapters, swagger entry, request specs
+- [ ] Background jobs — anything slow that should not block a request
+- [ ] Tests — operations and request specs; skip association/validation/policy/component tests
+- [ ] Implementation order — step-by-step sequence
+
+Ask: "Planning done? Should I generate feature_plan.md?"
+
+## Output: feature_plan.md
+
+Only when the user confirms, write `feature_plan.md` to the project root with this structure:
+
+```markdown
+# Feature: <name>
+
+## Overview
+What this feature does and why.
+
+## Database changes
+Migration details: tables, columns, types, indexes, constraints.
+
+## Models
+New or modified models, associations, validations, enums, scopes, concerns. Note any `Select2Helper` additions and the `select2_search_result` shape.
+
+## Routes
+```ruby
+# New routes to add
+```
+
+## Operations
+For each operation:
+- **Class**: `Feature::Operation::Action < Base::Operation::Base`
+- **Authorization**: authorize! / policy_scope / skip_authorize
+- **Logic**: step by step, including notice / redirect / sub-operations
+
+## Components
+For each component:
+- **Class**: `Feature::Component::Name < Base::Component::Base`
+- **kwargs**: what data it receives (specific names, not `model:`)
+- **Template**: key UI elements (header, table, modal, form)
+
+## Policies
+- **Class**: `FeaturePolicy < ApplicationPolicy`
+- **Rules**: per-action (`index?`, `show?`, `edit?`, `update?`, `destroy?`)
+- **Scope**: how `resolve` filters by account
+
+## API (only if applicable)
+- Controller: `Api::V1::FeatureController`
+- ParamsAdapter::Base shape (basic_output, full_output)
+- Per-action adapters: input_param declarations, input_params/output_params
+- Swagger entries to add
+
+## Locales
+```yaml
+# keys for every locale file in config/locales/
+```
+
+## Stimulus controllers
+If needed — file name, identifier, targets, actions, document-level listeners + disconnect cleanup.
+
+## Background jobs
+SolidQueue jobs for slow work — what gets enqueued and when.
+
+## Tests
+Operation specs (happy + unauthorized + edge cases); request specs (auth, validation, success). Skip policy/component/association/validation specs.
+
+## Implementation order
+Numbered step-by-step sequence to follow when implementing.
+```
+
+## Rules
+
+- NEVER write code or implement anything. Only plan.
+- Always read existing code before suggesting patterns — stay consistent with the codebase.
+- When researching external services, share what you found and discuss options before deciding.
+- Speak Ukrainian if the user writes in Ukrainian, English if in English.
+- Keep responses focused — don't dump walls of text. Ask one thing at a time.
+- Use compact class notation: `class Feature::Operation::Action < Base::Operation::Base`
+- Remember: controllers are thin wrappers (`endpoint Op, Component` or `api_endpoint Op, ParamsAdapter`), all logic lives in operations.
+- Locale keys live in All `config/locales/*.yml` files.