@event4u/agent-config 2.24.0 → 2.26.0

package/.agent-src/rules/roadmap-progress-sync.md

@@ -25,16 +25,17 @@ Roadmap touch = create / rename / delete / move file, add/rename/remove a phase,
 ```
 EVERY DONE STEP FLIPS [ ] → [x] IN THE SAME REPLY THAT LANDS THE WORK.
 NO "I UPDATE THE ROADMAP AT THE END OF THE PHASE."
-NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
 A REPLY THAT LANDS A VERIFIED STEP WITHOUT FLIPPING ITS CHECKBOX
 IS A RULE VIOLATION, NOT AN OVERSIGHT.
 ```
 
-`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The dashboard is a real-time monitor, not a post-hoc summary. Batched flips at the archive commit defeat the dashboard's purpose.
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The checkbox itself is the real-time monitor — the markdown file is the source of truth, the dashboard is a derived view.
 
 **Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one).
 
-**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts and regen — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+
+**Dashboard regen cadence — opt-in batching.** The checkbox flip is non-batchable. The **subprocess regen** (`./agent-config roadmap:progress`) is batchable per `roadmap.dashboard_regen_cadence` in `.agent-settings.yml` (`per_step` default · `every_5_steps` · `phase_boundary`). Run end, phase boundary, and any file-shape touch (rename / phase add / archive — Iron Law 1) always force an immediate regen regardless of cadence.
 
 ## Pre-send self-check — MANDATORY
 
@@ -42,10 +43,15 @@ Before sending any reply that landed roadmap work:
 
 1. Did this reply land a step (code/doc saved + verification passed)?
 2. Is its checkbox flipped to `[x]` / `[~]` / `[-]` in `agents/roadmaps/<file>.md`? If no → flip, then continue.
-3. Did `./agent-config roadmap:progress` run after the flip? If no → run, then continue.
+3. Is regen due now per `roadmap.dashboard_regen_cadence`?
+   - `per_step` → yes, always.
+   - `every_5_steps` → yes when this is the 5th, 10th, … closed step in the run, or the last step of the reply.
+   - `phase_boundary` → only when this reply closes the phase or run.
+   - Any file-shape touch (rename / phase add / archive) → yes, regardless of cadence.
+   If yes and not run yet → run `./agent-config roadmap:progress`, then continue.
 4. Did `count_open` reach 0? If yes → `git mv` to `archive/` and regen again — same reply.
 
-Any "no" at step 2 or 3 → reply is incomplete. Do not send.
+Any "no" at step 2 → reply is incomplete. Do not send. A skipped step 3 regen is fine when cadence permits — checkbox truth lives in the markdown file.
 
 Long-form mechanics (failure-mode catalog, Copilot fallback, `[~]` vs `[ ]` semantics, hook + CI defence-in-depth) live in `guideline:agent-infra/roadmap-progress-mechanics`.
 Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/user-interrupt-priority.md

@@ -0,0 +1,46 @@
+---
+type: "always"
+tier: "1"
+description: "User interrupts override the current task — STOP, complete new task in full, then ASK before resuming; never silently return to prior work"
+alwaysApply: true
+source: package
+load_context:
+  - ../contexts/execution/interrupt-examples.md
+---
+
+# User-Interrupt Priority
+
+A new instruction mid-flight is **not** a continuation. Examples and failure modes: [`contexts/execution/interrupt-examples.md`](../contexts/execution/interrupt-examples.md).
+
+## The Iron Law
+
+```
+NEW TASK FROM USER MID-FLIGHT → STOP CURRENT TASK.
+COMPLETE NEW TASK IN FULL.
+THEN ASK BEFORE RESUMING THE OLD TASK.
+NEVER SILENTLY RESUME.
+```
+
+Holds regardless of `personal.autonomy`, a standing autonomy directive, or roadmap authorization. Autonomy narrows trivial workflow questions — it does not authorize ignoring a fresh instruction.
+
+## Classify every user turn
+
+| Bucket | Signal | Action |
+|---|---|---|
+| **Continuation** | Same deliverable + target + success criterion. "weiter", "next step". | Keep working. |
+| **Clarification** | Question / correction about the current task. No new deliverable. | Answer, then continue. |
+| **Interrupt** | Different deliverable, target, or success criterion. Meta-tasks ("audit", "stop and analyze") count. | STOP. Run new task. ASK before resume. |
+
+In doubt → treat as interrupt. Cost of a spurious ask is one turn; cost of silent-resume is the rest of the unwanted work.
+
+## Stop-ask-resume protocol
+
+1. **STOP** — abandon the current tool plan. No "one more check" unless the new instruction says so.
+2. **EXECUTE** the new task in full. All other rules (Hard Floor, scope, autonomy) apply.
+3. **ASK** when done — name the interrupted task and request a resume decision:
+
+```
+Done with <new task>. Resume <interrupted task name>? (yes / no / different)
+```
+
+Only resume on `yes` or a restatement. "and then continue with X" = explicit resume authorization; no re-ask.

package/.agent-src/rules/verify-before-complete.md

@@ -22,7 +22,7 @@ If you haven't run the verification command **in this message**, you cannot clai
 
 Before claiming ANY work is complete:
 
-1. **IDENTIFY** — What command proves this claim? (tests, PHPStan, build, etc.)
+1. **IDENTIFY** — What command proves this claim? (tests, type-checker, linter, build — whichever the project actually runs)
 2. **RUN** — Execute the full command (fresh, complete, not cached)
 3. **READ** — Full output, check exit code, count failures
 4. **VERIFY** — Does the output actually confirm the claim?
@@ -43,7 +43,7 @@ Skip any step = the claim is unverified.
 - Expressing satisfaction before running verification
 - About to commit/push without running tests + quality
 - Trusting a previous run from earlier in the conversation
-- Relying on partial verification (ran tests but not PHPStan)
+- Relying on partial verification (ran tests but skipped the type-checker / linter)
 - ANY wording implying success without fresh evidence
 
 ## Verification commands
@@ -64,3 +64,12 @@ all live in
 The Iron Law and the Gate above are the obligation surface; the
 mechanics context is the lookup material the agent pulls when the
 gate fires.
+
+## Examples
+
+Pattern Memory — wrong / right / why demos for the Iron Law and the
+red-flags list:
+[`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md)
+(hedged claims, trusting earlier runs, partial-verification creep).
+Outcome baseline locked at
+[`tests/golden/outcomes/verify_before_complete.json`](../../tests/golden/outcomes/verify_before_complete.json).

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

