@event4u/agent-config 1.9.1

package/.agent-src/skills/php-coder/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: php-coder
+description: "Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts."
+source: package
+---
+
+# coder
+
+## When to use
+
+This skill applies to ALL code generation and editing tasks. Every other skill builds on top of this one.
+
+Do NOT use when:
+- Only reading/reviewing code (use `code-review` skill)
+- Only running quality tools (use `quality-tools` skill)
+
+## Procedure: Before writing code
+
+### Step 0: Inspect project
+
+1. Read `AGENTS.md` and `.github/copilot-instructions.md` for project-specific rules.
+2. If working in a module (`app/Modules/*/`), check `app/Modules/{Module}/agents/` for module docs.
+3. Look at neighboring files in the same directory — match the style.
+4. Read `./agents/` for project-specific architecture.
+5. Check `ecs.php` / `rector.php` (if they exist) — code accordingly.
+6. Read `Makefile` or `Taskfile.yml` for available build/test/quality targets.
+
+### Step 1: Detect project type
+
+- `artisan` exists → Laravel project (Pest, Modules if present)
+- No `artisan` + `composer.json` → Standalone PHP / Composer project
+- Check `AGENTS.md` and `./agents/` for conventions
+
+### Step 2: Apply conventions
+
+→ See `php-coding` rule (always loaded) for PHP coding standards.
+→ See guideline `php/general.md` for detailed PHP conventions.
+→ See guideline `php/controllers.md`, `php/eloquent.md`, etc. for domain-specific conventions.
+
+### Core principles
+
+- **KISS** — simplest solution that works. No over-engineering.
+- **YAGNI** — only build what's needed now.
+- **DRY** — extract shared logic. Don't abstract prematurely.
+- **SOLID** — single responsibility, depend on abstractions, small interfaces.
+
+### Validate
+
+- Run PHPStan on changed files — must pass at level 9.
+- Run affected tests — must pass.
+- Verify strict types, typed properties, return types on all new code.
+- Check that no `dd()`, `var_dump()`, `print_r()` remain.
+
+## Output format
+
+1. Code following project guidelines and existing patterns
+2. All downstream changes (callers, tests, imports) included
+
+## Gotcha
+
+- Don't introduce new patterns without being asked.
+- Don't refactor code you're not working on.
+- Use `Math` helper for ALL calculations — never raw PHP arithmetic.
+- `MonitoringHelper::captureException()` for Sentry reporting.
+
+## Do NOT
+
+- Do NOT use native arithmetic (`+`, `-`, `*`, `/`) for business calculations — use `Math` helper.
+- Do NOT refactor code you're not actively working on.
+- Do NOT use `var_dump()`, `print_r()`, `dd()` — disallowed by PHPStan.
+
+## Auto-trigger keywords
+
+- PHP coding
+- coding standards
+- SOLID
+- clean code
+- best practices

package/.agent-src/skills/php-coder/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "php-coder",
+  "description": "5 should-trigger + 5 should-not-trigger queries. Multi-skill co-activation (e.g. php-coder alongside pest-testing on a test query) is accepted as TP where writing PHP code is a legitimate sub-task. Near-misses share PHP/Laravel vocabulary without being code-generation tasks.",
+  "queries": [
+    {"q": "my UserController is getting huge, split it into a service", "trigger": true},
+    {"q": "write a class for parsing CSV files with proper type hints", "trigger": true},
+    {"q": "refactor this foreach to use array_map but keep it readable", "trigger": true},
+    {"q": "add a __toString method to this DTO and make fields readonly", "trigger": true},
+    {"q": "this legacy controller mixes config and business logic, clean it up", "trigger": true},
+    {"q": "run phpstan on this file and show me all errors", "trigger": false},
+    {"q": "create a migration for adding a phone column to users", "trigger": false},
+    {"q": "set up docker-compose for this PHP project", "trigger": false},
+    {"q": "write a Pest test for the UserRepository", "trigger": true, "note": "T-class: co-activation with pest-testing is accepted — Pest tests are PHP code, loading php-coder alongside pest-testing is legitimate multi-skill support"},
+    {"q": "explain what strict_types does in PHP", "trigger": false}
+  ]
+}

