@event4u/agent-config 2.25.0 → 2.26.0

package/.agent-src/skills/dependency-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-upgrade
-description: "Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification."
+description: "Use when upgrading dependencies — 'update framework X', 'bump runtime version', or 'upgrade packages'. Covers changelog review, breaking-change detection, and verification. Stack-agnostic."
 source: package
 domain: engineering
 ---
@@ -9,10 +9,10 @@ domain: engineering
 
 ## When to use
 
-Use this skill when upgrading Composer packages, npm packages, or any project dependency.
+Use this skill when upgrading project dependencies on any stack — Composer (PHP), npm / pnpm / yarn (JS/TS), pip / poetry / uv (Python), go.mod (Go), Cargo (Rust), or any other language-level package manager.
 
 Do NOT use when:
-- Installing new deps for the first time
+- Installing new dependencies for the first time
 - Routine code changes unrelated to package versions
 
 ## Procedure: Upgrade a dependency
@@ -25,7 +25,7 @@ Before upgrading:
 - **Identify breaking changes** — look for "BREAKING", "BC break", major version bumps.
 - **Check deprecation notices** — code using deprecated APIs needs updating.
 - **Review upgrade guides** — many packages provide migration docs.
-- **Check PHP/Node version requirements** — does the new version need a newer runtime?
+- **Check runtime version requirements** — does the new version need a newer PHP / Node / Python / Go / Rust toolchain?
 
 ### 2. Plan
 
@@ -73,23 +73,69 @@ npm install package-name@latest
 npm audit
 ```
 
-### 4. Verify
+#### pip / poetry / uv (Python)
+
+```bash
+# Check outdated packages
+pip list --outdated         # pip
+poetry show --outdated       # poetry
+uv pip list --outdated       # uv
+
+# Upgrade a specific package
+pip install --upgrade package-name
+poetry update package-name
+uv pip install --upgrade package-name
 
-After upgrading, run the full verification pipeline:
+# Check for vulnerabilities
+pip-audit                    # via pip-audit
+safety check                 # via safety
+```
+
+#### go.mod (Go)
 
 ```bash
