@event4u/agent-config 14.23.0 → 15.0.0

package/dist/agent-src/guidelines/php/api-design.md

@@ -0,0 +1,115 @@
+# API Design Guidelines
+
+> API conventions — response format, status codes, pagination, error handling, rate limiting, route naming.
+
+**Related Skills:** `api-design`, `laravel-api-endpoint`, `api-testing`
+**Related Guidelines:** [controllers.md](controllers.md), [resources.md](resources.md)
+
+## Response Format
+
+- **Always use API Resource classes** — never return raw models or arrays.
+- **Single item:** `{ "data": { ... } }`
+- **Collection:** `{ "data": [ ... ], "meta": { ... }, "links": { ... } }`
+
+## HTTP Status Codes
+
+| Code | When |
+|---|---|
+| `200` | Successful GET, PUT, PATCH |
+| `201` | Successful POST (resource created) |
+| `204` | Successful DELETE (no content) |
+| `400` | Bad request (malformed input) |
+| `401` | Unauthenticated |
+| `403` | Unauthorized (forbidden) |
+| `404` | Resource not found |
+| `422` | Validation error |
+| `429` | Rate limited |
+| `500` | Server error |
+
+## Pagination
+
+Use Laravel's built-in pagination for list endpoints:
+
+```php
+$projects = Project::query()
+    ->filter($filters)
+    ->paginate(perPage: $request->integer('per_page', 15));
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `page` | 1 | Current page number |
+| `per_page` | 15 | Items per page |
+
+## Filtering and Sorting
+
+- Use the project's **filter pipeline** pattern (see `agents/reference/docs/query-filter.md`).
+- Filter classes are dedicated, testable units — not inline query logic.
+- Sorting via `sort` query parameter.
+
+## Error Responses
+
+### Validation errors (422)
+
+Laravel's default format:
+
+```json
+{
+    "message": "The given data was invalid.",
+    "errors": {
+        "field": ["The field is required."]
+    }
+}
+```
+
+### Application errors
+
+```json
+{
+    "message": "Human-readable error description."
+}
+```
+
+Error format must match existing project convention — not RFC 7807 or other standards.
+
+## Rate Limiting
+
+```php
+// bootstrap/app.php or RouteServiceProvider
+RateLimiter::for('api', function (Request $request) {
+    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
+});
+
+RateLimiter::for('auth', function (Request $request) {
+    return Limit::perMinute(5)->by($request->ip());
+});
+```
+
+Include in responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` (on 429).
+
+## Idempotency
+
+For non-idempotent operations (POST), support idempotency keys:
+
+```
+POST /api/v1/orders
+Idempotency-Key: unique-client-generated-uuid
+```
+
+## Route Naming
+
+- Dot notation: `v1.projects.index`, `v1.projects.show`
+- Route prefixes in kebab-case: `/api/v1/client-software`
+- Controllers in singular: `ProjectController`
+- Implicit route model binding where possible
+- Scope bindings for nested resources
+- Max nesting depth: 2 levels (`/users/{id}/orders/{id}`)
+
+## Do NOT
+
+- Return raw Eloquent models — always use API Resources.
+- Put business logic in controllers — delegate to services.
+- Create breaking changes in existing versions — create a new version.
+- Use inconsistent response formats between endpoints.
+- Expose internal IDs or database column names that should be hidden.
+- Skip rate limiting on authentication endpoints.

package/dist/agent-src/guidelines/php/artisan-commands.md

