AGENTS.md

Project Agent Rules

Git commits

• Never commit on your own initiative. After finishing a change, stop at the working tree and report it; only run git commit (or any other history-changing command such as amend, rebase, cherry-pick, revert, or push) when the user explicitly asks you to commit in that request.
• Deleting throwaway test files and other cleanup is still expected before you report the change as done.
• When you are asked to commit, commit messages must use the repository's Gitmoji format: <emoji> <description>.
• Commit subjects and bodies use Chinese, with a concise imperative description in the subject. This project's commit language and style are fixed by these rules; do not read Git history to infer them or imitate past wording.
• Use the project gitmoji-commit skill and its selection reference. Choose the emoji from the commit's primary intent and actual staged diff, using the official Gitmoji semantics; consider specific-purpose icons before generic ones.
• Do not limit selection to familiar icons or force variety. Prefer a specific icon when it describes the primary intent; an incidental implementation detail does not override that intent.
• Do not add Conventional Commit prefixes such as fix: or feat: after the emoji.
• If the pre-commit hook formats tracked Dart files after the commit is created and leaves only formatting changes in the working tree, stage them and amend that local commit instead of creating a separate formatting commit. Never amend a commit that has already been pushed.

Windows filesystem integrity

• Never lower the integrity level of the project root, its parent directories, any project subdirectories, or generated files (including build outputs and executables) to Low or Untrusted. Keep project and build paths at the normal Medium level.
• This prohibition covers direct commands such as icacls /setintegritylevel L (including inheritable forms), Windows security APIs, helper scripts, and tool or sandbox setup under the agent's control. Do not lower integrity levels to work around sandbox, file access, build, launch, or debugging errors.
• Diagnose access errors by inspecting integrity labels, access rules, and processes holding files open. When an existing Low label causes a confirmed issue, restore only the affected paths to Medium and preserve unrelated access rules and ownership. Do not lower the integrity of system or user temporary directories to accommodate a Low process.
• If an external tool applies Low labels again, report the affected paths and available evidence about the source. Do not compensate by lowering additional directories or files.

Dependencies

• Keep package entries in pubspec.yaml alphabetically ordered by package name within dependencies, dev_dependencies, and dependency_overrides when present. Preserve each package's version, source configuration, and associated comments when reordering.

Tests

• When one-off verification requires temporary scripts, standalone test harnesses, or small builds, create a new purpose-named subdirectory under the project-root temp/ directory (for example, temp/rss-parser-check/). Keep all related scripts, source files, fixtures, build configurations, intermediate files, and outputs inside that subdirectory.
• For logic that needs ongoing maintenance against real-world data, such as episode matching, keep functional regression tests and their required fixtures and helpers under the project-root test/ directory, organized by feature or purpose. Retain these files after verification; they may be included with related changes when the user requests a commit and are exempt from the temporary-file cleanup rules below.
• One-off test files written while implementing a change are throwaway verification aids. After the feature or fix has been verified, delete them before creating the commit that delivers the change.
• Do not commit temporary verification files (tests, fixtures, or helper scripts) unless the user explicitly asks for them to be committed.
• If temporary verification files were already staged, unstage and delete them before committing.
• Unless explicitly told otherwise, do not write tests that require UI interaction (widget/page interaction, taps, navigation, dialogs, screenshots, and the like). The developer triggers those flows by hand.
• Only test functional behavior (pure logic, parsing, data transformations, protocol handling, persistence queries, and similar non-UI code). Do not go out of your way to build UI verification harnesses.
• Unless the user explicitly requests it, do not compile or build the entire project (for example, flutter build or dev_build.ps1) just to verify a change.
• This restriction does not apply to static code analysis. flutter analyze, dart analyze, MCP analyze_files, and similar code evaluation tools are allowed as needed; prefer analyzing the affected files when the tool supports it.
• The bt_download test suite remains opt-in and is run by hand by the developer: inside repos/bt_download run cmake --preset windows-x64-debug-tests, cmake --build --preset windows-x64-debug-tests, then ctest --preset windows-x64-debug-tests. Neither dev_build.ps1 nor the release workflow may build or run it.
• Do not start the app, drive it through MCP tooling, or run manual UI verification unless the user explicitly asks for it.

UI interaction

• In compact toolbars and list/card action bars, default to flat, icon-only IconButtons with Tooltips and accessible action labels. New actions such as playback follow the same pattern; do not introduce a filled icon-and-text button unless the user requests that style. This default does not require form submission, dialog confirmation, or standalone page actions to become icon-only.
• Keep existing actions directly visible when adding features or optimizing layouts. Do not move them into a "More" menu or dropdown unless the user requests regrouping. When space is limited, wrap the controls or place them on a separate row. Preserve existing tooltips and gestures, including long-press behavior.
• Match neighboring controls' icon size, hit area, spacing, and hover treatment. Keep the button footprint stable while loading: replace the icon with a compact progress indicator and put status or disabled reasons in the tooltip rather than adding inline text.
• Position flyouts outside their triggering controls with a visible gap, keeping the trigger fully visible while the panel is open.
• Open select and dropdown option panels below the selection field, or above it when space is limited. Never align the selected option over the field; constrain and scroll the panel when necessary to preserve the field's visibility.

AniBT integration

• For AniBT RSS, Open API, release metadata, subscriptions, downloads, or AniBT UI changes, read the project anibt skill.
• Verify API behavior against the current official Markdown or OpenAPI documents linked by the skill before changing endpoints, parameters, authentication, or parsing.
• Use the bangumi-today skill for repository architecture and the flutter-mcp skill for Flutter tooling alongside the AniBT skill.