@event4u/agent-config 1.9.1

package/.agent-src/skills/docker/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: docker
+description: "Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'."
+source: package
+---
+
+# docker
+
+## When to use
+
+Use this skill when working with Docker configuration, container setup, Dockerfile changes, or docker-compose modifications.
+
+
+Do NOT use when:
+- Production deployment (use `aws-infrastructure` skill)
+- Codespaces setup (use `devcontainer` skill)
+
+## Procedure: Modify Docker setup
+
+1. **Gather context** — read project Docker docs in `agents/` or `Docs/`, check `Makefile`/`Taskfile.yml` for targets, read `docker-compose.yml`/`compose.yaml` for service layout.
+2. **Identify scope** — determine which service(s) are affected (PHP, NGINX, worker, scheduler, database).
+3. **Inspect current state** — run `docker compose ps` to see running containers and their health status.
+4. **Make the change** — edit the relevant file (Dockerfile, compose file, NGINX config, Makefile target). Follow the conventions in the reference sections below.
+5. **Rebuild affected containers** — `docker compose build <service>` (add `--no-cache` if Dockerfile base layers changed).
+6. **Verify** — `docker compose up -d`, check `docker compose ps` for healthy status, run a smoke test (e.g., `make test-quick` or `curl localhost`).
+
+## Project architecture
+
+### Dockerfile (`.docker/Dockerfile`)
+
+Multi-stage build with these targets:
+
+| Stage | Purpose |
+|---|---|
+| `base` | Alpine + PHP-FPM + system packages + extensions |
+| `dev` | Development: Xdebug, dev tools, Composer dev deps |
+| `pro` | Production: optimized, no dev deps, New Relic agent |
+
+Key build args:
+- `PHP_VERSION` — extracted from Dockerfile, used by CI
+- `COMPOSER_AUTH` — private registry access (passed as secret)
+- `CACHEBUST` — weekly cache invalidation (`date +%Y-%U`)
+- `COMPOSER_NO_DEV` — `1` for production, `0` for dev
+
+### Dual-container architecture (PHP projects)
+
+Some projects run two PHP-FPM containers simultaneously (fast + Xdebug):
+
+| Container | Purpose | PHP-FPM mode |
+|---|---|---|
+| `{project}-php` | Fast execution, no debugger | `pm = dynamic` |
+| `{project}-php-xdebug` | Xdebug enabled, debugging | `pm = ondemand` |
+
+NGINX routes requests based on HTTP headers:
+- No header → fast container
+- `X-Xdebug-Enable: 1` or `X-Debug-Session: PHPSTORM` → Xdebug container
+
+### docker-compose services
+
+Read `docker-compose.yml` / `compose.yaml` to discover the actual service names. Common patterns:
+
+| Service type | Description |
+|---|---|
+| PHP-FPM | Main application server |
+| PHP-FPM + Xdebug | Debugging container |
+| NGINX | Reverse proxy |
+| Queue worker | Background job processing (e.g., Horizon) |
+| Scheduler | Cron/task scheduler |
+| Database | MariaDB / MySQL / PostgreSQL |
+| Cache | Redis / Memcached |
+
+## Conventions
+
+### Container commands
+
+- **Always execute PHP commands inside the container**, never on the host.
+- Use `docker compose exec -T <service> ...` for non-interactive (scripts, CI).
+- Use `make console` for interactive shell access.
+- Use `make console-xdebug` for Xdebug container access.
+
+### Image building
+
+- Production images use `target: pro` — no dev dependencies.
+- Check the project's CI/CD config for target platform and registry.
+- Docker Hub login may be needed for pulling base images (rate limits).
+
+### PHP extensions
+
+Extensions are installed via `mlocati/php-extension-installer`:
+- Check the Dockerfile for the current list.
+- Add new extensions in the `base` stage so they're available in all targets.
+
+### Environment files
+
+- `.env` is NOT baked into the Docker image.
+- Production: `.env` is fetched from **AWS Secrets Manager** at deploy time.
+- Development: `.env` is mounted via docker-compose volumes.
+
+## Makefile targets
+
+Always check the `Makefile` for available targets before using raw docker commands:
+
+```
+make start              # Start all containers
+make stop               # Stop all containers
+make console            # Enter PHP container (bash)
+make console-xdebug     # Enter Xdebug PHP container
+make composer-install   # Run composer install in container
+make migrate            # Run migrations
+make migrate-and-seed   # Run migrations + seed
+make test               # Run all tests (parallel)
+```
+
+
+## Container orchestration
+
+### Environment synchronization
+
+When the development environment is out of sync (missing containers, wrong state):
+
+1. **Check status** — `docker compose ps` to see which services are running.
+2. **Start missing services** — `make start` or `docker compose up -d`.
+3. **Rebuild if needed** — `docker compose build --no-cache <service>` after Dockerfile changes.
+4. **Reset state** — `make migrate-and-seed` after fresh container start.
+
+### Common sync issues
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Connection refused" | Container not running | `make start` |
+| "Table not found" | Migrations not run | `make migrate-and-seed` |
+| "Class not found" | Composer not installed | `make composer-install` |
+| Old PHP version | Image not rebuilt | `docker compose build <php-service>` |
+| Extension missing | Dockerfile changed | Rebuild with `--no-cache` |
+
+### Multi-project orchestration
+
+When running multiple projects simultaneously:
+- Check for **port conflicts** — each project needs unique exposed ports.
+- Use **Traefik** (see `traefik` skill) for routing by domain instead of port.
+- Shared services (MariaDB, Redis) can be in a dedicated `docker-compose.shared.yml`.
+
+## Security hardening checklist
+
+When creating or reviewing Dockerfiles:
+
+- [ ] **Non-root user** — create user with specific UID/GID, use `USER` directive before `CMD`.
+- [ ] **No secrets in layers** — never `ENV` or `COPY` secrets. Use `--mount=type=secret` (BuildKit) or runtime secrets.
+- [ ] **Minimal packages** — only install what's needed. Remove package manager cache in the same `RUN` layer.
+- [ ] **Read-only root filesystem** — use `--read-only` flag where possible, mount writable dirs explicitly.
+- [ ] **No `latest` tag** — pin base image versions (`node:18.19-alpine`, not `node:latest`).
+- [ ] **Scan images** — use `docker scout quickview` or Trivy for vulnerability scanning.
+
+```dockerfile
+# Security pattern
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -S appuser -u 1001 -G appgroup
+COPY --chown=appuser:appgroup . .
+USER 1001
+```
+
+## Health check patterns
+
+Always add health checks to long-running services:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:8080/health || exit 1
+```
+
+In docker-compose, use `condition: service_healthy` for dependency ordering:
+
+```yaml
+services:
+  app:
+    depends_on:
+      db:
+        condition: service_healthy
+```
+
+## Image size optimization
+
+| Technique | Impact | When |
+|---|---|---|
+| Multi-stage builds | **High** | Always — separate build from runtime |
+| Alpine base images | **High** | When compatibility allows |
+| Distroless images | **High** | Production, no shell needed |
+| `.dockerignore` | **Medium** | Always — exclude `node_modules`, `.git`, `tests`, docs |
+| Combine `RUN` layers | **Medium** | When installing packages + cleaning cache |
+| Copy only artifacts | **Medium** | `COPY --from=build` only what's needed |
+
+## Build cache optimization
+
+Use BuildKit cache mounts for package managers:
+
+```dockerfile
+# Composer (PHP)
+RUN --mount=type=cache,target=/root/.composer/cache \
+    composer install --no-dev --optimize-autoloader
+
+# npm (Node.js)
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci --only=production
+```
+
+**Layer ordering for cache efficiency:**
+1. System packages (changes rarely)
+2. Dependency files (`composer.json`, `package.json`) — changes sometimes
+3. `RUN install` — cached if dependency files unchanged
+4. Source code (`COPY . .`) — changes often, last layer
+
+## Output format
+
+1. Modified Docker configuration files (Dockerfile, docker-compose.yml)
+2. Updated Makefile targets if applicable
+3. Rebuild/restart instructions for affected containers
+
+## Auto-trigger keywords
+
+- Docker
+- docker-compose
+- container
+- Dockerfile
+- PHP container
+
+## Gotcha
+
+- All PHP commands (artisan, composer, phpunit) must run INSIDE the PHP container — never on the host.
+- The fast container and Xdebug container share the same codebase but have different PHP configs — don't confuse them.
+- `docker compose down -v` destroys volumes including the database — use `down` without `-v` unless you mean it.
+- The model forgets to use `docker compose exec -T` (no TTY) when running in scripts or CI.
+
+## Do NOT
+
+- Do NOT change the base Alpine or PHP version without checking CI compatibility.
+- Do NOT add dev-only tools to the `pro` stage.
+- Do NOT hardcode secrets in the Dockerfile — use build args or runtime secrets.
+- Do NOT change `platform` without verifying AWS runner architecture.
+
+## Related
+
+- **Skill:** `traefik` — local reverse proxy with real domains and HTTPS
+- **Skill:** `devcontainer` — DevContainer and Codespaces setup
+- **Skill:** `php-debugging` — Xdebug dual-container architecture
+- **Rule:** `docker-commands.md` — all PHP commands run inside Docker

package/.agent-src/skills/dto-creator/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: dto-creator
+description: "Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping."
+source: package
+---
+
+# dto-creator
+
+## When to use
+
+Use this skill when creating a new DTO for data transfer between layers (DB ↔ PHP, API ↔ Service, etc.).
+
+## Procedure: Create a DTO
+
+1. **Read the project's DTO docs** — check `agents/docs/dto.md` (if it exists) for project-specific conventions.
+2. **Check the base class** — search for the DTO base class in the project (e.g., `SimpleDto`, `LiteDto`, or a custom base).
+   Check `composer.json` for DTO-related packages.
+3. **Check existing DTOs** — look at neighboring DTOs in the same directory to match the style.
+4. **Understand the model** — if the DTO maps to a Model, read the model's properties and DB columns.
+
+## DTO conventions
+
+### Base class
+
+- Use the project's standard DTO base class (typically `SimpleDto` or `LiteDto`).
+- Never create plain PHP classes for DTOs that map to models — always extend the base class.
+
+### Property mapping
+
+- Use `#[Map('db_column')]` attributes to map between DB column names and PHP properties.
+- PHP properties: `camelCase`, English names.
+- DB columns: `snake_case`, may be German (legacy) — match what's in the database.
+
+### Type casting
+
+- Use typed properties (`int`, `string`, `float`, `bool`, `Carbon`, etc.).
+- The base class handles casting from DB strings to PHP types automatically.
+
+### Validation
+
+- Use validation attributes where appropriate: `#[Length(50)]`, `#[Email]`, `#[Decimal(10,2)]`, `#[Unsigned]`.
+- Add `#[ConvertEmptyToNull]` at class level if empty strings should become null.
+
+### Model linkage
+
+- Add `#[HasModel(ModelClass::class)]` on the DTO.
+- Add `#[HasDto(DtoClass::class)]` and `DtoMappingTrait` on the Model (if not already present).
+
+## Structure
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\DTO;
+
+use Vendor\DataHelpers\SimpleDto;
+use Vendor\DataHelpers\SimpleDto\Attributes\HasModel;
+use Vendor\DataHelpers\SimpleDto\Attributes\Map;
+
+#[HasModel(MyModel::class)]
+class MyModelDto extends SimpleDto
+{
+    #[Map('id_column')]
+    public ?int $id = null;
+
+    #[Map('name_column')]
+    public string $name = '';
+
+    #[Map('amount_column')]
+    public float $amount = 0.0;
+}
+```
+
+## Project detection
+
+The DTO pattern varies by project:
+
+- **Projects with a DTO package**: Use the package's base class with attribute mapping.
+  Read `agents/docs/dto.md` for full details (if it exists).
+- **Projects without a DTO package**: Check existing DTOs for the local pattern.
+  Some projects use plain `readonly` classes, others have custom base classes.
+
+Always check `composer.json` for DTO-related packages before choosing the approach.
+
+## Rules
+
+- **Match existing patterns** — if the project already has DTOs, follow their style.
+- **Do NOT create DTOs for trivial data** — if a simple array or typed parameter suffices, don't over-engineer.
+- **Use `Math` helper** for any calculated properties — never raw PHP arithmetic.
+- **`declare(strict_types=1)`** in every new file.
+
+
+## Output format
+
+1. DTO class extending SimpleDto with typed properties
+2. Static factory method(s) for construction from common sources
+
+## Gotcha
+
+- DTOs must extend `SimpleDto` — don't create plain PHP classes as DTOs.
+- The model forgets to add the model linkage (`$modelClass`) when the DTO maps to an Eloquent model.
+- Attribute names in the DTO must match the database column names (snake_case), not the PHP property names.
+
+## Do NOT
+
+- Do NOT add business logic to DTOs — they are data containers only.
+- Do NOT use arrays when a DTO can provide type safety.
+- Do NOT skip validation when creating DTOs from external input.
+
+## Auto-trigger keywords
+
+- DTO
+- data transfer object
+- SimpleDto
+- attribute mapping

package/.agent-src/skills/eloquent/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: eloquent
+description: "Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions."
+source: package
+---
+
+# eloquent
+
+## When to use
+
+Use when creating/modifying Eloquent models, relationships, scopes, or writing database queries.
+
+Do NOT use when:
+- Schema design or query optimization (use `database` skill)
+- Creating migrations only (use `migration-creator` skill)
+
+## Procedure: Create or modify a model
+
+### Step 0: Inspect
+
+1. Check existing models — match property declarations, cast patterns, relationship style, scope naming.
+2. Check for repositories — some projects use repository interfaces.
+3. Understand the schema — check migrations for column names, types, constraints.
+4. Check for multi-tenancy — which `$connection` to use?
+
+### Step 1: Read attribute access style
+
+Read `eloquent.access_style` from `.agent-settings.yml`. Default: `getters_setters`.
+
+| Value | Inside model | Outside model |
+|---|---|---|
+| `getters_setters` | `getAttribute()` / `setAttribute()` | Typed getters/setters |
+| `get_attribute` | `getAttribute()` / `setAttribute()` | Same |
+| `magic_properties` | `$this->column` | `$model->column` |
+
+→ See guideline `php/eloquent.md` and `php-coding` rule for full conventions.
+
+### Step 2: Build the model
+
+1. Set `$connection`, `$table`, `$fillable`/`$guarded`, `$casts`, `$attributes` (defaults).
+2. Add typed getters + fluent setters for each attribute (if `getters_setters` style).
+3. Add relationship getter above each relationship method.
+4. Add scopes for reusable query constraints.
+5. Register Observer via `#[ObservedBy]` — never use `booted()`.
+
+### Step 3: Write queries
+
+- Always eager load relationships accessed in loops: `->with(['customer'])`.
+- Always paginate list queries: `->paginate(15)`.
+- Use `exists()` over `count() > 0`.
+- Use `chunk()` / `lazy()` for large datasets.
+- Constrain eager loads when only a subset is needed.
+
+## Conventions
+
+→ See guideline `php/eloquent.md` for getter/setter examples, relationship getters, observers, casts.
+→ See guideline `php/database.md` for indexing, transactions, migrations.
+
+### Validate
+
+- Run PHPStan on model — must pass.
+- Verify no N+1: check that all relationship access in loops uses eager loading.
+- Confirm typed getters exist for every relationship.
+- Run affected tests — must pass.
+
+## Output format
+
+1. Model class with typed getters/setters, relationships, and observer
+2. Migration file if schema changes are needed
+
+## Gotcha
+
+- Never access relationships via magic properties — always use typed getter.
+- N+1 queries are the #1 performance issue — always eager load.
+- `getAttribute()` returns `mixed` — cast or type-check the result.
+- `$model->save()` can silently fail without fillable/guarded config.
+
+## Do NOT
+
+- Do NOT put business logic in models — delegate to services.
+- Do NOT access relationships in loops without eager loading.
+- Do NOT use `Model::all()` without pagination on list endpoints.
+- Do NOT use `booted()` for lifecycle hooks — use Observers with `#[ObservedBy]`.
+
+## Auto-trigger keywords
+
+- Eloquent
+- model
+- relationship
+- scope
+- accessor
+- mutator

