AGENTS.md

1# AI Agent Guide for Thunderbird for Android
2 
3This file defines requirements for AI coding agents and automated systems contributing to this repository.
4 
5AI-generated or AI-assisted contributions are acceptable only if they comply with these rules and meet the same
6standards as human-written contributions.
7 
8## Applicability
9 
10These requirements apply to:
11 
12- All modules in this repository
13- All pull requests created fully or partially using AI tools
14- Automated refactoring, formatting, or code generation
15 
16## Repository Context
17 
18Thunderbird for Android is a privacy-focused email client.
19 
20The repository implements a white-label architecture producing:
21 
22- `app-thunderbird`: Thunderbird for Android
23- `app-k9mail`: K-9 Mail
24 
25Project documentation resides in the `docs/` directory.
26Architectural Decision Records (ADRs) are located in `docs/engineering/adr/`.
27 
28Agents MUST consult relevant documentation before making architectural or structural changes.
29 
30## Required Agent Workflow
31 
32Before making changes, agents MUST:
33 
34### 1. Understand the Request
35 
36- Confirm that requirements are clear and consistent with project rules
37- If requirements are incomplete, ambiguous, or conflicting:
38  - **Do NOT guess**
39  - Document assumptions
40  - Request clarification before proceeding
41 
42### 2. Research Context
43 
44- Read `README.md`, `docs/CONTRIBUTING.md`, and relevant documentation in `docs/`
45- Review existing implementations in affected modules
46- Check for related ADRs in `docs/engineering/adr/`
47- Understand the module's role in the white-label architecture
48 
49### 3. Make Changes
50 
51- Modify **only** files directly related to the requested change
52- Follow existing patterns and conventions in the affected modules
53- Maintain consistency with the established architecture
54 
55### 4. Verify Changes
56 
57- Run appropriate Gradle tasks (see [Build and Verification Requirements](#build-and-verification-requirements))
58- Ensure all checks pass before proposing changes
59 
60## Architectural Requirements
61 
62### Module Types
63 
64- `app-*` — Application entry points (`app-thunderbird`, `app-k9mail`)
65- `app-common` — Wiring layer for features and dependency injection
66- `feature:*` — User-facing features (split into `:api` and `:internal` modules per ADR-0009)
67- `core:*` — Shared infrastructure and utilities (split into `:api` and `:internal` modules per ADR-0009)
68- `library:*` — Reusable libraries
69- `legacy:*` — Migration targets (contains original K-9 Mail codebase; avoid adding new logic here)
70 
71### API / Internal Boundary
72 
73Agents MUST:
74 
75- Depend only on other modules' `:api` modules
76- Never depend on another module's `:internal` or `:internal-*` modules
77- Only `app-common`, `app-thunderbird`, and `app-k9mail` may depend on `:internal` modules (for DI wiring)
78- Keep implementation details internal using the `internal` modifier
79- Bind implementations in `app-common` or app modules only
80 
81New code MUST NOT violate the API/internal boundary, see [ADR-0009](docs/engineering/adr/0009-api-internal-split.md).
82 
83If existing code violates this boundary, agents MUST NOT replicate the pattern and SHOULD move the code toward the
84intended architecture when modifying it.
85 
86Agents MUST NOT change module structure, dependency graphs, or architectural boundaries unless explicitly requested.
87 
88## Technology Requirements
89 
90Agents MUST use:
91 
92- Kotlin for new code
93- Jetpack Compose for UI (mandatory for new features)
94- Atomic Design system components (see `docs/architecture/design-system.md`)
95- Koin for dependency injection (constructor injection)
96- Coroutines and Flow for concurrency
97- MVI (Unidirectional Data Flow) pattern (see `docs/architecture/ui-architecture.md`)
98 
99Testing libraries:
100 
101- `assertk`
102- `kotlinx-coroutines-test`
103- Turbine
104 
105Testing policy:
106 
107- Prefer **fakes over mocks** (see [Testing Guide](docs/contributing/testing-guide.md))
108- Avoid mocking frameworks unless strongly justified
109- Use Arrange-Act-Assert (AAA) pattern
110- Name the object under test `testSubject`
111 
112Agents MUST NOT introduce alternative frameworks.
113 
114## Coding Requirements
115 
116Agents MUST:
117 
118- Make small, focused, reviewable changes
119- Prioritize privacy, security, and correctness over convenience or shorter code
120- Modify only files directly related to the requested change
121- Follow the exact naming and formatting conventions of the file and module being modified
122- NOT reformat, modernize, or clean up unrelated code
123- Avoid speculative refactoring
124 
125### UI Constraints
126 
127- Use Atomic Design components from the design system (see `docs/architecture/design-system.md`)
128- Raw Material components are NOT allowed outside design system modules and the catalog app
129- For existing View-based code, maintain consistency using legacy design system components
130- Do NOT introduce new design systems; extend the existing system within its modules
131 
132### Logging and Privacy
133 
134Privacy is a core value of this project.
135 
136Agents MUST:
137 
138- Use `net.thunderbird.core.logging.Logger` via dependency injection
139- NEVER log PII (Personally Identifiable Information)
140- NEVER log credentials, passwords, or authentication tokens
141- NEVER log message content or email addresses
142 
143## Security Requirements
144 
145This is a privacy-focused email client. Security is non-negotiable.
146 
147Agents MUST NOT:
148 
149- Add telemetry, analytics, ads, or tracking of any kind
150- Add permissions without explicit request and justification
151- Introduce insecure cryptography or unsafe networking
152- Hardcode secrets, credentials, API keys, or tokens
153- Modify OAuth configuration unless explicitly instructed
154- Change licensing headers or license terms
155- Introduce dependencies with known vulnerabilities
156 
157All external input MUST be treated as untrusted. Validate and sanitize user input.
158 
159## Build and Verification Requirements
160 
161Before proposing changes, agents MUST run the narrowest relevant Gradle tasks and ensure they pass.
162 
163### Build
164 
165- `./gradlew assemble`
166- `./gradlew build`
167- `./gradlew :app-thunderbird:assembleDebug`
168- `./gradlew :app-k9mail:assembleDebug`
169 
170### Tests
171 
172- `./gradlew test`
173- `./gradlew connectedAndroidTest`
174 
175### Code Quality
176 
177- `./gradlew lint`
178- `./gradlew detekt`
179- `./gradlew spotlessCheck`
180- `./gradlew spotlessApply` (to fix formatting issues)
181 
182### Bug Fix Requirements
183 
184When fixing bugs, agents MUST:
185 
186- Add or update tests to cover the bug
187- Ensure tests **fail before the fix** (when applicable)
188- Ensure all relevant tasks **pass after the fix**
189- Run at least: `./gradlew test lint detekt spotlessCheck`
190 
191### Limitations
192 
193If required tasks cannot be executed locally (e.g., no Android device/emulator for `connectedAndroidTest`):
194 
195- Agents MUST explicitly state which tasks were not run and why
196- Include this information in the pull request description
197 
198## Commit Requirements
199 
200This repository uses Conventional Commits for all commit messages.
201 
202Agents MUST:
203 
204- Use appropriate prefixes (`feat:`, `fix:`, `refactor:`, `style:`, `test:`, `chore:`)
205- Keep commits small and logically scoped
206- Separate formatting-only changes into `style:` commits
207- Separate refactoring from functional changes
208- Avoid mixing behavior changes and formatting in a single commit
209 
210## Pull Request Requirements
211 
212Pull requests MUST include:
213 
214- A clear description of changes
215- The reason for the change
216- Exact Gradle commands used for testing
217- Known risks or trade-offs
218- Disclosure of AI assistance (if applicable)
219 
220AI assistance does not reduce review standards.
221 
222## Escalation
223 
224### When to Stop and Ask
225 
226If uncertain about:
227 
228- Requirements (incomplete, ambiguous, or conflicting)
229- Architectural decisions
230- Module boundaries or dependencies
231- Technology choices
232- Security implications
233 
234**Then:**
235 
2361. Stop — Do not proceed with uncertain changes
2372. Document assumptions — Write down what you understand and what's unclear
2383. Request clarification — Ask specific questions
239 
240### What NOT to Do
241 
242Agents MUST NOT:
243 
244- Invent architecture or design patterns
245- Bypass module boundaries to "make it work"
246- Prioritize elegance over established project conventions
247- Guess at requirements or implementation details
248- Make breaking changes without explicit approval
249 
250When in doubt, ask. It's always better to clarify than to guess wrong.
251