package/.agent-src/skills/php-debugging/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: php-debugging
+description: "Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'."
+source: package
+---
+
+# php-debugging
+
+## When to use
+
+Use this skill when:
+- Setting up or troubleshooting Xdebug
+- Debugging PHP code with breakpoints
+- Investigating performance issues
+- Running code coverage
+- Helping users configure their IDE for debugging
+
+This skill extends `php-coder` and `php`.
+
+## Procedure: Debug with Xdebug
+
+1. **Detect the project's debug setup** — check `docker-compose.yml` / `compose.yaml` for Xdebug containers.
+2. **Check Dockerfile** — look for a `dev-xdebug` build stage or Xdebug installation.
+3. **Check NGINX config** — look for header-based routing to a debug container.
+4. **Read project docs** — check `Docs/XDEBUG_SETUP.md` or `docs/` for setup instructions.
+5. **Check `.env`** — look for `DOCKER_XDEBUG_MODE` and `DOCKER_XDEBUG_PORT`.
+
+## Dual-container architecture
+
+Many projects use two PHP containers for optimal performance:
+
+| Container | Purpose | When used |
+|---|---|---|
+| `*-php` | Fast PHP-FPM, no Xdebug overhead | All normal requests |
+| `*-php-xdebug` | PHP-FPM with Xdebug enabled | Only debug requests |
+
+NGINX routes requests based on HTTP headers:
+- **No debug header** → fast container (no Xdebug)
+- **Debug header present** → Xdebug container
+
+### Debug headers
+
+| Header | Value | Recommended for |
+|---|---|---|
+| `X-Xdebug-Enable` | `1` or `true` | Manual tests, Postman |
+| `X-Debug-Session` | `PHPSTORM` | IDE integration |
+| `XDEBUG-SESSION` | any value | Standard Xdebug header |
+
+**Important:** Use hyphens, not underscores. `XDEBUG_SESSION` does NOT work — use `XDEBUG-SESSION`.
+
+### Verify routing
+
+Check the `X-PHP-Backend` response header to confirm which container handled the request:
+
+```bash
+# Normal request
+curl -I http://localhost:8002/  # → X-PHP-Backend: *-php:9000
+
+# Debug request
+curl -I -H "X-Xdebug-Enable: 1" http://localhost:8002/  # → X-PHP-Backend: *-php-xdebug:9000
+```
+
+## Xdebug configuration
+
+### Environment variables
+
+```bash
+DOCKER_XDEBUG_MODE=develop,debug,coverage   # Xdebug modes
+DOCKER_XDEBUG_PORT=9003                      # IDE listens on this port
+```
+
+### Xdebug modes
+
+| Mode | Purpose |
+|---|---|
+| `debug` | Step debugging with breakpoints |
+| `develop` | Enhanced error messages, var_dump improvements |
+| `coverage` | Code coverage for tests |
+| `profile` | Performance profiling (generates cachegrind files) |
+| `trace` | Function call tracing |
+
+### PHP-FPM on-demand (Xdebug container)
+
+The Xdebug container typically uses `pm = ondemand` to save resources:
+- Workers start only when a debug request arrives
+- Idle workers terminate after 60s
+- Reduces memory usage by ~60-70% when not debugging
+- Unlimited request timeout for breakpoint sessions
+
+## IDE setup
+
+### PhpStorm
+
+1. **Debug port**: Settings → PHP → Debug → Port: `9003`
+2. **Enable listening**: Click "Start Listening for PHP Debug Connections" (phone icon)
+3. **Server config**: Settings → PHP → Servers:
+   - Host: `localhost`, Port: `80` (internal container port, not host port)
+   - Enable path mappings: local project root → `/var/www/html`
+4. **Browser extension**: Install "Xdebug helper", set IDE key to `PHPSTORM`
+
+### VS Code
+
+```json
+{
+  "name": "Listen for Xdebug",
+  "type": "php",
+  "request": "launch",
+  "port": 9003,
+  "pathMappings": {
+    "/var/www/html": "${workspaceFolder}"
+  }
+}
+```
+
+## Debugging workflow
+
+1. **Start listening** in IDE (PhpStorm: green phone icon)
+2. **Set breakpoints** in code
+3. **Send request with debug header** (browser extension, Postman, or curl)
+4. **IDE breaks** at breakpoint → inspect variables, step through code
+5. **Check `X-PHP-Backend` header** if debugging doesn't trigger
+
+## CLI debugging (Artisan commands, tests)
+
+For debugging Artisan commands or tests, enter the Xdebug container:
+
+```bash
+make console-xdebug    # Enter Xdebug container
+php artisan your:command   # Xdebug connects to IDE automatically
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| Breakpoints not hit | Check IDE is listening, verify path mappings, check `X-PHP-Backend` header |
+| IDE not connecting | `make console-xdebug` then `nc -zv host.docker.internal 9003` — should show "open" |
+| Wrong container used | Check response header `X-PHP-Backend`, verify debug header format (hyphens!) |
+| Slow normal requests | Verify normal requests go to fast container (no `X-PHP-Backend: *-xdebug*`) |
+| Xdebug logs | `make console-xdebug` then `tail -f /tmp/xdebug.log` |
+| Container not running | `docker compose ps` — both PHP containers should be "Up" |
+| Path mapping wrong | PhpStorm: Settings → PHP → Servers → verify local ↔ `/var/www/html` |
+
+## Container management
+
+```bash
+make console              # Fast PHP container (no Xdebug)
+make console-xdebug       # Xdebug container
+make rebuild-php-xdebug   # Rebuild Xdebug container only
+make rebuild-php-all      # Rebuild both PHP containers
+```
+
+## What NOT to do
+
+- Do not leave Xdebug enabled in production containers.
+- Do not use underscores in debug headers (`XDEBUG_SESSION` fails — use `XDEBUG-SESSION`).
+- Do not set PhpStorm server port to the host port (e.g. 8002) — use the internal port (80).
+- Do not run performance benchmarks against the Xdebug container.
+- Do not forget to check path mappings when breakpoints are silently skipped.
+
+
+## Output format
+
+1. Xdebug configuration or debugging session setup
+2. Root cause identified with evidence from debugger output
+
+## Gotcha
+
+- Xdebug runs in a separate container — don't confuse the fast container (port 80) with the debug container (port 8080).
+- The model tends to suggest `dd()` or `var_dump()` — they're forbidden by PHPStan config. Use Xdebug breakpoints.
+- Step-debugging over HTTP requires the `XDEBUG_SESSION` cookie/header — without it, breakpoints don't trigger.
+
+## Do NOT
+
+- Do NOT leave breakpoints or debug code in committed files.
+- Do NOT use var_dump() or dd() — use Xdebug breakpoints.
+- Do NOT debug in the fast container — switch to the Xdebug container.
+
+## Auto-trigger keywords
+
+- Xdebug
+- PHP debugging
+- breakpoint
+- step debugging

package/.agent-src/skills/php-service/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: php-service
+description: "Use when the user says 'create service', 'new service class', or needs a PHP service following SOLID principles with proper DI and repository usage."
+source: package
+---
+
+# php-service
+
+## When to use
+
+Use when creating a new service, extracting business logic from a controller, or refactoring into a service layer.
+
+Do NOT use when:
+- Controllers (use `laravel` skill)
+- DTOs (use `dto-creator` skill)
+- Models (use `eloquent` skill)
+
+## When to create a service
+
+✅ Multiple steps needing orchestration (save + calculate + notify)
+✅ Business rules beyond FormRequest
+✅ Logic reused across controllers, jobs, commands
+✅ Complex calculations or transformations
+
+❌ Simple CRUD — `$model->update($request->validated())` stays in controller
+❌ One-liner logic — no class for a single Eloquent call
+
+## Procedure: Create a service
+
+### Step 0: Inspect
+
+1. Read `./agents/` and `AGENTS.md` for service conventions.
+2. Check existing services — match naming, structure, DI patterns.
+3. Check for repositories — see `php/patterns/repositories.md` guideline.
+
+### Step 1: Create the class
+
+1. Location: `app/Services/{Domain}/` or `app/Modules/{Module}/App/Services/`.
+2. `declare(strict_types=1)`, proper namespace.
+3. Constructor inject dependencies (repositories, other services).
+4. Max 4 constructor dependencies — if more, split the service.
+
+### Step 2: Implement methods
+
+1. One responsibility per method.
+2. Delegate data access to repositories.
+3. Use DTOs for structured data.
+4. Use `Math` helper for calculations — never raw arithmetic.
+
+### Step 3: Wire up
+
+```php
+// Controller
+public function __invoke(
+    UpdateProjectRequest $request,
+    Project $project,
+    ProjectService $projectService,
+): ProjectResource {
+    $dto = UpdateProjectDTO::fromRequest($request);
+    return ProjectResource::make($projectService->update($project, $dto));
+}
+```
+
+## Conventions
+
+→ See guideline `php/patterns/service-layer.md` for full service layer conventions.
+
+### Validate
+
+- Run PHPStan on the service — must pass at level 9.
+- Verify single responsibility: service does one thing, no mixed concerns.
+- Confirm all dependencies are constructor-injected (no `app()` or facades in service).
+- Run affected tests — must pass.
+
+## Output format
+
+1. Service class with constructor injection and single responsibility
+2. Repository dependency if data access is needed
+
+## Gotcha
+
+- Don't create "god services" with 10+ methods — split by responsibility.
+- Don't inject `Request` into services — pass specific data.
+- Services are framework-agnostic — no HTTP/request logic.
+
+## Do NOT
+
+- Do NOT inject `Request` or `Controller` into services — services are framework-agnostic.
+- Do NOT create services with more than one responsibility — split them.
+
+## Auto-trigger keywords
+
+- service class
+- business logic
+- service layer
+- dependency injection

package/.agent-src/skills/playwright-testing/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: playwright-testing
+description: "Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns."
+source: package
+---
+
+# playwright-testing
+
+## When to use
+
+Use this skill when:
+- Writing end-to-end tests with Playwright
+- Automating browser interactions for testing
+- Setting up visual regression testing
+- Using Playwright MCP for design reviews
+- Debugging flaky E2E tests
+- Configuring Playwright for CI/CD
+
+**Guideline:** `.augment/guidelines/e2e/playwright.md` — full conventions, config templates, CI setup.
+**Rule:** `.augment/rules/e2e-testing.md` — constraints enforced during E2E test work.
+
+## Procedure: Write Playwright tests
+
+1. **Read the guideline** — `.augment/guidelines/e2e/playwright.md` for detailed conventions.
+2. **Check Playwright config** — `playwright.config.ts` for browsers, base URL, timeouts.
+3. **Check existing tests** — match patterns in `tests/e2e/` or `e2e/`.
+4. **Check test utilities** — look for page objects, fixtures, helpers.
+5. **Check CI setup** — how are E2E tests run in the pipeline?
+
+## Test structure
+
+```ts
+import { test, expect } from '@playwright/test'
+
+test.describe('User Authentication', () => {
+  test('should login with valid credentials', async ({ page }) => {
+    await page.goto('/login')
+    await page.getByLabel('Email').fill('user@example.com')
+    await page.getByLabel('Password').fill('password123')
+    await page.getByRole('button', { name: 'Sign in' }).click()
+
+    await expect(page).toHaveURL('/dashboard')
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible()
+  })
+
+  test('should show error for invalid credentials', async ({ page }) => {
+    await page.goto('/login')
+    await page.getByLabel('Email').fill('wrong@example.com')
+    await page.getByLabel('Password').fill('wrong')
+    await page.getByRole('button', { name: 'Sign in' }).click()
+
+    await expect(page.getByText('Invalid credentials')).toBeVisible()
+  })
+})
+```
+
+## Locator strategies (priority order)
+
+| Strategy | Example | When to use |
+|---|---|---|
+| **Role** | `getByRole('button', { name: 'Submit' })` | Default — most accessible |
+| **Label** | `getByLabel('Email')` | Form inputs |
+| **Text** | `getByText('Welcome')` | Visible text content |
+| **Placeholder** | `getByPlaceholder('Search...')` | Input placeholders |
+| **Test ID** | `getByTestId('submit-btn')` | Last resort — when no semantic locator works |
+| **CSS** | `page.locator('.my-class')` | Avoid — brittle |
+
+**Prefer semantic locators** (`getByRole`, `getByLabel`) over CSS selectors.
+
+## Reliable test patterns
+
+### Wait for network idle
+
+```ts
+// Wait for page to fully load
+await page.goto('/dashboard', { waitUntil: 'networkidle' })
+
+// Wait for specific API response
+await page.waitForResponse(resp =>
+  resp.url().includes('/api/users') && resp.status() === 200
+)
+```
+
+### Assertions with auto-retry
+
+```ts
+// ✅ Auto-retrying assertions (Playwright retries until timeout)
+await expect(page.getByText('Success')).toBeVisible()
+await expect(page.getByRole('list')).toHaveCount(5)
+
+// ❌ Non-retrying — can be flaky
+const text = await page.textContent('.message')
+expect(text).toBe('Success')
+```
+
+### Page Object Model
+
+```ts
+// pages/LoginPage.ts
+export class LoginPage {
+  constructor(private page: Page) {}
+
+  async goto() {
+    await this.page.goto('/login')
+  }
+
+  async login(email: string, password: string) {
+    await this.page.getByLabel('Email').fill(email)
+    await this.page.getByLabel('Password').fill(password)
+    await this.page.getByRole('button', { name: 'Sign in' }).click()
+  }
+}
+```
+
+## Visual regression testing
+
+```ts
+test('homepage visual regression', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveScreenshot('homepage.png', {
+    maxDiffPixelRatio: 0.01,
+  })
+})
+```
+
+- Screenshots are stored in `tests/*.png` (or configured path).
+- First run creates baseline screenshots.
+- Subsequent runs compare against baselines.
+- Update baselines: `npx playwright test --update-snapshots`.
+
+## Viewport testing
+
+```ts
+test.describe('Responsive design', () => {
+  for (const viewport of [
+    { width: 1440, height: 900, name: 'desktop' },
+    { width: 768, height: 1024, name: 'tablet' },
+    { width: 375, height: 812, name: 'mobile' },
+  ]) {
+    test(`renders correctly on ${viewport.name}`, async ({ page }) => {
+      await page.setViewportSize(viewport)
+      await page.goto('/')
+      await expect(page).toHaveScreenshot(`home-${viewport.name}.png`)
+    })
+  }
+})
+```
+
+## Debugging
+
+```bash
+# Run with headed browser (see what's happening)
+npx playwright test --headed
+
+# Run with Playwright Inspector (step through)
+npx playwright test --debug
+
+# View test report
+npx playwright show-report
+
+# Run specific test
+npx playwright test -g "should login"
+```
+
+## Avoiding flaky tests
+
+| Problem | Solution |
+|---|---|
+| Element not ready | Use auto-retrying assertions (`toBeVisible`, `toHaveText`) |
+| Animation interference | Use `page.evaluate(() => document.body.style.setProperty('--transition-duration', '0s'))` |
+| Network timing | Wait for specific responses, not arbitrary timeouts |
+| Test isolation | Use fresh browser context per test (Playwright default) |
+| Shared state | Reset database/state before each test |
+
+## Authentication pattern
+
+```ts
+// Use storageState to avoid logging in via UI in every test
+// auth.setup.ts
+import { test as setup } from '@playwright/test'
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login')
+  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!)
+  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!)
+  await page.getByRole('button', { name: 'Sign in' }).click()
+  await page.waitForURL('/dashboard')
+  await page.context().storageState({ path: '.auth/user.json' })
+})
+```
+
+```ts
+// playwright.config.ts — use storage state in projects
+projects: [
+  { name: 'setup', testMatch: /.*\.setup\.ts/ },
+  {
+    name: 'chromium',
+    use: { ...devices['Desktop Chrome'], storageState: '.auth/user.json' },
+    dependencies: ['setup'],
+  },
+]
+```
+
+## Network mocking
+
+```ts
+// Mock API responses for isolated testing
+await page.route('**/api/users', route =>
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+  })
+)
+```
+
+## Output format
+
+1. Playwright test file with Page Object pattern
+2. Reliable locators using role/label selectors over CSS
+
+## Auto-trigger keywords
+
+- Playwright
+- E2E test
+- browser automation
+- visual regression
+- end-to-end
+
+## Gotcha
+
+- Don't use `page.waitForTimeout()` as a fix — it masks the real problem and makes tests flaky.
+- The model tends to use CSS selectors instead of semantic locators — always prefer `getByRole`, `getByLabel`.
+- `test.fixme()` is for app bugs, `test.skip()` is for environment constraints — don't confuse them.
+- After 3 failed fix attempts on one test, mark it `test.fixme()` and move on.
+
+## Do NOT
+
+- Do NOT skip assertions — every test must verify something meaningful.
+- Do NOT share state between tests — each test should be independent.
+- Do NOT hardcode URLs — use `baseURL` from config.
+- Do NOT test implementation details — test user-visible behavior.
+- Do NOT put assertions in Page Objects — assertions belong in test files.
+- Do NOT commit `.only` — enforce via `forbidOnly: !!process.env.CI`.