@ai-support-agent/cli 0.1.32-beta.1 → 0.1.33-beta.0

package/dist/plugin/skills/api-design/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: api-design
+description: A pattern library for REST API design. Provides guidance on resource naming, choosing HTTP methods and status codes, error response formats, pagination, versioning, idempotency, authentication/authorization, and rate limiting. Use this when designing endpoints for a new API, reviewing the design of an existing API, or when you need decision criteria for a discussion about API conventions.
+---
+
+# REST API Design Patterns
+
+A collection of decision criteria and patterns for designing and implementing REST APIs. Reference this skill when adding new endpoints, revising an existing API, or doing a design review. Implementation examples favor NestJS, Django REST Framework, and Laravel.
+
+This skill covers HTTP interface design — formats and conventions. For server-side implementation details of authorization, rate limiting, and error handling, see the backend-patterns skill.
+
+## 1. Resource Design and Naming
+
+### Basic Principles
+
+- Represent resources as **plural nouns**. Don't use verbs.
+  - Good: `GET /users`, `POST /orders`, `GET /users/123`
+  - Bad: `GET /getUsers`, `POST /createOrder`
+- Use lowercase kebab-case for paths (`/purchase-orders`). For query parameters, pick either snake_case or camelCase and stay consistent within the project.
+- Represent IDs as path segments: `/users/{userId}`
+
+### Nesting Depth
+
+Keep nesting to **at most two levels** (two resources).
+
+```
+GET /users/123/orders                 # Acceptable: a user's orders
+GET /users/123/orders/456/items/789   # Avoid: too deep
+GET /order-items/789                  # Preferred: reference directly if the ID is unique
+```
+
+If a child resource can be uniquely identified without its parent, promote it to a top-level resource. Reserve nesting for expressing "belongs-to" relationships and narrowing list results.
+
+### Expressing Relationships
+
+- Express a relationship lookup either as a sub-resource (`/users/123/orders`) or as a filter (`/orders?user_id=123`). If you offer both, make sure their behavior matches.
+- Express many-to-many association/disassociation as POST/DELETE on a sub-resource.
+
+```
+POST   /articles/10/tags        # body: {"tag_id": 5} to attach a tag
+DELETE /articles/10/tags/5      # remove a tag
+```
+
+- Keep embedded related data in responses to the bare minimum (roughly an ID and a display name), or only expand it when explicitly requested (e.g. via `?include=`). Embedding deep relations unconditionally is a common source of N+1 queries and bloated payloads.
+
+## 2. HTTP Methods and Status Codes
+
+### Choosing a Method
+
+| Method | Purpose | Idempotent |
+|---|---|---|
+| GET | Retrieval. Must not have side effects | Yes |
+| POST | Create, or execute a non-idempotent action | No |
+| PUT | Replace the entire resource | Yes |
+| PATCH | Partial update | Not guaranteed (depends on design) |
+| DELETE | Delete | Yes |
+
+### When to Use Each Status Code
+
+- **200 OK**: Successful retrieval or update. Response body present.
+- **201 Created**: Successful creation. It's good practice to return the new resource's URL in the `Location` header.
+- **204 No Content**: Success with no body. The standard response for a successful DELETE.
+- **400 Bad Request**: The request is malformed syntactically (broken JSON, missing required parameters, etc.).
+- **401 Unauthorized**: Not authenticated. Token missing, invalid, or expired.
+- **403 Forbidden**: Authenticated, but not authorized for this action.
+- **404 Not Found**: The resource doesn't exist.
+- **409 Conflict**: A state conflict — unique constraint violation, optimistic lock failure, an operation that's already been processed, etc.
+- **422 Unprocessable Entity**: Well-formed but semantically invalid (validation error). Decide once, per project, how you split this from 400.
+- **500 Internal Server Error**: An unexpected server-side error. Log the details; never return them to the client.
+
+### Choosing Between 404 and 403
+
+Return 404 when you don't want an unauthorized user to even know the resource exists (e.g. another tenant's data, an unpublished draft). Return 403 when the resource's existence is public knowledge and only the action is forbidden (e.g. no edit permission on a published article). The deciding question is: "would revealing existence itself be a data leak?" In multi-tenant APIs, default to 404.
+
+## 3. Error Responses
+
+### Use One Consistent Shape
+
+Return the same error structure from every endpoint. At minimum, include a code, a message, and details.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "There were errors in your input.",
+    "details": [
+      { "field": "email", "code": "invalid_format", "message": "Email address format is invalid." },
+      { "field": "age", "code": "out_of_range", "message": "Must be between 0 and 150." }
+    ]
+  }
+}
+```
+
+- `code` should be a machine-readable constant string. Clients should branch on the code, not on the message text.
+- Return validation errors **per field** in a `details` array, so forms can display errors next to each field.
+- Aligning with RFC 9457 (Problem Details, `application/problem+json`) is also a solid choice. Either way, standardize on one shape.
+
+### Don't Leak Internal Information
+
+- Never include stack traces, raw SQL, file paths, or a library's raw exception message in a response.
+- For 5xx errors, return only a generic message and a correlation ID (request ID); log the details server-side.
+- On authentication failure, don't distinguish between "user doesn't exist" and "wrong password" in the response.
+
+### Implementation Example (NestJS)
+
+```typescript
+// An exception filter that converts all errors into the common shape
+@Catch()
+export class AppExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const res = host.switchToHttp().getResponse();
+    if (exception instanceof HttpException) {
+      res.status(exception.getStatus()).json({ error: this.toErrorBody(exception) });
+      return;
+    }
+    // Unexpected exception: log the details, return a generic message to the client
+    this.logger.error(exception);
+    res.status(500).json({
+      error: { code: 'INTERNAL_ERROR', message: 'An internal server error occurred.' },
+    });
+  }
+}
+```
+
+In Django REST Framework, point the `EXCEPTION_HANDLER` setting at a custom handler that repacks `ValidationError.detail` into the common shape. In Laravel, customize `render` via `withExceptions` in `bootstrap/app.php` (or the exception Handler).
+
+## 4. Pagination
+
+### Choosing a Strategy
+
+- **Offset-based** (`?page=2&per_page=20` / `?offset=20&limit=20`)
+  - Well suited to page-number UIs. Simple to implement.
+  - Downsides: gets slow at large offsets. Inserts/deletes mid-list cause duplicates or gaps.
+- **Cursor-based** (`?cursor=eyJpZCI6MTIzfQ&limit=20`)
+  - Well suited to infinite scroll, frequently-updated lists, and large datasets.
+  - The cursor encodes an opaque key that uniquely identifies the last row returned (e.g. `created_at` + `id`).
+
+Decision rule: if you need a total-count display and arbitrary page jumps, use offset-based. If the dataset is large, updated frequently, or performance-sensitive, use cursor-based.
+
+### Enforce a Limit Ceiling
+
+The server must **always enforce an upper bound** on `limit`/`per_page` (e.g. default 20, max 100). Never use the client-supplied value as-is.
+
+```python
+# Django REST Framework
+class StandardPagination(PageNumberPagination):
+    page_size = 20
+    page_size_query_param = "per_page"
+    max_page_size = 100  # requests above this are clamped to 100
+```
+
+Include metadata in the response: for offset-based, `total` / `page` / `per_page`; for cursor-based, `next_cursor` (null when there's no next page).
+
+## 5. Filtering, Sorting, and Search
+
+- Express filters as query parameters: `GET /orders?status=shipped&user_id=123`
+- Standardize a suffix convention for range conditions and stick to it: `?created_at_gte=2026-01-01&created_at_lt=2026-02-01` (or a `?created_at[gte]=...` style — pick one).
+- For sorting, a comma-separated list with a `-` prefix for descending order is concise: `?sort=-created_at,name`.
+- Route full-text/fuzzy search through `?q=keyword`, kept separate from structured filters.
+- Enforce an **allowlist**. The server must explicitly enumerate which fields are filterable/sortable, and must never accept an arbitrary column name (this prevents SQL injection and unintended index scans).
+
+```php
+// Laravel: restrict sortable fields with an allowlist
+$sortable = ['created_at', 'name', 'price'];
+$sort = $request->query('sort', '-created_at');
+$direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
+$column = ltrim($sort, '-');
+abort_unless(in_array($column, $sortable, true), 400);
+$query->orderBy($column, $direction);
+```
+
+## 6. Versioning
+
+### Policy
+
+**Prefer URL-path versioning (`/v1/users`).** It's explicit, and it's easy to work with in routing, logging, caching, and documentation alike.
+
+Options and decision criteria:
+
+| Approach | Example | Characteristics |
+|---|---|---|
+| URL path | `/v1/users` | Most explicit. Recommended. Easy to inspect via browser or curl |
+| Header | `Accept: application/vnd.api.v1+json` | Keeps the URL clean, but harder to debug and more costly to adopt |
+| Query param | `/users?version=1` | Tends to complicate cache keys. Not recommended |
+
+### Operating Rules
+
+- Version only the major number (`v1`, `v2`). Don't bump the version for backward-compatible changes (added fields, new endpoints).
+- Only cut a new version for breaking changes (removed fields, type changes, making a field required, changed behavior).
+- Announce a deprecation date for old versions and signal it via `Deprecation` / `Sunset` headers.
+- For internal-only APIs, it's reasonable to skip versioning and deploy the client and server together. For public APIs, versioning is mandatory.
+
+## 7. Idempotency
+
+- Implement **GET, PUT, and DELETE as idempotent**: sending the same request multiple times must leave the resource in the same state.
+  - A second DELETE may return 404 (the state — "doesn't exist" — is unchanged). If you'd rather keep the client logic simple, returning 204 again on the second call is also acceptable.
+- **POST is not idempotent**. You need a defense against duplicate execution from network failures or retries (double charges, duplicate orders).
+
+### Idempotency Keys
+
+The client sends a unique-per-request key (a UUID) in an `Idempotency-Key` header, and the server stores the key alongside the processing result for some retention window. On a retry with the same key, **return the stored response as-is**.
+
+```typescript
+// NestJS: sketch of duplicate-POST protection via an idempotency key
+@Post('payments')
+async create(@Headers('idempotency-key') key: string, @Body() dto: CreatePaymentDto) {
+  if (!key) throw new BadRequestException('Idempotency-Key header is required');
+  const cached = await this.idempotencyStore.find(key);
+  if (cached) return cached.response;           // Retry: return the stored result
+  const result = await this.payments.create(dto);
+  await this.idempotencyStore.save(key, result, { ttl: '24h' });
+  return result;
+}
+```
+
+- Store the key under a unique constraint, and prevent concurrent-execution races with a transaction or lock.
+- This is mandatory for any POST where duplicate execution causes real harm — payments, orders, notification sends.
+
+## 8. Authentication and Authorization
+
+### Token Authentication Basics
+
+- Send tokens via the `Authorization: Bearer <token>` header. Never put a token in a query parameter (it leaks into logs and referrers).
+- Keep access tokens short-lived (minutes to an hour) and refresh them with a refresh token.
+- 401 means "authentication failed"; 403 means "authenticated, but not authorized." Don't conflate them.
+
+### Per-Resource Authorization Checks
+
+Keep authentication (who you are) separate from authorization (what you can do), and **always check ownership/permission against the specific resource being accessed**. Letting a request through on authentication alone, with direct object access by ID, is the textbook API vulnerability (IDOR / BOLA).
+
+- Filter list endpoints at the query level. Filtering after fetching breaks pagination and result counts.
+- When denying access to a single resource because the caller lacks permission, return 404 if you want to hide its existence (see section 2).
+- For the authorization implementation mechanics and code examples (NestJS Guards, Laravel Policies, DRF `permission_classes`, etc.), see backend-patterns.
+
+## 9. Rate Limiting
+
+- Limit request counts per user (or token, or IP). Apply stricter limits to unauthenticated endpoints.
+- On exceeding the limit, return **429 Too Many Requests** with a `Retry-After` header telling the client how many seconds until it can retry.
+- Report the current limit state in every response's headers.
+
+```
+RateLimit-Limit: 100
+RateLimit-Remaining: 42
+RateLimit-Reset: 1718100000
+Retry-After: 30          # only present on 429
+```
+
+(The `X-RateLimit-*` header family is also widely used. Pick one convention per project.)
+
+- Apply a separate, stricter limit to authentication-related endpoints (login, password reset) than to the rest of the API.
+- For implementation mechanics (each framework's throttling middleware, etc.), see backend-patterns.
+
+## 10. Design Review Checklist
+
+- [ ] Are paths plural nouns, with nesting no deeper than two levels?
+- [ ] Does each endpoint's method and status codes (including 201/204/409/422) match its actual semantics?
+- [ ] Do all endpoints return errors in the same shape? Are validation errors broken out per field?
+- [ ] Do errors avoid leaking internal information (stack traces, SQL, file paths)?
+- [ ] Does every list endpoint paginate, with the limit enforced server-side?
+- [ ] Are filterable/sortable fields restricted to an allowlist?
+- [ ] Is the versioning policy defined, including how breaking changes are handled?
+- [ ] Do POSTs where duplicate execution causes real harm have idempotency-key protection?
+- [ ] Is there object-level authorization on every resource (IDOR protection)? Is the 403/404 policy consistent?
+- [ ] Is rate limiting configured, with 429 and RateLimit headers reported?
+
+## Related
+
+- Use the `/code-review` command for post-implementation code review.
+- Delegate detailed API implementation review criteria (security, performance, convention compliance) to code-reviewer subagents.

package/dist/plugin/skills/backend-patterns/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: backend-patterns
+description: A collection of backend design and implementation patterns covering layering, input validation, N+1 queries and transactions, caching, error handling, authentication/authorization, rate limiting, structured logging, and background jobs, for NestJS / Django / Flask / Laravel / CakePHP. Use this when designing, implementing, or reviewing backend APIs, service layers, or jobs.
+---
+
+# backend-patterns: Backend Design & Implementation Patterns
+
+Target stacks: NestJS / Django / Flask / Laravel / CakePHP.
+Code examples favor NestJS, Django, and Laravel; Flask and CakePHP equivalents are noted alongside them.
+For interface conventions such as URL design and status codes, see the api-design skill.
+
+## Layering
+
+- Keep controllers (handlers) thin. Their only responsibilities are: accepting and transforming input, calling the service layer, and shaping the response.
+- Put business logic in the service layer. Conditional branching, calculations, and cross-resource consistency all belong here.
+- Keep data access isolated in a repository/ORM layer. Don't leak raw SQL or query-builder details into the service layer.
+- Structuring things so the same logic can be called from both a controller and a job (CLI or queue worker) is a good self-check for whether your layering is actually sound.
+
+```typescript
+// NestJS
+// Bad: business logic and data access live directly in the controller
+@Post()
+async create(@Body() body: any) {
+  const user = await this.userRepo.findOne({ where: { email: body.email } });
+  if (user) throw new BadRequestException('exists');
+  if (body.plan === 'pro' && !body.cardToken) throw new BadRequestException();
+  return this.userRepo.save({ ...body });
+}
+
+// Good: the controller only passes through; decisions live in the service layer
+@Post()
+async create(@Body() dto: CreateUserDto) {
+  return this.usersService.register(dto);
+}
+```
+
+In Django, keep views thin and push logic into a service module (e.g. `services.py`) or model methods. In Laravel, delegate from controllers to service/action classes, and push complex Eloquent queries into query scopes or repositories. In CakePHP, preserve the Controller → Table (model layer) separation.
+
+## Input Validation
+
+Use the framework's built-in validation mechanism. Hand-rolled chains of `if` statements are easy to miss cases with and hard to review.
+
+- NestJS: DTOs + class-validator + `ValidationPipe` (always enable `whitelist: true`)
+- Django: Forms / DRF Serializers
+- Flask: schema validation libraries such as marshmallow or pydantic
+- Laravel: FormRequest
+- CakePHP: Validator (the Table's `validationDefault`)
+
+```typescript
+// NestJS
+// Good: declare types and constraints via a DTO, and strip unknown fields with whitelist
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @Length(8, 72)
+  password: string;
+}
+// main.ts: app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+```
+
+```python
+# Django REST Framework
+# Bad: passing request.data straight into the model (mass assignment)
+User.objects.create(**request.data)
+
+# Good: use a serializer to explicitly declare which fields are accepted
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ["email", "password"]  # avoid fields = "__all__"
+```
+
+```php
+// Laravel
+// Bad: mass-assigning $request->all() (is_admin etc. could be overwritten)
+User::create($request->all());
+
+// Good: use only FormRequest's validated() data, and keep $fillable minimal
+public function store(StoreUserRequest $request)
+{
+    return User::create($request->validated());
+}
+```
+
+The principle behind mass-assignment protection is the same everywhere: explicitly whitelist which fields may be accepted. Attributes tied to permissions or ownership — `is_admin`, `role`, `tenant_id`, and the like — should be set from server-side context (the authenticated identity), never from the request body.
+
+## Database
+
+### Detecting N+1 Queries and Batching Fetches
+
+Always be suspicious of queries issued inside a loop. During development, check actual query counts with a query log (Django Debug Toolbar, Laravel Telescope / `DB::listen`, TypeORM's `logging: true`).
+
+```python
+# Django
+# Bad: fetches the author one row at a time per article (1 + N queries)
+for article in Article.objects.all():
+    print(article.author.name)
+
+# Good: preload via JOIN / batch fetch
+for article in Article.objects.select_related("author"):
+    print(article.author.name)
+# Use prefetch_related for many-to-many and reverse relations
+```
+
+```php
+// Laravel
+// Bad: accessing $article->author inside a loop triggers N lazy-load queries
+$articles = Article::all();
+
+// Good: eager loading fetches everything up front
+$articles = Article::with('author')->get();
+```
+
+In NestJS + TypeORM, achieve the same with `relations` or `leftJoinAndSelect` on the QueryBuilder. With Prisma, use `include`.
+
+### Transaction Boundaries
+
+Identify the unit of work that must be "all succeed or all fail," and wrap exactly that unit in a transaction.
+
+- Open transactions in the service layer. Opening them in a controller or in an individual repository call leaves the boundary ambiguous.
+- Never put external API calls, email sending, or other long-running operations inside a transaction. Doing so extends how long locks are held, and if the external call fails and you roll back the DB, the external side effect can't be undone. Perform external effects after commit, or hand them off to a job queue.
+
+```python
+# Django
+# Good: confirming an order and decrementing stock happen in one transaction
+from django.db import transaction
+
+def confirm_order(order_id: int) -> None:
+    with transaction.atomic():
+        order = Order.objects.select_for_update().get(pk=order_id)
+        order.confirm()
+        order.save()
+        Stock.objects.filter(product=order.product).update(
+            quantity=F("quantity") - order.quantity
+        )
+    # Good: send the email only after commit
+    transaction.on_commit(lambda: send_order_mail.delay(order_id))
+```
+
+Laravel uses `DB::transaction(fn () => ...)`; NestJS + TypeORM uses `dataSource.transaction()` or a QueryRunner. In systems built around command/event sourcing with separate write and read models, a single command is typically the unit of consistency — don't try to force consistency across multiple aggregates into one transaction; instead, design the cross-aggregate effects as eventually-consistent follow-up processing.
+
+## Caching
+
+The default pattern is cache-aside: check the cache on read, and on a miss, fetch from the database and populate the cache.
+
+```typescript
+// NestJS (cache-aside skeleton)
+async getProduct(id: string): Promise<Product> {
+  const cached = await this.cache.get<Product>(`product:${id}`);
+  if (cached) return cached;
+  const product = await this.productRepo.findOneByOrFail({ id });
+  await this.cache.set(`product:${id}`, product, 300); // always set a TTL
+  return product;
+}
+```
+
+- Design assuming invalidation is hard. Combine explicit deletion on update with a TTL as a second line of defense, and decide per data type how much staleness is acceptable until the TTL expires. Standardize keys as `resource-name:id` so you can always identify what to invalidate.
+- Safe to cache: master/reference data, public content, expensive aggregate results — anything that looks the same to everyone and can tolerate some staleness.
+- Do not cache (or be extremely careful with): authorization decisions, entire responses containing personal information, or values that demand strict accuracy such as balances or inventory counts. Storing user-specific data under a key that doesn't include the user ID is a classic way to leak one user's data to another — avoid it absolutely.
+
+## Error Handling
+
+### Centralized Handlers
+
+Don't scatter exception handling throughout the codebase; consolidate it in the framework's centralized mechanism.
+
+- NestJS: Exception Filter (`@Catch()`)
+- Django: middleware / DRF's `EXCEPTION_HANDLER`
+- Flask: `@app.errorhandler`
+- Laravel: exception handling configuration in `bootstrap/app.php` (formerly the Handler class)
+- CakePHP: ErrorController / a custom ExceptionRenderer
+
+A centralized handler has three jobs: logging (including the stack trace), producing a safe, well-formed response for the client, and mapping errors to status codes.
+
+### Preventing Internal Information Leaks
+
+Never include stack traces, SQL, file paths, or environment variables in production error responses. Always verify `DEBUG=False` (Django) and `APP_DEBUG=false` (Laravel) in production. Return only an error code and a correlation ID (request ID) to the client; keep the details in server-side logs.
+
+```typescript
+// NestJS
+// Bad: returns the raw exception message (leaks internal details)
+catch (e) { throw new InternalServerErrorException(e.message); }
+
+// Good: log the details, return only a fixed code and correlation ID to the client
+catch (e) {
+  this.logger.error({ requestId, err: e }, 'order confirmation failed');
+  throw new InternalServerErrorException({ code: 'INTERNAL_ERROR', requestId });
+}
+```
+
+### Retries with Exponential Backoff (External API Calls)
+
+Transient external API failures (timeouts, 429s, 5xx) are worth retrying. 4xx errors (validation failures, etc.) won't succeed on retry, so fail fast instead.
+
+```python
+# Python (conceptual skeleton — in practice, use a library like tenacity)
+# Good: exponential backoff + jitter, with a cap on retry attempts
+import random, time
+
+def call_with_retry(func, max_attempts=4, base=0.5):
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return func()
+        except TransientError:
+            if attempt == max_attempts:
+                raise
+            time.sleep(base * (2 ** (attempt - 1)) + random.uniform(0, 0.1))
+```
+
+Anything you retry must be idempotent. Don't casually retry a non-idempotent POST — only do so if you can attach an idempotency key. Use the silent-failure-hunter subagent to check for swallowed exceptions (`except: pass`, empty `catch` blocks).
+
+## Authentication & Authorization
+
+- Always enforce authorization server-side. Hiding a button or a screen on the frontend is a UX affordance, not a security control — design as if the API can be hit directly.
+- Separate authentication (who you are) from authorization (what you're allowed to do). Even after authentication succeeds, check permission on the target resource for every request.
+- Use each framework's declarative mechanism for role-based authorization: NestJS uses Guards + custom decorators, Django uses `permission_classes` / `@permission_required`, Laravel uses Policies/Gates, Flask uses decorators, CakePHP uses the Authorization plugin.
+- Guard against IDOR (Insecure Direct Object Reference — being able to view another user's resource just by guessing its ID) by including "does the logged-in user own this" as part of the query condition, not as an afterthought check.
+
+```php
+// Laravel
+// Bad: fetching by ID alone (exposes other users' orders)
+$order = Order::findOrFail($id);
+
+// Good: scope the query to the owner, then authorize via a Policy
+$order = $request->user()->orders()->findOrFail($id);
+$this->authorize('view', $order);
+```
+
+```typescript
+// NestJS
+// Good: declare the required role via a decorator and enforce it centrally with a Guard
+@Roles('admin')
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Delete(':id')
+remove(@Param('id') id: string) { ... }
+```
+
+In multi-tenant setups, never accept the tenant ID from the request body — derive it from the authenticated identity and enforce it on every query.
+
+## Rate Limiting
+
+Apply rate limiting to publicly exposed endpoints (login, sign-up, password reset, search, public APIs). This defends against both brute-force attacks and general overload.
+
+- NestJS: `@nestjs/throttler`
+- Django: DRF throttling (`AnonRateThrottle` / `ScopedRateThrottle`), django-ratelimit
+- Flask: Flask-Limiter
+- Laravel: the `throttle` middleware (RateLimiter)
+- CakePHP: a rate-limiting plugin used as middleware
+- Serverless setups: also apply throttling at the API Gateway / WAF layer
+
+In multi-instance deployments, the rate-limit counter must live in a shared store such as Redis — otherwise per-instance counters make the limit effectively meaningless.
+
+## Structured Logging
+
+- Emit logs in a structured format (e.g. JSON) rather than embedding values into message strings, so they're searchable and aggregable as fields.
+- Attach a request ID (correlation ID) to every log line so you can trace one request's full processing path. In NestJS, use AsyncLocalStorage (e.g. nestjs-cls); in Django/Flask, attach it via middleware.
+- For the full house rules on log levels, debug-mode conventions (recording function entry/exit and inputs/outputs), and X-Ray/Sentry integration, consult your repository's own logging conventions/rules document.
+- Include identifying fields (userId, orderId, etc.) as structured fields. Never log personal data or credentials — passwords, tokens, card numbers — under any circumstances.
+
+```typescript
+// NestJS (structured logger such as pino)
+// Bad: no context, not searchable, doesn't say what failed
+this.logger.log('failed');
+
+// Good: correlation ID and target ID as structured fields
+this.logger.warn(
+  { requestId, orderId, reason: 'stock_shortage' },
+  'order confirmation rejected',
+);
+```
+
+How to choose a log level:
+
+- `error`: a failure that needs a human to respond. Should trigger alerts.
+- `warn`: something abnormal but self-recovered, or an expected-in-business failure (succeeded after retry, frequent validation rejections, etc.).
+- `info`: business-event milestones (order confirmed, job completed).
+- `debug`: development-time detail. Disabled by default in production.
+
+Avoid letting your level scheme collapse — e.g. logging normal operation at `error`, or swallowing an exception while logging it at `info`.
+
+## Background Jobs
+
+- Use a durable queue backend: BullMQ (Redis), Celery (Redis / RabbitMQ), Laravel Queue (Redis / SQS / database), SQS, and similar. In-process queues — an in-memory array, chained `setTimeout` calls, or Laravel's `sync` driver in production — are not acceptable; jobs vanish on process restart or deploy.
+- Design jobs to be idempotent. Queues generally guarantee at-least-once delivery, so the same job may run twice — make sure that doesn't corrupt results. Absorb duplicate execution with a "already processed" flag, a uniqueness constraint, or an idempotency key.
+
+```python
+# Celery
+# Bad: running this twice double-charges the customer
+@shared_task
+def charge(order_id):
+    api.charge(amount=get_order(order_id).total)
+
+# Good: a processed-check plus an idempotency key make double execution harmless
+@shared_task(bind=True, max_retries=5)
+def charge(self, order_id):
+    order = get_order(order_id)
+    if order.charged:
+        return
+    api.charge(amount=order.total, idempotency_key=f"charge-{order_id}")
+    order.mark_charged()
+```
+
+- Always design for the failure path: cap the retry count, use exponential backoff, and on exhausting retries, route the job to a dead-letter queue (DLQ) or a failure table (Laravel's `failed_jobs`) with a notification. Never let a failure disappear silently.
+- Pass an ID into the job, not the full entity, and re-fetch the latest state at execution time — this avoids acting on stale data that sat in the queue for a while.
+
+## Related Commands & Subagents
+
+- During the design phase, use `/plan` to nail down the implementation approach before starting.
+- After implementation, request review from `/code-review` and code-reviewer subagents.
+- Use the silent-failure-hunter subagent to check for swallowed exceptions and silently discarded errors.