AGENTS.md

1# AGENTS.md
2 
3This file is the entry point for AI coding agents working in this repository. Keep it small: detailed guidance lives under
4`.agents/`, and discoverable repo skills live under `.agents/skills/*/SKILL.md`.
5 
6## Start Here
7 
8Read these files before making changes:
9 
10- [.agents/project.md](.agents/project.md): project overview, versions, and build dependencies.
11- [.agents/commands.md](.agents/commands.md): build, development, code generation, and test commands.
12- [.agents/rules.md](.agents/rules.md): lint, testing, generated-code, and workflow rules.
13 
14Read these only when the task touches their area:
15 
16- [.agents/architecture.md](.agents/architecture.md): core integration, providers, database, managers, build system, and
17  local plugins.
18- [.agents/agent-config.md](.agents/agent-config.md): how to choose between `AGENTS.md`, `.agents`, skills, Codex config,
19  command rules, and hooks.
20- [.agents/skills.md](.agents/skills.md): index of repo-scoped skills in `.agents/skills/`.
21 
22## Highest Priority Rules
23 
24- When the user explicitly requests a scoped, low-risk change, inspect the relevant context and implement it directly.
25  Do not require brainstorming, design documents, implementation plans, multiple-option proposals, or repeated confirmation.
26  Ask only when material ambiguity, destructive impact, additional authority, or scope expansion could change the result.
27- Do not add code or configuration comments unless the user explicitly asks for comments. This includes explanatory,
28  narrative, TODO, and documentation comments.
29- Use `flutter test`, not `dart test`, because models pull in Flutter types.
30- Run code generation after modifying models, providers, or database schema.
31- Do not manually edit generated files.
32- Preserve lifecycle ownership: desktop Core process convergence belongs to `lib/core/desktop/`; Android service intent
33  arbitration belongs to `ServiceState`. UI/provider code may request a transition but must not become a second source of
34  truth.
35- Keep start/stop/restart paths latest-intent-safe. Flutter-to-Android service commands are deliberately optimistic, while
36  native state serializes the actual work; desktop lifecycle results distinguish applied, coalesced, and superseded
37  requests.
38- Follow `analysis_options.yaml`, especially single quotes, trailing commas, `child:` last, no `print()`, const/final
39  preferences, and declared return types.
40- For CI parity, verify with `flutter pub get`, `flutter analyze --no-fatal-infos`, and
41  `flutter test --reporter expanded` when practical.
42 
43## Repo Skills
44 
45Use repo skills from `.agents/skills/` when a task matches their descriptions. Current skills cover localization,
46provider tests, UI work, and core/platform changes.
47