AGENTS.md

AGENTS.md

This file is the entry point for AI coding agents working in this repository. Keep it small: detailed guidance lives under .agents/, and discoverable repo skills live under .agents/skills/*/SKILL.md.

Start Here

Read these files before making changes:

• .agents/project.md: project overview, versions, and build dependencies.
• .agents/commands.md: build, development, code generation, and test commands.
• .agents/rules.md: lint, testing, generated-code, and workflow rules.
• .agents/fork-workflow.md: fork branches, upstream synchronization, versioning, and releases.
• .agents/fork-changes.md: fork-only changes to preserve, replace, or remove while syncing upstream.

Read these only when the task touches their area:

• .agents/architecture.md: core integration, providers, database, managers, build system, and local plugins.
• .agents/agent-config.md: how to choose between AGENTS.md, .agents, skills, Codex config, command rules, and hooks.
• .agents/skills.md: index of repo-scoped skills in .agents/skills/.

Highest Priority Rules

• When the user explicitly requests a scoped, low-risk change, inspect the relevant context and implement it directly. Do not require brainstorming, design documents, implementation plans, multiple-option proposals, or repeated confirmation. Ask only when material ambiguity, destructive impact, additional authority, or scope expansion could change the result.
• Do not add code or configuration comments unless the user explicitly asks for comments. This includes explanatory, narrative, TODO, and documentation comments.
• Use flutter test, not dart test, because models pull in Flutter types.
• Run code generation after modifying models, providers, or database schema.
• Do not manually edit generated files.
• Preserve lifecycle ownership: desktop Core process convergence belongs to lib/core/desktop/; Android service intent arbitration belongs to ServiceState. UI/provider code may request a transition but must not become a second source of truth.
• Keep start/stop/restart paths latest-intent-safe. Flutter-to-Android service commands are deliberately optimistic, while native state serializes the actual work; desktop lifecycle results distinguish applied, coalesced, and superseded requests.
• Follow analysis_options.yaml, especially single quotes, trailing commas, child: last, no print(), const/final preferences, and declared return types.
• For CI parity, verify with flutter pub get, flutter analyze --no-fatal-infos, and flutter test --reporter expanded when practical.

Repo Skills

Use repo skills from .agents/skills/ when a task matches their descriptions. Current skills cover localization, provider tests, UI work, and core/platform changes.

Fork Workflow

• Keep main as the only long-lived fork integration branch and base it on the latest non-prerelease upstream tag.
• Make product and infrastructure changes on short-lived fix/*, feat/*, chore/*, or sync/* branches.
• Keep fork-wide files such as Actions and agent guidance in main after review; delete their working branches after merge.
• Name fork releases v<upstream-version>-r<number>, for example v0.8.94-r1.
• Follow .agents/fork-workflow.md when synchronizing upstream or preparing a fork release.