AI Agent Workflow Collection

Use when creating, updating, reviewing, or deciding whether to write a project skill (docs/skills/.md) — covers the file template, verb-led naming, the quality bar, the pre-write 5-weakness self-check, and when NOT to write a skill. Pairs with the always-on "scan docs/skills before a task / create-or-update after" rule in CLAUDE.md.

Use when adding background jobs (Bull queues) or a Redis cache to a backend service — multi-queue architecture, enqueue/process, dynamic delayed jobs, job idempotency via a DB lock, graceful shutdown, and Redis caching (read-through wrap, key conventions, event-driven + prefix-SCAN invalidation). NestJS/TypeORM reference, framework-flexible. Complements (not replaces) the SQS cross-service events pattern.

Use when writing a Dockerfile or a CI/CD pipeline for a backend service — a multi-stage build (heavy builder → slim runtime), base images pulled through a dependency proxy / private registry, authenticating to private package registries during build and SCRUBBING those creds before the final stage, lockfile-first layer caching, purpose-specific images (app / DB-migration job / test), and a CI pipeline (install → lint → test → build → push → migrate → deploy) kept thin per repo by including one shared org template, with per-branch→environment deploy rules and secrets from CI variables (never baked in). Docker + GitLab CI reference, framework-flexible.

Use when designing how a backend service (or a fleet of services) reports errors — a typed exception hierarchy (one base + per-status subclasses carrying statusCode/message/data), a validation-error flattener wired into the global ValidationPipe, a global exception filter that maps every throw to ONE uniform response body (+ trace id, severity-based logging, hide internals on 5xx), an RPC/microservice filter twin, and a log-and-swallow decorator for fire-and-forget handlers. NestJS reference, framework-flexible.

Use when importing/exporting CSV, downloading files (single or zipped), viewing/parsing PDFs, or uploading files in a frontend app — one central file-util module covering CSV (papaparse), download (file-saver/jszip), PDF (pdf.js), and upload with magic-number MIME detection + presigned URL + image resize. React/TS reference, framework-flexible.

Use when building a bulk CSV/spreadsheet import endpoint — streaming parse, per-row validation with a row-numbered error report, data normalization (Excel quotes, multi-format dates), atomic chunked upsert in a transaction, partial-success response, and fan-out to workers for large files. NestJS/TypeORM reference, framework-flexible.

Use when integrating a third-party/external system — calling a vendor API (anti-corruption adapter behind your own interface, resilient HTTP with circuit breaker + retry/backoff, outbound HMAC request signing, idempotency keys), receiving inbound webhooks (raw-body capture, signature verification, idempotent fast-ack-then-enqueue, vendor→internal event mapping), or exposing a partner/public API edge (client-credentials + token introspection + scopes, API-key role guard, client→tenant mapping). NestJS/TS reference, framework-flexible. For service-to-service calls inside your own platform, see integrate-internal-services.

Use when adding third-party login or identity verification to a backend — social login (Sign in with Google / Apple / Facebook) and national digital identity / KYC (e.g. Singpass) via the OIDC relying-party flow (authorization code + PKCE + state/nonce → token exchange), validating the resulting token (.well-known → JWKS signature + iss/aud/exp, or introspection), centralizing many IdPs behind one identity broker (e.g. Keycloak), mapping an external identity to your user by (provider, subject), and treating verified attributes as KYC-grade. Framework-flexible. The frontend login UI is in secure-a-frontend-app.

Use when one backend service calls or consumes from another inside the same platform — synchronous RPC (a uniform request/response envelope + server-side message handlers), SNS→SQS event fan-out (one topic → many subscriber queues), async-consumer robustness (ack vs DLQ + lifecycle hooks), cross-service reads (batch + cache, no network N+1), identity/context propagation across hops, and the worker/consumer service shape (no HTTP, graceful drain). NestJS/TS reference, framework-flexible. Complements write-service-code §6 (single producer→consumer events) and §9 (client-proxy lifecycle).

Use when a service OOMs / its tasks restart after a PR that added a dependency, when memory-tight replicas (small containers — e.g. 512MB/1GB) die under load or on deploy, or whenever the proposed fix for memory pressure is "just give it more RAM". Also use proactively when ADDING a heavy or optional library (cloud/vendor SDK, PDF/image/ML/crypto lib) to a long-running service. The discipline: keep per-process RSS lean by lazy-loading cold-path dependencies, and treat a memory regression as a code smell to hunt — not a reason to upsize the host. Covers the reservation-vs-actual-RSS + deploy-2x-surge mechanism that turns a small boot-memory regression into a full OOM outage. Principle-first; Node/ESM examples, ports to any language/orchestrator.