@@ -104,7 +104,7 @@ Only surface trade-offs or concerns that need the user's input.
 - **feature-planning** — adversarial review after Understanding Lock, before presenting the plan.
 - **bug-analyzer** — review the proposed fix before implementing.
 - **code-review** — self-review before creating a PR.
-- **migration-creator** — review migration for data safety.
+- **laravel-migration** (or framework-native equivalent) — review migration for data safety.
 - **api-design** — review API design for consistency and breaking changes.
 - **security** — review security-sensitive changes for attack surface.
 

package/.agent-src/skills/ai-council/SKILL.md

@@ -3,6 +3,7 @@ name: ai-council
 description: "Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'."
 source: package
 domain: process
+meta_skill: true
 ---
 
 <!-- cloud_safe: degrade -->

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow)."
 source: package
 domain: engineering
 ---
@@ -9,178 +9,82 @@ domain: engineering
 
 ## When to use
 
-Use this skill when the user asks to create a new API endpoint, REST route, or controller action.
-
+Use this skill when the user asks to create a new API endpoint, REST route, or HTTP handler.
 
 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 `../../../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 |
+- Modifying existing endpoints — use the code-refactoring skill.
+- API design decisions (versioning, deprecation, contract shape) — use [`api-design`](../api-design/SKILL.md).
+
+## Stack routing
+
+Detect the stack, then hand off to the matching carve-out skill for the framework-specific procedure (file layout, validation primitive, response-shaping convention).
+
+| Detected stack | Carve-out skill |
 |---|---|
-| 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` |
+| Laravel (`artisan` + `composer.json` with `laravel/framework`) | [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) |
+| Symfony (`bin/console` + `composer.json` with `symfony/framework-bundle`) | [`symfony-workflow`](../symfony-workflow/SKILL.md) |
+| Next.js (`next` in `package.json`) | [`nextjs-patterns`](../nextjs-patterns/SKILL.md) |
+| Express / Fastify / NestJS / plain Node | follow project conventions in `agents/` + `package.json scripts` |
+| FastAPI / Django / Flask | follow project conventions in `agents/` + `pyproject.toml` |
+| Go (`net/http`, `gin`, `echo`, `fiber`) | follow project conventions in `agents/` + `go.mod` |
+| Rust (`axum`, `actix-web`, `rocket`) | follow project conventions in `agents/` + `Cargo.toml` |
+
+If the project doc folder (`agents/`) has an endpoint-creation guide, that is the source of truth — read it before generating code.
+
+## Procedure: Create an API endpoint (stack-neutral)
+
+1. **Read project docs** — Check `./agents/` and `AGENTS.md` for endpoint conventions, routing layout, response shape.
+2. **Detect stack** and route to the carve-out per the table above.
+3. **Plan the endpoint** — method, path, request shape, response shape, auth requirement, idempotency.
+4. **Create the route registration** in the project's routing surface (route file, decorator-annotated handler, file-based router).
+5. **Create the request handler / controller** — thin; delegate business logic to a service / use-case.
+6. **Validate input at the boundary** via the framework's validation primitive (FormRequest, Zod, class-validator, Pydantic, struct-tag validators, etc.) — never inline ad-hoc `if` checks.
+7. **Authorize the action** via the framework's authz primitive (Policy, voter, guard, middleware, route dependency).
+8. **Shape the response** through a transformer / serializer / DTO — never return raw ORM entities.
+9. **Document** the endpoint (OpenAPI annotations / generated spec / project doc).
+10. **Verify** — run the project type-checker + targeted tests + smoke probe (`curl` / Bruno / Postman / integration test).
+
+## Conventions (apply on every stack)
+
+- **One handler, one responsibility** — prefer single-purpose handlers over multi-action controllers when the framework supports it.
+- **No business logic in the handler** — delegate to a service / use-case layer.
+- **Validate at the boundary** — never trust raw request data inside the handler.
+- **Authorize every state-changing action** — no unprotected mutating endpoints.
+- **Shape responses through a transformer** — DTO, serializer, API resource, response model — never expose raw ORM entities.
+- **Version the API surface** explicitly (`/v1/`, header, content-type) — don't rely on implicit versioning.
 
