diff --git a/AGENTS.md b/AGENTS.md
index 9103978d0..dcee062af 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -259,6 +259,14 @@ end
 ```
 
 
+### For planning agents
+
+When planning new features or architectural changes, use the `layered-rails` skill for analysis:
+- `/layered-rails:plan` — plan incremental adoption of layered patterns
+- `/layered-rails:analyze` — full codebase architecture analysis
+- `/layered-rails:review` — review code from a layered architecture perspective
+- `/layered-rails:spec-test` — apply the specification test to evaluate layer placement
+
 ## Important Patterns
 
 ### Controllers
diff --git a/README.md b/README.md
index 4333002a6..a802bbf51 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,26 @@ If you prefer Docker, see the commands in `bin/d*`:
 
 We use Bootstrap 5. Documentation: https://getbootstrap.com/docs/5.2/getting-started/introduction/
 
+## Architectural approach
+
+This project follows layered architecture principles as described in *[Layered Design for Ruby on Rails Applications](https://www.packtpub.com/en-us/product/layered-design-for-ruby-on-rails-applications-9781806114221)* by Vladimir Dementyev. The goal is to organise code into four layers with strict unidirectional dependencies:
+
+| Layer | Responsibility | Key directories |
+|-------|---------------|-----------------|
+| **Presentation** | HTTP/WebSocket concerns | `app/controllers/`, `app/views/`, `app/mailers/` |
+| **Application** | Orchestration, coordination | `app/services/`, `app/form_models/`, `app/policies/` |
+| **Domain** | Business logic, rules | `app/models/`, `app/models/concerns/` |
+| **Infrastructure** | Persistence, external APIs | Active Record models, external service clients |
+
+**Guidelines for contributors:**
+- Keep controllers thin — they should only handle HTTP concerns (params, session, response format)
+- Put business logic in domain models, not services (services orchestrate, they don't own logic)
+- Don't reference `Current` attributes from models — pass values explicitly
+- Extract reusable queries into query objects, complex view logic into presenters
+- Use form objects for multi-model forms or complex validation
+
+AGENTS.md also references these patterns in its *For planning agents* section.
+
 ## Finding something to work on
 
 You can pick one of the open [issues](https://github.com/codebar/planner/issues), fix a bug, improve the interface, refactor the code or improve test coverage!