package/.agent-src/skills/eloquent/evals/last-run.json

@@ -0,0 +1,99 @@
+{
+  "skill": "eloquent",
+  "model": "claude-sonnet-4-5",
+  "timestamp": "2026-04-21T08:32:36+00:00",
+  "router": "mock",
+  "queries": [
+    {
+      "q": "fetch all users with their latest order eagerly",
+      "expected": true,
+      "observed": true,
+      "loaded_skills": [
+        "eloquent"
+      ],
+      "passed": true
+    },
+    {
+      "q": "add a scope to Product that filters by active and in-stock",
+      "expected": true,
+      "observed": true,
+      "loaded_skills": [
+        "eloquent"
+      ],
+      "passed": true
+    },
+    {
+      "q": "my blog model should cast the tags column to array",
+      "expected": true,
+      "observed": true,
+      "loaded_skills": [
+        "eloquent"
+      ],
+      "passed": true
+    },
+    {
+      "q": "write a relationship from Invoice to LineItems using hasMany",
+      "expected": true,
+      "observed": true,
+      "loaded_skills": [
+        "eloquent"
+      ],
+      "passed": true
+    },
+    {
+      "q": "this N+1 is killing me \u2014 how do I eager load nested relations?",
+      "expected": true,
+      "observed": true,
+      "loaded_skills": [
+        "eloquent"
+      ],
+      "passed": true
+    },
+    {
+      "q": "create a migration for adding an index on users.email",
+      "expected": false,
+      "observed": false,
+      "loaded_skills": [],
+      "passed": true
+    },
+    {
+      "q": "write a Pest test for the UserService",
+      "expected": false,
+      "observed": false,
+      "loaded_skills": [],
+      "passed": true
+    },
+    {
+      "q": "phpstan says mixed return type on my model method",
+      "expected": false,
+      "observed": false,
+      "loaded_skills": [],
+      "passed": true
+    },
+    {
+      "q": "run the seeder with --class=ProductSeeder",
+      "expected": false,
+      "observed": false,
+      "loaded_skills": [],
+      "passed": true
+    },
+    {
+      "q": "what SQL does chunk() generate under the hood?",
+      "expected": false,
+      "observed": false,
+      "loaded_skills": [],
+      "passed": true
+    }
+  ],
+  "metrics": {
+    "true_positive": 5,
+    "false_positive": 0,
+    "true_negative": 5,
+    "false_negative": 0,
+    "precision": 1.0,
+    "recall": 1.0
+  },
+  "input_tokens": 20122,
+  "output_tokens": 160,
+  "cost_usd_estimate": 0.062766
+}

