agent-flutter 0.1.1

package/templates/shared/skills/flutter-ui-widgets/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: Flutter UI Widgets
+description: Principles for maintainable UI components and project-specific widget standards.
+---
+
+# UI & Widgets
+
+## **Priority: P1**
+
+- **Design Tokens (STRICT)**:
+  - Typography: 1–1 mapping from Figma. Use `AppStyles`; `height = lineHeight / fontSize`. Bundle exact font-family/weight.
+  - Colors: Use `AppColors`; no hex/raw colors.
+  - Spacing: Use `int_extensions` and `AppDimensions`; no free-form numbers.
+  - Radius: Preserve Figma values; do not coerce to presets.
+  - Icon: Sizes must follow Figma numeric tokens. Common 24×24; container per Figma (e.g., 40×40, 44×44). Do not assume fixed size. Reference via `AppAssets`.
+  - Shadows: Normalize `BoxShadow` close to CSS box-shadow.
+  - Backgrounds: Use `DecorationImage` + appropriate `BoxFit` (cover/contain).
+
+## Quality & Safety
+- **Async Gaps**: After `await`, check `if (context.mounted)` before using `BuildContext`.
+- **Optimization**: Prefer `ColoredBox`/`Padding`/`DecoratedBox` over `Container` when only color/background/padding is needed.
+- **Layout Tips**: Avoid `IntrinsicWidth/Height`; use `Stack` + `FractionallySizedBox` for overlays; `Flex` + int extensions (`n.height`/`n.width`) for spacing.
+- **Large Lists**: Use `AppListView` for large lists.
+- **SVG Color**: Do not use `colorFilter` if the SVG already matches Figma; only apply when design requires and the icon is flattened stroke→fill (see Assets Skill).
+
+## Examples
+
+### Async Gaps
+```dart
+onPressed: () async {
+  await Future.delayed(const Duration(milliseconds: 100));
+  if (!context.mounted) return;
+  Navigator.pop(context);
+}
+```
+
+### ColoredBox vs Container
+```dart
+// GOOD: only color + padding
+ColoredBox(
+  color: AppColors.white,
+  child: Padding(
+    padding: const EdgeInsets.all(16),
+    child: Text('Content', style: AppStyles.bodyLarge()),
+  ),
+);
+```
+
+### Spacing with int extensions
+```dart
+Column(
+  children: [
+    Text('Title', style: AppStyles.h3),
+    12.height, // vertical space
+    Row(
+      children: [
+        Text('Left'),
+        8.width, // horizontal space
+        Text('Right'),
+      ],
+    ),
+  ],
+);
+```
+
+### SVG Color Handling
+```dart
+// No recolor (SVG already has Figma color)
+SvgPicture.asset(AppAssets.iconsCalendarSvg);
+
+// Recolor only for mono icons prepared with fill
+SvgPicture.asset(AppAssets.iconsChevronSolidSvg, color: AppColors.primary);
+```
+
+### Overlay Layout
+```dart
+Stack(
+  children: [
+    Image.asset(AppAssets.bgContainerPng, fit: BoxFit.cover),
+    const FractionallySizedBox(
+      alignment: Alignment.bottomCenter,
+      heightFactor: 0.25,
+      child: AppCardSection(child: Text('Bottom Sheet')),
+    ),
+  ],
+);
+```
+
+## Customization & Defaults
+- Every `App*` widget must provide parameters to override tokens per Figma: `size`, `radius`, `padding/margin`, `backgroundColor`, `textStyle`, `iconSize`, `constraints`.
+- Defaults are fallbacks and must use tokens (`AppStyles`, `AppColors`, `AppDimensions`). Do not hardcode display values.
+- Example: `AppButtonBar(size: 40, radius: 14, iconSize: 24, backgroundColor: AppColors.white)`; if Figma differs, pass matching parameters.
+- When overriding numeric tokens, preserve Figma values; do not round or force presets.
+
+- **Naming Convention**:
+  - Shared widgets in `lib/src/ui/widgets` MUST use the `App` prefix (e.g., `AppInput`, `AppButton`, `AppCardSection`).
+  - Use these pre-built `App*` widgets instead of raw Material/Cupertino widgets to ensure consistency.
+- **Styling (Colors & Typography)**:
+  - **Source of Truth**: Always use `AppColors` and `AppStyles` from `lib/src/utils/`.
+  - **Forbidden**: Do NOT hardcode colors (e.g., `Colors.red`, `Color(0xFF...)`) or text styles.
+  - **Usage**: `AppColors.primary`, `AppStyles.bodyMedium`.
+- **State**: 
+  - Use `StatelessWidget` by default.
+  - Use `StatefulWidget` for self-contained UI logic (e.g., `AppInput` handling focus/password visibility internally) to keep parent Pages clean.
+- **Composition**: Extract UI into small, atomic `const` widgets.
+- **Theming**: Use `Theme.of(context)` where applicable, but prefer `AppColors`/`AppStyles` for specific design system tokens.
+- **Layout**: Use `Flex` + int extensions (`n.height`/`n.width`).
+- **Specialized**:
+  - `SelectionArea`: For multi-widget text selection.
+  - `InteractiveViewer`: For zoom/pan.
+  - `ListWheelScrollView`: For pickers.
+  - `IntrinsicWidth/Height`: Avoid unless strictly required.
+- **Large Lists**: Always use `ListView.builder` (or `AppListView` if available).
+
+## **Common System Widgets**
+
+Refer to `lib/src/ui/widgets/` for the source of truth. Common examples:
+
+- **Inputs**: `AppInput` (handles focus, labels, password visibility).
+- **Buttons**: `AppButtonBar` (standard back button; container/radius/icon size per Figma, e.g., 40×40, radius 14, icon 24), `AppButton` (primary actions).
+- **Text**: `AppTextGradient` (gradient text).
+- **Containers**: `AppCardSection`, `AppContainerExpand`.
+
+```dart
+// Example of using project-standard widgets and styles
+class WorkDetailPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: AppColors.background, // Use AppColors
+      appBar: AppBar(
+        leading: AppButtonBar(), // Standard back button
+        title: AppTextGradient(  // Standard styled text
+          text: 'Detail',
+          gradient: AppColors.primaryTextGradient(),
+        ),
+      ),
+      body: Column(
+        children: [
+          Text('Welcome', style: AppStyles.h3), // Use AppStyles
+          AppInput(label: 'Email'), 
+          AppInput(label: 'Password', isPassword: true),
+        ],
+      ),
+    );
+  }
+}
+```
+
+## Related Topics
+
+performance | testing