-### OpenAPI documentation
+## Stack-specific procedures
 
-Controllers use PHP 8 attributes for OpenAPI spec generation from `App\OpenApi\Schema\`:
+For Laravel projects (the most fully-fleshed-out carve-out in this package), see [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) — covers single-action controllers, `FormRequest`, `Resource`, `Policy`, `CollectionFormRequest`, OpenAPI attributes, and the versioned route layout.
 
-- `ShowResourceRequestSchema`, `ListResourceRequestSchema`, `CreateResourceRequestSchema`
-- `ShowResourceResponseSchema`, `ListResourceResponseSchema`, `CreateResourceResponseSchema`
-- `ResourceNotFoundResponse`, `ValidationErrorResponse`
+For other stacks, read the matching carve-out from the table above and combine with the project's `agents/` docs.
 
 ## 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
+1. Generated files — route registration, handler, request validator, response shaper, authorization rule.
+2. Test file with happy path and validation-error cases (using the project's test framework).
+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.
+- Don't forget to register the route — creating the handler 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.
+- Validation rules must match the documented contract (OpenAPI / schema / typed client) — keep them in sync.
+- Response shapes are part of the public contract — adding a field is additive; renaming or removing is breaking.
 
 ## 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()`.
+- Do NOT put business logic in the handler — delegate to services / use-cases.
+- Do NOT skip request validation — every handler validates at the boundary via the framework's primitive.
+- Do NOT return raw ORM entities — always go through a transformer / serializer / response model.
+- Do NOT create unprotected state-changing endpoints — authorize every mutation.
+- Do NOT improvise framework idioms — read the carve-out (`laravel-api-endpoint`, `nextjs-patterns`, etc.) for the stack-correct shape.
 
 ## Auto-trigger keywords
 
 - create endpoint
 - new API route
+- route handler
 - controller creation
-- form request
-- API resource
+- REST endpoint
+- add endpoint

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

@@ -151,6 +151,17 @@ expect($data['title'])->toBeString();
 expect($data['total'])->toBeString(); // Money as string, not float
 ```
 
+When a failing test dumps the full JSON body, narrow the diagnosis with `jq` or `grep`
+instead of scrolling the whole payload:
+
+```bash
+# Extract only the failing assertion path
+echo "$RESPONSE_JSON" | jq '.data.status, .errors'
+
+# Targeted log scan
+rg --json 'API call failed' storage/logs/laravel.log | jq -r '.data.lines.text'
+```
+
 ## External service mocking
 
 ```php

package/.agent-src/skills/character-consistency/SKILL.md

@@ -2,7 +2,6 @@
 name: character-consistency
 description: "Use when a character must stay visually identical across AI video scenes — locks identity tokens (silhouette, palette, wardrobe, prop) in JSON. Triggers 'character lock', 'same character'."
 personas:
