@event4u/agent-config 1.9.1

package/.agent-src/skills/api-endpoint/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: api-endpoint
+description: "Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs."
+source: package
+---
+
+# api-endpoint
+
+## When to use
+
+Use this skill when the user asks to create a new API endpoint, REST route, or controller action.
+
+
+Do NOT use when:
+- Modifying existing endpoints (use `code-refactoring` skill)
+- API design decisions (use `api-design` skill)
+
+## Procedure: Create an API endpoint
+
+1. **Read project docs** — Check `./agents/` and `AGENTS.md` for controller conventions, resource patterns, routing.
+2. **Create route** — Add to the correct `routes/api.php` or module route file.
+3. **Create controller** — Thin controller, delegate logic to service.
+4. **Create FormRequest** — Validate all input at the boundary.
+5. **Create Resource** — Transform model output via API Resource.
+6. **Verify** — Run PHPStan, run tests, confirm response shape matches conventions.
+
+## Laravel projects
+
+### What to generate
+
+1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `.augment/guidelines/php/controllers.md`.
+2. **FormRequest** — Validation rules, `authorize()` via policies. Read `.augment/guidelines/php/validations.md`.
+3. **Resource** — JSON response transformation. Read `agents/docs/api-resources.md`.
+4. **Route** — Add to the correct versioned route file.
+5. **Policy** — If authorization is needed.
+6. **Filter classes** — If it's a list endpoint with filtering. Read `agents/docs/query-filter.md` (if it exists).
+
+### Conventions
+
+- Controllers are thin — delegate to Services.
+- **Every controller MUST return an API Resource** — never raw arrays, models, or `response()->json()`.
+- Controllers type-hint the return value as the Resource class (e.g. `): ProjectResource`).
+- Use `Resource::make()` for single items, `Resource::collection()` for lists.
+- Use method injection on `__invoke()` for new controllers.
+- Use DTOs for data transfer between layers.
+
+### Show endpoint example
+
+```php
+declare(strict_types=1);
+
+namespace App\Http\Controllers\v1\Project;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\v1\Projects\ShowProjectRequest;
+use App\Http\Resources\v1\Project\ProjectResource;
+use App\Models\ExternalCustomerDatabase\Project\Project;
+use App\OpenApi\Schema\Request\ShowResourceRequestSchema;
+use App\OpenApi\Schema\Response\ResourceNotFoundResponse;
+use App\OpenApi\Schema\Response\ShowResourceResponseSchema;
+
+class ShowProjectController extends Controller
+{
+    #[ShowResourceRequestSchema(path: '/projects/{id}', version: '1', resource: ProjectResource::class)]
+    #[ShowResourceResponseSchema(ProjectResource::class, wrapInDataObject: false)]
+    #[ResourceNotFoundResponse(ProjectResource::class)]
+    public function __invoke(ShowProjectRequest $request, Project $project): ProjectResource
+    {
+        return ProjectResource::make($project);
+    }
+}
+```
+
+### Create endpoint with service injection
+
+```php
+class CreateCustomerController extends Controller
+{
+    #[CreateCustomerRequestSchema(path: '/customers', version: '1', resource: CustomerResource::class)]
+    #[CreateResourceResponseSchema(resource: CreatedCustomerResource::class, wrapInDataObject: false)]
+    #[ValidationErrorResponse]
+    public function __invoke(
+        CreateCustomerRequest $request,
+        CustomerModelService $customerService,
+    ): CustomerResource {
+        $result = $customerService->create(CreateCustomerDTO::fromRequest($request));
+
+        return CreatedCustomerResource::make($result);
+    }
+}
+```
+
+### FormRequest example
+
+```php
+declare(strict_types=1);
+
+namespace App\Http\Requests\v1\Projects;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class ShowProjectRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('view', $this->route('project'));
+    }
+
+    /** @return array<string, mixed> */
+    public function rules(): array
+    {
+        return [];
+    }
+}
+```
+
+### List endpoint with CollectionFormRequest
+
+For list endpoints, extend `CollectionFormRequest` which provides `perPage`, `page`, and `orderBy` rules:
+
+```php
+use App\Contracts\Http\Requests\CollectionFormRequest;
+
+class ListProjectsRequest extends CollectionFormRequest
+{
+    public string $model = Project::class;
+
+    /** @return array<string, mixed> */
+    public function rules(): array
+    {
+        return [
+            ...parent::rules(),
+            'status' => ['sometimes', 'string'],
+        ];
+    }
+}
+```
+
+### File locations
+
+| Component | Path |
+|---|---|
+| Controller | `app/Http/Controllers/v{N}/{Domain}/{Action}{Entity}Controller.php` |
+| FormRequest | `app/Http/Requests/v{N}/{Domain}/{Action}{Entity}Request.php` |
+| Resource | `app/Http/Resources/v{N}/{Domain}/{Entity}Resource.php` |
+| Route | `routes/api/v{N}/{domain}.php` |
+| Policy | `app/Policies/{Entity}Policy.php` |
+
+### OpenAPI documentation
+
+Controllers use PHP 8 attributes for OpenAPI spec generation from `App\OpenApi\Schema\`:
+
+- `ShowResourceRequestSchema`, `ListResourceRequestSchema`, `CreateResourceRequestSchema`
+- `ShowResourceResponseSchema`, `ListResourceResponseSchema`, `CreateResourceResponseSchema`
+- `ResourceNotFoundResponse`, `ValidationErrorResponse`
+
+## Output format
+
+1. Generated files — controller, route registration, FormRequest, Resource, Policy
+2. Test file with happy path and validation error cases
+3. Summary of created files and their locations
+
+## Gotcha
+
+- Don't forget to register the route — creating the controller without the route is a common miss.
+- Always check if a similar endpoint already exists — duplicates cause confusion.
+- FormRequest validation rules must match the OpenAPI schema — keep them in sync.
+- The model tends to forget the `return` type on Resource `toArray()` methods.
+
+## Do NOT
+
+- Do NOT put business logic in controllers — delegate to services.
+- Do NOT skip FormRequest validation — every controller needs a FormRequest.
+- Do NOT return raw Eloquent models — always use API Resources.
+- Do NOT create routes without proper authorization (Policy in FormRequest or middleware).
+- Do NOT create multi-action controllers — only single-action with `__invoke()`.
+- Do NOT use `response()->json()` — use `Resource::make()`.
+
+## Auto-trigger keywords
+
+- create endpoint
+- new API route
+- controller creation
+- form request
+- API resource

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

@@ -0,0 +1,206 @@
+---
+name: api-testing
+description: "Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing."
+source: package
+---
+
+# api-testing
+
+## When to use
+
+Use this skill when writing or reviewing API endpoint tests — integration tests,
+contract validation, response structure checks, or external service mocking.
+
+## Procedure: Write API tests
+
+1. **Understand the endpoint** — Read controller, form request, existing tests. Understand expected behavior and edge cases before writing anything.
+2. **Set up test data** — Use seeders (preferred) or factories. Mock external services with `Http::fake()`.
+3. **Write test cases** — Cover success, validation errors, authorization failures, edge cases.
+4. **Assert response** — Check status code, JSON structure, data values. Use `assertJsonStructure()`.
+5. **Verify** — Run the test. Must pass. Check no flaky assertions (no time-dependent, no random ordering).
+
+### Example
+
+```php
+describe('GET /api/v1/projects', function () {
+    it('returns paginated projects for authenticated user', function () {
+        $user = loginAsTestUser();
+
+        $response = $this->getJson('/api/v1/projects');
+
+        $response->assertOk()
+            ->assertJsonStructure([
+                'data' => [['id', 'title', 'status']],
+                'meta' => ['current_page', 'per_page', 'total'],
+            ]);
+    });
+
+    it('returns 401 for unauthenticated request', function () {
+        $this->getJson('/api/v1/projects')
+            ->assertUnauthorized();
+    });
+
+    it('returns 403 when user lacks permission', function () {
+        loginAsRestrictedUser();
+
+        $this->getJson('/api/v1/projects')
+            ->assertForbidden();
+    });
+});
+```
+
+## Test categories
+
+### Happy path
+
+Test the expected success scenario with valid input:
+
+```php
+it('creates a project', function () {
+    loginAsTestUser();
+
+    $this->postJson('/api/v1/projects', [
+        'title' => 'New Project',
+        'customer_id' => $customerId,
+    ])
+        ->assertCreated()
+        ->assertJsonPath('data.title', 'New Project');
+
+    $this->assertDatabaseHas('projects', ['title' => 'New Project']);
+});
+```
+
+### Validation
+
+Test that invalid input is rejected with correct error messages:
+
+```php
+it('rejects project without title', function () {
+    loginAsTestUser();
+
+    $this->postJson('/api/v1/projects', [
+        'customer_id' => $customerId,
+    ])
+        ->assertUnprocessable()
+        ->assertJsonValidationErrors(['title']);
+});
+```
+
+### Authorization
+
+Test that unauthorized access is blocked:
+
+```php
+it('prevents non-owner from updating project', function () {
+    $otherUser = loginAsOtherUser();
+
+    $this->putJson("/api/v1/projects/{$project->id}", [
+        'title' => 'Hijacked',
+    ])
+        ->assertForbidden();
+});
+```
+
+### Edge cases
+
+Test boundary conditions:
+
+```php
+it('handles empty collection', function () {
+    loginAsTestUser();
+
+    $this->getJson('/api/v1/projects')
+        ->assertOk()
+        ->assertJsonCount(0, 'data');
+});
+
+it('paginates large result sets', function () {
+    loginAsTestUser();
+
+    $this->getJson('/api/v1/projects?per_page=5')
+        ->assertOk()
+        ->assertJsonPath('meta.per_page', 5);
+});
+```
+
+## Response contract validation
+
+### Assert JSON structure
+
+```php
+// Verify response shape (keys exist)
+$response->assertJsonStructure([
+    'data' => ['id', 'title', 'status', 'created_at'],
+]);
+
+// Verify exact values
+$response->assertJsonPath('data.status', 'active');
+
+// Verify collection count
+$response->assertJsonCount(3, 'data');
+```
+
+### Assert response types
+
+```php
+// When strict typing matters
+$data = $response->json('data');
+expect($data['id'])->toBeInt();
+expect($data['title'])->toBeString();
+expect($data['total'])->toBeString(); // Money as string, not float
+```
+
+## External service mocking
+
+```php
+it('handles external API failure gracefully', function () {
+    Http::fake([
+        'external-api.com/*' => Http::response(null, 500),
+    ]);
+
+    loginAsTestUser();
+
+    $this->postJson('/api/v1/sync')
+        ->assertStatus(502)
+        ->assertJsonPath('message', 'External service unavailable');
+});
+```
+
+## Test checklist per endpoint
+
+| Category | Tests needed |
+|---|---|
+| **Auth** | Unauthenticated (401), unauthorized (403) |
+| **Validation** | Missing fields, wrong types, boundary values |
+| **Happy path** | Success with valid input, correct status code |
+| **Response** | JSON structure, field types, pagination meta |
+| **Side effects** | Database changes, events dispatched, jobs queued |
+| **Edge cases** | Empty results, large payloads, concurrent access |
+
+## Output format
+
+1. Pest test file covering happy path, validation, auth, and edge cases
+2. Test names as readable sentences describing expected behavior
+3. Mocked external services where applicable
+
+## Auto-trigger keywords
+
+- API test
+- endpoint test
+- integration test
+- response validation
+- contract testing
+
+## Gotcha
+
+- Don't test framework internals (e.g., "does Laravel return 422 on validation error") — test YOUR validation rules.
+- Always seed test data explicitly — don't rely on data from other tests (parallel execution).
+- Mock external APIs with `Http::fake()` — never hit real services in tests.
+- The model forgets to assert response structure, only checking status codes — always check both.
+
+## Do NOT
+
+- Do not hardcode IDs or timestamps — use factories or seeders.
+- Do not skip auth tests — always test both authenticated and unauthenticated.
+- Do not assert entire JSON responses — assert only meaningful fields.
+- Do not use `Http::fake()` without also testing the real integration path.

package/.agent-src/skills/artisan-commands/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: artisan-commands
+description: "Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling."
+source: package
+---
+
+# artisan-commands
+
+## When to use
+
+Use when creating or modifying Laravel Artisan commands — maintenance scripts, imports/exports, batch processing, repair/cleanup, scheduled tasks, developer utilities.
+
+Do NOT use when:
+- Writing queue jobs (use `jobs-events` skill)
+- Writing scheduled task config (use `laravel-scheduling` skill)
+
+## Procedure: Create an Artisan command
+
+### Step 0: Inspect
+
+1. Check existing commands — match naming, signature style, output format.
+2. Determine audience: developer, support, operations, cron, or scheduler.
+3. Determine if interactive or automated.
+4. Identify related services — commands orchestrate, not own business logic.
+
+### Step 1: Scaffold
+
+1. Create command class in `app/Console/Commands/` or module `App/Commands/`.
+2. Name: `{domain}:{action}` — e.g. `users:cleanup`, `orders:sync`.
+3. Define arguments (required) and options (toggles/filters) explicitly.
+
+### Step 2: Implement handle()
+
+1. Validate preconditions (environment, input, dependencies).
+2. Call service/action for business logic.
+3. Report progress and results via console output.
+4. Return appropriate exit code.
+
+### Step 3: Safety checks
+
+- Destructive? → Add `--force` flag + confirmation.
+- Scheduled? → Ensure non-interactive, idempotent, loud failures.
+- Long-running? → Use chunking/cursors, progress bar.
+- Production? → Add environment check if needed.
+
+### Step 4: Test
+
+- Assert exit codes, console output, side effects, option behavior.
+- Use `$this->artisan()` in Pest tests.
+
+## Conventions
+
+→ See guideline `php/artisan-commands.md` for full conventions.
+
+## Output format
+
+1. Artisan command class with signature, description, and handle method
+2. Registration in service provider or auto-discovery
+3. Example usage shown in a code comment
+
+## Gotcha
+
+- `$this->info()` is suppressed in quiet mode — use `$this->line()` for critical info.
+- Always add `--force` for destructive commands — never delete data without confirmation.
+- Add environment checks for production commands.
+
+## Do NOT
+
+- Do NOT run destructive operations without `--force` confirmation.
+- Do NOT use `$this->ask()` for non-interactive commands (cron/queue).
+- Do NOT put business logic in commands — delegate to services.
+
+## Auto-trigger keywords
+
+- artisan command
+- console command
+- CLI command
+- command signature

package/.agent-src/skills/authz-review/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: authz-review
+description: "Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows."
+source: package
+---
+
+# authz-review
+
+> You are a reviewer specialized in **end-to-end authorization enforcement**.
+> Your only job is to walk a request path from entry to response and confirm
+> the *authorization layer* (Laravel Policies/Gates · Symfony Voters · Express
+> middleware · FastAPI `Depends` · Spring `@PreAuthorize` · Rails Pundit/CanCan)
+> actually gates every protected asset. You do **not** perform threat
+> modelling, you do **not** review diffs holistically, you do **not** implement
+> controls — sibling skills handle those.
+
+## When to use
+
+* A change adds or modifies permission checks, roles, or ownership rules
+* A change exposes a new route, action, or admin-only capability
+* A query fetches tenant-scoped or user-scoped records and you must confirm scope
+* A bug report mentions "user A saw user B's data" or "non-admin accessed admin page"
+* `security-sensitive-stop-rule` fires on an auth/tenant/ownership code path
+
+Do NOT use when:
+
+* The change has no trust boundary crossing — skip entirely
+* You need a pre-implementation risk model — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* A full codebase authorization audit is requested — route to
+  [`security-audit`](../security-audit/SKILL.md)
+* The concern is a diff ready for review — route to
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md)
+* The concern is response/log leakage rather than access gating — route to
+  [`data-exposure-review`](../data-exposure-review/SKILL.md)
+* The concern is implementing a control once identified — route to
+  [`security`](../security/SKILL.md)
+
+## Procedure
+
+### 1. Pick the entrypoints under review
+
+Collect the route(s), action(s), or job(s) in scope for this review. Read the
+task description, open ticket, or user request — do not invent scope. If the
+entrypoint list is unclear, stop and ask.
+
+### 2. Inspect each path end-to-end
+
+For every entrypoint, analyze the authorization chain and record what you find:
+
+| Stage | What to confirm |
+|---|---|
+| Route / binding | HTTP method, URL, controller/handler, middleware chain |
+| Authentication gate | Is login enforced? By which middleware / guard? |
+| Authorization layer | Which policy, gate, voter, or check? Which action/ability? |
+| Data scope | Does the query filter by current user / tenant / owner? |
+| Response filter | Are sensitive fields stripped (resource/serializer/DTO)? |
+| Tests | Is there a negative test (other-tenant / lower-role returns 403/404)? |
+
+Record **what is there**, not what should be there. Use file:line citations.
+
+### 3. Surface the gaps
+
+For every gap, answer:
+
+- Which stage is missing or weak?
+- Which actor can exploit it? (anonymous · authenticated non-owner · wrong tenant · lower role)
+- Concrete impact? (cross-tenant read, privilege escalation, horizontal escalation)
+- Minimum control to add? (policy method, scope, middleware, resource transform)
+- Required negative test assertion?
+
+Do **not** list generic findings ("should use policies") — always anchor to a
+file:line and a specific actor who can reach the gap.
+
+## Validation
+
+Before finalizing the report, confirm:
+
+1. Every entrypoint in scope is walked through **all six stages** of the table
+2. Every 🔴 finding names: stage · actor · impact · missing control · required test
+3. Every 🔴 finding cites at least one file path with line number
+4. You have NOT listed stages that are already correctly enforced as findings
+5. You have NOT confused authentication with authorization in any finding
+6. You have NOT proposed exploit payloads, bypass chains, or offensive steps
+
+## Output format
+
+```
+Skill:   authz-review
+Targets: <routes / actions / jobs, one per line>
+
+Per-entrypoint walk:
+  <METHOD /route> — <controller@action>  (file:line)
+    Auth gate:           <middleware/guard>   ✅/⚠️/❌
+    Authorization:       <policy#ability>     ✅/⚠️/❌   (file:line)
+    Data scope:          <scope/where>        ✅/⚠️/❌   (file:line)
+    Response filter:     <resource/serializer> ✅/⚠️/❌  (file:line)
+    Negative test:       <test path or "—">   ✅/⚠️/❌
+
+Findings (prioritized):
+  🔴  <name> — entrypoint · stage · actor
+      Impact: <concrete damage>
+      Missing control: <what to add, where>
+      Required test: <negative assertion, test file>
+  🟡  ...
+  🟢  ...
+
+Implementation plan:
+  1. <control>, <file/layer>
+  2. ...
+
+Missing tests:
+  1. <assertion>, <test file>
+```
+
+Severity: 🔴 reachable by external or cross-tenant/cross-user actor with
+current privileges / 🟡 reachable only by elevated actor or requires
+partial compromise / 🟢 defense-in-depth hardening, not a live exploit path.
+
+Required fields (ordered):
+
+1. **Skill** and **Targets** — entrypoints in scope
+2. **Per-entrypoint walk** — six-stage table per entrypoint with file:line citations
+3. **Findings** — prioritized, each with entrypoint · stage · actor · impact · missing control · required test
+4. **Implementation plan** — ordered controls mapped to files/layers
+5. **Missing tests** — ordered negative assertions
+
+Runtime confirmation (e.g. *"reproduce the cross-tenant read against staging"*,
+*"query the DB to prove scope leakage"*) is a follow-up for the implementer —
+**this skill does not execute tools, run requests, or touch the database**.
+
+## Gotcha
+
+* **Authentication ≠ authorization.** A logged-in user is not an authorized
+  user. Auth gate green does not make authorization green.
+* **Implicit tenancy via current session** — `Auth::user()->posts` looks safe
+  but breaks the moment an admin impersonation or service-account path bypasses it.
+* **Query scope bypass through relations** — `$user->load('orders.customer')`
+  can leak a sibling tenant if the `customer` relation has no scope.
+* **Resource/serializer leakage** — the policy gated the action; the resource
+  still exposed `internal_notes`. Response filter is a distinct stage.
+* **"Route middleware covers it"** — middleware enforces auth, not per-record
+  authorization. Still need the policy + scope.
+* **Generic advice without file:line** — reject your own finding if you cannot
+  cite the exact location.
+
+## Do NOT
+
+* NEVER return `clean` out of politeness when gaps exist — list them even if the change "probably works"
+* NEVER silently fall back to generic advice when you cannot locate a stage — mark it `❌ not found` with the file you searched
+* NEVER approve a 🔴 finding without a named required negative test
+* NEVER propose exploit payloads, bypass chains, or offensive verification steps — if asked, stop per `never-help-build-offensive-cyber-capability`
+* NEVER treat "only admins reach this" as a control without proof the admin gate is enforced at this stage for this request
+* NEVER rubber-stamp authentication middleware as if it enforced per-record authorization
+
+## References
+
+- **OWASP ASVS v4.0.3** — Chapter V4 Access Control, especially V4.1
+  (General Access Control Design) and V4.2 (Operation-level Access Control).
+  [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
+- **OWASP Top 10 2021 — A01 Broken Access Control** — canonical failure modes
+  (IDOR, missing function-level checks, forced browsing, metadata tampering).
+  [owasp.org/Top10/A01_2021-Broken_Access_Control/](https://owasp.org/Top10/A01_2021-Broken_Access_Control/)
+- **NIST SP 800-53 AC family** — AC-3 Access Enforcement, AC-6 Least Privilege
+  — rubric for "minimum control" recommendations.
+  [csrc.nist.gov/projects/risk-management/sp800-53-controls](https://csrc.nist.gov/projects/risk-management/sp800-53-controls/release-search#!/800-53)
+- [`threat-modeling`](../threat-modeling/SKILL.md),
+  [`data-exposure-review`](../data-exposure-review/SKILL.md),
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
+  [`security`](../security/SKILL.md),
+  [`security-audit`](../security-audit/SKILL.md) — sibling review / implementation skills.