-# PHP/Laravel
-vendor/bin/phpstan analyse           # Check for type errors
-vendor/bin/rector process            # Auto-fix refactoring
-vendor/bin/ecs check --fix           # Auto-fix code style
-php artisan test                     # Run all tests
-
-# JavaScript
-npm run build     # Check build succeeds
-npm test          # Run all tests
-npm run lint      # Check code style
+# List available updates
+go list -u -m all
+
+# Upgrade a specific module
+go get example.com/pkg@latest
+go get example.com/pkg@v1.2.3
+
+# Tidy after upgrade
+go mod tidy
+
+# Check for known vulnerabilities
+govulncheck ./...
 ```
 
+#### Cargo (Rust)
+
+```bash
+# Check outdated
+cargo outdated               # requires cargo-outdated
+
+# Upgrade
+cargo update -p crate-name
+cargo add crate-name@1.2     # edition-aware add
+
+# Audit
+cargo audit                  # requires cargo-audit
+```
+
+### 4. Verify
+
+After upgrading, run the project's full verification pipeline. The exact commands depend on the stack — resolve via the project's `Taskfile.yml`, `package.json scripts`, `composer.json scripts`, `Makefile`, or the `quality-tools` skill.
+
+| Stack | Type-check | Lint / autofix | Tests |
+|---|---|---|---|
+| PHP / Laravel | `vendor/bin/phpstan analyse` | `vendor/bin/rector process` + `vendor/bin/ecs check --fix` | `php artisan test` (or `vendor/bin/pest`) |
+| TypeScript | `tsc --noEmit` | `eslint --fix` + `prettier --write` | `pnpm test` (or `vitest run`, `jest`) |
+| Python | `mypy` / `pyright` | `ruff check --fix` + `ruff format` | `pytest` |
+| Go | `go vet ./...` | `golangci-lint run --fix` | `go test ./...` |
+| Rust | `cargo check` | `cargo clippy --fix` + `cargo fmt` | `cargo test` |
+
+Re-run the type-checker after any auto-fixer that can rewrite types (Rector for PHP, `eslint --fix` for TS).
+
 ### 5. Document
 
 - Note the upgrade in the commit message: `chore: upgrade vendor/package from 2.x to 3.x`
@@ -100,7 +146,7 @@ npm run lint      # Check code style
 When upgrading multiple packages:
 
 - **Upgrade one at a time** — easier to identify which upgrade broke something.
-- **Exception:** Tightly coupled packages (e.g., `laravel/framework` + `laravel/*`) can be upgraded together.
+- **Exception:** Tightly coupled packages can be upgraded together (e.g., `laravel/framework` + `laravel/*`; `@nestjs/core` + `@nestjs/*`; `react` + `react-dom`; `next` + `@next/*`).
 - **Run tests after each upgrade** — don't batch upgrades and test once at the end.
 
 ## Common pitfalls
@@ -111,7 +157,7 @@ When upgrading multiple packages:
 | Upgrading all packages at once | One package at a time (or tightly coupled groups) |
 | Trusting `composer update` blindly | Use `--dry-run` first, review changes |
 | Ignoring deprecation warnings | Fix deprecations before they become errors |
-| Skipping tests after upgrade | Full test suite + PHPStan after every upgrade |
+| Skipping tests after upgrade | Full test suite + project type-checker (PHPStan / tsc / mypy / `go vet` / `cargo check`) after every upgrade |
 | Lock file conflicts | Coordinate upgrades with the team |
 
 ## Version constraint guidelines
@@ -165,7 +211,7 @@ npm audit
 |---|---|---|
 | **Known CVEs** | `composer audit` / `npm audit` | Direct vulnerabilities |
 | **Maintenance status** | GitHub: last commit, open issues | Abandoned packages are a risk |
-| **Dependency tree** | `composer show -t vendor/pkg` / `npm ls new-package` | Transitive deps may conflict |
+| **Dependency tree** | `composer show -t vendor/pkg` / `npm ls new-package` | Transitive dependencies may conflict |
 | **License compatibility** | `composer licenses` / check `package.json` | Legal compliance |
 | **Bundle size** (npm) | `npx bundlephobia new-package` | Impact on frontend bundle |
 

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -84,8 +84,8 @@ When UI changes are involved:
 - `rg`, `grep` for text: specific patterns, not full files
 - `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
 - `--filter`, `--json`, `--format` flags on CLI tools — always use them
-- Laravel: `route:list --json | jq '.[] | select(.uri | test("users"))'`
-- Logs: `rg "request_id=abc123" storage/logs` — never `cat storage/logs/laravel.log`
+- Route lookup — Laravel `php artisan route:list --json | jq '…'`, Rails `bin/rails routes | grep users`, Express `console.log(app._router.stack)`, FastAPI `app.routes`, Symfony `bin/console debug:router`.
+- Logs — `rg "request_id=abc123" <log-dir>` — never `cat <log-file>`. Log dirs by stack: Laravel `storage/logs/`, Rails `log/`, Node `./logs/` or `journalctl`, Python `./logs/` or `journalctl`, Docker `docker compose logs <svc> --since 5m`.
 
 ### Avoid large output by default
 
@@ -156,22 +156,33 @@ If full TDD is not practical: at least write down the expected output before cod
 #### Backend examples
 
 ```bash
-# Laravel route lookup — targeted, not full dump
-php artisan route:list --json | jq '.[] | select(.uri == "api/users") | {method, uri, name, action, middleware}'
-
-# Config/debug
-php artisan config:show app | grep env
+# Route lookup — pick the project's framework
+php artisan route:list --json | jq '.[] | select(.uri == "api/users") | {method, uri, name, action, middleware}'   # Laravel
+bin/console debug:router --format=json | jq '.[] | select(.path == "/api/users")'                                  # Symfony
+bin/rails routes -g users                                                                                          # Rails
+curl -s http://localhost:3000/__routes | jq '.[] | select(.path == "/api/users")'                                  # Express custom-introspection
+curl -s http://localhost:8000/openapi.json | jq '.paths["/api/users"]'                                             # FastAPI
+
+# Config inspection
+php artisan config:show app | grep env       # Laravel
+bin/console debug:config framework            # Symfony
+bin/rails runner 'puts Rails.application.config_for(:database)'  # Rails
 
 # API inspection — extract only what you need
 curl -s http://localhost/api/users | jq '.[0] | {id, email, status}'
 curl -s http://localhost/api/users/1 | jq '{id, name, roles: [.roles[].name]}'
 
-# Logs — scoped by request ID, timestamp, or error type
-rg "request_id=abc123|OrderFailed" storage/logs
-tail -n 200 storage/logs/laravel.log | rg "payment|timeout"
-
-# Database — targeted queries, not full table dumps
-php artisan tinker --execute="User::where('email', 'test@example.com')->first(['id','email','status'])"
+# Recent logs — targeted, not full dump
+tail -n 200 storage/logs/laravel.log | rg "payment|timeout"             # Laravel
+tail -n 200 log/development.log | rg "payment|timeout"                   # Rails
+docker compose logs api --since 5m --no-color | rg "payment|timeout"     # any container stack
+journalctl -u myapp --since "5 min ago" | rg "payment|timeout"           # systemd
+
+# DB-state probe — targeted single record, not full table
+php artisan tinker --execute="User::where('email','x@y')->first(['id','email','status'])"   # Laravel
+bin/rails runner "p User.where(email: 'x@y').first&.slice(:id,:email,:status)"               # Rails
+bin/console doctrine:query:sql "SELECT id,email,status FROM users WHERE email='x@y' LIMIT 1" # Symfony
+psql -d mydb -c "SELECT id,email,status FROM users WHERE email='x@y' LIMIT 1"                 # raw SQL fallback
 ```
 
 #### Debugging with Xdebug
@@ -218,7 +229,7 @@ Never load full output into context when a filter gives you the answer.
 
 Tests are mandatory when behavior changes or bugs are fixed.
 
-Prefer: failing test first → impl → passing test.
+Prefer: failing test first → implementation → passing test.
 
 Test types: unit (isolated logic), feature/integration (behavior), UI (frontend), regression (bugs).
 

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

@@ -15,7 +15,7 @@ Use when creating/modifying Eloquent models, relationships, scopes, or writing d
 
 Do NOT use when:
 - Schema design or query optimization (use `database` skill)
-- Creating migrations only (use `migration-creator` skill)
+- Creating migrations only (use `laravel-migration` skill)
 
 ## Procedure: Create or modify a model
 

package/.agent-src/skills/feature-planning/SKILL.md

@@ -145,7 +145,7 @@ Structural roadmap tasks must include:
 
 1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
 2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
-3. **Exact command** — `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php`, never *"run the migration"*.
+3. **Exact command** — the precise CLI invocation, never *"run the migration"*. Examples: `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php` (Laravel), `bin/console doctrine:migrations:migrate --no-interaction` (Symfony), `bin/rails db:migrate VERSION=20260509…` (Rails), `npx prisma migrate deploy` (Prisma), `alembic upgrade +1` (Python / Alembic), `sqlx migrate run` (Rust).
 4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
 5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
 

package/.agent-src/skills/file-editor/SKILL.md

@@ -40,7 +40,7 @@ Relevant settings for this skill:
 
 | Key | Values | Default | Description |
 |---|---|---|---|
-| `personal.ide` | `code`, `phpstorm` | _(empty)_ | CLI command to open files |
+| `personal.ide` | `code`, `cursor`, `windsurf`, `phpstorm`, `webstorm`, `idea`, `goland`, `rubymine`, `pycharm`, `rider`, `subl`, `vim`, `nvim`, `emacs`, `zed` | _(empty)_ | CLI command to open files |
 | `personal.open_edited_files` | `true`, `false` | `false` | Whether to auto-open edited files |
 
 ## Behavior
@@ -62,31 +62,49 @@ cat .agent-settings.yml 2>/dev/null
 After editing one or more files, open them using the `ide` setting.
 **Always jump to the first edited line.** The syntax depends on the IDE:
 
-**PhpStorm** (`personal.ide: phpstorm`):
+**JetBrains IDEs** (`personal.ide: phpstorm` / `webstorm` / `idea` / `pycharm` / `goland` / `rubymine` / `rider`):
 ```bash
-phpstorm --line {line} {file}
+phpstorm --line {line} {file}        # PHP
+webstorm --line {line} {file}        # JS / TS
+idea     --line {line} {file}        # Java / Kotlin / general
+pycharm  --line {line} {file}        # Python
+goland   --line {line} {file}        # Go
 ```
 
-**VS Code** (`personal.ide: code`):
+**VS Code-family** (`personal.ide: code` / `cursor` / `windsurf`):
 ```bash
-code -g {file}:{line}
+code    --goto {file}:{line}
+cursor  --goto {file}:{line}
+windsurf --goto {file}:{line}
 ```
 
-For multiple files, run one command per file:
+**Zed** (`personal.ide: zed`):
 ```bash
-# PhpStorm
-phpstorm --line 42 app/Models/User.php
-phpstorm --line 15 app/Services/UserService.php
+zed {file}:{line}
+```
 
-# VS Code
-code -g app/Models/User.php:42
-code -g app/Services/UserService.php:15
+**Terminal editors** (`personal.ide: vim` / `nvim` / `emacs`):
+```bash
+vim  +{line} {file}
+nvim +{line} {file}
+emacs +{line} {file}
 ```
 
-If the line number is unknown (e.g. new file), omit the line parameter:
+For multiple files, run one command per file:
 ```bash
-phpstorm app/Models/User.php
-code app/Models/User.php
+# JetBrains (PhpStorm / WebStorm / GoLand / PyCharm)
+phpstorm --line 42 src/Services/UserService.php
+webstorm --line 15 src/services/user-service.ts
+goland   --line 27 internal/user/service.go
+pycharm  --line 88 app/services/user_service.py
+
+# VS Code-family
+code     --goto src/services/user-service.ts:15
+cursor   --goto app/services/user_service.py:88
+
+# Open file without jumping to a line
+code     src/services/user-service.ts
+phpstorm src/Services/UserService.php
 ```
 
 ### Rules
@@ -102,8 +120,16 @@ code app/Models/User.php
 
 | IDE | Command | Install |
 |---|---|---|
-| VS Code | `code {file}` | Shell Command: Install 'code' in PATH |
-| PhpStorm | `phpstorm {file}` | JetBrains Toolbox CLI or `Create command-line launcher` in PhpStorm |
+| VS Code         | `code {file}`     | Shell Command: Install 'code' in PATH                                        |
+| Cursor          | `cursor {file}`   | Settings → "Install 'cursor' shell command"                                  |
+| Windsurf        | `windsurf {file}` | Settings → "Install 'windsurf' shell command"                                |
+| Zed             | `zed {file}`      | Settings → "Install CLI" (creates `zed` in PATH)                             |
+| PhpStorm        | `phpstorm {file}` | JetBrains Toolbox CLI or *Tools → Create command-line launcher* in PhpStorm  |
+| WebStorm        | `webstorm {file}` | JetBrains Toolbox CLI or *Tools → Create command-line launcher* in WebStorm  |
+| IntelliJ IDEA   | `idea {file}`     | JetBrains Toolbox CLI or *Tools → Create command-line launcher* in IDEA      |
+| PyCharm         | `pycharm {file}`  | JetBrains Toolbox CLI or *Tools → Create command-line launcher* in PyCharm   |
+| GoLand          | `goland {file}`   | JetBrains Toolbox CLI or *Tools → Create command-line launcher* in GoLand    |
+| Vim / Neovim    | `vim {file}` / `nvim {file}` | Bundled with most distros                                         |
 
 ## Output format
 
@@ -121,8 +147,8 @@ code app/Models/User.php
 ## Gotcha
 
 - Check `.agent-settings.yml` for `personal.open_edited_files` before opening anything — the user may have disabled it.
-- Don't open files during batch operations (e.g., fixing 20 PHPStan errors) — only open when specifically relevant.
-- PHPStorm sometimes locks files when opening — wait briefly before editing the same file.
+- Don't open files during batch operations (e.g., fixing 20 type-checker errors across PHPStan / tsc / mypy / `cargo check`) — only open when specifically relevant.
+- JetBrains IDEs (PhpStorm, WebStorm, IDEA, PyCharm, GoLand, RubyMine, Rider) sometimes briefly lock a file on open — wait a moment before editing the same file.
 
 ## Do NOT
 

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -61,7 +61,7 @@ Run the full end-of-work gate before presenting any options — see
 
 1. Targeted tests green
 2. Full test suite green
-3. Quality pipeline (PHPStan → Rector dry-run → ECS → PHPStan) green
+3. Quality pipeline green — the project's full sequence (type-checker → auto-fixer dry-run → linter → type-checker; e.g. PHPStan → Rector → ECS → PHPStan for Laravel-PHP, tsc → eslint --fix → eslint → tsc for TS, mypy → ruff --fix → ruff → mypy for Python)
 4. `git status` clean — nothing unstaged, no stray files
 5. Branch is pushed or explicitly marked local-only
 
@@ -102,7 +102,7 @@ a different sub-procedure (steps 5a–5d).
 1. Ensure the branch is up to date with the base →
    [`prepare-for-review`](../../commands/prepare-for-review.md)
 2. Self-review the full diff → [`review-changes`](../../commands/review-changes.md)
-3. Write the PR description → [`create-pr-description`](../../commands/create-pr-description.md)
+3. Write the PR description → [`create-pr-description`](../../commands/create-pr/description-only.md)
 4. Open the PR → [`create-pr`](../../commands/create-pr.md)
 5. Confirm the PR opened green, not red
 

package/.agent-src/skills/git-workflow/SKILL.md

@@ -27,8 +27,8 @@ Do NOT use when:
 
 ## Procedure: Before opening a PR
 
-1. Run quality pipeline: PHPStan → Rector → ECS → PHPStan (see `quality-tools` skill).
-2. Run tests: `php artisan test`.
+1. Run the project's quality pipeline (see `quality-tools` skill) — typically: type-checker → auto-fixer → linter → type-checker.
+2. Run the project's test command — detect from manifest: `php artisan test` / `vendor/bin/phpunit` (PHP), `npm test` / `pnpm test` / `vitest` / `jest` (JS-TS), `pytest` (Python), `cargo test` (Rust), `go test ./...` (Go).
 3. Rebase onto `main`.
 4. Fill in PR template completely.
 
@@ -83,7 +83,7 @@ Use ONLY when the user explicitly authorized a squash on a branch that
 is already on origin. The whole sequence runs in **one turn** — never
 end the session between rewrite and push.
 
-Trigger context: `post-push-rewrite-discipline` rule routed here.
+Trigger context: `git-history-discipline` rule routed here.
 
 ### 1. Snapshot before touching anything
 
@@ -159,7 +159,7 @@ A blind `git pull --rebase` here replays remote commits on top of a
 local history that may already represent the same work in a different
 shape — guaranteed conflict storm in derived files, possible
 double-application of the same change. This is the documented failure
-mode behind `post-push-rewrite-discipline`.
+mode behind `git-history-discipline`.
 
 ### 2. Tag both sides immediately
 

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

@@ -0,0 +1,187 @@
+---
+name: laravel-api-endpoint
+description: "Use when creating a new Laravel API endpoint — Controller, FormRequest, Resource, route, Policy, OpenAPI annotations — versioned route layout, single-action `__invoke` controllers."
+source: package
+domain: engineering
+---
+
+# laravel-api-endpoint
+
+## When to use
+
+Use this skill when the project is **Laravel** (detected via `artisan` + `composer.json` with `laravel/framework`) and the user asks to create a new API endpoint, REST route, or controller action.
+
+Routed in from [`api-endpoint`](../api-endpoint/SKILL.md) once the stack is detected as Laravel.
+
+Do NOT use when:
+- Modifying existing endpoints — use the code-refactoring skill.
+- API design decisions — use [`api-design`](../api-design/SKILL.md).
+- The project is Symfony / Next.js / FastAPI / etc. — go back to [`api-endpoint`](../api-endpoint/SKILL.md) and pick the right carve-out.
+
+## Procedure: Create a Laravel 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 (`routes/api/v{N}/{domain}.php`).
+3. **Create controller** — Single-action invokable controller, thin, delegate logic to a service.
+4. **Create FormRequest** — Validate all input at the boundary; authorize via Policy in `authorize()`.
+5. **Create Resource** — Transform model output via API Resource (never raw arrays / models / `response()->json()`).
+6. **Create Policy** — If authorization is needed and no Policy exists yet.
+7. **Verify** — Run PHPStan, run tests, confirm response shape matches conventions.
+
+## What to generate
+
+1. **Controller** — Single Action (invokable). Read `agents/docs/controller.md` and `../../../docs/guidelines/php/controllers.md`.
+2. **FormRequest** — Validation rules, `authorize()` via policies. Read `../../../docs/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
+
+- laravel endpoint
+- laravel controller
+- form request
+- API resource
+- laravel api route

package/.agent-src/skills/{dto-creator → laravel-dto}/SKILL.md

@@ -1,11 +1,12 @@
 ---
-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."
+name: laravel-dto
+description: "Use when creating a Laravel/PHP DTO with the SimpleDto base class and attribute mapping. For DTOs in other stacks, use the stack-native skill (TypeScript, Python, Rust, Go)."
 source: package
 domain: engineering
+framework: laravel
 ---
 
-# dto-creator
+# laravel-dto
 
 ## When to use
 
@@ -102,7 +103,7 @@ Always check `composer.json` for DTO-related packages before choosing the approa
 
 - 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 DB column names (snake_case), not the PHP property names.
+- Attribute names in the DTO must match the database column names (snake_case), not the PHP property names.
 
 ## Do NOT
 

package/.agent-src/skills/{migration-creator → laravel-migration}/SKILL.md

@@ -1,11 +1,12 @@
 ---
-name: migration-creator
-description: "Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness."
+name: laravel-migration
+description: "Use when creating a Laravel migration — table prefixes, column naming, multi-tenant awareness, php artisan make:migration. Other stacks: use stack-native migration tooling."
 source: package
 domain: engineering
+framework: laravel
 ---
 
-# migration-creator
+# laravel-migration
 
 ## When to use
 
@@ -27,9 +28,9 @@ Use this skill when the user asks to create a database migration, add a column,
 
 ## Laravel projects
 
-### Multi-DB architecture
+### Multi-database architecture
 
-Some projects use multiple DB connections. Check `config/database.php` for connections.
+Some projects use multiple database connections. Check `config/database.php` for connections.
 
 | Check | How |
 |---|---|
@@ -37,9 +38,9 @@ Some projects use multiple DB connections. Check `config/database.php` for conne
 | Migration directories | `database/migrations/` (default), check for additional directories |
 | Custom migrate commands | `php artisan list migrate` — look for project-specific commands |
 
-**Always determine which DB the table belongs to before creating a migration.**
+**Always determine which database the table belongs to before creating a migration.**
 
-### API DB migration
+### API database migration
 
 ```bash
 php artisan make:migration create_example_table
@@ -73,13 +74,13 @@ return new class extends Migration {
 };
 ```
 
-### Customer DB migration
+### Customer database migration
 
 ```bash
 php artisan make:migration:customer AddWeatherColumn --table=cl_lv_weather
 ```
 
-Customer DB tables use the `cl_` prefix (e.g. `cl_user`, `cl_lv_weather`).
+Customer database tables use the `cl_` prefix (e.g. `cl_user`, `cl_lv_weather`).
 
 ### Adding a column (with explicit connection)
 
@@ -153,7 +154,7 @@ Focus on the "Database migrations" attack questions: Can this destroy data? Is r
 
 ## Auto-trigger keywords
 
-- DB migration
+- database migration
 - create migration
 - table prefix
 - column naming