@@ -0,0 +1,81 @@
+# Artisan Command Guidelines
+
+> Console command conventions — naming, structure, input/output, safety, scheduling.
+
+**Related Skills:** `artisan-commands`
+**Related Guidelines:** [patterns/service-layer.md](patterns/service-layer.md)
+
+## Naming
+
+- Clear, intention-revealing names: `users:cleanup`, `orders:sync`, `reports:generate`
+- Follow Laravel naming style: `{domain}:{action}`
+
+## Structure
+
+- Commands **orchestrate** — they accept input, validate conditions, call services, report results.
+- Heavy business logic belongs in services/actions, not in `handle()`.
+- Keep `handle()` readable and linear.
+
+## Input
+
+- **Arguments** for required primary input.
+- **Options** for toggles, filters, execution modes.
+- Validate critical inputs before expensive/destructive work.
+- Provide safe defaults where appropriate.
+- Use `--force` flag for destructive commands — always check it.
+
+## Output
+
+- Use `$this->info()`, `$this->warn()`, `$this->error()`, `$this->table()`, progress bars.
+- Keep output readable for both humans and logs.
+- Don't flood the console — use verbose mode for noisy output.
+- `$this->info()` is suppressed in quiet mode — use `$this->line()` for critical info.
+
+## Interactive vs Automated
+
+- Use confirmations for destructive operations in manual commands.
+- **Never** add interactive prompts to scheduler/CI commands.
+- Support non-interactive execution (`--no-interaction`).
+
+## Batch and Long-Running
+
+- Use chunking, cursors, or batching for large datasets.
+- Report progress for long-running tasks.
+- Handle partial failures intentionally.
+- Avoid loading large datasets into memory at once.
+
+## Safety
+
+- Treat cleanup, repair, sync, and deletion as high-risk.
+- Add safeguards for destructive operations.
+- Be explicit about dry-run behavior if supported.
+- Never perform irreversible work silently.
+- Add environment checks for production commands.
+
+## Scheduling
+
+Commands for the scheduler must:
+- Run non-interactively
+- Be idempotent where possible
+- Log/report useful status
+- Fail loudly enough for monitoring
+
+## Error Handling
+
+- Fail with meaningful messages.
+- Don't swallow exceptions silently.
+- Return appropriate exit codes.
+- Surface enough context to diagnose without exposing sensitive data.
+
+## Testing
+
+- Test behavior, not just class existence.
+- Assert: exit codes, console output, side effects, option/argument behavior.
+
+## Do NOT
+
+- Put business logic in commands — delegate to services.
+- Use `dd()` or `var_dump()` — use `$this->info()` / `$this->error()`.
+- Skip input validation in command signatures.
+- Make scheduled commands interactive.
+- Run destructive operations without safeguards.

package/dist/agent-src/guidelines/php/blade-ui.md

@@ -0,0 +1,78 @@
+# Blade UI Guidelines
+
+> Blade template conventions — views, components, partials, forms, escaping, styling.
+
+**Related Skills:** `blade-ui`, `livewire`, `flux`
+**Related Guidelines:** [controllers.md](controllers.md)
+
+## View Structure
+
+- Use the project's existing layout system.
+- Organize templates into clear sections.
+- Extract repeated sections into partials or components.
+- Prefer semantic HTML.
+- Avoid deeply nested conditionals — use a partial/component instead.
+
+## Blade Logic
+
+- Use Blade directives for **simple presentation logic** only.
+- Keep conditionals small and view-focused.
+- No business calculations or database access in templates.
+- No heavy data transformations in Blade.
+- Move non-trivial formatting to controllers, view models, presenters, or components.
+
+## Components
+
+- Use Blade components for reusable UI pieces (when project already uses them).
+- Keep component APIs clean and explicit — clear prop/slot names.
+- Don't create a component for something used only once (unless it significantly improves clarity).
+
+## Partials
+
+- Use partials for repeated markup fragments when a full component is unnecessary.
+- Name partials clearly per project conventions.
+- Avoid deep partial hierarchies that make UI hard to trace.
+
+## Forms
+
+- Follow the project's form style for labels, inputs, validation messages, old values, session feedback.
+- Use CSRF protection correctly.
+- Render validation errors consistently.
+- Preserve user input using project conventions.
+- Reuse existing field components/partials — don't duplicate.
+
+## Validation and Feedback
+
+- Display validation errors clearly and consistently.
+- Show success/error flash messages per project conventions.
+- Keep feedback near the relevant UI.
+- Don't invent a second feedback pattern if one already exists.
+
+## Escaping and Output Safety
+
+- Escape output by default — use `{{ }}`.
+- Use `{!! !!}` only when intentionally safe and already sanitized.
+- Be careful with rich content, HTML snippets, and user-generated content.
+
+## Styling
+
+- Reuse existing CSS/Tailwind conventions.
+- Don't introduce a new styling approach in one template.
+- Match class usage with neighboring templates.
+- If the project uses design-system components, follow them.
+- Always use utility classes — not inline styles.
+
+## Accessibility
+
+- Use labels for form fields.
+- Prefer semantic elements.
+- Add ARIA only where it meaningfully improves accessibility.
+
+## Do NOT
+
+- Place business logic in Blade templates.
+- Query the database from views.
+- Echo unescaped user data without explicit sanitization.
+- Inline large blocks of CSS or JS — use asset files.
+- Duplicate repeated markup when a component/partial exists.
+- `@include` shares parent scope — components don't. Know the difference.