-  - pixar-storyboard-artist
   - hollywood-director
 source: package
 domain: product
@@ -118,3 +117,15 @@ the lock.
 - Do NOT skip the reference frame after the first render — visual
   regression has nothing to compare against.
 - Do NOT lock a character that appears in only one scene.
+
+## Policies
+
+When a character lock would identify or render a real person, consult before emitting the JSON:
+
+- [`agents/policies/media/likeness.md`](../../../agents/policies/media/likeness.md) — real-person identity tokens require a cited likeness release.
+- [`agents/policies/media/public-figures.md`](../../../agents/policies/media/public-figures.md) — recognised public figures carry the harder gate (publicity rights + transformative-intent).
+- [`agents/policies/media/voice-cloning.md`](../../../agents/policies/media/voice-cloning.md) — when `voice_note` references a real person's voice.
+- [`agents/policies/media/disclosure.md`](../../../agents/policies/media/disclosure.md) — outputs carrying a real-person lock require the non-removable AI-generation disclosure downstream.
+
+Refuse-and-surface the file path; do not silently sanitise the prompt.
+

package/.agent-src/skills/code-refactoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-refactoring
-description: "Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools."
+description: "Use when the user says 'refactor this', 'rename class', or 'move method'. Safely refactors code in any language — finds all callers, updates downstream dependencies, verifies via quality tools."
 source: package
 domain: engineering
 ---
@@ -20,7 +20,7 @@ Do NOT use when:
 ## Before refactoring
 
 1. **Read the agent docs** — check `agents/docs/` and `agents/contexts/` for the area you're refactoring.
-   For modules, also read `app/Modules/{Module}/agents/`. See the `project-docs` skill for the mapping.
+   For modules, also read the project's module-docs directory (path varies by stack — Laravel: `app/Modules/{Module}/agents/`; Nx: `apps/{app}/docs/`; mono-repo: per-package `docs/`). See the `project-docs` skill for the mapping.
 2. **Understand the scope** — what exactly needs to change and why?
 3. **Find ALL references** — use `codebase-retrieval` and `view` with `search_query_regex` to find every
    caller, implementation, test, and configuration that references the code being changed.
@@ -34,34 +34,35 @@ Do NOT use when:
 - Rename, extract, move, or restructure the target code.
 - Keep the change minimal and focused.
 
-### Step 2: Update all downstream deps
+### Step 2: Update all downstream dependencies
 
 For each affected file (from the impact analysis):
 
 - **Callers**: Update method calls, constructor arguments, imports.
 - **Interfaces / abstract methods**: Update all implementations to match new signatures.
 - **Subclasses**: Update overridden methods.
-- **Type hints / PHPDoc**: Update type references.
+- **Type hints / annotations**: Update type references (PHPDoc, TypeScript types, Python type hints, Go generics, Rust generics).
 - **Config / bindings**: Update service container bindings, route references, etc.
-- **Imports**: Add or update `use` statements.
+- **Imports**: Add or update import statements (`use` for PHP, `import` for JS/TS/Python, `import` blocks for Go, `use` for Rust).
 
-### Step 3: Update API layer (if controllers/endpoints are affected)
+### Step 3: Update API layer (if request handlers / endpoints are affected)
 
-When refactoring touches controllers, requests, resources, or routes:
+When refactoring touches handlers, route registrations, request validators, or response shapers, walk the stack-appropriate boundary. Use the carve-out skill for the project's framework if one exists; otherwise consult the table below for what to check on each stack.
 
-| Component | What to check and update |
+| Layer | What to check and update |
 |---|---|