package/.agent-src/skills/eloquent/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "eloquent",
+  "description": "5 should-trigger + 5 should-not-trigger queries. A-class accepted ambiguity (e.g. 'User*' substring pulling eloquent alongside a non-Model intent) is marked with trigger=true and a note — the router loading eloquent is defensible, not a routing failure. Near-misses share Laravel/database vocabulary (migration, seeder, model, SQL) without being Model:: read/write tasks.",
+  "queries": [
+    {"q": "fetch all users with their latest order eagerly", "trigger": true},
+    {"q": "add a scope to Product that filters by active and in-stock", "trigger": true},
+    {"q": "my blog model should cast the tags column to array", "trigger": true},
+    {"q": "write a relationship from Invoice to LineItems using hasMany", "trigger": true},
+    {"q": "this N+1 is killing me — how do I eager load nested relations?", "trigger": true},
+    {"q": "create a migration for adding an index on users.email", "trigger": false},
+    {"q": "write a Pest test for the UserService", "trigger": true, "note": "A-class: 'User*' is inherently ambiguous (Model or Service). Router loading eloquent alongside pest-testing / php-service is defensible multi-skill activation, not a routing failure. Pushy 'NOT for non-Eloquent services' description tail was insufficient to override the lexical pull — see agents/docs/trigger-evals-poc-findings.md #3"},
+    {"q": "phpstan says mixed return type on my model method", "trigger": false},
+    {"q": "run the seeder with --class=ProductSeeder", "trigger": false},
+    {"q": "what SQL does chunk() generate under the hood?", "trigger": false}
+  ]
+}