Use before ANY change to a deployed container service behind a load balancer (AWS ECS/Fargate, or equivalent) — changing an env var / task-def, scaling, deploying, terminating an instance — AND when such a service is down (502/503, deploy stuck below desired, tasks failing the LB health check) or a scheduled/cron worker isn't running. A verify-before-mutate discipline + an observe→diagnose→recover playbook. Principle-first; AWS ECS commands shown, but the failure modes apply to any orchestrated container service.

Use BEFORE committing to a public/shared repo, pushing, publishing a package, or syncing/exporting code, config, docs, or skills to an open-source or external destination — to avoid leaking secrets, PII, or internal identifiers. Also the remediation playbook if something already leaked (untrack → rewrite history → force-push → forks/cache → support → rotate). Prevention >> remediation: you can't fully un-publish.

Use when sending a templated transactional email (or generating a templated PDF/document) — rendering from a named template + data through one shared render service, with per-locale template files, CSS inlining, returning subject/html/text, then dispatching via the notification facade (not inline). Covers reusing the same render for HTML→PDF. NestJS/TS reference, framework-flexible.

Use when a change must take effect LATER (a future-dated plan/tier/price change, a scheduled deactivation, an end-of-cycle update) or must be visible / cancellable / auditable before it applies — model it as a pending-changes table (the change payload + an effective date + a status), swept by a scheduled job that applies DUE rows in a transaction, snapshots prior state to a history table, and marks them done. Covers when to use this vs a Redis delayed job. NestJS/TypeORM reference, framework-flexible.

Use when wiring auth/session, protecting routes, or handling secrets in a frontend app — OIDC login via NextAuth + server session store + access-token refresh & injection, route guards + permission-matrix RBAC, SSR cookie propagation + hydration, and vault secrets + public/private config split. React/Next.js reference, framework-flexible.

Send a Slack message to a channel or DM using the local send.js script. Use whenever the user asks to send or notify team via Slack.

Use when pushing realtime updates to connected clients over WebSockets (a socket.io / WS gateway) — authenticating the socket at the handshake (once, not per message), joining sockets to rooms for targeted broadcast, scaling across instances with a Redis pub/sub adapter (+ sticky sessions), bridging domain events to room emits, and connection-lifecycle hygiene (reconnect, listener cleanup). NestJS/socket.io reference, framework-flexible.

Use when scaffolding a backend service, adding a feature/module, or reviewing folder layout, file/class naming, DTO & entity structure, or the CQRS read/write split. Language-agnostic with TS/NestJS examples.

Use when scaffolding a frontend app, adding a feature or page, or reviewing FE folder layout — thin routing → feature modules, the feature-module pattern (Component + .actions hooks + .hook + styles + barrel), shared-vs-feature code, naming, path aliases, request/response models. React/Next.js reference, framework-flexible.

Use when organizing a shared backend infrastructure library that many services depend on (e.g. @org/infra-) — how to split it into focused packages by dependency weight, expose one barrel per package, avoid dependency cycles with peer deps, version/publish it, decide what belongs in the lib vs a service, and the canonical primitives it should provide (a base entity with soft-delete + audit columns, base pagination/response DTOs, column transformers, type helpers). NestJS/TypeORM reference, framework-flexible. The backend twin of structure-a-shared-ui-lib.

Use when building or organizing an internal shared UI / design-system library that multiple apps depend on — src layout, folder-per-component with version coexistence, the createStore/query/Utils wrappers it re-exports, versioned generated design tokens, subpath build & exports, Storybook + visual regression. React/TS reference, framework-flexible.

Drive a feature/bugfix test-first when the project mandates HTTP-layer-only testing — the failing RED test must be an HTTP/route-harness test (e.g. supertest), never a service/validator/util unit test. Trigger phrases — "làm theo TDD", "viết test fail trước", "write the failing test first", "do this test-first" — in any repo whose rules forbid unit tests.

Use when gating a code path behind a feature flag or rolling something out gradually — evaluating a flag from a central flag service (scoped by service + flag name + user/session + targeting properties), failing safe (unknown/error/timeout = off), caching the lookup, and choosing a flag over a NODEENV/env branch. Covers flag lifecycle (name, owner, removal) and its tie to safe releases. NestJS/TS reference, framework-flexible.

Use when writing a reusable request-pipeline primitive rather than feature logic — a custom decorator (param/metadata/method-wrapper + applyDecorators bundles), a guard (metadata-driven role/scope, or an OR-composition "any of these guards" guard), a pipe (polymorphic/variant DTO validation, or wrapping a built-in pipe to throw your typed error), an interceptor (metadata-driven audit/logging that fires after the response), middleware (correlation id), or a custom validation constraint (sync or async-with-DI via class-validator). NestJS reference, framework-flexible.