sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/skills/flutter-setup-localization/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: flutter-setup-localization
+description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Tue, 21 Apr 2026 21:27:35 GMT
+---
+# Internationalizing Flutter Applications
+
+## Contents
+- [Core Concepts](#core-concepts)
+- [Setup Workflow](#setup-workflow)
+- [Implementation Workflow](#implementation-workflow)
+- [Advanced Formatting](#advanced-formatting)
+- [Examples](#examples)
+
+## Core Concepts
+Flutter handles internationalization (i18n) and localization (l10n) via the `flutter_localizations` and `intl` packages. The standard approach uses App Resource Bundle (`.arb`) files to define localized strings, which are then compiled into a generated `AppLocalizations` class for type-safe access within the widget tree.
+
+## Setup Workflow
+
+Copy and track this checklist when initializing internationalization in a Flutter project:
+
+- [ ] **Task Progress**
+  - [ ] 1. Add dependencies to `pubspec.yaml`.
+  - [ ] 2. Enable the `generate` flag.
+  - [ ] 3. Create the `l10n.yaml` configuration file.
+  - [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
+
+### 1. Add Dependencies
+Add the required localization packages to the project. Execute the following commands in the terminal:
+```bash
+flutter pub add flutter_localizations --sdk=flutter
+flutter pub add intl:any
+```
+
+Verify your `pubspec.yaml` includes the following under `dependencies`:
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  intl: any
+```
+
+### 2. Enable Code Generation
+Open `pubspec.yaml` and enable the `generate` flag within the `flutter` section to automate localization tasks:
+```yaml
+flutter:
+  generate: true
+```
+
+### 3. Create Configuration File
+Create a new file named `l10n.yaml` in the root directory of the Flutter project. Define the input directory, template file, and output file:
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: true
+```
+
+### 4. Configure the App Entry Point
+Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`.
+
+```dart
+import 'package:flutter_localizations/flutter_localizations.dart';
+import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Adjust path if synthetic-package is false
+
+// ... inside build method
+return MaterialApp(
+  localizationsDelegates: const [
+    AppLocalizations.delegate,
+    GlobalMaterialLocalizations.delegate,
+    GlobalWidgetsLocalizations.delegate,
+    GlobalCupertinoLocalizations.delegate,
+  ],
+  supportedLocales: const [
+    Locale('en'), // English
+    Locale('es'), // Spanish
+  ],
+  home: const MyHomePage(),
+);
+```
+
+## Implementation Workflow
+
+Follow this workflow when adding or modifying localized content.
+
+### 1. Define ARB Files
+*   **If creating NEW content:** Add the base string to the template file (`lib/l10n/app_en.arb`). Include a description for context.
+*   **If EDITING existing content:** Locate the key in all supported `.arb` files and update the values.
+
+```json
+{
+  "helloWorld": "Hello World!",
+  "@helloWorld": {
+    "description": "The conventional newborn programmer greeting"
+  }
+}
+```
+
+Create corresponding files for other locales (e.g., `app_es.arb`):
+```json
+{
+  "helloWorld": "¡Hola Mundo!"
+}
+```
+
+### 2. Generate Localization Classes
+Run the following command to trigger code generation:
+```bash
+flutter pub get
+```
+*Feedback Loop:* Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run `flutter pub get`.
+
+### 3. Consume Localized Strings
+Access the localized strings in your widget tree using `AppLocalizations.of(context)`. Ensure the widget calling this is a descendant of `MaterialApp`.
+
+```dart
+Text(AppLocalizations.of(context)!.helloWorld)
+```
+
+## Advanced Formatting
+
+Use placeholders for dynamic data, plurals, and conditional selects.
+
+### Placeholders
+Define parameters within curly braces and specify their type in the metadata object.
+```json
+"hello": "Hello {userName}",
+"@hello": {
+  "description": "A message with a single parameter",
+  "placeholders": {
+    "userName": {
+      "type": "String",
+      "example": "Bob"
+    }
+  }
+}
+```
+
+### Plurals
+Use the `plural` syntax to handle quantity-based string variations. The `other` case is mandatory.
+```json
+"nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
+"@nWombats": {
+  "description": "A plural message",
+  "placeholders": {
+    "count": {
+      "type": "num",
+      "format": "compact"
+    }
+  }
+}
+```
+
+### Selects
+Use the `select` syntax for conditional strings, such as gendered text.
+```json
+"pronoun": "{gender, select, male{he} female{she} other{they}}",
+"@pronoun": {
+  "description": "A gendered message",
+  "placeholders": {
+    "gender": {
+      "type": "String"
+    }
+  }
+}
+```
+
+## Examples
+
+### Complete `l10n.yaml`
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: true
+use-escaping: true
+```
+
+### Complete Widget Implementation
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+
+class GreetingWidget extends StatelessWidget {
+  final String userName;
+  final int notificationCount;
+
+  const GreetingWidget({
+    super.key, 
+    required this.userName, 
+    required this.notificationCount,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final l10n = AppLocalizations.of(context)!;
+
+    return Column(
+      children: [
+        Text(l10n.hello(userName)),
+        Text(l10n.nWombats(notificationCount)),
+      ],
+    );
+  }
+}
+```

package/skills/flutter-skills/skills/flutter-use-http-package/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: flutter-use-http-package
+description: Use the `http` package to execute GET, POST, PUT, or DELETE requests. Use when you need to fetch from or send data to a REST API.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Tue, 21 Apr 2026 21:36:42 GMT
+---
+# Implementing Flutter Networking
+
+## Contents
+- [Configuration & Permissions](#configuration--permissions)
+- [Request Execution & Response Handling](#request-execution--response-handling)
+- [Background Parsing](#background-parsing)
+- [Workflow: Executing Network Operations](#workflow-executing-network-operations)
+- [Examples](#examples)
+
+## Configuration & Permissions
+
+Configure the environment and platform-specific permissions required for network access.
+
+1. Add the `http` package dependency via the terminal:
+   ```bash
+   flutter pub add http
+   ```
+2. Import the package in your Dart files:
+   ```dart
+   import 'package:http/http.dart' as http;
+   ```
+3. Configure Android permissions by adding the Internet permission to `android/app/src/main/AndroidManifest.xml`:
+   ```xml
+   <uses-permission android:name="android.permission.INTERNET" />
+   ```
+4. Configure macOS entitlements by adding the network client key to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:
+   ```xml
+   <key>com.apple.security.network.client</key>
+   <true/>
+   ```
+
+## Request Execution & Response Handling
+
+Execute HTTP operations and map responses to strongly typed Dart objects.
+
+*   **URIs:** Always parse URL strings using `Uri.parse('your_url')`.
+*   **Headers:** Inject authorization and content-type headers via the `headers` parameter map. Use `HttpHeaders.authorizationHeader` for auth tokens.
+*   **Payloads:** For POST and PUT requests, encode the body using `jsonEncode()` from `dart:convert`.
+*   **Status Validation:** Evaluate `response.statusCode`. Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success. 
+*   **Error Handling:** Throw explicit exceptions for non-success status codes. Never return `null` on failure, as this prevents `FutureBuilder` from triggering its error state and causes infinite loading indicators.
+*   **Deserialization:** Parse the raw string using `jsonDecode(response.body)` and map it to a custom Dart object using a factory constructor (e.g., `fromJson`).
+
+## Background Parsing
+
+Offload expensive JSON parsing to a separate Isolate to prevent UI jank (frame drops).
+
+*   Import `package:flutter/foundation.dart`.
+*   Use the `compute()` function to run the parsing logic in a background isolate.
+*   Ensure the parsing function passed to `compute()` is a top-level function or a static method, as closures or instance methods cannot be passed across isolates.
+
+## Workflow: Executing Network Operations
+
+Use the following checklist to implement and validate network operations.
+
+**Task Progress:**
+- [ ] 1. Define the strongly typed Dart model with a `fromJson` factory constructor.
+- [ ] 2. Implement the network request method returning a `Future<Model>`.
+- [ ] 3. Apply conditional logic based on the operation type:
+  - **If fetching data (GET):** Append query parameters to the URI.
+  - **If mutating data (POST/PUT):** Set `'Content-Type': 'application/json; charset=UTF-8'` and attach the `jsonEncode` body.
+  - **If deleting data (DELETE):** Return an empty model instance on success (`200 OK`).
+- [ ] 4. Validate the `statusCode` and throw an `Exception` on failure.
+- [ ] 5. Integrate the `Future` into the UI using `FutureBuilder`.
+- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, and default to a `CircularProgressIndicator`.
+- [ ] 7. **Feedback Loop:** Run the app -> trigger the network request -> review console for unhandled exceptions -> fix parsing or permission errors.
+
+## Examples
+
+### High-Fidelity Implementation: Fetching and Parsing in the Background
+
+```dart
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:http/http.dart' as http;
+
+// 1. Top-level parsing function for Isolate
+List<Photo> parsePhotos(String responseBody) {
+  final parsed = (jsonDecode(responseBody) as List<Object?>)
+      .cast<Map<String, Object?>>();
+  return parsed.map<Photo>(Photo.fromJson).toList();
+}
+
+// 2. Network execution with background parsing
+Future<List<Photo>> fetchPhotos() async {
+  final response = await http.get(
+    Uri.parse('https://jsonplaceholder.typicode.com/photos'),
+    headers: {
+      HttpHeaders.authorizationHeader: 'Bearer your_token_here',
+      HttpHeaders.acceptHeader: 'application/json',
+    },
+  );
+
+  if (response.statusCode == 200) {
+    // Offload heavy parsing to a background isolate
+    return compute(parsePhotos, response.body);
+  } else {
+    throw Exception('Failed to load photos. Status: ${response.statusCode}');
+  }
+}
+}
+
+// 3. Strongly typed model
+class Photo {
+  final int id;
+  final String title;
+  final String thumbnailUrl;
+
+  const Photo({
+    required this.id,
+    required this.title,
+    required this.thumbnailUrl,
+  });
+
+  factory Photo.fromJson(Map<String, dynamic> json) {
+    return Photo(
+      id: json['id'] as int,
+      title: json['title'] as String,
+      thumbnailUrl: json['thumbnailUrl'] as String,
+    );
+  }
+}
+
+// 4. UI Integration
+class PhotoGallery extends StatefulWidget {
+  const PhotoGallery({super.key});
+
+  @override
+  State<PhotoGallery> createState() => _PhotoGalleryState();
+}
+
+class _PhotoGalleryState extends State<PhotoGallery> {
+  late Future<List<Photo>> _futurePhotos;
+
+  @override
+  void initState() {
+    super.initState();
+    // Initialize Future once to prevent re-fetching on rebuilds
+    _futurePhotos = fetchPhotos();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return FutureBuilder<List<Photo>>(
+      future: _futurePhotos,
+      builder: (context, snapshot) {
+        if (snapshot.hasData) {
+          final photos = snapshot.data!;
+          return ListView.builder(
+            itemCount: photos.length,
+            itemBuilder: (context, index) => ListTile(
+              leading: Image.network(photos[index].thumbnailUrl),
+              title: Text(photos[index].title),
+            ),
+          );
+        } else if (snapshot.hasError) {
+          return Center(child: Text('Error: ${snapshot.error}'));
+        }
+        
+        // Default loading state
+        return const Center(child: CircularProgressIndicator());
+      },
+    );
+  }
+}
+```

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/add-dart-lint-validation-rule/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: add-dart-lint-validation-rule
+description: Instructions for adding a new validation rule and CLI flag to dart_skills_lint.
+---
+
+# Add a New Validation Rule and Flag
+
+Use this skill when you need to add a new validation rule to the `dart_skills_lint` package, expose it as a toggleable CLI flag, and verify its behavior.
+
+---
+
+## 🛠️ Step-by-Step Implementation
+
+### 1. Create the Rule Class
+Create a new file in `lib/src/rules/` extending `SkillRule`.
+
+> [!TIP]
+> If your rule expects a specific structure in the skill's YAML frontmatter (e.g., inside `metadata`), document this structure clearly in the class Dart docstring.
+
+```dart
+// lib/src/rules/my_new_rule.dart
+
+import '../models/analysis_severity.dart';
+import '../models/skill_context.dart';
+import '../models/skill_rule.dart';
+import '../models/validation_error.dart';
+
+class MyNewRule extends SkillRule {
+  MyNewRule({super.severity});
+
+  @override
+  Future<List<ValidationError>> validate(SkillContext context) async {
+    final errors = <ValidationError>[];
+    // Add validation logic here using context.rawContent or context.directory
+    return errors;
+  }
+}
+```
+
+#### Accessing YAML Frontmatter
+If your rule needs configuration from the skill's YAML frontmatter, you can access it via `context.parsedYaml`.
+
+```dart
+  @override
+  Future<List<ValidationError>> validate(SkillContext context) async {
+    final errors = <ValidationError>[];
+    final yaml = context.parsedYaml;
+    if (yaml != null) {
+      final metadata = yaml['metadata'];
+      if (metadata is Map) {
+        // Read your custom config here
+      }
+    }
+    return errors;
+  }
+```
+
+### 2. Register the Rule in `lib/src/rule_registry.dart`
+
+Add a new `CheckType` instance to `RuleRegistry.allChecks` list. This automatically exposes it as a CLI flag.
+
+```dart
+// lib/src/rule_registry.dart in allChecks list
+
+  const CheckType(
+    name: MyNewRule.ruleName,
+    defaultSeverity: MyNewRule.defaultSeverity,
+    help: 'Description of what the rule does for CLI help.',
+  ),
+```
+
+Then, add a case to `RuleRegistry.createRule` to instantiate your rule:
+
+```dart
+// lib/src/rule_registry.dart in createRule method
+
+  static SkillRule? createRule(String name, AnalysisSeverity severity) {
+    switch (name) {
+      // ... other rules
+      case MyNewRule.ruleName:
+        return MyNewRule(severity: severity);
+      default:
+        return null;
+    }
+  }
+```
+
+### 3. Handle Disabled by Default Rules (If applicable)
+If the rule is disabled by default (`defaultSeverity: AnalysisSeverity.disabled`), passing the flag `--check-my-new-rule` will automatically enable it with `AnalysisSeverity.error` severity (handled in `entry_point.dart`).
+
+---
+
+## 🧪 Testing the New Rule
+
+You must write automated tests verifying your rule triggers when it should and skips when it shouldn't.
+
+### Preferred Approach: In-Memory Unit Tests
+Instead of writing files to disk, test the rule directly using a mock `SkillContext`. This is faster and avoids I/O dependencies.
+
+```dart
+// test/my_new_rule_test.dart
+
+import 'dart:io';
+import 'package:dart_skills_lint/src/models/analysis_severity.dart';
+import 'package:dart_skills_lint/src/models/skill_context.dart';
+import 'package:dart_skills_lint/src/models/validation_error.dart';
+import 'package:dart_skills_lint/src/rules/my_new_rule.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('MyNewRule', () {
+    test('flags invalid content', () async {
+      final rule = MyNewRule(severity: AnalysisSeverity.warning);
+      final context = SkillContext(
+        directory: Directory('dummy'),
+        rawContent: 'Invalid content',
+      );
+
+      final List<ValidationError> errors = await rule.validate(context);
+
+      expect(errors, isNotEmpty);
+      expect(errors.first.message, contains('Expected error message'));
+    });
+
+    test('passes valid content', () async {
+      final rule = MyNewRule(severity: AnalysisSeverity.warning);
+      final context = SkillContext(
+        directory: Directory('dummy'),
+        rawContent: 'Valid content',
+      );
+
+      final List<ValidationError> errors = await rule.validate(context);
+
+      expect(errors, isEmpty);
+    });
+  });
+}
+```
+
+### Alternative Approach: File System Interaction
+If the rule interacts with the file system or wraps an external CLI tool (like `popmark`), you should use a temporary directory for testing instead of in-memory mocks.
+
+```dart
+    late Directory tempDir;
+
+    setUp(() async {
+      tempDir = await Directory.systemTemp.createTemp('my_rule_test.');
+    });
+
+    tearDown(() async {
+      if (tempDir.existsSync()) {
+        await tempDir.delete(recursive: true);
+      }
+    });
+
+    test('flags invalid file content', () async {
+      final Directory skillDir = await Directory('${tempDir.path}/test-skill').create();
+      await File('${skillDir.path}/SKILL.md').writeAsString('Invalid content');
+
+      final rule = MyNewRule(severity: AnalysisSeverity.warning);
+      final context = SkillContext(directory: skillDir, rawContent: 'Invalid content');
+
+      final List<ValidationError> errors = await rule.validate(context);
+
+      expect(errors, isNotEmpty);
+    });
+```
+
+### Integration Tests
+If the rule interacts with CLI flags or configuration files, add a test in `test/cli_integration_test.dart` using `TestProcess`.
+> [!IMPORTANT]
+> When writing integration tests that use config files and `TestProcess`, ensure that paths in the config file and paths passed to the CLI match in style (both relative or both absolute) to avoid issues with path matching in `entry_point.dart`.
+
+---
+
+## 📚 Documentation Updates
+
+When a new rule is introduced, verify that you synchronize sibling markdown files!
+
+1.  **`README.md`:**
+    *   Add your flag under the **Usage** and **Flags** sections so users know it exists.
+2.  **`documentation/knowledge/SPECIFICATION.md`:**
+    *   Document the formal constraint in the specification if it defines a standard for skill files.
+
+---
+
+## 🚦 Checklist Before Submitting PR
+
+- [ ] Rule class created in `lib/src/rules/`.
+- [ ] Rule registered in `lib/src/rule_registry.dart`.
+- [ ] Unit tests added in `test/` using in-memory `SkillContext`.
+- [ ] Usage listed in `README.md`.
+- [ ] Schema documented in `documentation/knowledge/SPECIFICATION.md` (if applicable).
+- [ ] Run `dart format .` to format code.
+- [ ] Run `dart analyze --fatal-infos` to ensure no issues.
+- [ ] Run `dart test` to ensure tests passing.

package/skills/flutter-skills/tool/dart_skills_lint/.agents/skills/dart-best-practices/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: dart-best-practices
+description: |-
+  General best practices for Dart development.
+  Covers code style, effective Dart, and language features.
+license: Apache-2.0
+---
+
+# Dart Best Practices
+
+## 1. When to use this skill
+Use this skill when:
+-   Writing or reviewing Dart code.
+-   Looking for guidance on idiomatic Dart usage.
+
+## 2. Best Practices
+
+### Multi-line Strings
+Prefer using multi-line strings (`'''`) over concatenating strings with `+` and
+`\n`, especially for large blocks of text like SQL queries, HTML, or
+PEM-encoded keys. This improves readability and avoids
+`lines_longer_than_80_chars` lint errors by allowing natural line breaks.
+
+**Avoid:**
+```dart
+final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
+    base64Encode(fullBytes) +
+    '\n-----END RSA PRIVATE KEY-----';
+```
+
+**Prefer:**
+```dart
+final pem = '''
+-----BEGIN RSA PRIVATE KEY-----
+${base64Encode(fullBytes)}
+-----END RSA PRIVATE KEY-----''';
+```
+
+### Line Length
+Avoid lines longer than 80 characters, even in Markdown files and comments.
+This ensures code is readable in split-screen views and on smaller screens
+without horizontal scrolling.
+
+**Prefer:**
+Target 80 characters for wrapping text. Exceptions are allowed for long URLs
+or identifiers that cannot be broken.
+
+## Discovery
+
+### Multi-line Strings
+To find candidates for multi-line strings, search for string concatenation
+with `+` involving newlines:
+- **Regex**: `['"]\s*\+\s*['"]`
+- **Regex**: `\+\s*['"].*\\n`
+
+### Line Length
+- Rely on the `lines_longer_than_80_chars` lint from the analyzer.
+
+## Related Skills
+
+- **[dart-modern-features]**: For idiomatic
+  usage of modern Dart features like Pattern Matching (useful for deep JSON
+  extraction), Records, and Switch Expressions.
+
+[dart-modern-features]: https://github.com/kevmoo/dash_skills/blob/main/.agent/skills/dart-modern-features/SKILL.md