Non-negotiable rules:

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

Route NestJS work through the project's module-based architecture so implementation follows the established patterns for dependency injection, validation, data access, and request lifecycle.

Step 0: Read the stack contract

Always start with:

• references/stack.md

That establishes: NestJS version, ORM (TypeORM/Prisma/Drizzle), package manager, auth strategy, queue system, and locked dependency choices.

Success criteria: The project's NestJS architecture and locked decisions are explicit before implementation starts.

Step 1: Load only the relevant references

Use the routing table to pick reference files. Do not bulk-load the full reference tree.

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: Only the task-relevant NestJS conventions are in play.

Step 2: Implement with the core NestJS guardrails

Keep these rules active:

• 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

Success criteria: The change fits the project's NestJS module architecture instead of bypassing the framework.

Step 3: Verify the affected surface

Use the narrowest relevant verification:

• 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

Success criteria: The changed NestJS surface still builds, type-checks, and passes tests.

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

Report:

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