-| **Controller** | `__invoke()` signature, injected services, return type |
-| **FormRequest** | `authorize()`, `rules()`, validated field names |
-| **Resource** | `toArray()` field mapping, conditional fields, nested resources |
-| **OpenAPI Schema Attributes** | Request schemas (`ShowResourceRequestSchema`, `CreateResourceRequestSchema`, etc.) |
-| **OpenAPI Response Attributes** | Response schemas (`ShowResourceResponseSchema`, `CreateResourceResponseSchema`, etc.) |
-| **OpenAPI Error Attributes** | `ResourceNotFoundResponse`, `ValidationErrorResponse` |
-| **Custom Request Schemas** | Extended schema classes in `app/OpenApi/Schema/Request/v{N}/` |
-| **Route definition** | Route file in `routes/api/v{N}/`, route name, URL path, HTTP method |
-| **Route model binding** | Parameter name in route must match variable name in controller |
-| **Version inheritance** | If v1 extends v2 (or vice versa), check both versions |
-| **Module routes** | Module routes in `app/Modules/*/Routes/api.php` with version prefix |
+| **Route registration** | Route file / decorator / file-based-router entry — name, URL, HTTP method, parameter binding |
+| **Handler / Controller** | Entry signature, injected dependencies, return type |
+| **Request validator** | Validation rule definitions, allowlisted fields (FormRequest, Zod schema, class-validator DTO, Pydantic model, struct tags) |
+| **Response shaper** | Field mapping in the transformer (API Resource, serializer, DTO mapper, response model) |
+| **API contract** | OpenAPI annotations, generated spec, typed client (regenerate if generated) |
+| **Authorization rule** | Policy / voter / guard / middleware / route dependency that protects the route |
+| **Module routes** | Module-local routing surface (Laravel `app/Modules/*/Routes/`, Nx `apps/*/src/routes`, mono-repo per-package routes) |
+
+Carve-out routing:
+- Laravel: [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md)
+- Next.js: [`nextjs-patterns`](../nextjs-patterns/SKILL.md)
+- Symfony: [`symfony-workflow`](../symfony-workflow/SKILL.md)
 
 ### Step 4: Update tests — with user approval
 
@@ -89,19 +90,24 @@ When refactoring touches controllers, requests, resources, or routes:
 - Do NOT delete tests — adapt them to the new code structure.
 - Do NOT reduce test coverage — if you split a class, split the test too.
 
-### Step 5: Verify with quality tools
+### Step 5: Verify with the project's quality tools
 
-Run quality tools after each significant step — do NOT batch everything to the end:
+Run the project's type-checker and linter after each significant step — do NOT batch everything to the end. The exact command set depends on the stack; resolve via `quality-tools` skill or the project's `Taskfile.yml` / `package.json scripts` / `composer.json scripts` / `Makefile`.
 
-- Run PHPStan: `vendor/bin/phpstan analyse` (see `quality-tools` skill for detection).
-- If PHPStan finds new errors from the refactoring → fix immediately before continuing.
-- Run Rector + ECS: `vendor/bin/rector process && vendor/bin/ecs check --fix`.
-- Run PHPStan again after Rector (Rector can introduce issues).
+| Stack | Typical pipeline |
+|---|---|
+| Laravel / PHP | `vendor/bin/phpstan analyse` → `vendor/bin/rector process` → `vendor/bin/ecs check --fix` → re-run PHPStan |
+| TypeScript | `tsc --noEmit` → `eslint --fix` → `prettier --write` |
+| Python | `mypy` (or `pyright`) → `ruff check --fix` → `ruff format` |
+| Go | `go vet ./...` → `golangci-lint run --fix` → `gofmt -w` |
+| Rust | `cargo check` → `cargo clippy --fix` → `cargo fmt` |
+
+If auto-fixers can rewrite types (Rector for PHP, `eslint --fix` for TS), re-run the type-checker after them — auto-fixers can introduce new errors.
 
 ### Step 6: Run tests
 
-- Run tests related to the changed code first (`php artisan test --filter=...`).
-- Then run the full test suite (`php artisan test`).
+- Run tests related to the changed code first (`php artisan test --filter=...`, `pnpm test -- <pattern>`, `pytest -k <pattern>`, `go test ./{path}/...`, `cargo test {pattern}`).
+- Then run the full test suite (`php artisan test`, `pnpm test`, `pytest`, `go test ./...`, `cargo test`).
 - All tests must pass before the refactoring is considered complete.
 
 ### Step 7: Update documentation
@@ -142,9 +148,9 @@ After the code changes are verified, update all affected documentation:
 1. Update controller + request + resource + OpenAPI schemas + route → present test changes →
    update docs (`agents/docs/controller.md`, `agents/docs/api-resources.md`) → run PHPStan → run tests.
 
-### Replace impl (e.g. switch service)
-1. Create new impl → update binding → find all direct references → update → present test
-   changes → update docs → run PHPStan → run tests → remove old impl.
+### Replace implementation (e.g. switch service)
+1. Create new implementation → update binding → find all direct references → update → present test
+   changes → update docs → run PHPStan → run tests → remove old implementation.
 
 ### Move/restructure module
 1. Move files → update namespaces → update `ModuleServiceProvider` if needed → update module routes →