Imported from ylstack1/ylagents-stack (
AGENTS.md). Install upstream withnpx skills add ylstack1/ylagents-stack. Copyright stays with the author.
AGENTS.md
Kelivo is a cross-platform Flutter LLM chat client (Android / iOS / macOS / Windows / Linux). This file defines hard constraints for AI-assisted development. Predictable, auditable, repeatable.
1. Repository Facts
- This is a Flutter app repository. Root
pubspec.yamldeclaressdk: ^3.12.1andflutter: >=3.44.1withflutter.generate: true. - Main code lives in
lib/, tests intest/. Local path dependencies exist:dependencies/mcp_clientdependencies/tray_manager/packages/tray_managerdependencies/flutter_ttsdependencies/flutter-permission-handler/permission_handler_windows
- Localization is driven by
l10n.yaml:arb-dir: lib/l10ntemplate-arb-file: app_en.arboutput-localization-file: app_localizations.dartuntranslated-messages-file: desiredFileName.txt
- There are exactly 4 ARB files that must stay in sync:
lib/l10n/app_en.arblib/l10n/app_zh.arblib/l10n/app_zh_Hans.arblib/l10n/app_zh_Hant.arb
- The following are generated or build artifacts. Never hand-edit them:
lib/l10n/app_localizations*.dartlib/core/models/*.g.dart- All other generated logic must go through commands, not manual edits
.dart_tool/**build/**
- The package name is
Kelivo. Existing imports usepackage:Kelivo/...everywhere. Do not "normalize" the package name. - Top-level platform entry is
_selectHome()inlib/main.dart:- macOS / Windows / Linux ->
DesktopHomePage - Android / iOS ->
HomePage
- macOS / Windows / Linux ->
- Desktop is NOT "mobile stretched wider":
lib/desktop/desktop_home_page.dartis the desktop app shell: nav rail, window title bar, hotkeys, desktop settings, translate/storage tabs, and other desktop-level interactionslib/desktop/desktop_chat_page.dartis the desktop chat entry, currently reusingHomePagelib/features/home/pages/home_page.dartonly handles the shared chat page, switching internally by width tohome_mobile_layout.dartorhome_desktop_layout.dart- Therefore "wide/tablet layout" != "desktop app entry". Do not conflate them.
- Reusable UI primitives live in these locations:
lib/shared/widgets/ios_tactile.dart:IosIconButton,IosCardPresslib/shared/widgets/ios_tile_button.dartlib/shared/widgets/ios_switch.dartlib/shared/widgets/ios_checkbox.dartlib/shared/widgets/ios_form_text_field.dartlib/desktop/widgets/desktop_select_dropdown.dartlib/shared/dialogs/**lib/shared/responsive/**
- Theme and dynamic color follow the repo as-is:
lib/theme/**is the single source of truth for theming and tokens- Android dynamic color is only enabled per-platform in
main.dart. Do not extrapolate Android visual or interaction rules to desktop.
2. Working Style
- Communicate in Chinese throughout. Stay focused on the current task. No vague suggestions.
- Facts first. All conclusions must be based on current code, config, tests, build scripts, or git state. No guessing.
- Debug-first. Never add silent degradation, swallowed errors, hidden fallback paths, or fake success branches just to "make it run".
- Default to KISS / YAGNI:
- Use the most direct, most verifiable approach first.
- Do not pre-plant extra layers, empty abstractions, or config switches for "architectural completeness" or "might need it later".
- SOLID is a tool, not a goal:
- Only split responsibilities when it genuinely reduces coupling and improves readability.
- Do not shatter simple logic into a chain of tiny files just for formal layering.
- Minimal closed loop. Make only the minimum change needed for the current task. Do not fix unrelated issues on the side.
- Parallel context gathering by default during exploration:
- Independent file reads,
rgsearches,git status, config checks, and log inspections should be batched in a single parallel round. - Do not serialize what can be parallelized.
- Independent file reads,
- For complex tasks, write a brief Mini Control Contract before touching code:
Primary Setpoint: What exactly must be achievedAcceptance: What command, test, or behavior proves itGuardrails: What must not break as a side effectBoundary: Which files/modules are in scopeRisks: 1 to 3 key risks
3. Mandatory Rules
3.1 All User-Visible Text Must Be Localized
- No user-visible text may be hardcoded in Dart UI code. This includes but is not limited to:
- Page titles
- Button labels
SnackBar/Dialog/TooltipcontentsemanticLabel- Notification text
- Tray menu text
- When adding or modifying user-visible strings, ALL 4 files must be updated simultaneously:
lib/l10n/app_en.arblib/l10n/app_zh.arblib/l10n/app_zh_Hans.arblib/l10n/app_zh_Hant.arb
- Updating only
app_en.arbor onlyapp_zh.arband stopping is not acceptable. - Placeholders, plurals, selects, and
@keymetadata must be consistent across all four ARB files. - New keys follow the existing camelCase convention with a feature prefix. Do not use context-free short names like
title1orlabelText. - After ARB changes, run:
flutter gen-l10n
- Never hand-edit
lib/l10n/app_localizations.dartorlib/l10n/app_localizations_*.dart. desiredFileName.txtis the untranslated messages file. Do not introduce new untranslated entries. If you add a key, provide translations for all languages in the same change.
3.2 Generated Code Must Be Maintained Via Commands
- After modifying Hive models,
@HiveType,@HiveField, orpart '*.g.dart'references, run:
dart run build_runner build --delete-conflicting-outputs
- Generated file changes must correspond strictly to source changes. Do not hand-craft
*.g.dartfiles.
3.3 Format Code Before Finishing
- Any change to Dart/Flutter code requires formatting before completion.
- Prefer formatting only the changed paths. For large changes, format
lib/andtest/.
dart format <changed-paths>
- Unformatted code must not be committed.
3.4 Minimum Sufficient Verification After Completion
- Default minimum verification loop:
flutter analyze
flutter test
- If the change scope is clearly narrow, at minimum run the relevant test subset and explain in the delivery notes why only a subset was run.
- If the following content types are modified, the corresponding extra action is mandatory:
| Change Type | Required Action |
|---|---|
| ARB / localization | flutter gen-l10n, check desiredFileName.txt, then flutter analyze |
| Hive model / generated code | dart run build_runner build --delete-conflicting-outputs, then run related tests |
pubspec.yaml / dependencies |
flutter pub get, then flutter analyze and related tests |
.github/workflows/** / build scripts |
Check ALL similar workflow files, not just one |
Platform directories android/ ios/ macos/ linux/ windows/ |
At least one targeted platform verification; if impossible, state why explicitly |
dependencies/** path dependencies |
Run analysis/tests in the dependency's own directory, not just the root repo |
lib/desktop/**, desktop hotkeys/tray/window logic |
At least one desktop-targeted verification (e.g. flutter run -d macos, flutter build macos, or the corresponding Windows/Linux target); if only the current machine's platform was verified, state the uncovered platform boundary |
- If local environment limitations prevent completing any verification, the final delivery notes must explicitly state "what was not run, why, and where the risk lies".
3.5 Do Not Hand-Edit or Commit What Should Not Be Committed
- Never hand-edit:
.dart_tool/**build/**- Content maintained by
flutter gen-l10n/build_runner
- Do not modify unless required by the task:
.idea/**- Platform signing, certificates, personal environment files
- Workflows unrelated to the current task
3.6 Secrets and Fallback Mechanisms
- Never commit real secrets to source code.
lib/secrets/fallback.dartcurrently contains placeholder implementations. CI injects real values across multiple workflows. Do not write real keys into the repo.- Do not silently add new fallback keys, fallback APIs, or error-swallowing logic just to "make it run".
- If a fallback mechanism is genuinely needed, it must satisfy ALL of:
- Explicit toggle
- Clear logging
- Can be disabled
- Reason documented in the task description
3.7 Change Boundary and Duplicate Workflows
- This repo has multiple similar GitHub Actions workflow files, especially for builds. When touching build, versioning, or injection logic, check ALL similar workflows for sync.
- Do not expand scope just because you spotted something that "could be unified". Finish the current task first, then decide whether to open a separate refactoring task.
- When touching a path dependency, treat it as an independent module. Do not only patch the surface at the root repo level.
3.8 Desktop Tasks: Determine Entry Layer First
- When the task mentions desktop, Windows, macOS, Linux, tray, hotkeys, window, context menu, or desktop settings, first determine which layer the issue belongs to:
- Top-level desktop app shell:
lib/desktop/** - Shared chat content layer:
lib/features/home/** - Platform services or providers:
lib/core/**, platform directories, or path dependencies
- Top-level desktop app shell:
- For desktop app shell changes, check these first:
lib/main.dartlib/desktop/desktop_home_page.dartlib/desktop/desktop_settings_page.dartlib/desktop/setting/**lib/desktop/window_title_bar.dartlib/desktop/desktop_tray_controller.dartlib/desktop/hotkeys/**
- Only when the issue clearly belongs to "shared content area reused by desktop chat page" should you prioritize:
lib/features/home/pages/home_page.dartlib/features/home/pages/home_desktop_layout.dartlib/features/home/widgets/**
- Do not guess desktop platform behavior in
home_mobile_layout.dartor mobile branches. Do not stuff desktop-specific control flow into mobile entry points. - Desktop interactions differ from mobile. For example, chat messages currently use "long-press on mobile, right-click menu on desktop". Desktop tasks must consider hover, right-click, keyboard shortcuts, window size, and title bar -- not just touch gestures.
- If a task spans both the desktop shell and the shared content layer, state the primary landing point in the description first, then apply minimal changes in each respective layer. Do not scatter platform routing across unrelated locations.
3.9 UI Component Reuse and Custom iOS Style Boundary
- Before adding new UI, search these directories for existing components instead of hand-rolling a new one inline:
lib/shared/widgets/**lib/shared/dialogs/**lib/shared/responsive/**lib/desktop/widgets/**
- Prefer reusing or extending existing components, such as:
IosIconButtonIosCardPressIosTileButtonIosSwitchIosCheckboxIosFormTextFieldDesktopSelectDropdownWindowTitleBar
- If a new style will appear on two or more pages, do not keep adding page-private widgets (e.g. new
_IosFilledButton,_TactileIconButton,_CustomDropdownvariants). Extract it tolib/shared/widgets/orlib/desktop/widgets/as a reusable component. - Visual and interaction style defaults to "custom iOS style", not Android style:
- Do not introduce Android ripple, Material default splash, default FAB emphasis, or Android-style button feedback
- Hover/press feedback should prefer the existing iOS tactile components' approach: color, opacity, subtle scale transitions
- Desktop allows hover, right-click, and focus states, but the overall feel must remain unified to the custom iOS style, not a Material/Android mashup
- If Material native components must be used for semantic or framework reasons, explicitly suppress off-style default feedback and consolidate styling into shared components instead of patching it piecemeal across pages.
- Icons, spacing, forms, dialogs, and panel styles should follow existing theme tokens and components. Do not mix multiple visual languages on the same page.
3.10 Tests and Self-Review Must Be Requirement-Driven
- Tests must be driven by requirements, defect symptoms, or acceptance criteria -- not by chasing implementation details.
- Before writing tests, list the minimum scenario set for this task. At minimum, explicitly cover:
- Happy path
- Boundary inputs
- Error or failure paths
- State transitions or interaction branches (if applicable)
- When fixing bugs, write a minimal failing case first, then fix. Do not only add an after-the-fact weak-assertion test that "happens to pass".
- Never widen public API surface, expose private internals, or distort production code responsibilities just to make tests easier to write.
- Before completion, perform at least one self-review explicitly checking these dimensions:
- Maintainability: Is the code easier to read and modify than before?
- Performance: Any obvious extra rebuilds, IO, traversals, or allocations introduced?
- Security: Any input validation gaps, secret leaks, path/command injection, or permission boundary errors?
- Style consistency: Does it match the repo's existing naming, organization, and UI language?
- Documentation and comments: Does complex intent need minimal explanation?
- Compatibility boundary: Does it affect existing user data, config, persisted fields, import/export formats, or established interactions?
- Compatibility is not a default-ignore item. When existing data or published behavior is involved, explicitly judge compatibility. If breaking, the delivery notes must state the breakage scope and migration path.
4. Recommended Execution Order
git status --short-- confirm workspace baseline.- Read relevant code and config. Write clear acceptance criteria. For desktop tasks, confirm entry topology first:
main.dart->lib/desktop/**-> shared chat layout. - Batch all independent context reads, searches, and status checks in parallel, then decide the minimal change landing point.
- List requirement scenarios and verification methods first, then make minimal changes. Do not mix in unrelated refactoring.
- Run the generation, formatting, analysis, and test commands relevant to this task.
- Self-review
git diff. Confirm no missed localization, generated files, compatibility risks, or unrelated changes. - When delivering, state explicitly:
- What was changed
- What commands were run
- What verification was skipped
- What residual risks remain
5. Pre-Commit Checklist
- All new user-visible text uses
AppLocalizations. - All 4 ARB files have been updated in sync.
flutter gen-l10nhas been executed and generated files match ARB content.- If Hive models were touched,
build_runnerhas been executed. dart formathas been executed.flutter analyzehas been executed.- Related
flutter testhas been executed. If no related tests exist, create and run them following official testing standards. - Test scenarios cover the happy path, boundary values, and failure paths for this task's requirements -- not just a single green run.
- Desktop tasks have confirmed the entry layer. No desktop-only logic leaked into mobile branches.
- New or adjusted UI prioritized reuse of existing shared / desktop components. No near-duplicate widgets created.
- New UI does not introduce unnecessary Android ripple or Material default interaction feedback.
- At least one round of self-review completed, checking maintainability, performance, security, style consistency, and compatibility boundary.
- No real secrets, build artifacts, or unrelated files committed.
- If workflows / platform directories / path dependencies were touched, corresponding extra verification has been done.
6. External Best Practices
- Code should follow the Flutter contribution guide:
- Tests should reference:
- For Flutter code style, follow the Flutter styleguide first. Follow Effective Dart: Style only when it does not conflict:
- If the repo ever introduces
engine/-level changes, add engine test guidance then. The repo currently has no such directory; do not apply it mechanically. - PR descriptions should include the Pre-launch Checklist from the Flutter PR template when applicable:
7. Design Principles
- Readability first. Code is for humans to read, not for machines to show off.
- Default against bloated implementations, idle abstractions, and academic over-engineering.
- If you can remove complexity, remove it. If you can avoid a branch, avoid it. If you can skip a layer of indirection, skip it.
- Simple, stable, and verifiable first. "Elegant" comes after.
- Avoid dual state and dual truth. Keep one source of truth.
- Write only what is needed now, but write it right.
- Error messages must be useful -- they should help locate and recover, not just say "failed".
- Mechanisms over hand-picked magic constants. If a threshold must be hardcoded, explain why and state its boundaries.
- When small-step verification is possible, do not make large irreversible changes.
8. Historical Pitfall Log
Record significant pitfalls encountered during development here.
- Recording principles:
- Only record issues that actually occurred in this repo and have reuse value for future development.
- Do not write "heard this might happen" hearsay entries.
- When adding entries, prefer "symptom -> root cause -> fix/constraint". Avoid recording conclusions without context.
Appendix: Skills Usage Rules
- Before starting a task, scan available skill documents in
/.agents/skills/. - When activating a skill, declare the skill name and purpose in communication.
- Regular development does not mandate any specific skill. Activate only when semantically matched.
