nestjs-clean-arch

Use this agent when you need to audit or generate Swagger/OpenAPI documentation for NestJS code using @nestjs/swagger decorators. Examples: <example> Context: Developer just created a new DTO for a feature and needs Swagger decorators added user: "I just added CreateCommentDto with title, body, and status fields. Can you add Swagger docs to it?" assistant: "I'll use the api-docs-writer agent to add @ApiProperty decorators to each field in CreateCommentDto with accurate type, required status, and descriptions." <commentary> User is asking to document a specific DTO. The api-docs-writer agent knows exactly how to add @ApiProperty with correct arguments including enum descriptions. </commentary> </example> <example> Context: Developer wants to audit all presenters in the project for missing @ApiProperty user: "Audit all our presenters and add any missing @ApiProperty decorators" assistant: "I'll use the api-docs-writer agent to scan every presenter under src/adapters/controllers/*/presenters/, identify fields missing @ApiProperty, and add them with proper type and description." <commentary> Bulk audit of presenters across all features. The agent will glob-discover all presenter files and systematically patch missing decorators. </commentary> </example> <example> Context: A new controller endpoint was added but has no Swagger metadata user: "The new PATCH /tasks/:id endpoint is missing Swagger docs — can you document it?" assistant: "I'll use the api-docs-writer agent to add @ApiOperation with a summary, @ApiResponse referencing the presenter type, and @ApiBearerAuth since it's a JWT-protected route." <commentary> Controller endpoint documentation needs @ApiOperation, @ApiResponse, and auth decorators. The api-docs-writer agent handles this pattern precisely. </commentary> </example> <example> Context: An enum field lacks a description listing its values in the Swagger UI user: "The status field on TaskDto uses TaskStatusEnum but Swagger just shows the raw numbers — add proper enum descriptions" assistant: "I'll use the api-docs-writer agent to update @ApiProperty on the status field with enum: TaskStatusEnum and a description listing each value, e.g. '2: Completed, 3: OnGoing'." <commentary> Enum fields need both the enum reference and a human-readable description. The api-docs-writer agent enforces this pattern consistently. </commentary> </example>

Reviews code changes for Clean Architecture violations — dependency direction errors, domain layer impurity, naming convention issues, controller business logic, missing presenters, and incomplete layer coverage. Use this agent when the user asks to review code, check architecture, or validate structural correctness after implementing a feature. Examples: <example> Context: The user just finished implementing a new Comment feature across all layers. user: "I just finished the Comment feature, can you check it for architecture violations?" assistant: "I'll run an architecture review on the Comment feature files now." <commentary> Post-implementation review is the primary use case — user has completed code and wants validation before committing. </commentary> </example> <example> Context: The user has staged several changed files and wants a review before opening a PR. user: "Review my recent changes for clean architecture violations" assistant: "Let me check your changed files for any architectural issues." <commentary> Explicit review request with staged/changed files — trigger immediately. </commentary> </example> <example> Context: The user suspects their domain layer has improper imports. user: "Does my domain layer have any NestJS or TypeORM imports?" assistant: "I'll scan the domain layer for any forbidden framework imports." <commentary> Specific layer purity check — a targeted architecture question best handled by this agent. </commentary> </example> <example> Context: The user is learning the architecture and wants to know if they placed code correctly. user: "Is my code in the right layer? I put some business logic in the controller." assistant: "I'll review your controller and check if any logic should move to a use case." <commentary> Layer placement question — agent can scan, identify violations, and suggest fixes. </commentary> </example>

Use this agent when you need to design or implement CASL authorization policies, add a new subject/entity to the ability system, diagnose 403 Forbidden errors related to authorization, or protect endpoints with role-based checks in this NestJS Clean Architecture project. Examples: <example> Context: Developer just created a new Comment domain entity and repository and needs authorization rules for it. user: "I've added a Comment entity. How do I add CASL policies for it?" assistant: "I'll use the casl-policy-advisor agent to design and implement the Comment authorization policies." <commentary> Adding a new entity to the authorization system requires updating TSubject in ability.interface.ts and adding rules in casl-ability.factory.ts — exactly the casl-policy-advisor's domain. </commentary> </example> <example> Context: Developer wants to review whether existing CASL policies are correctly structured and follow the project's architectural rules. user: "Can you audit our current CASL policies and check if they're correct?" assistant: "I'll use the casl-policy-advisor agent to audit the existing authorization policies." <commentary> Auditing authorization policies for correctness, completeness, and architectural compliance is a core casl-policy-advisor capability. </commentary> </example> <example> Context: A user is receiving a 403 error on an endpoint they should have access to and the developer can't identify the cause. user: "Users are getting a 403 on GET /tasks even though they should have read access. What's wrong?" assistant: "I'll use the casl-policy-advisor agent to trace the authorization chain and identify the missing rule." <commentary> 403 Forbidden errors flow through PoliciesGuard → CaslAbilityFactory → ability.can(). Diagnosing this requires deep familiarity with the CASL setup, which is the casl-policy-advisor's specialty. </commentary> </example> <example> Context: Developer needs to add a new admin-only endpoint for deleting tasks and wants correct authorization protection. user: "I need a DELETE /tasks/:id endpoint that only admins can call. How do I set up the CASL policy?" assistant: "I'll use the casl-policy-advisor agent to implement the admin-only CASL policy for the delete endpoint." <commentary> Admin-only endpoint protection requires knowing the RoleEnum, CaslAbilityFactory rule structure, and the @CheckPolicies decorator — all within the casl-policy-advisor's expertise. </commentary> </example>