package/dist/agent-src/guidelines/php/controllers.md

@@ -0,0 +1,90 @@
+# Controller Guidelines
+
+> Project-specific controller conventions. Thin controllers, single-action pattern, OpenAPI annotations.
+
+**Related Skills:** `laravel-api-endpoint`, `laravel`, `openapi`
+**Related Guidelines:** [validations.md](validations.md), [resources.md](resources.md)
+
+## Core Rules
+
+- **Single Action Controllers** only (`__invoke()`) — no Resource Controllers
+- Each controller must have: FormRequest, OpenAPI schema attributes
+- Use Resource responses where applicable (not all controllers return JSON — e.g. Delete returns an empty response, file downloads return a file stream)
+- Thin controllers — business logic in Services/Actions
+
+## Naming Schema
+
+| Action  | Controller                  | FormRequest                | Resource             |
+|---------|-----------------------------|----------------------------|----------------------|
+| Create  | `Create{Entity}Controller`  | `Create{Entity}Request`    | `{Entity}Resource`   |
+| List    | `List{Entities}Controller`  | `List{Entities}Request`    | `{Entity}Resource`   |
+| Show    | `Show{Entity}Controller`    | `Show{Entity}Request`      | `{Entity}Resource`   |
+| Update  | `Update{Entity}Controller`  | `Update{Entity}Request`    | `{Entity}Resource`   |
+| Delete  | `Delete{Entity}Controller`  | `Delete{Entity}Request`    | empty `Response`     |
+| Restore | `Restore{Entity}Controller` | `Restore{Entity}Request`   | `{Entity}Resource`   |
+
+> List uses **plural** entity name. All others use **singular**.
+
+## HTTP Actions
+
+| Action  | Method | Path                 | Notes                                     |
+|---------|--------|----------------------|-------------------------------------------|
+| Create  | POST   | `/api/{entities}`    | JSON body                                 |
+| List    | GET    | `/api/{entities}`    | Filters, Pagination                       |
+| Show    | GET    | `/api/{entities}/{id}` |                                         |
+| Update  | PATCH  | `/api/{entities}/{id}` | JSON body                               |
+| Delete  | DELETE | `/api/{entities}/{id}` | `?force=true` for hard delete            |
+| Restore | GET    | `/api/{entities}/{id}/restore` |                                |
+
+## Controller Pattern
+
+```php
+class CreateLinkController extends Controller
+{
+    #[CreateLinkRequestSchema(path: '/links', version: '1', resource: LinkResource::class)]
+    #[CreateResourceResponseSchema(LinkResource::class)]
+    #[ValidationErrorResponse]
+    public function __invoke(CreateLinkRequest $request): LinkResource
+    {
+        $link = Link::create($request->validated());
+        return LinkResource::make($link);
+    }
+}
+```
+
+**Key points:**
+- Use `$request->validated()` — never `$request->all()`
+- Use `Resource::make()` instead of `new Resource()` (easier to test)
+- Simple CRUD can live directly in the controller
+- Complex logic → Service class / Repository
+
+## Filters & Ordering
+
+Use the `pipeline` / `paginatedPipeline` macros with filter classes:
+
+```php
+$links = Link::query()
+    ->paginatedPipeline([
+        StringFilter::on('text')->isLike()->some(),
+        DateFilter::on('created_at')->all(),
+        OrderFilter::on(['id', 'name'])->default(['id' => 'asc']),
+    ]);
+```
+
+## OpenAPI Documentation
+
+- Always extend `{Action}ResourceRequestSchema` for Create/Update/List (keeps controllers clean)
+- Show/Delete/Restore use the base schema classes directly
+- No per-endpoint auth/permission error schemas (documented globally)
+- **`ValidationErrorResponse`** must be added to **every** controller that accepts input (Create, Update, etc.)
+- **`ResourceNotFoundResponse`** must be added to every controller that queries a single entity (Show, Update, Delete, Restore)
+
+| Action  | Request Schema           | Response Schema            | Error Responses                                    |
+|---------|--------------------------|----------------------------|----------------------------------------------------|
+| Create  | Extended (custom class)  | `CreateResourceResponseSchema` | `ValidationErrorResponse`                      |
+| List    | Extended (custom class)  | `ListResourceResponseSchema`  |                                                 |
+| Show    | `ShowResourceRequestSchema` | `ShowResourceResponseSchema` | `ResourceNotFoundResponse`                     |
+| Update  | Extended (custom class)  | `UpdateResourceResponseSchema` | `ValidationErrorResponse`, `ResourceNotFoundResponse` |
+| Delete  | `DeleteResourceRequestSchema` | `DeleteResourceResponseSchema` | `ResourceNotFoundResponse`                  |
+| Restore | `RestoreResourceRequestSchema` | `RestoreResourceResponseSchema` | `ResourceNotFoundResponse`               |
+

