@h1dr0n/skill-pool 0.1.0

package/skills/laravel/skills/laravel-tdd.md

@@ -0,0 +1,277 @@
+# Laravel TDD Workflow
+
+Test-driven development for Laravel applications using PHPUnit and Pest with 80%+ coverage (unit + feature).
+
+## When to Use
+
+- New features or endpoints in Laravel
+- Bug fixes or refactors
+- Testing Eloquent models, policies, jobs, and notifications
+- Prefer Pest for new tests unless the project already standardizes on PHPUnit
+
+## How It Works
+
+### Red-Green-Refactor Cycle
+
+1) Write a failing test
+2) Implement the minimal change to pass
+3) Refactor while keeping tests green
+
+### Test Layers
+
+- **Unit**: pure PHP classes, value objects, services
+- **Feature**: HTTP endpoints, auth, validation, policies
+- **Integration**: database + queue + external boundaries
+
+Choose layers based on scope:
+
+- Use **Unit** tests for pure business logic and services.
+- Use **Feature** tests for HTTP, auth, validation, and response shape.
+- Use **Integration** tests when validating DB/queues/external services together.
+
+### Database Strategy
+
+- `RefreshDatabase` for most feature/integration tests (runs migrations once per test run, then wraps each test in a transaction when supported; in-memory databases may re-migrate per test)
+- `DatabaseTransactions` when the schema is already migrated and you only need per-test rollback
+- `DatabaseMigrations` when you need a full migrate/fresh for every test and can afford the cost
+
+Use `RefreshDatabase` as the default for tests that touch the database: for databases with transaction support, it runs migrations once per test run (via a static flag) and wraps each test in a transaction; for `:memory:` SQLite or connections without transactions, it migrates before each test. Use `DatabaseTransactions` when the schema is already migrated and you only need per-test rollbacks.
+
+### Testing Framework Choice
+
+- Default to **Pest** for new tests when available.
+- Use **PHPUnit** only if the project already standardizes on it or requires PHPUnit-specific tooling.
+
+## Examples
+
+### PHPUnit Example
+
+```php
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class ProjectControllerTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_owner_can_create_project(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->postJson('/api/projects', [
+            'name' => 'New Project',
+        ]);
+
+        $response->assertCreated();
+        $this->assertDatabaseHas('projects', ['name' => 'New Project']);
+    }
+}
+```
+
+### Feature Test Example (HTTP Layer)
+
+```php
+use App\Models\Project;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class ProjectIndexTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_projects_index_returns_paginated_results(): void
+    {
+        $user = User::factory()->create();
+        Project::factory()->count(3)->for($user)->create();
+
+        $response = $this->actingAs($user)->getJson('/api/projects');
+
+        $response->assertOk();
+        $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
+    }
+}
+```
+
+### Pest Example
+
+```php
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+use function Pest\Laravel\actingAs;
+use function Pest\Laravel\assertDatabaseHas;
+
+uses(RefreshDatabase::class);
+
+test('owner can create project', function () {
+    $user = User::factory()->create();
+
+    $response = actingAs($user)->postJson('/api/projects', [
+        'name' => 'New Project',
+    ]);
+
+    $response->assertCreated();
+    assertDatabaseHas('projects', ['name' => 'New Project']);
+});
+```
+
+### Feature Test Pest Example (HTTP Layer)
+
+```php
+use App\Models\Project;
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+use function Pest\Laravel\actingAs;
+
+uses(RefreshDatabase::class);
+
+test('projects index returns paginated results', function () {
+    $user = User::factory()->create();
+    Project::factory()->count(3)->for($user)->create();
+
+    $response = actingAs($user)->getJson('/api/projects');
+
+    $response->assertOk();
+    $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
+});
+```
+
+### Factories and States
+
+- Use factories for test data
+- Define states for edge cases (archived, admin, trial)
+
+```php
+$user = User::factory()->state(['role' => 'admin'])->create();
+```
+
+### Database Testing
+
+- Use `RefreshDatabase` for clean state
+- Keep tests isolated and deterministic
+- Prefer `assertDatabaseHas` over manual queries
+
+### Persistence Test Example
+
+```php
+use App\Models\Project;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class ProjectRepositoryTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_project_can_be_retrieved_by_slug(): void
+    {
+        $project = Project::factory()->create(['slug' => 'alpha']);
+
+        $found = Project::query()->where('slug', 'alpha')->firstOrFail();
+
+        $this->assertSame($project->id, $found->id);
+    }
+}
+```
+
+### Fakes for Side Effects
+
+- `Bus::fake()` for jobs
+- `Queue::fake()` for queued work
+- `Mail::fake()` and `Notification::fake()` for notifications
+- `Event::fake()` for domain events
+
+```php
+use Illuminate\Support\Facades\Queue;
+
+Queue::fake();
+
+dispatch(new SendOrderConfirmation($order->id));
+
+Queue::assertPushed(SendOrderConfirmation::class);
+```
+
+```php
+use Illuminate\Support\Facades\Notification;
+
+Notification::fake();
+
+$user->notify(new InvoiceReady($invoice));
+
+Notification::assertSentTo($user, InvoiceReady::class);
+```
+
+### Auth Testing (Sanctum)
+
+```php
+use Laravel\Sanctum\Sanctum;
+
+Sanctum::actingAs($user);
+
+$response = $this->getJson('/api/projects');
+$response->assertOk();
+```
+
+### HTTP and External Services
+
+- Use `Http::fake()` to isolate external APIs
+- Assert outbound payloads with `Http::assertSent()`
+
+### Coverage Targets
+
+- Enforce 80%+ coverage for unit + feature tests
+- Use `pcov` or `XDEBUG_MODE=coverage` in CI
+
+### Test Commands
+
+- `php artisan test`
+- `vendor/bin/phpunit`
+- `vendor/bin/pest`
+
+### Test Configuration
+
+- Use `phpunit.xml` to set `DB_CONNECTION=sqlite` and `DB_DATABASE=:memory:` for fast tests
+- Keep separate env for tests to avoid touching dev/prod data
+
+### Authorization Tests
+
+```php
+use Illuminate\Support\Facades\Gate;
+
+$this->assertTrue(Gate::forUser($user)->allows('update', $project));
+$this->assertFalse(Gate::forUser($otherUser)->allows('update', $project));
+```
+
+### Inertia Feature Tests
+
+When using Inertia.js, assert on the component name and props with the Inertia testing helpers.
+
+```php
+use App\Models\User;
+use Inertia\Testing\AssertableInertia;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class DashboardInertiaTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_dashboard_inertia_props(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->get('/dashboard');
+
+        $response->assertOk();
+        $response->assertInertia(fn (AssertableInertia $page) => $page
+            ->component('Dashboard')
+            ->where('user.id', $user->id)
+            ->has('projects')
+        );
+    }
+}
+```
+
+Prefer `assertInertia` over raw JSON assertions to keep tests aligned with Inertia responses.

