1. Read

   references/stack.md

   first to understand the project's NestJS version, ORM, and locked decisions.
2. Then load only the references needed for the actual task.
3. One module per domain — controllers, services, DTOs, and entities live together in their module directory.
4. Controllers are thin — validate (DTO + pipe), delegate (service), return. No business logic.
5. All input validated via DTOs — class-validator decorators on every DTO,

   ValidationPipe

   globally.
6. Dependency injection everywhere — never

   new Service()

   . Inject via constructor, provide via module.
7. No circular dependencies — use

   forwardRef()

   only as a last resort, prefer restructuring.
8. Keep the heavy NestJS guidance in

   references/

   , not inline here. </EXTREMELY-IMPORTANT>

nestjs

Inputs

• $request

  : The NestJS module, endpoint, subsystem, or feature being worked on

Goal

Step 0: Read the stack contract

• references/stack.md

Step 1: Load only the relevant references

references/stack.md

references/project-structure.md

references/modules.md

references/controllers.md

references/providers.md

references/validation.md

references/typeorm.md

references/prisma.md

references/auth.md

references/interceptors.md

references/pipes.md

references/error-handling.md

references/queues.md

references/websockets.md

references/microservices.md

references/openapi.md

references/testing.md

references/config.md

references/middleware.md

references/logging.md

references/health.md

references/cqrs.md

references/scheduling.md

references/docker.md

Step 2: Implement with the core NestJS guardrails

• every module declares its controllers, providers, imports, and exports explicitly
• controllers validate via DTOs +

  ValidationPipe

  , delegate to services, return typed responses
• services contain business logic, injected via constructor — never instantiated with

  new

• entities/models are separate from DTOs — never return a raw entity from a controller
• guards handle auth/authz, interceptors handle cross-cutting concerns, pipes handle transformation
• all external input has a DTO with class-validator decorators
• database mutations wrapped in transactions where atomicity matters
• use

  @nestjs/config

  with Zod or Joi validation for env vars

Step 3: Verify the affected surface

• unit tests (

  jest --testPathPattern=<module>

  )
• e2e tests (

  jest --config test/jest-e2e.json

  )
• type checking (

  tsc --noEmit

  )
• linting (

  eslint .

  )
• OpenAPI spec regeneration if decorators changed

Guardrails

• Do not inline the whole NestJS handbook in

  SKILL.md

  .
• Do not skip

  references/stack.md

  .
• Do not put business logic in controllers — delegate to services.
• Do not return raw entities — use DTOs or serialization interceptors.
• Do not bypass dependency injection — never

  new Service()

  .
• Do not create circular module dependencies without exhausting alternatives first.
• Do not use

  @nestjs/common

  barrel imports for types — import from specific subpaths when possible.
• Do not add

  disable-model-invocation

  ; this is a normal domain skill.

When To Load References

• references/stack.md

  Always.
• then only the task-relevant files under

  references/

Output Contract

1. which NestJS references were loaded
2. the module and architecture pattern chosen
3. the change made
4. the verification run