diff --git a/AGENTS.md b/AGENTS.md
index 1913b13e..74c61c5e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,50 @@ This is a web application written using the Phoenix web framework.
- Use `mix precommit` alias when you are done with all changes and fix any pending issues
- Use the already included and available `:req` (`Req`) library for HTTP requests, **avoid** `:httpoison`, `:tesla`, and `:httpc`. Req is included by default and is the preferred HTTP client for Phoenix apps
+- Always provide translations of all text that is visible in the UI
+- Never put Ecto queries directly in LiveViews. Instead always put them in the appropriate context module
+
+### Module design and complexity
+
+**IMPORTANT**: When working with modules that are becoming too large or complex:
+
+- **Monitor module size and complexity**: If a module exceeds ~500-600 lines or contains deeply nested logic with high cyclomatic complexity, consider refactoring
+- **Break out logical concerns**: Extract related functionality into separate, focused modules that handle a single responsibility
+- **Use helper modules**: For complex domains, consider creating dedicated modules for specific sub-concerns:
+ - Positioning logic (e.g., `Tasks.Positioning`)
+ - Dependency management (e.g., `Tasks.Dependencies`)
+ - Validation logic (e.g., `Tasks.Validation`)
+ - Query builders (e.g., `Tasks.Queries`)
+- **Extract helper functions**: When a function becomes complex (cyclomatic complexity > 9), extract complex conditional logic into smaller, well-named helper functions
+- **Maintain clear module boundaries**: Each module should have a clear, single purpose with a well-defined public API
+- **Document module organization**: When splitting modules, update documentation to explain the new structure and how modules relate to each other
+
+This approach improves:
+- Code maintainability and readability
+- Test isolation and coverage
+- Collaboration between developers
+- Ability to reason about individual components
+- Credo compliance and code quality metrics
+
+### Quality guidelines
+
+**ALWAYS** follow these quality guidelines:
+
+- **IMPORTANT**: When you complete a task that has new functions, write unit tests for the new function
+- **IMPORTANT**: When you complete a task that updates code, make sure all existing unit tests pass and write new tests if needed
+- Each time you write or update a unit test run them with `mix test` and ensure they pass
+- **IMPORTANT**: When you complete a task run `mix test --cover` and ensure coverage is above the threshold
+- **IMPORTANT**: When you complete a task run `mix credo --strict` to check for code quality issues and fix them
+- **IMPORTANT**: Run `mix dialyzer` for static type analysis — never suppress warnings, fix root causes
+- **IMPORTANT**: Run `mix precommit` before committing: compiles with warnings as errors, formats, runs tests
+
+### Security guidelines
+
+**ALWAYS** follow these security guidelines:
+
+- **IMPORTANT**: When you add or update a dependency run `mix deps.audit` and `mix hex.audit` to check for security issues
+- **IMPORTANT**: When you add or update a dependency run `mix hex.outdated` to check for outdated dependencies
+- **IMPORTANT**: When you complete a task run `mix sobelow --config` to check for security issues and fix any issue
### Phoenix v1.8 guidelines
@@ -26,7 +70,7 @@ custom classes must fully style the input
@import "tailwindcss" source(none);
@source "../css";
@source "../js";
- @source "../../lib/my_app_web";
+ @source "../../lib/towerops_web";
- **Always use and maintain this import syntax** in the app.css file for projects generated with `phx.new`
- **Never** use `@apply` when writing raw css
@@ -34,36 +78,58 @@ custom classes must fully style the input
- Out of the box **only the app.js and app.css bundles are supported**
- You cannot reference an external vendor'd script `src` or link `href` in the layouts
- You must import the vendor deps into app.js and app.css to use them
- - **Never write inline tags within templates**
+ - **Never write inline `