FlClash/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.

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.