package/dist/agent-src/guidelines/php/database.md

@@ -0,0 +1,194 @@
+# Database Guidelines
+
+> Database conventions — indexing, query optimization, migrations, transactions, multi-connection patterns.
+
+**Related Skills:** `database`, `eloquent`, `multi-tenancy`
+**Related Guidelines:** [eloquent.md](eloquent.md)
+
+## Indexing
+
+Three separate things get conflated here, and keeping them apart is what makes
+the rest of this section decidable:
+
+1. **Declaring an integrity constraint** — a uniqueness or foreign-key
+   constraint. This is a correctness decision about the data model.
+2. **Indexing the referencing column** — the child side of a foreign key, which
+   is what makes the lookup and the constraint check fast.
+3. **Adding an optional query-performance index** — everything else.
+
+The row-count guidance below governs **(3) only**. It has never governed (1),
+and it must not be read as governing (2).
+
+### When to add indexes
+
+- Columns in `WHERE` clauses
+- Columns in `JOIN` conditions
+- Columns in `ORDER BY` (especially with pagination)
+- Foreign key columns (Laravel adds with `foreignId()`)
+- Columns carrying a declared uniqueness constraint
+
+### When NOT to add indexes
+
+These apply to **optional performance indexes** — category (3) above:
+
+- Boolean columns with low selectivity (99% same value)
+- Tables that are both small (< 1000 rows) **and rarely accessed**
+- Frequently updated columns (indexes slow writes)
+
+**Row count decides nothing on its own.** A 40-row lookup table joined in every
+report query and a 40-row config table read twice a week are the same size and
+not the same decision — index the first on its observed access pattern, leave
+the second alone. "Small" without "rarely accessed" is the folklore half of this
+rule.
+
+**Foreign-key and uniqueness indexes are created regardless of table size.**
+They serve integrity and lookup latency, and a row count bears on neither. A
+40-row child table pointing at a customers table gets its foreign-key column
+indexed like any other. Omit one only on the strength of inspected schema
+behavior plus a representative workload measurement showing it serves no access
+path — never on an anticipated write cost.
+
+### Composite indexes
+
+Order matters, and what decides it is the **predicate shape**, not selectivity:
+
+1. Columns compared with **equality** (`=`, `IN`) come first.
+2. Then the column compared with a **range** (`<`, `>`, `BETWEEN`, `LIKE 'x%'`).
+3. Then columns the query only **orders by**.
+
+Selectivity is a tie-break *within* a group, never the primary key of the
+decision. An index cannot use any column after the first range predicate for
+lookup, so a highly selective range column placed first throws away every column
+behind it.
+
+```php
+// WHERE customer_id = ? AND created_at > ?  ORDER BY created_at
+$table->index(['customer_id', 'created_at']);
+```
+
+`customer_id` leads because it is the **equality** predicate — not because it is
+more selective. Reverse the order and the equality column sits behind a range,
+where the index can no longer seek on it. That holds even when `created_at` is
+the more selective of the two, which is exactly the case the folklore rule gets
+wrong.
+
+## Query Optimization
+
+### EXPLAIN analysis
+
+| Column | Value worth a second look | The question it raises |
+|---|---|---|
+| `rows` | High number | Too many rows examined |
+| `Extra` | `Using filesort` | Sorting without index |
+| `Extra` | `Using temporary` | Temp table — optimize GROUP BY/DISTINCT |
+| `key` | `NULL` | No index used |
+
+Good values: `type` = `ref`, `eq_ref`, `const`; `Extra` = `Using index`.
+
+**`type = ALL` is a full table scan, and a full table scan is often the correct
+plan.** It belongs in no "bad value" column, because the row itself does not
+decide:
+
+- On a table small enough to sit in a page or two, the scan is **cheaper** than
+  an index lookup — the index costs a second read plus a row fetch per hit.
+- On a predicate that matches a large fraction of the table, the planner picks
+  the scan **on purpose**; forcing an index there is slower, and many planners
+  will ignore the hint.
+- On a table with hundreds of thousands of rows and a predicate matching a
+  handful, `ALL` is the defect.
+
+The question to answer is *how many rows the predicate matches, out of how
+many* — not whether `type` reads `ALL`. Compare the planner's `rows` estimate
+against the table's size before concluding anything.
+
+### Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `SELECT *` in production | Select only needed columns |
+| `LIKE '%search%'` | Fulltext search or `LIKE 'search%'` |
+| `OFFSET` on large tables | Cursor pagination |
+| `ORDER BY RAND()` | Application-level randomization |
+
+**Subqueries in `WHERE` are not on that list**, and the unconditional "rewrite
+as a JOIN" they used to carry here was wrong more often than it was right:
+
+| The subquery is | Do |
+|---|---|
+| **correlated** — it references the outer row, so it re-executes per row | rewrite as a JOIN, or as a derived table joined once. This is the case the folklore rule was built for |
+| an **uncorrelated `IN` / `EXISTS`** | leave it. Planners flatten these into a semi-join already, and the hand-written JOIN often introduces the duplicate rows a semi-join was avoiding |
+| a **bound on the driving set** — it produces a small list the outer query then filters on | leave it. Rewriting widens the driving set, which is the opposite of the intent |
+
+Check the plan before rewriting: if the subquery already shows as a semi-join or
+a materialized derived table executed once, the rewrite buys nothing and costs
+correctness.
+### Pagination
+
+Always paginate list endpoints — never `get()` on unbounded queries:
+
+```php
+// Standard
+$users = User::query()->paginate(15);
+
+// Cursor pagination for large tables
+$users = User::query()->orderBy('id')->cursorPaginate(15);
+```
+
+## Migrations
+
+- Use `php artisan make:migration` to generate.
+- Use `decimal` for money — never `float`.
+- Add foreign keys with `constrained()`, and **choose** the `onDelete()` action
+  rather than copying one: `cascade` when the child is expendable without its
+  parent, `restrict` when the child is a record in its own right (an invoice, an
+  audit row, a payment), `set null` when it survives the parent with the link
+  removed — which needs a nullable column. The decision table lives in
+  [`laravel-migration`](../../skills/laravel-migration/SKILL.md)
+  § Referential action is a decision.
+- Always add indexes for searchable/filterable columns.
+- One logical change per migration.
+- **Declare recovery, always.** Either a `down()` that restores the prior state,
+  or — when restoration is genuinely impossible — a roll-forward plan written in
+  the migration file itself, naming why restoration is impossible with the
+  evidence, the ordered recovery steps and their inputs, the criteria that say
+  recovery succeeded, and the responsible owner. Silence is the violation, not
+  the absence of `down()`. Full contract:
+  [`laravel-migration`](../../skills/laravel-migration/SKILL.md)
+  § The recovery contract.
+
+### Multi-connection migrations
+
+```php
+Schema::connection('tenant_database')->create('projects', function (Blueprint $table) {
+    // ...
+});
+```
+
+## Transactions
+
+```php
+// Single connection
+DB::transaction(function () use ($order, $items): void {
+    $order->save();
+    $order->items()->createMany($items);
+});
+
+// Explicit connection
+DB::connection('tenant_database')->transaction(function () {
+    // Tenant-specific operations
+});
+```
+
+## Multi-Connection Architecture
+
+- Always specify `$connection` on models.
+- Use explicit connection in migrations targeting specific databases.
+- Transactions are per-connection — cross-connection requires manual begin/commit/rollback.
+
+## Do NOT
+
+- Use raw SQL with user input — always parameterize.
+- Use `float` for money — use `decimal`.
+- Use `get()` or `all()` on large tables without pagination.
+- Run migrations without specifying connection in multi-DB project.
+- Add indexes without checking existing ones — duplicates waste write performance.