Generates all boilerplate files for a new entity/feature following Clean Architecture conventions — domain entity, repository interface, use cases, TypeORM entity, repository implementation, DTOs, presenters, controller, module, test stubs, and unit tests. Use this agent when the user wants to scaffold, bootstrap, or generate the file structure for a new resource. Examples: <example> Context: The user wants to create a Comment feature and provides field definitions. user: "Scaffold a Comment entity with fields: content (string), taskId (number), userId (number)" assistant: "I'll scaffold the full Comment feature across all Clean Architecture layers now." <commentary> Explicit scaffold request with entity name and fields — proceed directly to file generation without asking for more info. </commentary> </example> <example> Context: The user wants to add a new resource but doesn't want to create each file manually. user: "Generate all the files I need for a Project feature" assistant: "I'll set up all the Project files. A few quick questions: what fields should Project have, and which use cases do you need (Create, GetList, GetDetail, Update, Delete)?" <commentary> Scaffold request with entity name but missing field info — ask the minimum needed before generating. </commentary> </example> <example> Context: The user is starting a new feature and wants the boilerplate done quickly. user: "Create the boilerplate for a Tag entity with name and color fields, both strings" assistant: "I'll generate all the Tag feature files now across all layers." <commentary> Complete enough info provided — entity name and fields given, generate immediately. </commentary> </example> <example> Context: The user references implementing a feature and implies needing scaffolding. user: "I need to implement a Notification system, can you set up all the files?" assistant: "I'll scaffold the Notification feature. What fields should the Notification entity have?" assistant: "I'll scaffold the Notification feature. What fields should the Notification entity have?" <commentary> Implicit scaffold request — user wants the structure set up but hasn't specified fields yet. </commentary> </example>

Use this agent when the user needs to create, run, troubleshoot, or audit TypeORM database migrations in a NestJS Clean Architecture project. Examples: <example> Context: User has just created a new TypeORM entity and needs a migration for it user: "I added a new Comment entity. Can you generate a migration for it?" assistant: "I'll use the migration-manager agent to generate the migration for your new Comment entity." <commentary> New TypeORM entity created — the migration-manager agent should inspect the entity file, verify naming conventions, and run the generate command in the Docker container. </commentary> </example> <example> Context: User added a new column to an existing TypeORM entity user: "I added a `description` field to the Task entity. Now what?" assistant: "I'll use the migration-manager agent to generate an add-column migration for the Task entity." <commentary> Schema change on existing entity — the migration-manager agent should check the entity diff and generate a properly named add-{field}-to-{table} migration. </commentary> </example> <example> Context: User ran migrations but they failed or the app cannot start user: "The migration:run command failed. How do I fix it?" assistant: "I'll use the migration-manager agent to diagnose the migration failure." <commentary> Migration failure — the migration-manager agent should diagnose Docker container status, check the migration history table, inspect SQL syntax in the failing migration, and guide recovery. </commentary> </example> <example> Context: User wants to know whether the database schema is in sync with the codebase user: "Are my migrations up to date with the current entities?" assistant: "I'll use the migration-manager agent to audit schema drift between entities and migrations." <commentary> Schema drift check — the migration-manager agent should list all TypeORM entity files, compare them against existing migration files, and report whether a new migration needs to be generated. </commentary> </example>

Use this agent when the user wants to analyze TypeORM repositories or queries for performance issues, detect N+1 problems, find missing indexes, audit pagination, or optimize slow endpoints in a NestJS/PostgreSQL project. Examples: <example> Context: The user wants a full audit of all repository files for potential N+1 query problems. user: "Can you analyze all my repositories for N+1 query issues?" assistant: "I'll use the performance-analyzer agent to scan every repository method in `src/infrastructure/databases/postgresql/repositories/` and report any N+1 patterns with severity labels and fix suggestions." <commentary> The user is asking for a comprehensive N+1 analysis across all repositories — exactly the kind of autonomous, multi-file scan this agent is designed for. </commentary> </example> <example> Context: The user is concerned that some queries might be hitting unindexed columns and causing slow full-table scans. user: "Check if my queries are missing database indexes on frequently filtered columns." assistant: "I'll launch the performance-analyzer agent to cross-reference every `WHERE` condition in the repository layer against the `@Index()` decorators on the corresponding TypeORM entities and flag any gaps." <commentary> Index gap detection requires reading both repository queries and entity decorators together — a task suited to this agent's structured analysis workflow. </commentary> </example> <example> Context: A specific API endpoint is responding slowly in production and the developer suspects the underlying query is the culprit. user: "The GET /tasks endpoint is slow. Can you review the TaskRepository to find what's wrong?" assistant: "I'll have the performance-analyzer agent inspect `TaskRepository` — examining `findTasks`, pagination settings, selected columns, loaded relations, and `ORDER BY` clauses — then produce a severity-ranked report with optimized code." <commentary> Reviewing a single slow endpoint maps directly to this agent's per-method analysis capability; it reads the repository, checks entities for indexes, and outputs actionable fixes. </commentary> </example> <example> Context: The user recently implemented a paginated list feature and wants to make sure the query is stable, efficient, and won't degrade at scale. user: "Review my paginated task list query and optimize it." assistant: "I'll invoke the performance-analyzer agent to audit the paginated query for missing `take`/`skip`, unstable ordering (no `ORDER BY`), unnecessary column loads, and unindexed filter columns, then provide an optimized version." <commentary> Paginated query optimization is a core use case: the agent checks take/skip, order stability, column selection, and index coverage in one pass. </commentary> </example>

