timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/dart/rules/code-style.md

@@ -0,0 +1,96 @@
+---
+title: Code Style (Effective Dart)
+impact: HIGH
+tags: style, naming, linting, documentation
+---
+
+## Code Style (Effective Dart)
+
+Effective Dart 기반 코딩 컨벤션. `dart_style` 포매터 + strict analysis_options.
+
+### analysis_options.yaml
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+# 또는 non-Flutter: package:lints/recommended.yaml
+
+linter:
+  rules:
+    # 필수 추가 규칙
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - avoid_dynamic_calls
+    - unawaited_futures
+    - cancel_subscriptions
+    - close_sinks
+    - prefer_final_locals
+    - avoid_print        # debugPrint 사용
+    - require_trailing_commas
+
+analyzer:
+  errors:
+    missing_return: error
+    unawaited_futures: warning
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+```
+
+### 네이밍
+
+| 종류 | 규칙 | 예시 |
+|------|------|------|
+| 클래스, enum, typedef | UpperCamelCase | `UserProfile`, `AuthState` |
+| 변수, 함수, 파라미터 | lowerCamelCase | `userName`, `fetchData()` |
+| 상수 | lowerCamelCase | `defaultTimeout` (UPPER_SNAKE 금지) |
+| 파일 | snake_case | `user_profile.dart` |
+| 라이브러리 접두사 | snake_case | `import 'x' as my_lib` |
+
+**Incorrect:**
+```dart
+const MAX_RETRY_COUNT = 3;  // UPPER_SNAKE
+class user_service { }       // snake_case 클래스
+String UserName = '';         // UpperCamel 변수
+```
+
+**Correct:**
+```dart
+const maxRetryCount = 3;
+class UserService { }
+String userName = '';
+```
+
+### Import 정리
+
+```dart
+// 1. dart: 표준 라이브러리
+import 'dart:async';
+import 'dart:convert';
+
+// 2. package: 외부 패키지
+import 'package:flutter/material.dart';
+import 'package:riverpod/riverpod.dart';
+
+// 3. 프로젝트 내부 (상대 경로 금지)
+import 'package:my_app/features/auth/domain/user.dart';
+```
+
+### 문서화
+
+```dart
+/// 사용자 프로필을 가져온다.
+///
+/// [userId]에 해당하는 사용자가 없으면 null 반환.
+/// 네트워크 에러 시 [FetchException] 발생.
+Future<UserProfile?> fetchProfile(String userId) async { ... }
+```
+
+### 규칙
+
+- `dart format .` 자동 포매팅 (커밋 전 필수)
+- 상대 import 금지 → `package:` import
+- `print()` 금지 → `debugPrint()` 또는 logger
+- `part`/`part of` 금지 → 파일 분리
+- trailing comma 필수 (위젯 트리 가독성)
+- `prefer_final_locals` 활성화

package/templates/base/skills/mobile/dart/rules/null-safety.md

@@ -0,0 +1,84 @@
+---
+title: Sound Null Safety
+impact: CRITICAL
+tags: null-safety, dart3, patterns
+---
+
+## Sound Null Safety
+
+Dart의 null safety는 컴파일 타임에 null 참조를 방지한다.
+`!`와 `late` 남용은 런타임 크래시를 초래하므로 패턴으로 해결.
+
+### Bang Operator (!) 금지
+
+**Incorrect:**
+```dart
+final user = users.firstWhere((u) => u.id == id);
+print(user!.name); // NoSuchElementException 위험
+```
+
+**Correct:**
+```dart
+final user = users.where((u) => u.id == id).firstOrNull;
+if (user case final found?) {
+  print(found.name);
+} else {
+  throw UserNotFoundException(id);
+}
+```
+
+### Nullable Collection 처리
+
+**Incorrect:**
+```dart
+final List<String?> items = getData();
+for (final item in items) {
+  print(item!.length); // null이면 크래시
+}
+```
+
+**Correct:**
+```dart
+final List<String?> items = getData();
+final validItems = items.whereType<String>(); // null 필터링 + 타입 내로잉
+for (final item in validItems) {
+  print(item.length); // String 보장
+}
+```
+
+### late 사용 기준
+
+**Incorrect:**
+```dart
+class MyWidget extends StatefulWidget { ... }
+class _MyWidgetState extends State<MyWidget> {
+  late final ApiService api; // dispose 전에 접근하면 크래시
+  late String userName;      // 초기화 보장 없음
+}
+```
+
+**Correct:**
+```dart
+class _MyWidgetState extends State<MyWidget> {
+  late final TextEditingController _controller; // initState에서 반드시 초기화
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = TextEditingController();
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+}
+```
+
+### 규칙
+
+- `late` 는 lifecycle 보장 컨텍스트에서만: `initState`, `setUp`, 생성자 body
+- `!` 대신 `case`, `??`, `?.` 사용
+- `firstWhere` → `firstOrNull` + null 체크
+- 함수 파라미터에서 `required` 키워드로 null 방지

package/templates/base/skills/mobile/dart/rules/type-system.md

@@ -0,0 +1,111 @@
+---
+title: Type System (Dart 3+)
+impact: HIGH
+tags: sealed-class, pattern-matching, records, extension-type
+---
+
+## Type System (Dart 3+)
+
+Dart 3의 sealed class, 패턴 매칭, records, extension type으로 타입 안전한 코드 작성.
+
+### Sealed Class (상태 모델링)
+
+**Incorrect:**
+```dart
+enum LoadState { loading, success, error }
+
+class ScreenState {
+  final LoadState state;
+  final List<Item>? data;   // success일 때만 유효
+  final String? error;       // error일 때만 유효
+  // 불가능한 조합이 가능: state=loading + data!=null
+}
+```
+
+**Correct:**
+```dart
+sealed class ScreenState {}
+class Loading extends ScreenState {}
+class Success extends ScreenState {
+  final List<Item> data;
+  Success(this.data);
+}
+class Failure extends ScreenState {
+  final String message;
+  Failure(this.message);
+}
+
+// exhaustive switch — 새 상태 추가 시 컴파일 에러
+Widget build(BuildContext context) => switch (state) {
+  Loading() => const CircularProgressIndicator(),
+  Success(:final data) => ItemList(items: data),
+  Failure(:final message) => ErrorView(message: message),
+};
+```
+
+### 패턴 매칭
+
+**Incorrect:**
+```dart
+if (response is Map<String, dynamic>) {
+  if (response.containsKey('data')) {
+    final data = response['data'];
+    if (data is List) {
+      // 중첩 if 지옥
+    }
+  }
+}
+```
+
+**Correct:**
+```dart
+if (response case {'data': List<Map<String, dynamic>> items}) {
+  final users = items.map(User.fromJson).toList();
+}
+```
+
+### Records (경량 튜플)
+
+**Incorrect:**
+```dart
+// 위치 좌표를 위한 불필요한 클래스
+class LatLng {
+  final double lat;
+  final double lng;
+  LatLng(this.lat, this.lng);
+}
+```
+
+**Correct:**
+```dart
+// Named record로 간결하게
+typedef LatLng = ({double lat, double lng});
+
+LatLng getLocation() => (lat: 1.3521, lng: 103.8198);
+
+final (:lat, :lng) = getLocation(); // 구조 분해
+```
+
+### Extension Type (Zero-Cost Wrapper)
+
+```dart
+extension type UserId(String value) {
+  factory UserId.fromInt(int id) => UserId('user_$id');
+}
+
+extension type PostId(String value) {}
+
+// 컴파일 타임에 타입 구분, 런타임 오버헤드 0
+void fetchUser(UserId id) { ... }
+void fetchPost(PostId id) { ... }
+
+fetchUser(PostId('abc')); // 컴파일 에러!
+```
+
+### 규칙
+
+- 상태/에러/결과는 `sealed class` + exhaustive switch
+- Map 접근은 패턴 매칭 `case` 사용
+- 2-3개 값 반환은 Record `(int, String)` 사용 (클래스 불필요)
+- ID 타입은 `extension type`으로 구분
+- `dynamic` 타입 금지 → `Object?` + 패턴 매칭

package/templates/base/skills/mobile/flutter/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: flutter
+description: Flutter 개발 가이드라인. Feature-first 아키텍처, Riverpod 상태관리, 위젯 합성, 성능 최적화, 크로스플랫폼 적응형 UI.
+version: "1.0.0"
+tags: [flutter, mobile, cross-platform, riverpod]
+user-invocable: false
+---
+
+# Flutter Development Guidelines
+
+Flutter 3.x 기반 크로스플랫폼 앱 개발 가이드라인.
+Flutter 공식 아키텍처 가이드 + VGV + Riverpod 커뮤니티 베스트 프랙티스 종합.
+
+## Philosophy
+
+- 위젯은 합성 — 상속보다 조합, 작게 분리
+- 상태는 구조화 — Riverpod로 선언적 의존성
+- Feature-first — 기능 단위로 코드 구성
+- const 는 습관 — 불필요한 리빌드 원천 차단
+
+## Resources
+
+8개 규칙 + 2개 참조. 카테고리별 배치.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [widget-conventions](rules/widget-conventions.md) | 위젯 합성, const, Key 사용, 크기 제한 |
+| CRITICAL | rule | [state-management](rules/state-management.md) | Riverpod Provider/Notifier 패턴 |
+| CRITICAL | rule | [architecture](rules/architecture.md) | Feature-first + MVVM + Data/Domain/UI 레이어 |
+| HIGH | rule | [navigation-routing](rules/navigation-routing.md) | go_router 선언적 라우팅, 딥링크 |
+| HIGH | rule | [performance](rules/performance.md) | 리빌드 최적화, ListView.builder, Impeller |
+| HIGH | rule | [testing](rules/testing.md) | Widget/Golden/Integration 테스트, mocktail |
+| MEDIUM | rule | [platform-adaptive](rules/platform-adaptive.md) | 적응형 UI, 반응형 레이아웃, 플랫폼 분기 |
+| MEDIUM | rule | [animations](rules/animations.md) | 암시적/명시적 애니메이션, Hero, 모션 가이드라인 |
+| — | ref | [project-structure](references/project-structure.md) | Feature-first + melos 모노레포 구조 |
+| — | ref | [freezed-patterns](references/freezed-patterns.md) | freezed + json_serializable 불변 모델 |
+
+## Quick Rules
+
+### 위젯
+- `const` 생성자 적극 사용 (리빌드 스킵)
+- 위젯 200줄 이하 — 초과 시 추출
+- build() 안에서 로직 금지 — ViewModel/Notifier로 분리
+- `GlobalKey` 남용 금지 — `ValueKey`/`ObjectKey` 사용
+
+### 상태 관리 (Riverpod)
+- UI 상태: `NotifierProvider` + `Notifier`
+- 서버 데이터: `FutureProvider` / `StreamProvider`
+- 파생 상태: `Provider` (computed)
+- `ref.watch` (build), `ref.listen` (side effect), `ref.read` (이벤트 핸들러)
+
+### 아키텍처
+- Feature-first 구조 (`lib/features/{name}/`)
+- 각 feature: `data/` + `domain/` + `presentation/`
+- Repository 패턴으로 데이터 소스 추상화
+- DTO ↔ Domain Model 변환 레이어
+
+### 네비게이션
+- go_router 선언적 라우팅
+- 딥링크/유니버설 링크 지원
+- 중첩 네비게이션 (ShellRoute)
+
+### 성능
+- `const` 위젯 우선
+- 리스트는 `ListView.builder` (lazy)
+- `RepaintBoundary`로 리빌드 범위 격리
+- 이미지: `cached_network_image` + 적절한 크기
+
+### 테스트
+- Widget test: `testWidgets` + `pumpWidget`
+- Unit test: Notifier/Repository 독립 테스트
+- Integration test: `patrol` (네이티브 상호작용)
+- Mock: `mocktail` (코드 생성 불필요)
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | const 생성자 사용 (lint: prefer_const_constructors) |
+| CRITICAL | Riverpod Provider 타입 올바르게 선택 |
+| CRITICAL | Feature-first 디렉토리 구조 |
+| CRITICAL | build() 안에 비즈니스 로직 없음 |
+| HIGH | ListView.builder 사용 (10+ 아이템) |
+| HIGH | Repository 패턴 (데이터 소스 추상화) |
+| HIGH | go_router 선언적 라우팅 |
+| HIGH | Widget test 작성 |
+| MEDIUM | RepaintBoundary 적용 (복잡한 서브트리) |
+| MEDIUM | 적응형 UI (Material + Cupertino) |
+| MEDIUM | 이미지 캐싱 + 적절한 리사이징 |

package/templates/base/skills/mobile/flutter/ci-cd/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ci-cd
+description: |
+  Flutter CI/CD 파이프라인 가이드라인.
+  코드 서명, Fastlane, Codemagic, GitHub Actions,
+  스토어 배포, 버전 관리 자동화.
+version: "1.0.0"
+tags: [flutter, ci-cd, fastlane, codemagic, github-actions, code-signing, deployment]
+user-invocable: false
+---
+
+# CI/CD Pipeline
+
+Flutter 앱의 빌드, 테스트, 서명, 배포 자동화 가이드.
+iOS/Android 코드 서명, Fastlane/Codemagic/GitHub Actions 파이프라인, 스토어 배포, 버전 관리.
+
+## Philosophy
+
+- 배포는 자동 — 수동 빌드/업로드 금지, CI가 전부 처리
+- 서명은 분리 — 코드 서명 키를 CI 환경에 안전하게 주입, 레포에 절대 포함 금지
+- 버전은 규칙 — 시맨틱 버저닝 + 빌드 넘버 자동 증가
+- 환경은 격리 — dev/staging/prod 설정 분리, 환경별 독립 파이프라인
+
+## Resources
+
+6개 규칙 + 1개 참조. CI/CD 파이프라인 전체를 커버.
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [code-signing](rules/code-signing.md) | iOS provisioning profile, Android keystore, 인증서 관리 |
+| HIGH | rule | [fastlane-setup](rules/fastlane-setup.md) | Fastfile 구성, match, supply, deliver, .env 관리 |
+| HIGH | rule | [codemagic-setup](rules/codemagic-setup.md) | codemagic.yaml 워크플로우, 환경변수, 빌드 트리거 |
+| HIGH | rule | [github-actions](rules/github-actions.md) | Flutter 빌드 워크플로우, 테스트-빌드-업로드 파이프라인 |
+| HIGH | rule | [store-deployment](rules/store-deployment.md) | TestFlight, Play Store tracks, 메타데이터, 단계적 출시 |
+| MEDIUM | rule | [versioning](rules/versioning.md) | 시맨틱 버저닝, 빌드 넘버 자동 증가, CHANGELOG, git 태그 |
+| — | ref | [ci-cd-pipeline](references/ci-cd-pipeline.md) | 파이프라인 아키텍처, 환경 설정, 시크릿 관리, 롤백 |
+
+## Quick Rules
+
+### 코드 서명
+- iOS: `match` 로 인증서/프로필 Git 저장소 관리 (팀 공유)
+- Android: keystore 파일을 CI 환경변수로 base64 주입
+- 개발용/배포용 인증서 분리 — 동일 인증서 사용 금지
+- 서명 키를 레포에 커밋 금지 — `.gitignore` 에 `*.keystore`, `*.jks`, `*.p12` 추가
+
+### Fastlane
+- `Fastfile` 에 `ios`/`android` 레인 분리
+- `match` → iOS 인증서 자동 관리 (Git 저장소 or Google Cloud Storage)
+- `supply` → Google Play 업로드, `deliver` → App Store 업로드
+- `.env` 로 환경별 설정 분리 (`.env.production`, `.env.staging`)
+
+### CI/CD 플랫폼
+- Codemagic: Flutter 네이티브 지원, `codemagic.yaml` 로 워크플로우 정의
+- GitHub Actions: `subosito/flutter-action` 으로 Flutter 설치, pub cache 캐시 필수
+- 빌드 트리거: 태그 푸시 (`v*`) → 릴리스, PR → 테스트만
+
+### 스토어 배포
+- TestFlight: `deliver` 또는 `app-store-connect` API로 업로드
+- Play Store: internal → closed → open → production 트랙 순서
+- 단계적 출시 (staged rollout): 1% → 5% → 20% → 50% → 100%
+- 메타데이터 (스크린샷, 설명) 코드로 관리 (`fastlane/metadata/`)
+
+### 버전 관리
+- `pubspec.yaml`: `version: major.minor.patch+buildNumber`
+- 빌드 넘버: CI에서 자동 증가 (`--build-number=$CI_BUILD_NUMBER`)
+- git 태그: `v1.2.3` 형식, 릴리스 빌드와 1:1 매핑
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | iOS 코드 서명 (provisioning profile + 인증서) CI에 구성 |
+| CRITICAL | Android keystore CI 환경변수로 안전하게 주입 |
+| CRITICAL | 서명 키/인증서 `.gitignore` 에 추가 확인 |
+| CRITICAL | CI 파이프라인: test → build → deploy 순서 보장 |
+| HIGH | Fastlane match 설정 (iOS 인증서 팀 공유) |
+| HIGH | 환경별 (dev/staging/prod) 빌드 설정 분리 |
+| HIGH | 스토어 업로드 자동화 (TestFlight + Play Store) |
+| HIGH | 빌드 넘버 자동 증가 전략 구현 |
+| MEDIUM | CHANGELOG 자동 생성 (conventional commits 기반) |
+| MEDIUM | 슬랙/디스코드 배포 알림 설정 |
+| MEDIUM | 롤백 절차 문서화 및 테스트 |