package/templates/shared/skills/getx-localization-standard/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: GetX Localization Standard
+description: "Standards for GetX-based multi-language (locale_key + lang_*.dart). Invoke when generating a new page/feature or adding any user-facing text."
+---
+
+# GetX Localization Standard
+
+## **Priority: P1 (HIGH)**
+
+All user-facing text MUST be localized via **GetX Translations** using `locale_key.dart` + `lang_*.dart`.
+
+## Core Rules (When generating a page)
+
+### 1) locale_key.dart MUST be updated
+- Add every new key used by the new page.
+- Keys MUST be stable and semantic.
+- Key naming format: `<feature>_<screen>_<element>` in `snake_case` (e.g. `customer_detail_title`).
+
+### 2) ALL language files MUST be updated
+Whenever a new key is added, you MUST update:
+- `lang_en.dart`
+- `lang_ja.dart`
+- Any existing `lang_*.dart` languages in the project
+
+No language is allowed to miss keys.
+
+### 3) UI MUST use `.tr` (no raw strings)
+- Always write: `LocaleKey.someKey.tr`
+- Never hardcode labels like `'Home'`, `'ホーム'`, `'Trang chủ'` in widgets.
+
+## Project Implementation (Source of Truth)
+
+- Keys: `lib/src/core/localization/locale_key.dart`
+- Translations:
+  - `lib/src/core/localization/lang_en.dart`
+  - `lib/src/core/localization/lang_ja.dart`
+- Registry: `lib/src/core/localization/app_translations.dart`
+- App wiring: `lib/main.dart` uses `GetMaterialApp(...)` with `translations`, `supportedLocales`, `fallbackLocale`, and Flutter `localizationsDelegates`.
+
+## Conflict-Free Workflow (Recommended)
+- **Modularize per Feature**: Split translations by feature to avoid PR conflicts:
+  - `lib/src/core/localization/en/<feature>.dart`
+  - `lib/src/core/localization/ja/<feature>.dart`
+- **Aggregate Maps**: Keep `lang_en.dart` and `lang_ja.dart` as aggregators that merge feature maps:
+  ```dart
+  // lang_en.dart
+  import 'en/home.dart' as en_home;
+  import 'en/customer.dart' as en_customer;
+  final Map<String, String> enUs = {
+    ...en_home.map,
+    ...en_customer.map,
+    // ...
+  };
+  ```
+  ```dart
+  // en/home.dart
+  final map = <String, String>{
+    LocaleKey.home_title: 'Home',
+    // ...
+  };
+  ```
+- **Key Namespacing**: Prefix keys by feature (`customer_detail_title`), keep `snake_case`.
+- **Sorting & Lint**: Sort keys alphabetically; reject PRs with duplicate keys or missing locales.
+- **Append-Only**: Do not rename/remove keys in active release branches; add new keys and deprecate old ones separately.
+- **CI Check (Optional)**: Script to validate:
+  - All keys in `locale_key.dart` exist in every `lang_*.dart`.
+  - No duplicate keys across feature maps.
+  - Aggregators compile successfully.
+
+## Integration with TranslationManager
+- **Existing Manager**: `lib/src/locale/translation_manager.dart` expects `enUs` and `jaJp` maps from `lang_en.dart` and `lang_ja.dart`.
+- **Do NOT rename** exported variables `enUs` / `jaJp`. Keep aggregator files exporting exactly these names.
+- **Wiring remains**: `TranslationManager.keys` continues to return `{'en_US': enUs, 'ja_JP': jaJp}` — modularization happens inside aggregators.
+- **Adding Languages**: When adding a new language, update:
+  - Aggregator `lang_<code>.dart` to export `<code>_<COUNTRY>` map variable.
+  - `TranslationManager.appLocales` and `.keys` to include the new locale.
+
+## Common Keys & Reuse Policy
+- **Purpose**: Reduce duplicate text using shared keys for app-wide phrases.
+- **Common Module**:
+  - Create `lib/src/core/localization/en/common.dart` and `ja/common.dart` for common phrases (Save, Cancel, OK, Back, Next, Loading, Error, Retry…).
+  - Aggregators include `...common.map` before feature maps.
+- **Key Naming**: Use `common_` prefix (e.g., `common_save`, `common_cancel`, `common_error_network`).
+- **Feature Usage**: When a screen uses text that matches common, **reuse** `LocaleKey.common_*` instead of creating a feature key.
+- **Screen-Specific**: Create new keys only for context-specific texts (e.g., `customer_detail_no_records_found`).
+- **CI De-dup (Optional)**:
+  - Script detects repeated values within a language and suggests moving to `common_*`.
+  - Reject PRs if a common phrase appears under multiple different keys across features.
+
+## Adding a New Language
+
+1. Create `lang_<code>.dart` (e.g. `lang_ko.dart`) as `Map<String, String>`.
+2. Register it in `AppTranslations.keys` using `<lang>_<COUNTRY>` (e.g. `ko_KR`).
+3. Add the corresponding `Locale('<lang>', '<COUNTRY>')` to `supportedLocales`.
+4. Ensure every key in `locale_key.dart` exists in the new language map.
+
+## Quality Gates (Reject if violated)
+
+- Any new page introduces raw strings in UI.
+- `locale_key.dart` is changed but any `lang_*.dart` misses the same keys.
+- Key names are generic or unstable (e.g. `title1`, `text_2`, random ids).

