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>

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.

5 hooks across 4 events