claude-code-pilot 2.0.0 → 3.0.0

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

@@ -0,0 +1,283 @@
+---
+name: laravel-tdd
+description: Test-driven development for Laravel with PHPUnit and Pest, factories, database testing, fakes, and coverage targets.
+origin: ECC
+---
+
+# 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/src/skills/laravel-verification/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: laravel-verification
+description: Verification loop for Laravel projects: env checks, linting, static analysis, tests with coverage, security scans, and deployment readiness.
+origin: ECC
+---
+
+# 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/src/skills/mcp-server-patterns/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
+origin: ECC
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Connecting with stdio
+
+For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+### Remote (Streamable HTTP)
+
+For Cursor, cloud, or other remote clients, use **Streamable HTTP** (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
+
+## Examples
+
+### Install and server setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+```
+
+Register tools and resources using the API your SDK version provides: some versions use `server.tool(name, description, schema, handler)` (positional args), others use `server.tool({ name, description, inputSchema }, handler)` or `registerTool()`. Same for resources — include a `uri` in the handler when the API provides it. Check the official MCP docs or Context7 for the current `@modelcontextprotocol/sdk` signatures to avoid copy-paste errors.
+
+Use **Zod** (or the SDK’s preferred schema format) for input validation.
+
+## Best Practices
+
+- **Schema first**: Define input schemas for every tool; document parameters and return shape.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Rate and cost**: For tools that call external APIs, consider rate limits and cost; document in the tool description.
+- **Versioning**: Pin SDK version in package.json; check release notes when upgrading.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.