package/templates/shared/skills/getx-localization-standard/references/new-page-localization.example.md

@@ -0,0 +1,61 @@
+# New Page Localization Template (GetX)
+
+This template matches the current project structure (TranslationManager uses `enUs` / `jaJp`).
+
+## 1) Add keys (locale_key.dart)
+
+Example for `customer_detail` page:
+
+```dart
+// lib/src/locale/locale_key.dart
+class LocaleKey {
+  // ...
+  static const String customerDetailTitle = 'customerDetailTitle';
+  static const String customerDetailSave = 'customerDetailSave';
+  static const String customerDetailDelete = 'customerDetailDelete';
+}
+```
+
+## 2) Add translations (ALL languages)
+
+`lang_en.dart`
+```dart
+// lib/src/locale/lang_en.dart
+import 'package:link_home/src/locale/locale_key.dart';
+
+Map<String, String> enUs = {
+  // ...
+  LocaleKey.customerDetailTitle: 'Customer Detail',
+  LocaleKey.customerDetailSave: 'Save',   // Prefer reuse: LocaleKey.ok if suitable
+  LocaleKey.customerDetailDelete: 'Delete',
+};
+```
+
+`lang_ja.dart`
+```dart
+// lib/src/locale/lang_ja.dart
+import 'package:link_home/src/locale/locale_key.dart';
+
+Map<String, String> jaJp = {
+  // ...
+  LocaleKey.customerDetailTitle: '顧客詳細',
+  LocaleKey.customerDetailSave: '保存',
+  LocaleKey.customerDetailDelete: '削除',
+};
+```
+
+## 3) Use in UI
+
+```dart
+Text(LocaleKey.customerDetailTitle.tr)
+```
+
+## 4) Common Keys & Reuse (Recommended)
+
+- Reuse common keys when the text is generic:
+  - `LocaleKey.ok`, `LocaleKey.cancel`, `LocaleKey.success`, `LocaleKey.error`, `LocaleKey.next`...
+- Only create feature-specific keys for context-specific texts that differ from common meanings.
+
+## 5) Optional: Modularization to avoid conflicts
+
+- If needed, split translations by feature (`en/<feature>.dart`, `ja/<feature>.dart`) and merge them in `lang_en.dart` / `lang_ja.dart` to keep `enUs` / `jaJp` for `TranslationManager`.

