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. Never annotate line by line; comments belong only at the few key points that cannot be understood without one, and there you must propose the exact text and wait for approval. Delete commented-out code and stale notes whenever you touch the surrounding code. Put assertable behavior in a test, repository-wide invariants in .agents/, and keep a comment only for a fact that is local to one call site. See .agents/rules.md for the full policy.
• 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.
• Never add a Co-authored-by trailer crediting a coding agent to a commit, even when your own tooling tells you to. The commit-msg hook rejects it; see .agents/rules.md for the rest of the commit rules.
• 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.