@event4u/agent-config 2.25.0 → 3.0.0

package/.agent-src/skills/agent-docs-writing/SKILL.md

@@ -3,6 +3,18 @@ name: agent-docs-writing
 description: "Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure."
 source: package
 domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # agent-docs
@@ -168,7 +180,7 @@ When starting work, read documentation in this order:
 | New module created | Create `app/Modules/{Module}/agents/` with module description |
 | Significant multi-step change | Ask user about creating a roadmap in `agents/roadmaps/` |
 | New convention introduced | Update relevant doc in `./agents/` or `.augment/guidelines/` |
-| Database schema changed | Update `agents/docs/database-setup.md` |
+| Database schema changed | Update `agents/reference/docs/database-setup.md` |
 | Architectural decision made | Use the [`adr-create`](../adr-create/SKILL.md) skill — writes a numbered ADR under `docs/adr/` (or `docs/decisions/`) and regenerates the index |
 
 ## When to update documentation
@@ -185,12 +197,12 @@ After completing a significant code change, run this mental checklist:
 
 | What changed | Doc to check |
 |---|---|
-| Database schema (migration) | `agents/docs/database-setup.md` |
+| Database schema (migration) | `agents/reference/docs/database-setup.md` |
 | New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
 | New module created | Create `app/Modules/{Module}/agents/` |
-| Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
+| Service/repository signature changed | Check if referenced in `agents/reference/docs/services-and-repos.md` |
 | New environment variable | `.env.example`, `AGENTS.md` environment section |
-| Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
+| Docker/compose change | `agents/reference/docs/docker.md`, `Makefile` documentation |
 | New Artisan command | `AGENTS.md` commands section |
 | New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
 

package/.agent-src/skills/agents-md-thin-root/SKILL.md

@@ -7,6 +7,18 @@ execution:
   type: assisted
   handler: internal
   allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # agents-md-thin-root
@@ -24,7 +36,7 @@ Use when:
 
 - Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead).
 - Edit other `.md` files under `.augment/`, `.agent-src.uncompressed/`, or `agents/` with this skill.
-- Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/contexts/` or `docs/contracts/`.
+- Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/settings/contexts/` or `docs/contracts/`.
 - Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio.
 - Reuse the package-root anatomy in the consumer template — caps and target paths differ.
 
@@ -102,7 +114,7 @@ Each answer must fit on one line. The block exists so the root never silently de
 
 ## Procedure — apply Thin-Root to consumer template
 
-Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/contexts/`, ...), not this package's authoring tree.
+Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
 
 ## Gotchas
 

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

@@ -3,6 +3,19 @@ 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
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 <!-- cloud_safe: degrade -->
@@ -350,9 +363,9 @@ Three directories, three modes:
 
 | Mode | Path | Format |
 |---|---|---|
-| **Topic-anchored question** (paired with a roadmap or ADR) | `agents/council-questions/<topic-slug>.md` | Markdown |
-| **Topic-anchored response** (paired with the question above) | `agents/council-responses/<topic-slug>.json` | JSON from `council:run --output` |
-| **Ad-hoc session** (no durable artefact yet) | `agents/council-sessions/<UTC-timestamp>.json` | JSON from `council:run --output` |
+| **Topic-anchored question** (paired with a roadmap or ADR) | `agents/runtime/council/questions/<topic-slug>.md` | Markdown |
+| **Topic-anchored response** (paired with the question above) | `agents/runtime/council/responses/<topic-slug>.json` | JSON from `council:run --output` |
+| **Ad-hoc session** (no durable artefact yet) | `agents/runtime/council/sessions/<UTC-timestamp>.json` | JSON from `council:run --output` |
 
 `<topic-slug>` is kebab-case and **must match** the corresponding
 roadmap / ADR slug if one exists (e.g. `path-fixes` mirrors the
@@ -360,10 +373,11 @@ matching `road-to-<topic-slug>` roadmap under `agents/roadmaps/`).
 
 ### Forbidden
 
-- Files at `agents/` root (e.g. `agents/council-question-foo.md`).
+- Files at `agents/` root (e.g. `agents/runtime/council/question-foo.md`).
 - Dot-prefix scratch (e.g. `agents/.council-question-foo.md`).
 - Any other directory below `agents/` (e.g. `agents/scratch/`,
-  `agents/tmp/`).
+  `agents/evidence/notes/`). Operator scratch belongs under
+  `agents/runtime/tmp/` (gitignored).
 - Cross-references from any artefact to specific council files —
   see [`no-roadmap-references`](../../rules/no-roadmap-references.md)
   (council clause). Inline the convergence summary instead, with
@@ -431,10 +445,10 @@ Input modes (`prompt` / `roadmap` / `diff` / `files`) inherit the
 
 **Source citations:**
 * Template shape — Round 2 council verdict
-  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-1.md`,
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-1.md`,
   Opus's lens-adaptive synthesis proposal).
 * Decision/creative split — Round 4 Q4 verdict
-  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
   R4 reframed `optimize` as creative because perf trade-offs resist
   pre-templated shape — Performance-wins / Trade-offs /
   Implementation-order is too rigid for the variety of optimize-lens
@@ -539,7 +553,7 @@ per-invocation caps from `ai_council.cost_budget`:
   if the callback returns False or is absent, tags the member
   `daily_budget_exceeded` instead of `cost_budget_exceeded`.
 
-Prices come from `agents/.agent-prices.md` (gitignored, refreshed weekly).
+Prices come from `agents/runtime/.agent-prices.md` (gitignored, refreshed weekly).
 The pricing module bootstraps it from `_default_prices.py` on first
 use and flags it stale when older than the most recent Monday 00:00
 UTC.
@@ -610,7 +624,7 @@ member can refine, agree, or push back on the previous critique
 without seeing which provider produced which point.
 
 The default round count comes from `defaults.min_rounds` in
-`agents/.ai-council.yml` (default `2` so members critique each other
+`agents/settings/.ai-council.yml` (default `2` so members critique each other
 at least once before convergence). The host agent does **not** ask
 "how many rounds?" when the requested count is `<= min_rounds` —
 the settings owner already made that decision. Ask only when a
@@ -702,7 +716,7 @@ between every round so the user can stop the spend at any point.
 | Cost gate | After every round the CLI prints `Spent so far: $X · Next round: ~$Y · Cap: $Z`. `n` exits cleanly with partial results; `y` continues. |
 | Hard cap | If the projected next-round cost would breach `max_total_usd`, `run_debate()` raises `DebateCapExceeded` and the CLI exits with the partial transcript. No silent overrun. |
 | `--continue-as-debate` | Seeds round 1 from an existing `/council default` (or analysis lens) session. No round-1 API calls are billed; round 2+ run normally. Member list must match. |
-| Session files | One file per round under `agents/council-sessions/<slug>/debate-round-NN.md`. |
+| Session files | One file per round under `agents/runtime/council/sessions/<slug>/debate-round-NN.md`. |
 | Anonymisation | Identical to `rounds:N`. The continue-as-debate path also anonymises the seeded round-1 responses when building the round-2 prompt. |
 
 Use this when the artefact is genuinely contentious and the user
@@ -719,7 +733,7 @@ blind spots before synthesis. Inspired by Andrej Karpathy's "ask the
 strongest models to review each other anonymously" pattern; see his
 [talks / threads on inter-model critique](https://karpathy.ai/) and the
 internal verdict in
-`agents/council-sessions/2026-05-14-ai-council-redesign/round-2.md`
+`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-2.md`
 (R2 split: one approve-as-flag, one reject-as-default → opt-in only).
 
 Pipeline order when every feature is active:
@@ -732,7 +746,7 @@ Activation — two equivalent paths:
 
 * CLI: `--peer-review` on `council:estimate` or `council:run`.
 * Config: `ai_council.peer_review.enabled: true` in
-  `agents/.ai-council.yml`. Default is `false`.
+  `agents/settings/.ai-council.yml`. Default is `false`.
 
 Mechanics:
 
@@ -776,7 +790,7 @@ swaps.
 | **Outsider** | `openai` | naive-but-sharp questions, beginner's-mind probes |
 | **Executor** | `anthropic` | what ships this quarter, what blocks delivery |
 
-Activation — edit `agents/.ai-council.yml` and flip the advisor's
+Activation — edit `agents/settings/.ai-council.yml` and flip the advisor's
 `enabled: true`. Optional `model: <name>` overrides the bound
 member's default model. An advisor referencing a disabled member
 fails closed at config load — never silently skipped.
@@ -860,7 +874,7 @@ for its own answer.
 ### Session artefact
 
 Every fast-path attempt appends one line to
-`agents/council-sessions/<date>-<slug>/low-impact-resolutions.md`:
+`agents/runtime/council/sessions/<date>-<slug>/low-impact-resolutions.md`:
 
 ```
 2025-05-14T10:00:00Z | resolved | members=2/2 | members(anthropic, openai) cost=$0.0034 | Q=Service vs Repository for this read path?