package/skills/laravel/skills/laravel-verification.md

@@ -0,0 +1,173 @@
+# Laravel Verification Loop
+
+Run before PRs, after major changes, and pre-deploy.
+
+## When to Use
+
+- Before opening a pull request for a Laravel project
+- After major refactors or dependency upgrades
+- Pre-deployment verification for staging or production
+- Running full lint -> test -> security -> deploy readiness pipeline
+
+## How It Works
+
+- Run phases sequentially from environment checks through deployment readiness so each layer builds on the last.
+- Environment and Composer checks gate everything else; stop immediately if they fail.
+- Linting/static analysis should be clean before running full tests and coverage.
+- Security and migration reviews happen after tests so you verify behavior before data or release steps.
+- Build/deploy readiness and queue/scheduler checks are final gates; any failure blocks release.
+
+## Phase 1: Environment Checks
+
+```bash
+php -v
+composer --version
+php artisan --version
+```
+
+- Verify `.env` is present and required keys exist
+- Confirm `APP_DEBUG=false` for production environments
+- Confirm `APP_ENV` matches the target deployment (`production`, `staging`)
+
+If using Laravel Sail locally:
+
+```bash
+./vendor/bin/sail php -v
+./vendor/bin/sail artisan --version
+```
+
+## Phase 1.5: Composer and Autoload
+
+```bash
+composer validate
+composer dump-autoload -o
+```
+
+## Phase 2: Linting and Static Analysis
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+```
+
+If your project uses Psalm instead of PHPStan:
+
+```bash
+vendor/bin/psalm
+```
+
+## Phase 3: Tests and Coverage
+
+```bash
+php artisan test
+```
+
+Coverage (CI):
+
+```bash
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+CI example (format -> static analysis -> tests):
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+## Phase 4: Security and Dependency Checks
+
+```bash
+composer audit
+```
+
+## Phase 5: Database and Migrations
+
+```bash
+php artisan migrate --pretend
+php artisan migrate:status
+```
+
+- Review destructive migrations carefully
+- Ensure migration filenames follow `Y_m_d_His_*` (e.g., `2025_03_14_154210_create_orders_table.php`) and describe the change clearly
+- Ensure rollbacks are possible
+- Verify `down()` methods and avoid irreversible data loss without explicit backups
+
+## Phase 6: Build and Deployment Readiness
+
+```bash
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+- Ensure cache warmups succeed in production configuration
+- Verify queue workers and scheduler are configured
+- Confirm `storage/` and `bootstrap/cache/` are writable in the target environment
+
+## Phase 7: Queue and Scheduler Checks
+
+```bash
+php artisan schedule:list
+php artisan queue:failed
+```
+
+If Horizon is used:
+
+```bash
+php artisan horizon:status
+```
+
+If `queue:monitor` is available, use it to check backlog without processing jobs:
+
+```bash
+php artisan queue:monitor default --max=100
+```
+
+Active verification (staging only): dispatch a no-op job to a dedicated queue and run a single worker to process it (ensure a non-`sync` queue connection is configured).
+
+```bash
+php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
+php artisan queue:work --once --queue=healthcheck
+```
+
+Verify the job produced the expected side effect (log entry, healthcheck table row, or metric).
+
+Only run this on non-production environments where processing a test job is safe.
+
+## Examples
+
+Minimal flow:
+
+```bash
+php -v
+composer --version
+php artisan --version
+composer validate
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+php artisan test
+composer audit
+php artisan migrate --pretend
+php artisan config:cache
+php artisan queue:failed
+```
+
+CI-style pipeline:
+
+```bash
+composer validate
+composer dump-autoload -o
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+composer audit
+php artisan migrate --pretend
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+php artisan schedule:list
+```

package/skills/mobile/agents/dart-build-resolver.md

@@ -0,0 +1,201 @@
+---
+name: dart-build-resolver
+description: Dart/Flutter build, analysis, and dependency error resolution specialist. Fixes `dart analyze` errors, Flutter compilation failures, pub dependency conflicts, and build_runner issues with minimal, surgical changes. Use when Dart/Flutter builds fail.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Dart/Flutter Build Error Resolver
+
+You are an expert Dart/Flutter build error resolution specialist. Your mission is to fix Dart analyzer errors, Flutter compilation issues, pub dependency conflicts, and build_runner failures with **minimal, surgical changes**.
+
+## Core Responsibilities
+
+1. Diagnose `dart analyze` and `flutter analyze` errors
+2. Fix Dart type errors, null safety violations, and missing imports
+3. Resolve `pubspec.yaml` dependency conflicts and version constraints
+4. Fix `build_runner` code generation failures
+5. Handle Flutter-specific build errors (Android Gradle, iOS CocoaPods, web)
+
+## Diagnostic Commands
+
+Run these in order:
+
+```bash
+# Check Dart/Flutter analysis errors
+flutter analyze 2>&1
+# or for pure Dart projects
+dart analyze 2>&1
+
+# Check pub dependency resolution
+flutter pub get 2>&1
+
+# Check if code generation is stale
+dart run build_runner build --delete-conflicting-outputs 2>&1
+
+# Flutter build for target platform
+flutter build apk 2>&1           # Android
+flutter build ipa --no-codesign 2>&1  # iOS (CI without signing)
+flutter build web 2>&1           # Web
+```
+
+## Resolution Workflow
+
+```text
+1. flutter analyze        -> Parse error messages
+2. Read affected file     -> Understand context
+3. Apply minimal fix      -> Only what's needed
+4. flutter analyze        -> Verify fix
+5. flutter test           -> Ensure nothing broke
+```
+
+## Common Fix Patterns
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `The name 'X' isn't defined` | Missing import or typo | Add correct `import` or fix name |
+| `A value of type 'X?' can't be assigned to type 'X'` | Null safety — nullable not handled | Add `!`, `?? default`, or null check |
+| `The argument type 'X' can't be assigned to 'Y'` | Type mismatch | Fix type, add explicit cast, or correct API call |
+| `Non-nullable instance field 'x' must be initialized` | Missing initializer | Add initializer, mark `late`, or make nullable |
+| `The method 'X' isn't defined for type 'Y'` | Wrong type or wrong import | Check type and imports |
+| `'await' applied to non-Future` | Awaiting a non-async value | Remove `await` or make function async |
+| `Missing concrete implementation of 'X'` | Abstract interface not fully implemented | Add missing method implementations |
+| `The class 'X' doesn't implement 'Y'` | Missing `implements` or missing method | Add method or fix class signature |
+| `Because X depends on Y >=A and Z depends on Y <B, version solving failed` | Pub version conflict | Adjust version constraints or add `dependency_overrides` |
+| `Could not find a file named "pubspec.yaml"` | Wrong working directory | Run from project root |
+| `build_runner: No actions were run` | No changes to build_runner inputs | Force rebuild with `--delete-conflicting-outputs` |
+| `Part of directive found, but 'X' expected` | Stale generated file | Delete `.g.dart` file and re-run build_runner |
+
+## Pub Dependency Troubleshooting
+
+```bash
+# Show full dependency tree
+flutter pub deps
+
+# Check why a specific package version was chosen
+flutter pub deps --style=compact | grep <package>
+
+# Upgrade packages to latest compatible versions
+flutter pub upgrade
+
+# Upgrade specific package
+flutter pub upgrade <package_name>
+
+# Clear pub cache if metadata is corrupted
+flutter pub cache repair
+
+# Verify pubspec.lock is consistent
+flutter pub get --enforce-lockfile
+```
+
+## Null Safety Fix Patterns
+
+```dart
+// Error: A value of type 'String?' can't be assigned to type 'String'
+// BAD — force unwrap
+final name = user.name!;
+
+// GOOD — provide fallback
+final name = user.name ?? 'Unknown';
+
+// GOOD — guard and return early
+if (user.name == null) return;
+final name = user.name!; // safe after null check
+
+// GOOD — Dart 3 pattern matching
+final name = switch (user.name) {
+  final n? => n,
+  null => 'Unknown',
+};
+```
+
+## Type Error Fix Patterns
+
+```dart
+// Error: The argument type 'List<dynamic>' can't be assigned to 'List<String>'
+// BAD
+final ids = jsonList; // inferred as List<dynamic>
+
+// GOOD
+final ids = List<String>.from(jsonList);
+// or
+final ids = (jsonList as List).cast<String>();
+```
+
+## build_runner Troubleshooting
+
+```bash
+# Clean and regenerate all files
+dart run build_runner clean
+dart run build_runner build --delete-conflicting-outputs
+
+# Watch mode for development
+dart run build_runner watch --delete-conflicting-outputs
+
+# Check for missing build_runner dependencies in pubspec.yaml
+# Required: build_runner, json_serializable / freezed / riverpod_generator (as dev_dependencies)
+```
+
+## Android Build Troubleshooting
+
+```bash
+# Clean Android build cache
+cd android && ./gradlew clean && cd ..
+
+# Invalidate Flutter tool cache
+flutter clean
+
+# Rebuild
+flutter pub get && flutter build apk
+
+# Check Gradle/JDK version compatibility
+cd android && ./gradlew --version
+```
+
+## iOS Build Troubleshooting
+
+```bash
+# Update CocoaPods
+cd ios && pod install --repo-update && cd ..
+
+# Clean iOS build
+flutter clean && cd ios && pod deintegrate && pod install && cd ..
+
+# Check for platform version mismatches in Podfile
+# Ensure ios platform version >= minimum required by all pods
+```
+
+## Key Principles
+
+- **Surgical fixes only** — don't refactor, just fix the error
+- **Never** add `// ignore:` suppressions without approval
+- **Never** use `dynamic` to silence type errors
+- **Always** run `flutter analyze` after each fix to verify
+- Fix root cause over suppressing symptoms
+- Prefer null-safe patterns over bang operators (`!`)
+
+## Stop Conditions
+
+Stop and report if:
+- Same error persists after 3 fix attempts
+- Fix introduces more errors than it resolves
+- Requires architectural changes or package upgrades that change behavior
+- Conflicting platform constraints need user decision
+
+## Output Format
+
+```text
+[FIXED] lib/features/cart/data/cart_repository_impl.dart:42
+Error: A value of type 'String?' can't be assigned to type 'String'
+Fix: Changed `final id = response.id` to `final id = response.id ?? ''`
+Remaining errors: 2
+
+[FIXED] pubspec.yaml
+Error: Version solving failed — http >=0.13.0 required by dio and <0.13.0 required by retrofit
+Fix: Upgraded dio to ^5.3.0 which allows http >=0.13.0
+Remaining errors: 0
+```
+
+Final: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`
+
+For detailed Dart patterns and code examples, see `skill: flutter-dart-code-review`.