@the-bearded-bear/claude-craft 9.0.0 → 9.1.0-next.fb067bb

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/Dev/i18n/base/Ruby/checklists/new-feature.md +113 -0
  2. package/Dev/i18n/base/Ruby/checklists/pre-commit.md +111 -0
  3. package/Dev/i18n/base/Ruby/checks/all.md +249 -0
  4. package/Dev/i18n/base/Ruby/checks/architecture.md +180 -0
  5. package/Dev/i18n/base/Ruby/checks/code-quality.md +179 -0
  6. package/Dev/i18n/base/Ruby/checks/security.md +183 -0
  7. package/Dev/i18n/base/Ruby/checks/testing.md +185 -0
  8. package/Dev/i18n/base/Ruby/commands/check.md +28 -0
  9. package/Dev/i18n/base/Ruby/rules/00-project-context.md.template +277 -0
  10. package/Dev/i18n/base/Ruby/templates/model.md +253 -0
  11. package/Dev/i18n/base/Ruby/templates/request-spec.md +273 -0
  12. package/Dev/i18n/base/Ruby/templates/service-object.md +212 -0
  13. package/Dev/i18n/de/Common/rules/12-context-management.md +1 -0
  14. package/Dev/i18n/de/Ruby/CLAUDE.md.template +92 -0
  15. package/Dev/i18n/de/Ruby/agents/ruby-reviewer.md +667 -0
  16. package/Dev/i18n/de/Ruby/checks/all.md +249 -0
  17. package/Dev/i18n/de/Ruby/commands/check.md +28 -0
  18. package/Dev/i18n/de/Ruby/rules/02-architecture-ruby.md +547 -0
  19. package/Dev/i18n/de/Ruby/rules/03-coding-standards.md +451 -0
  20. package/Dev/i18n/de/Ruby/rules/06-tooling.md +472 -0
  21. package/Dev/i18n/de/Ruby/rules/07-testing-ruby.md +542 -0
  22. package/Dev/i18n/de/Ruby/rules/08-quality-tools.md +397 -0
  23. package/Dev/i18n/de/Ruby/rules/11-security-ruby.md +566 -0
  24. package/Dev/i18n/en/Common/rules/12-context-management.md +1 -0
  25. package/Dev/i18n/en/Ruby/CLAUDE.md.template +92 -0
  26. package/Dev/i18n/en/Ruby/agents/ruby-reviewer.md +667 -0
  27. package/Dev/i18n/en/Ruby/checks/all.md +249 -0
  28. package/Dev/i18n/en/Ruby/commands/check.md +28 -0
  29. package/Dev/i18n/en/Ruby/rules/02-architecture-ruby.md +547 -0
  30. package/Dev/i18n/en/Ruby/rules/03-coding-standards.md +451 -0
  31. package/Dev/i18n/en/Ruby/rules/06-tooling.md +472 -0
  32. package/Dev/i18n/en/Ruby/rules/07-testing-ruby.md +542 -0
  33. package/Dev/i18n/en/Ruby/rules/08-quality-tools.md +397 -0
  34. package/Dev/i18n/en/Ruby/rules/11-security-ruby.md +566 -0
  35. package/Dev/i18n/es/Common/rules/12-context-management.md +1 -0
  36. package/Dev/i18n/es/Ruby/CLAUDE.md.template +92 -0
  37. package/Dev/i18n/es/Ruby/agents/ruby-reviewer.md +667 -0
  38. package/Dev/i18n/es/Ruby/checks/all.md +250 -0
  39. package/Dev/i18n/es/Ruby/commands/check.md +28 -0
  40. package/Dev/i18n/es/Ruby/rules/02-architecture-ruby.md +547 -0
  41. package/Dev/i18n/es/Ruby/rules/03-coding-standards.md +451 -0
  42. package/Dev/i18n/es/Ruby/rules/06-tooling.md +472 -0
  43. package/Dev/i18n/es/Ruby/rules/07-testing-ruby.md +542 -0
  44. package/Dev/i18n/es/Ruby/rules/08-quality-tools.md +397 -0
  45. package/Dev/i18n/es/Ruby/rules/11-security-ruby.md +566 -0
  46. package/Dev/i18n/fr/Common/rules/12-context-management.md +1 -0
  47. package/Dev/i18n/fr/Ruby/CLAUDE.md.template +92 -0
  48. package/Dev/i18n/fr/Ruby/agents/ruby-reviewer.md +667 -0
  49. package/Dev/i18n/fr/Ruby/checks/all.md +249 -0
  50. package/Dev/i18n/fr/Ruby/commands/check.md +28 -0
  51. package/Dev/i18n/fr/Ruby/rules/02-architecture-ruby.md +547 -0
  52. package/Dev/i18n/fr/Ruby/rules/03-coding-standards.md +451 -0
  53. package/Dev/i18n/fr/Ruby/rules/06-tooling.md +472 -0
  54. package/Dev/i18n/fr/Ruby/rules/07-testing-ruby.md +542 -0
  55. package/Dev/i18n/fr/Ruby/rules/08-quality-tools.md +397 -0
  56. package/Dev/i18n/fr/Ruby/rules/11-security-ruby.md +566 -0
  57. package/Dev/i18n/pt/Common/rules/12-context-management.md +1 -0
  58. package/Dev/i18n/pt/Ruby/CLAUDE.md.template +92 -0
  59. package/Dev/i18n/pt/Ruby/agents/ruby-reviewer.md +667 -0
  60. package/Dev/i18n/pt/Ruby/checks/all.md +249 -0
  61. package/Dev/i18n/pt/Ruby/commands/check.md +28 -0
  62. package/Dev/i18n/pt/Ruby/rules/02-architecture-ruby.md +547 -0
  63. package/Dev/i18n/pt/Ruby/rules/03-coding-standards.md +451 -0
  64. package/Dev/i18n/pt/Ruby/rules/06-tooling.md +472 -0
  65. package/Dev/i18n/pt/Ruby/rules/07-testing-ruby.md +542 -0
  66. package/Dev/i18n/pt/Ruby/rules/08-quality-tools.md +397 -0
  67. package/Dev/i18n/pt/Ruby/rules/11-security-ruby.md +566 -0
  68. package/Dev/scripts/check-config.sh +1 -1
  69. package/Dev/scripts/install-from-config.sh +3 -0
  70. package/Dev/scripts/install-ruby-rules.sh +155 -0
  71. package/Dev/stack-profiles/ruby/permissions.txt +4 -0
  72. package/Dev/stack-profiles/ruby/quality.md +3 -0
  73. package/Dev/stack-profiles/ruby/stack.txt +2 -0
  74. package/README.md +8 -3
  75. package/bundles/cursor/.cursorrules +4 -3
  76. package/bundles/windsurf/.windsurfrules +4 -3
  77. package/cli/lib/doctor.js +1 -1
  78. package/cli/lib/tech-registry.js +10 -0
  79. package/package.json +1 -1