You are a database seed expert for NestJS projects that use `typeorm-extension`. Your sole responsibility is generating, updating, and registering factory and seeder files so developers always have realistic, relational test data.

Generates missing unit tests for a NestJS Clean Architecture project, covering use cases, controllers, and repository implementations. Use this agent when the user wants to create tests for a specific file, find untested files in a feature, or improve test coverage. Examples: <example> Context: The user wants tests generated for a specific use case that is missing a spec file. user: "Generate a unit test for CreateTaskUseCase" assistant: "I'll use the test-generator agent to create a complete unit test for CreateTaskUseCase." <commentary> Explicit request to generate a use case test — the agent should find the source file, read it, locate similar existing tests for style reference, and produce a complete spec file with happy path and error cases. </commentary> </example> <example> Context: The user wants to audit which tests are missing across an entire feature. user: "Find all missing tests in the tasks feature" assistant: "I'll use the test-generator agent to compare src/ vs test/ for the tasks feature and list every untested file." <commentary> The user wants a coverage gap analysis — the agent should mirror src/use-cases/tasks/ and src/adapters/controllers/tasks/ against test/ to surface missing spec files. </commentary> </example> <example> Context: The user just implemented a controller and wants tests written for it. user: "Write a test for the TasksController" assistant: "I'll use the test-generator agent to write a controller spec that mocks all use cases and validates DTOs and presenters." <commentary> Controller test request — agent should read the controller source, mock each injected use case, and verify that the correct presenter output is returned for each endpoint. </commentary> </example> <example> Context: The user has a new TypeORM repository implementation and wants an integration-style unit test. user: "Create a test for TaskRepository" assistant: "I'll use the test-generator agent to write a repository spec that mocks the TypeORM DataSource and verifies each query method." <commentary> Repository implementation test request — agent reads the repository source, mocks TypeORM dependencies, and tests each public method including error paths. </commentary> </example>

Workflow for safely modifying, extending, or refactoring existing features in the NestJS Clean Architecture project. Use this skill when the user asks to "add a field", "add an endpoint", "modify existing", "extend", "refactor", "change existing feature", "brownfield", "update entity", "add column", "add relation", or needs to change something that already exists — including impact analysis, migration strategy, and backward compatibility.

Structured workflow for diagnosing, fixing, and verifying bugs in the NestJS Clean Architecture project. Use this skill when the user reports a "bug", "error", "failing test", "not working", "broken", "unexpected behavior", "500 error", "null reference", "type error", or needs to debug, troubleshoot, or fix an issue in any layer of the application.

This skill should be used when the user asks to "add authorization", "add CASL", "register subject", "protect route", "check policy", "add permissions", or "role-based access" to a new entity or feature in a NestJS Clean Architecture project.

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

Activates when the user asks to throw an exception, handle error, add error handling, throw not found, throw forbidden, throw bad request, or inject exception service in a NestJS Clean Architecture project. Guides correct use of IException interface with proper injection, error codes, and module wiring.

Step-by-step workflow for implementing entirely new features from scratch in the NestJS Clean Architecture project. Use this skill when the user asks to "add a new feature", "create a new resource/entity", "implement [Entity] from scratch", "new entity", "greenfield", or needs to build something that doesn't exist yet — including all layers from domain entity to tests.

Guide for implementing new features following Clean Architecture with NestJS. Use this skill whenever the user asks to add a new feature, create a new resource/entity/module, write a use case, implement a repository, build a controller, set up dependency injection in a module, write tests, or asks anything about how code should be structured in this project — even if they don't mention "clean architecture" explicitly.

Activate when the user asks to add swagger docs, document API, add @ApiProperty, add swagger response type, add OpenAPI decorators, use ApiResponseType or ApiCreatedResponseType, or document an endpoint in the NestJS Clean Architecture project. Apply this skill whenever OpenAPI/Swagger documentation must be added or updated for controllers, DTOs, or presenters.

Activates this skill when a developer asks to "write a test", "create unit test", "test a use case", "test a controller", "create stub", "add test for", "how to test", "write spec", "mock a repository", "mock a use case", or "set up a TestingModule". Provides the exact testing conventions, patterns, and file structures used in this NestJS Clean Architecture project so that all tests are consistent with the existing test suite.

5 hooks across 4 events