AGENTS.md

1# App
2 
3## Directory Structure
4 
5- `app/components/` - ViewComponent-based UI components (Ruby + ERB)
6- `app/contracts/` - Validation and authorization contracts
7- `app/controllers/` - Rails controllers
8- `app/models/` - ActiveRecord models
9- `app/services/` - Service objects (business logic)
10- `app/workers/` - Background job workers
11 
12## Code Style Guidelines
13 
14### Ruby
15- Follow [Ruby community style guide](https://github.com/bbatsov/ruby-style-guide)
16- Use service objects for complex business logic (return `ServiceResult`)
17- Use contracts for validation and authorization
18- Keep controllers thin, models focused
19- Document with [YARD](https://yardoc.org/)
20- Write RSpec tests for all new features
21- **Work package identifiers**: `WorkPackage.find("PROJ-42")` resolves semantic identifiers transparently. Use `find_by_display_id` only when input could legitimately be numeric OR semantic (controllers, URL-driven components, macro resolvers). Low-level code (queries, filters, services) should stick to `find_by(id:)` with primary keys. See `app/models/work_package/semantic_identifier/finder_methods.rb`.
22 
23### Templates
24- Use ERB for server-rendered views
25- Use ViewComponents for reusable UI (with Lookbook previews)
26- Lint with erb_lint before committing
27 
28## Translations
29 
30- UI strings must use translation keys (never hard-coded)
31