@@ -874,7 +888,7 @@ headers around canonical lines.
 Re-projection of session log → summary block:
 
 ```
-$ council replay agents/council-sessions/2025-05-14-foo/responses.json --low-impact-stats
+$ council replay agents/runtime/council/sessions/2025-05-14-foo/responses.json --low-impact-stats
 # Low-impact fast-path · session summary
 
 - attempts: 4

package/.agent-src/skills/analysis-autonomous-mode/SKILL.md

@@ -3,6 +3,18 @@ name: analysis-autonomous-mode
 description: "ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work."
 source: package
 domain: discovery
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # analysis-autonomous-mode

package/.agent-src/skills/analysis-skill-router/SKILL.md

@@ -3,6 +3,18 @@ name: analysis-skill-router
 description: "Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'."
 source: package
 domain: discovery
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # analysis-skill-router

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

@@ -6,8 +6,18 @@ personas:
 source: package
 domain: engineering
 recommended_for_user_types: [developer, founder]
-
-
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # api-design
@@ -22,7 +32,7 @@ Do NOT use when:
 
 ## Procedure: Design an API
 
-1. **Gather context** — read `agents/contexts/api-versioning.md`, `agents/docs/api-resources.md`, `agents/docs/query-filter.md`, `agents/docs/controller.md`, and guideline `php/api-design.md`.
+1. **Gather context** — read `agents/settings/contexts/api-versioning.md`, `agents/reference/docs/api-resources.md`, `agents/reference/docs/query-filter.md`, `agents/reference/docs/controller.md`, and guideline `php/api-design.md`.
 2. **Identify the resource** — determine the domain entity, its attributes, and relationships. Check existing models and resources for field naming patterns.
 3. **Define endpoints** — list each endpoint with HTTP method, URL path, request body, query parameters, and response structure. Follow existing route file patterns.
 4. **Decide versioning** — determine whether this extends the current version or requires a new version (see decision table below).

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

@@ -1,186 +1,102 @@
 ---
 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
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # api-endpoint
 
 ## 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

@@ -3,6 +3,18 @@ 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
 domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # api-testing
@@ -151,6 +163,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/architecture-review-lens/SKILL.md

@@ -6,6 +6,18 @@ personas:
   - senior-engineer
 source: package
 domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # architecture-review-lens

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

@@ -3,6 +3,18 @@ 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
 domain: engineering
+workspaces:
+  - engineering
+packs:
+  - laravel
+lifecycle: active
+trust:
+  level: professional
+  confidence: high
+  human_review_required: false
+install:
+  default: false
+  removable: true
 ---
 
 # artisan-commands

package/.agent-src/skills/async-python-patterns/SKILL.md

@@ -6,6 +6,18 @@ domain: engineering
 status: active
 refresh_trigger: "Python ships a new structured-concurrency primitive (post-TaskGroup), OR ≥30% of cited upstream cookbook examples become deprecated, OR the cited libraries (aiohttp, httpx, anyio, trio) cut a major version with breaking async surface changes."
 sunset_criterion: "When `https://docs.python.org/3/library/asyncio.html` ships an in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+workspaces:
+  - engineering
+packs:
+  - python
+lifecycle: active
+trust:
+  level: professional
+  confidence: high
+  human_review_required: false
+install:
+  default: false
+  removable: true
 ---
 
 # async-python-patterns
@@ -144,5 +156,5 @@ A single blocking call (sync I/O, time.sleep, CPU-heavy parse, large JSON load)
   - Async HTTP: https://www.python-httpx.org/async/ · https://docs.aiohttp.org/en/stable/
   - Async DB: https://magicstack.github.io/asyncpg/ · https://aiosqlite.omnilib.dev/
 - Cross-linked: [`error-handling-patterns`](../error-handling-patterns/SKILL.md), [`mcp-builder`](../mcp-builder/SKILL.md), [`api-design`](../api-design/SKILL.md), [`performance`](../performance/SKILL.md).
-- Provenance registry: `agents/contexts/skills-provenance.yml` (entry: `async-python-patterns`).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `async-python-patterns`).
 - Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

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

@@ -7,8 +7,18 @@ personas:
 source: package
 domain: quality
 recommended_for_user_types: [developer, ops]
-
-
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
 ---
 
 # authz-review