@@ -0,0 +1,113 @@
1
+ # New Feature Development Checklist - Ruby / Rails
2
+
3
+ ## Before Starting
4
+
5
+ - [ ] Feature discussed and validated with the team
6
+ - [ ] Acceptance criteria written (Given/When/Then)
7
+ - [ ] Assumptions stated explicitly (inputs, invariants, volume, authorization)
8
+ - [ ] API contract defined if exposed (OpenAPI 3.x, error format RFC 9457)
9
+ - [ ] Database changes identified (tables, columns, indexes, constraints)
10
+ - [ ] Impact analysis done: files touched, breaking changes, rollback plan
11
+ - [ ] Feature flag decided for risky changes (Flipper or equivalent)
12
+
13
+ ## Development (TDD: Red, Green, Refactor)
14
+
15
+ ### Design (Rails Way first)
16
+
17
+ - [ ] Start with conventional Rails: model, `resources` route, RESTful controller, views
18
+ - [ ] New behavior modeled as a resource (`resources :refunds`) rather than a custom action
19
+ - [ ] Extract a service/form/query object only when a model or controller action grows unwieldy (YAGNI)
20
+ - [ ] No speculative abstractions, options, or parameters
21
+
22
+ ### Model Layer
23
+
24
+ - [ ] Validations match database constraints (`null: false`, unique index, check constraint)
25
+ - [ ] Associations declare `dependent:` and `inverse_of` where needed
26
+ - [ ] Scopes are chainable and named for intent
27
+ - [ ] Enums defined with explicit values (`enum :status, { pending: 0, paid: 1 }`)
28
+ - [ ] Callbacks limited to data normalization; side effects in jobs or services
29
+ - [ ] Sensitive attributes encrypted (`encrypts :field`)
30
+
31
+ ### Database
32
+
33
+ - [ ] Migration generated with `bin/rails generate migration` and is reversible
34
+ - [ ] Foreign keys and indexes on every reference
35
+ - [ ] Large-table changes done safely (concurrent index, backfill in a separate step)
36
+ - [ ] `db/schema.rb` committed
37
+
38
+ ### Controller and Routes
39
+
40
+ - [ ] Only REST actions; thin actions (<= 10 lines)
41
+ - [ ] Strong parameters via `params.expect(...)` (Rails 8) or `require/permit`
42
+ - [ ] Authentication and authorization enforced; records loaded through the current user's scope
43
+ - [ ] `rate_limit` added on sensitive endpoints (login, password reset, expensive operations)
44
+ - [ ] Turbo-friendly responses (`redirect_to` with `status: :see_other` after mutations, `turbo_stream` where useful)
45
+ - [ ] Errors rendered consistently (422 for validation, 404 for missing, 403 for forbidden)
46
+
47
+ ### Views and Hotwire
48
+
49
+ - [ ] Partials and components small and reusable; no logic in templates
50
+ - [ ] Turbo Frames/Streams used for partial updates before reaching for custom JavaScript
51
+ - [ ] Stimulus controllers small, one concern each
52
+ - [ ] Output escaped by default; no `html_safe` on user input
53
+ - [ ] Accessibility checked (labels, focus order, contrast)
54
+ - [ ] I18n keys used for user-visible text (`t(".title")`)
55
+
56
+ ### Background Work
57
+
58
+ - [ ] Operations > 200 ms moved to Active Job
59
+ - [ ] Jobs idempotent, take GlobalID/IDs, declare `retry_on` / `discard_on`
60
+ - [ ] Queue configured (Solid Queue by default in Rails 8) and monitored
61
+
62
+ ### Code Quality
63
+
64
+ - [ ] RuboCop passes (`bin/rubocop`)
65
+ - [ ] `# frozen_string_literal: true` in new files
66
+ - [ ] Naming explicit; comments explain WHY
67
+ - [ ] Types added if the project uses RBS/Steep or Sorbet, and the checker passes
68
+
69
+ ## Testing
70
+
71
+ - [ ] Model tests: validations, associations, scopes, domain methods
72
+ - [ ] Service/form/query object tests: success and each failure path
73
+ - [ ] Request (integration) tests for every new endpoint, including unauthenticated and unauthorized cases
74
+ - [ ] System test (Capybara) for the main user journey
75
+ - [ ] Job and mailer tests where added
76
+ - [ ] Factories (or fixtures) added and minimal
77
+ - [ ] Coverage stays >= 80%; time frozen with `travel_to`; external HTTP stubbed
78
+
79
+ ## Security
80
+
81
+ - [ ] Brakeman clean; bundler-audit clean
82
+ - [ ] No string interpolation in SQL; no `permit!`
83
+ - [ ] IDOR checked: users cannot reach other users' or tenants' records
84
+ - [ ] Secrets in credentials, not in code
85
+ - [ ] New logs do not contain sensitive data (`filter_parameters` updated)
86
+
87
+ ## Performance
88
+
89
+ - [ ] No N+1 (`includes`, `preload`, `strict_loading`)
90
+ - [ ] Pagination on list endpoints (Pagy or Kaminari)
91
+ - [ ] Caching considered for hot reads (fragment cache, `Rails.cache.fetch`)
92
+ - [ ] Query plans checked for new heavy queries (`explain`)
93
+
94
+ ## Documentation
95
+
96
+ - [ ] README or docs updated
97
+ - [ ] API documentation updated
98
+ - [ ] ADR written for significant decisions
99
+ - [ ] CHANGELOG entry added
100
+
101
+ ## Before Merge
102
+
103
+ - [ ] `bin/ci` passes locally and in CI
104
+ - [ ] Self-review of the diff completed
105
+ - [ ] PR description explains the why, links the ticket, lists risks and rollback
106
+ - [ ] Reviewer approval received; squash merge with Conventional Commit title
107
+
108
+ ## Deployment
109
+
110
+ - [ ] Migrations run before the new code starts (Kamal deploy hook or release step)
111
+ - [ ] Feature flag default set; rollback path verified
112
+ - [ ] Monitoring and alerts in place (error tracker, job queue depth)
113
+ - [ ] Smoke test after deploy (`/up` health check and the main flow)
@@ -0,0 +1,111 @@
1
+ # Pre-Commit Checklist - Ruby / Rails
2
+
3
+ ## Quick Validation Before Each Commit
4
+
5
+ All commands run in Docker (`docker compose exec app ...`). The fastest full gate is `bin/ci` (Rails 8.1), which runs the steps defined in `config/ci.rb`.
6
+
7
+ ### Code Quality
8
+
9
+ - [ ] RuboCop clean (`bin/rubocop`, or `bundle exec rubocop`)
10
+ - [ ] Auto-correct applied only for safe cops (`rubocop -a`) and the diff reviewed
11
+ - [ ] `# frozen_string_literal: true` present in new Ruby files
12
+ - [ ] No unused `require`, dead code, or commented-out code
13
+ - [ ] No `binding.irb`, `byebug`, `debugger`, `puts`, `pp` left behind
14
+ - [ ] Methods < 10 lines (limit 20), nesting <= 3, parameters <= 4
15
+
16
+ ### Tests
17
+
18
+ - [ ] All tests pass (`bundle exec rspec` or `bin/rails test`)
19
+ - [ ] System tests pass for touched user journeys (`bin/rails test:system` or `bundle exec rspec spec/system`)
20
+ - [ ] New behavior has tests written first (Red, Green, Refactor)
21
+ - [ ] Bug fixes include a regression test that failed before the fix
22
+ - [ ] Coverage maintained at 80% or higher (SimpleCov)
23
+ - [ ] No skipped or pending tests added without a ticket
24
+
25
+ ### Security
26
+
27
+ - [ ] Brakeman clean (`bin/brakeman --no-pager -q`)
28
+ - [ ] `bundle exec bundler-audit check --update` reports no advisories
29
+ - [ ] No hardcoded secrets; `config/master.key` and `.env` not staged
30
+ - [ ] Strong parameters on new controller actions (no `permit!`)
31
+ - [ ] No string interpolation in `where`, `order`, or raw SQL fragments
32
+ - [ ] No new `html_safe` / `raw` on user-provided data
33
+ - [ ] New actions authorized (and rate limited when they authenticate or send mail)
34
+
35
+ ### Database
36
+
37
+ - [ ] Migration is reversible, has indexes and foreign keys, and `db/schema.rb` is updated
38
+ - [ ] No data backfill mixed into the schema migration
39
+ - [ ] `bin/rails db:migrate` then `db:rollback` then `db:migrate` works locally
40
+ - [ ] N+1 checked on new queries (`includes`, `preload`, `strict_loading`, Bullet)
41
+
42
+ ### Dependencies
43
+
44
+ - [ ] `Gemfile.lock` committed and consistent (`bundle check`)
45
+ - [ ] New gems justified (maintained, license compatible, no overlap with Rails built-ins)
46
+
47
+ ### Documentation and Git
48
+
49
+ - [ ] README / docs updated when behavior or setup changed
50
+ - [ ] CHANGELOG updated if applicable
51
+ - [ ] Commit message follows Conventional Commits (`feat(orders): add refund endpoint`)
52
+ - [ ] Commit is atomic; branch up to date with `main`
53
+ - [ ] No unrelated files staged (`git status`, `git diff --staged`)
54
+
55
+ ## Automated Validation
56
+
57
+ ### Rails 8.1 `bin/ci`
58
+
59
+ ```ruby
60
+ # config/ci.rb
61
+ CI.run do
62
+ step "Setup", "bin/setup --skip-server"
63
+ step "Style: Ruby", "bin/rubocop"
64
+ step "Security: Gem audit", "bin/bundler-audit"
65
+ step "Security: Brakeman", "bin/brakeman --quiet --no-pager --exit-on-warn --exit-on-error"
66
+ step "Tests: Rails", "bin/rails test"
67
+ step "Tests: System", "bin/rails test:system"
68
+ end
69
+ ```
70
+
71
+ Run it in the container:
72
+
73
+ ```bash
74
+ docker compose exec app bin/ci
75
+ ```
76
+
77
+ ### Git pre-commit hook (Lefthook)
78
+
79
+ ```yaml
80
+ # lefthook.yml
81
+ pre-commit:
82
+ parallel: true
83
+ commands:
84
+ rubocop:
85
+ glob: "*.rb"
86
+ run: docker compose exec -T app bundle exec rubocop --force-exclusion {staged_files}
87
+ brakeman:
88
+ glob: "{app,config,lib}/**/*.rb"
89
+ run: docker compose exec -T app bin/brakeman --no-pager -q
90
+ pre-push:
91
+ commands:
92
+ tests:
93
+ run: docker compose exec -T app bin/rails test
94
+ ```
95
+
96
+ Replace `bin/rails test` with `bundle exec rspec` on RSpec projects. Hooks are requirements, CLAUDE.md is a suggestion.
97
+
98
+ ## Quick Commands
99
+
100
+ ```bash
101
+ docker compose exec app bin/rubocop -a
102
+ docker compose exec app bin/brakeman --no-pager -q
103
+ docker compose exec app bundle exec bundler-audit check --update
104
+ docker compose exec app bin/rails test # or: bundle exec rspec
105
+ docker compose exec app bin/rails zeitwerk:check
106
+ docker compose exec app bin/ci
107
+ ```
108
+
109
+ ## Final Check
110
+
111
+ If any box is unchecked, do not commit. Fix first, then re-run `bin/ci`.
@@ -0,0 +1,249 @@
1
+ # Check Complete Ruby / Rails Compliance
2
+
3
+ ## Arguments
4
+
5
+ $ARGUMENTS (optional: path to project to analyze)
6
+
7
+ ## Plan Mode
8
+
9
+ > Plan mode is activated automatically when the scope spans multiple modules or requires cross-cutting investigation.
10
+
11
+ ## MISSION
12
+
13
+ Perform a complete compliance audit of the Ruby on Rails project by orchestrating the 4 major checks: Architecture, Code Quality, Tests, and Security. Produce a consolidated report with an overall score out of 100 points.
14
+
15
+ ### Step 1: Audit Preparation
16
+
17
+ Prepare audit environment:
18
+ - [ ] Identify project path to audit
19
+ - [ ] Verify presence of configuration files (`Gemfile`, `Gemfile.lock`, `.ruby-version`, `.rubocop.yml`, `config/application.rb`)
20
+ - [ ] List main directories (`app/`, `config/`, `db/`, `spec/` or `test/`, `lib/`)
21
+ - [ ] Identify Ruby and Rails versions
22
+
23
+ ```bash
24
+ docker compose exec app ruby -v
25
+ docker compose exec app bin/rails -v
26
+ docker compose exec app bin/rails about
27
+ ```
28
+
29
+ **Note**: If $ARGUMENTS provided, use it as project path, otherwise use current directory.
30
+
31
+ ### Step 2: Architecture Audit (25 points)
32
+
33
+ Execute architecture check: `/ruby:check architecture` or follow `.claude/references/ruby/checks/architecture.md`
34
+
35
+ **Evaluated Criteria**:
36
+ - Rails conventions and directory layout (5 pts)
37
+ - Thin controllers (6 pts)
38
+ - Model design and extraction of service/form/query objects (6 pts)
39
+ - Data layer: migrations, constraints, N+1 (4 pts)
40
+ - Background jobs, caching, realtime (Solid Queue/Cache/Cable) (2 pts)
41
+ - Zeitwerk autoloading and dependency direction (2 pts)
42
+
43
+ **Reference**: `.claude/references/ruby/checks/architecture.md`
44
+
45
+ ### Step 3: Code Quality Audit (25 points)
46
+
47
+ Execute code quality check: `/ruby:check code-quality` or follow `.claude/references/ruby/checks/code-quality.md`
48
+
49
+ **Evaluated Criteria**:
50
+ - RuboCop (rubocop-rails-omakase or project config) clean (6 pts)
51
+ - Idiomatic Ruby 4.0 (frozen string literals, pattern matching, keyword args) (5 pts)
52
+ - KISS/DRY/YAGNI and complexity (4 pts)
53
+ - Error handling (4 pts)
54
+ - Naming conventions and documentation (3 pts)
55
+ - Typing (RBS/Steep or Sorbet, optional) and dead code (3 pts)
56
+
57
+ **Reference**: `.claude/references/ruby/checks/code-quality.md`
58
+
59
+ ### Step 4: Testing Audit (25 points)
60
+
61
+ Execute testing check: `/ruby:check testing` or follow `.claude/references/ruby/checks/testing.md`
62
+
63
+ **Evaluated Criteria**:
64
+ - Code coverage with SimpleCov, 80% minimum (7 pts)
65
+ - Model and object unit tests (6 pts)
66
+ - Request and integration tests (5 pts)
67
+ - System tests (Capybara) (3 pts)
68
+ - Factories/fixtures quality (2 pts)
69
+ - Test isolation and speed (2 pts)
70
+
71
+ **Reference**: `.claude/references/ruby/checks/testing.md`
72
+
73
+ ### Step 5: Security Audit (25 points)
74
+
75
+ Execute security check: `/ruby:check security` or follow `.claude/references/ruby/checks/security.md`
76
+
77
+ **Evaluated Criteria**:
78
+ - Brakeman static analysis (6 pts)
79
+ - Dependency vulnerabilities (bundler-audit, Dependabot) (4 pts)
80
+ - Secrets and credentials management (4 pts)
81
+ - Authentication and authorization (4 pts)
82
+ - Injection, XSS and mass assignment prevention (4 pts)
83
+ - Secure configuration, headers, rate limiting (3 pts)
84
+
85
+ **Reference**: `.claude/references/ruby/checks/security.md`
86
+
87
+ ### Step 6: Consolidation and Global Scoring
88
+
89
+ - [ ] Sum the 4 scores (max 100 points)
90
+ - [ ] Identify critical categories (<50%)
91
+ - [ ] List all critical cross-cutting issues
92
+ - [ ] Prioritize actions by impact/effort
93
+ - [ ] Produce final consolidated report
94
+
95
+ **Grading Scale**:
96
+ - 90-100: Excellent - Reference project
97
+ - 75-89: Very Good - Some minor improvements
98
+ - 60-74: Acceptable - Requires improvements
99
+ - 40-59: Insufficient - Major refactoring required
100
+ - 0-39: Critical - Complete overhaul necessary
101
+
102
+ ### Step 7: Recommendations and Action Plan
103
+
104
+ - [ ] Identify top 3 priority actions across all categories
105
+ - [ ] Estimate effort (Low/Medium/High) and impact (Low/Medium/High) for each
106
+ - [ ] Propose implementation order
107
+ - [ ] Suggest quick wins (high impact/effort ratio)
108
+
109
+ **Version health** (reported in the executive summary, not scored):
110
+ - Ruby 4.0.x is current; Ruby 3.x is accepted but flag a migration plan.
111
+ - Rails 8.1 is supported until 2027-10-10. Rails 8.0 reaches end of life on 2026-11-07: flag it as a high-priority upgrade.
112
+
113
+ ## OUTPUT FORMAT
114
+
115
+ ```
116
+ RUBY / RAILS COMPLIANCE AUDIT - COMPLETE REPORT
117
+ =============================================
118
+
119
+ OVERALL SCORE: XX/100
120
+
121
+ COMPLIANCE LEVEL: [Excellent/Very Good/Acceptable/Insufficient/Critical]
122
+
123
+ Ruby: X.Y.Z Rails: X.Y.Z Test framework: [RSpec/Minitest]
124
+
125
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
126
+
127
+ SCORES BY CATEGORY:
128
+
129
+ ARCHITECTURE : XX/25 [██████████░░░░░░░░░░] XX%
130
+ CODE QUALITY : XX/25 [██████████░░░░░░░░░░] XX%
131
+ TESTS : XX/25 [██████████░░░░░░░░░░] XX%
132
+ SECURITY : XX/25 [██████████░░░░░░░░░░] XX%
133
+
134
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
135
+
136
+ OVERALL STRENGTHS:
137
+ 1. [Strength identified in multiple categories]
138
+ 2. [Other major strength]
139
+ 3. [Third strength]
140
+
141
+ OVERALL IMPROVEMENTS:
142
+ 1. [Cross-cutting improvement]
143
+ 2. [Other recommended improvement]
144
+ 3. [Third improvement]
145
+
146
+ CRITICAL ISSUES:
147
+ 1. [Critical issue #1 - affected category]
148
+ 2. [Critical issue #2 - affected category]
149
+ 3. [Critical issue #3 - affected category]
150
+
151
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
152
+
153
+ DETAILS BY CATEGORY:
154
+
155
+ ┌─────────────────────────────────────────────┐
156
+ │ ARCHITECTURE (XX/25) │
157
+ └─────────────────────────────────────────────┘
158
+
159
+ Sub-scores:
160
+ • Rails conventions / layout : XX/5
161
+ • Thin controllers : XX/6
162
+ • Model design / extraction : XX/6
163
+ • Data layer : XX/4
164
+ • Jobs, cache, realtime : XX/2
165
+ • Autoloading / dependencies : XX/2
166
+
167
+ Strengths:
168
+ - [Architecture strengths]
169
+
170
+ Issues:
171
+ - [Architecture issues]
172
+
173
+ [Similar sections for Code Quality, Tests, and Security...]
174
+
175
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
176
+
177
+ TOP 3 PRIORITY ACTIONS (ALL CATEGORIES):
178
+
179
+ 1. CRITICAL - [Action #1]
180
+ Category : [Architecture/Quality/Tests/Security]
181
+ Impact : [High/Medium/Low]
182
+ Effort : [High/Medium/Low]
183
+ Priority : IMMEDIATE
184
+
185
+ Detailed description:
186
+ [Explanation of problem and proposed solution]
187
+
188
+ Affected files:
189
+ - [file:line]
190
+
191
+ Correction example:
192
+ [Code or correction command]
193
+
194
+ 2. IMPORTANT - [Action #2]
195
+ [Same format...]
196
+
197
+ 3. RECOMMENDED - [Action #3]
198
+ [Same format...]
199
+
200
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
201
+
202
+ QUICK WINS (High Impact / Low Effort):
203
+
204
+ - [Quick win #1] - Category: [X] - Impact: [X] - Effort: [X]
205
+ - [Quick win #2] - Category: [X] - Impact: [X] - Effort: [X]
206
+ - [Quick win #3] - Category: [X] - Impact: [X] - Effort: [X]
207
+
208
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
209
+
210
+ RECOMMENDED ACTION PLAN:
211
+
212
+ WEEK 1 (Immediate):
213
+ - [ ] [Critical action #1]
214
+ - [ ] [Priority quick win]
215
+
216
+ WEEK 2-4 (Short term):
217
+ - [ ] [Important action #2]
218
+ - [ ] [Other quick wins]
219
+
220
+ MONTH 2-3 (Medium term):
221
+ - [ ] [Recommended action #3]
222
+ - [ ] [Progressive improvements]
223
+
224
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
225
+
226
+ EXECUTIVE SUMMARY:
227
+
228
+ [Summary paragraph on overall project state, major strengths,
229
+ major weaknesses, version health (Ruby/Rails support status), and
230
+ recommended trajectory. Say whether the project is production-ready,
231
+ requires corrections, or needs refactoring.]
232
+
233
+ General Recommendation: [Production-ready / Minor corrections /
234
+ Major refactoring / Overhaul necessary]
235
+
236
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
237
+ ```
238
+
239
+ ## IMPORTANT NOTES
240
+
241
+ - This command orchestrates the 4 specialized audits
242
+ - Use Docker for all analysis tools (`docker compose exec app ...`)
243
+ - Provide concrete examples with file:line for each problem
244
+ - Prioritize actions based on Impact/Effort matrix
245
+ - Security problems are ALWAYS top priority
246
+ - Rails Way first: do not penalize a project for lacking hexagonal layering
247
+ - Propose automatable corrections (`bin/ci`, pre-commit hooks, GitHub Actions)
248
+ - Report must be actionable, not just descriptive
249
+ - Adapt recommendations to project business context
@@ -0,0 +1,180 @@
1
+ # Check Ruby / Rails Architecture
2
+
3
+ ## Arguments
4
+
5
+ $ARGUMENTS (optional: path to project to analyze)
6
+
7
+ ## Plan Mode
8
+
9
+ > Plan mode is activated automatically when the scope spans multiple modules or requires cross-cutting investigation.
10
+
11
+ ## MISSION
12
+
13
+ Audit the architecture of the Rails application (Rails 8.1, Ruby 4.0). Stance: **Rails Way first**. Conventions are the default architecture; extract service, form, query or policy objects only when a model or controller grows beyond a readable size ("pragmatic Clean"). Hexagonal layering is NOT required and must not be scored.
14
+
15
+ All commands run in Docker (`docker compose exec app ...`).
16
+
17
+ ### Step 1: Project Structure (5 points)
18
+
19
+ ```bash
20
+ docker compose exec app ls app/ config/ db/ lib/
21
+ docker compose exec app bin/rails about
22
+ docker compose exec app bin/rails stats
23
+ docker compose exec app bin/rails routes --unused | head -50
24
+ ```
25
+
26
+ Checklist:
27
+ - [ ] Standard Rails layout (`app/models`, `app/controllers`, `app/views`, `app/jobs`, `app/mailers`)
28
+ - [ ] Extra objects live under `app/` (for example `app/services`, `app/queries`, `app/forms`, `app/policies`) so Zeitwerk autoloads them
29
+ - [ ] No business code in `lib/` unless it is a genuinely framework-independent library
30
+ - [ ] `config/routes.rb` uses `resources` and shallow nesting (max 1 level)
31
+ - [ ] Rails 8 defaults respected unless a documented ADR says otherwise (Propshaft, importmap or a JS bundler, Solid Queue/Cache/Cable, Kamal)
32
+
33
+ Detect anti-patterns:
34
+
35
+ ```bash
36
+ # Non-RESTful custom routes
37
+ docker compose exec app grep -nE "^\s*(get|post|put|patch|delete) " config/routes.rb | head -30
38
+ # Deep nesting
39
+ docker compose exec app grep -nE "resources .* do" config/routes.rb
40
+ ```
41
+
42
+ **Scoring**: 5 pts, minus 1 per violation (min 0).
43
+
44
+ ### Step 2: Thin Controllers (6 points)
45
+
46
+ Controllers coordinate: authenticate, authorize, load, call, respond. No business rules.
47
+
48
+ ```bash
49
+ # Largest controllers
50
+ docker compose exec app sh -c 'find app/controllers -name "*.rb" | xargs wc -l | sort -rn | head -10'
51
+ # Query building or business logic in controllers
52
+ docker compose exec app grep -rnE "\.(where|joins|includes|group|order)\(" app/controllers | head -30
53
+ # Transactions or bulk writes in controllers
54
+ docker compose exec app grep -rnE "transaction do|\.update_all|\.delete_all" app/controllers | head
55
+ ```
56
+
57
+ Checklist:
58
+ - [ ] Actions are <= 10 lines (target 7)
59
+ - [ ] Only the 7 REST actions per controller; extra behavior becomes a new resource controller
60
+ - [ ] Strong parameters (`params.expect` on Rails 8, or `require(...).permit(...)`) in a private method
61
+ - [ ] Authorization on every action (`before_action`, Pundit, CanCanCan or equivalent)
62
+ - [ ] Concerns used for cross-cutting behavior only, not as a dumping ground
63
+ - [ ] `respond_to` / Turbo Stream responses handled explicitly
64
+
65
+ **Scoring**: 6 pts. Deduct 1 per controller with an action > 15 lines or query-building logic, max -6.
66
+
67
+ ### Step 3: Model Design and Object Extraction (6 points)
68
+
69
+ ```bash
70
+ docker compose exec app sh -c 'find app/models -name "*.rb" | xargs wc -l | sort -rn | head -10'
71
+ docker compose exec app grep -rnE "^\s*(before|after|around)_(save|create|update|destroy|commit)" app/models | wc -l
72
+ docker compose exec app grep -rnE "Net::HTTP|Faraday|HTTParty|deliver_" app/models | head
73
+ docker compose exec app ls app/services app/queries app/forms app/policies
74
+ ```
75
+
76
+ Checklist:
77
+ - [ ] Models contain associations, validations, scopes, and domain behavior; no HTTP calls or mail delivery in callbacks
78
+ - [ ] Callbacks limited to data normalization; side effects moved to jobs or service objects
79
+ - [ ] Models over 200 lines have extracted concerns (cohesive) or objects
80
+ - [ ] Service objects have a single public method (`call`), return a result, no hidden state
81
+ - [ ] Form objects (`ActiveModel::Model`) for multi-model forms
82
+ - [ ] Query objects or scopes for complex reads; no raw SQL fragments scattered across controllers
83
+ - [ ] Enums and value types declared with `enum` / `attribute` rather than magic strings
84
+ - [ ] No God objects: a class named `Manager`, `Helper` or `Processor` with many unrelated methods is a smell
85
+
86
+ **Scoring**: 6 pts. Deduct 1 per god model (> 400 lines), 1 per side-effect callback pattern, 1 per service with more than one responsibility.
87
+
88
+ ### Step 4: Data Layer (4 points)
89
+
90
+ ```bash
91
+ docker compose exec app bin/rails db:migrate:status | tail -20
92
+ docker compose exec app grep -cE "add_foreign_key|add_index|null: false" db/schema.rb
93
+ # N+1 detection tooling
94
+ docker compose exec app grep -nE "bullet|prosopite|strong_migrations" Gemfile
95
+ # Foreign key columns (verify each has an index and a foreign key)
96
+ docker compose exec app grep -nE "_id\"" db/schema.rb | head -30
97
+ ```
98
+
99
+ Checklist:
100
+ - [ ] Every `_id` column has an index and a database foreign key
101
+ - [ ] `null: false`, unique indexes and check constraints mirror model validations
102
+ - [ ] Migrations are reversible and safe (`strong_migrations` if used); no data backfill inside schema migrations
103
+ - [ ] `schema.rb` (or `structure.sql`) committed and in sync (`bin/rails db:migrate` produces no diff)
104
+ - [ ] N+1 prevented via `includes` / `preload` / `strict_loading`; Bullet or Prosopite in development/test
105
+ - [ ] Multi-row writes wrapped in `transaction`; optimistic locking (`lock_version`) where concurrent edits matter
106
+ - [ ] Rails 8 Solid databases (`queue`, `cache`, `cable`) configured in `config/database.yml` when used
107
+
108
+ **Scoring**: 4 pts, minus 1 per failed group above (integrity, migrations, N+1, transactions).
109
+
110
+ ### Step 5: Jobs, Cache, Realtime (2 points)
111
+
112
+ ```bash
113
+ docker compose exec app ls app/jobs
114
+ docker compose exec app grep -rnE "queue_adapter|solid_queue|solid_cache|solid_cable" config
115
+ docker compose exec app grep -rnE "perform_later|deliver_later" app | wc -l
116
+ ```
117
+
118
+ Checklist:
119
+ - [ ] Anything slower than ~200 ms in a request is moved to Active Job (`perform_later`)
120
+ - [ ] Jobs are idempotent and take IDs or GlobalID, not large serialized objects
121
+ - [ ] Retry policy declared (`retry_on`, `discard_on`); failures are observable
122
+ - [ ] Production queue/cache/cable backend configured (Solid Queue/Cache/Cable by default in Rails 8)
123
+ - [ ] Fragment caching or `Rails.cache.fetch` with explicit keys and expiry on hot paths
124
+
125
+ **Scoring**: 2 pts (1 for jobs hygiene, 1 for caching/realtime config).
126
+
127
+ ### Step 6: Autoloading and Dependency Direction (2 points)
128
+
129
+ ```bash
130
+ docker compose exec app bin/rails zeitwerk:check
131
+ docker compose exec app grep -rnE "^\s*(require|require_relative) " app | head
132
+ docker compose exec app grep -rnE "ENV\[" app/models | head
133
+ ```
134
+
135
+ Checklist:
136
+ - [ ] `bin/rails zeitwerk:check` passes ("All is good!")
137
+ - [ ] No `require` / `require_relative` of application files inside `app/`
138
+ - [ ] Models do not depend on controllers or request state; `Current` attributes used sparingly
139
+ - [ ] Engines or namespaces (`app/models/billing/...`) delimit large domains; cross-domain calls go through public methods
140
+ - [ ] Configuration read through `Rails.configuration` / `config_for` / credentials, not scattered `ENV[]`
141
+
142
+ **Scoring**: 2 pts (1 for Zeitwerk, 1 for dependency direction).
143
+
144
+ ## OUTPUT FORMAT
145
+
146
+ ```
147
+ RUBY / RAILS ARCHITECTURE AUDIT
148
+ ===============================
149
+
150
+ SCORE: XX/25
151
+
152
+ Rails: X.Y.Z Ruby: X.Y.Z Models: N Controllers: N Service objects: N
153
+
154
+ SUB-SCORES:
155
+ Structure and conventions : XX/5
156
+ Thin controllers : XX/6
157
+ Model design / extraction : XX/6
158
+ Data layer : XX/4
159
+ Jobs, cache, realtime : XX/2
160
+ Autoloading / dependencies : XX/2
161
+
162
+ STRENGTHS:
163
+ - [...]
164
+
165
+ ISSUES (by severity):
166
+ - CRITICAL: [file:line] [description] -> [fix]
167
+ - IMPORTANT: ...
168
+ - MINOR: ...
169
+
170
+ RECOMMENDATIONS:
171
+ 1. [Action] (effort: Low/Medium/High, impact: Low/Medium/High)
172
+ 2. ...
173
+ ```
174
+
175
+ ## IMPORTANT NOTES
176
+
177
+ - Findings must cite `file:line` and propose a concrete refactoring (for example "extract an `Orders::Place` service from `OrdersController#create`")
178
+ - Do not recommend new abstractions when the code is small and readable (YAGNI)
179
+ - Fat models are acceptable when cohesive; split by responsibility, not by line count alone
180
+ - Never run destructive tasks (`db:drop`, `db:reset`) during an audit