package/templates/shared/skills/ui-documentation-workflow/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "UI Documentation Workflow"
+description: "Generates and maintains spec/ui-workflow.md for UI flows. Invoke when creating/modifying features or when asked to update documentation."
+---
+
+# AI Documentation Workflow (UI)
+
+## Goal
+Automatically generate and maintain `spec/ui-workflow.md` describing business logic and user flows, so devs/AI can understand features quickly.
+
+## Trigger (When to Invoke)
+- A new UI feature is created
+- An existing UI feature is significantly modified
+- User explicitly requests to update documentation
+
+## Workflow
+1) Analyze the Feature
+- Read for EACH feature:
+  - `*_page.dart`: UI elements and interactions
+  - `interactor/*_bloc.dart` (or Controller): logic, state changes, API calls
+  - `binding/*_binding.dart`: dependencies
+  - `locale_key.dart`: terminology
+
+2) Write Documentation
+- Append or update a section in `spec/ui-workflow.md` with:
+```
+## [Feature Name]
+**Path**: lib/src/ui/<feature>
+
+### 1. Description
+Goal: ...
+Features:
+- ...
+
+### 2. UI Structure
+- Screen: <Page>
+- Components: ...
+
+### 3. User Flow & Logic
+1) ...
+2) ...
+
+### 4. Key Dependencies
+- ...
+
+### 5. Notes & Known Issues (Optional)
+- Tech Debt: ...
+- UX Issues: ...
+- Todo: ...
+```
+
+3) Verification
+- Ensure documented flow matches code
+- Keep “User Flow” business-friendly; avoid low-level jargon
+- Note raw strings, complex logic, or potential issues