{
  "markdown": "# NestJS Hexagonal Architecture Plugin\n\n> Claude Code plugin for building NestJS bounded contexts with Hexagonal Architecture, DDD, and CQRS patterns.\n\n## Overview\n\nThis plugin provides layer-specific skills, specialized agents, and workflow orchestrators for creating well-structured NestJS bounded contexts. It codifies Ports & Adapters architecture combined with Domain-Driven Design and the `@nestjs/cqrs` module.\n\n**Who it's for:** Teams building NestJS applications that follow clean architecture and want consistent, reviewable code.\n\n**Key patterns:**\n- Entity modeling with `AggregateRoot`, domain events via `entity.commit()`, and `EventBus`\n- Value Objects (scalar, composed, enum, state machine)\n- Repository interfaces as ports with Prisma and in-memory implementations\n- Three application patterns (plain UseCase, CQRS Command/Query, Handler-as-Orchestrator)\n- WebSocket broadcasting via `WsGatewayPort` abstraction\n- NestJS module wiring that exports only port tokens\n\n**Compatible with GSD workflow** (usable as phase execution within milestones).\n\n## Installation\n\n### From GitHub\n\n```bash\n# 1. Add the marketplace (one time)\n/plugin marketplace add softtor/nestjs-hexagonal\n\n# 2. Install the plugin\n/plugin install nestjs-hexagonal\n```\n\n### Local development\n\n```bash\nclaude --plugin-dir /path/to/nestjs-hexagonal\n```\n\n## Skills\n\n### Layer Skills\n\n| Skill | Trigger examples | What it does |\n|---|---|---|\n| `nestjs-hexagonal:domain` | \"create entity\", \"new value object\" | Entity (AggregateRoot), VOs, events, repo interfaces, data builders |\n| `nestjs-hexagonal:application` | \"create use case\", \"cqrs handler\" | Use cases, handlers, DTOs, ports, read models |\n| `nestjs-hexagonal:infrastructure` | \"prisma repo\", \"module wiring\" | Prisma repos, mappers, adapters, NestJS modules |\n| `nestjs-hexagonal:presentation` | \"create controller\", \"request dto\" | Controllers, request DTOs, Swagger, error filters |\n| `nestjs-hexagonal:websocket-broadcasting` | \"broadcast event\", \"ws gateway\" | Domain event -> WebSocket broadcast to frontend |\n\n### Workflow Skills\n\n| Skill | What it does |\n|---|---|\n| `nestjs-hexagonal:create-subdomain` | Orchestrates full BC creation by dispatching agents per layer |\n| `nestjs-hexagonal:review-subdomain` | Architecture compliance + over-engineering + code smell review |\n\n## Agents\n\nEach agent loads its corresponding skill and specializes in one concern.\n\n| Agent | Model | Purpose |\n|---|---|---|\n| `domain-agent` | **Claude Opus 5** (`claude-opus-5`) | Domain modeling — entities, VOs, events, repo interfaces |\n| `application-agent` | Claude Sonnet 5 (`claude-sonnet-5`) | Use cases, CQRS handlers, DTOs, ports |\n| `infrastructure-agent` | Claude Sonnet 5 (`claude-sonnet-5`) | Prisma repos, module wiring, adapters |\n| `presentation-agent` | Claude Sonnet 5 (`claude-sonnet-5`) | Controllers, request DTOs, Swagger |\n| `broadcasting-agent` | Claude Sonnet 5 (`claude-sonnet-5`) | WS gateway (backend) + event consumption (Next.js/React frontend) |\n| `listener-agent` | Claude Sonnet 5 (`claude-sonnet-5`) | Creates event listeners (same-BC projections, cross-BC reactions, bridge) |\n| `architecture-reviewer` | **Claude Opus 5** (`claude-opus-5`) | Over-engineering detection + code smell identification |\n| `event-debug-agent` | **Claude Opus 5** (`claude-opus-5`) | Debug full event chain: entity -> dispatch -> WS -> frontend |\n\n**Why Opus 5 for domain, review, and debug?** Domain modeling requires critical decisions. Review requires deep judgment to distinguish necessary from unnecessary complexity. Event debugging requires tracing across 6 layers systematically.\n\n**Model pins:** Agents use full IDs (`claude-opus-5`, `claude-sonnet-5`) so resolution does not fall back to legacy 4.x aliases on some providers. Requires Claude Code **v2.1.219+** (Opus 5) and **v2.1.197+** (Sonnet 5) — run `claude update` if needed.\n\n## Architecture Overview\n\n### Event Flow (CQRS)\n\n```\nUseCase\n  -> entity = Entity.create(props)    # entity.apply(event) queues internally\n  -> repo.save(entity)                # repo is PURE persistence\n  -> return entity                    # UseCase returns entity to Handler\n\nHandler\n  -> publisher.mergeObjectContext(entity)   # Handler wraps entity\n  -> entity.commit()                       # Handler dispatches via EventBus\n  -> return { id: entity.id }\n\nEventBus -> @EventsHandler             # Side effects, projections, WS broadcast\n```\n\n**Critical rule:** `EventPublisher` lives in the Handler, NEVER in the UseCase.\n\n### Pattern Selection (Application Layer)\n\n| Scenario | Pattern |\n|---|---|\n| Simple CRUD without side effects | **A**: Plain UseCase + TOKEN |\n| Module uses CQRS | **B**: Command/Query handlers |\n| Complex orchestration with multiple services | **C**: Handler as Orchestrator |\n| Simple `findById` without RBAC | No use case — repo directly in controller |\n\n### Validation Layers\n\n| Layer | Where | Tool | Responsibility |\n|---|---|---|---|\n| Request DTO | presentation | `class-validator` | Format, presence, types |\n| Application DTO | application | TypeScript interfaces | Layer contract |\n| Domain VO | domain | Manual `validate()` | Business invariants |\n| Queue Schema | integration | Zod | Inter-service contract |\n\n### WebSocket Broadcasting (simplified)\n\nOne pattern only: `@EventsHandler` -> enrich if needed -> `WsGatewayPort.emit()`.\n\nNo generic relay, no event maps, no custom broadcast events. Each event that needs to reach the frontend has its own explicit handler.\n\n## Shared Examples\n\nThe `shared/` directory contains `.ts.example` reference implementations for projects that don't yet have base classes.\n\n| File | What it provides |\n|---|---|\n| `entity.ts.example` | Entity extending AggregateRoot with `apply()` |\n| `value-object.ts.example` | Abstract ValueObject with validation |\n| `unique-entity-id.ts.example` | UUID-based entity ID |\n| `domain-event.ts.example` | IEvent implementation |\n| `repository-contracts.ts.example` | Pure persistence interface |\n| `searchable-repository.ts.example` | SearchParams + SearchResult + SearchableRepositoryInterface |\n| `in-memory-searchable.ts.example` | In-memory repo for unit tests |\n| `domain-error-filter.ts.example` | DomainError -> HTTP status mapping |\n| `env-config.service.ts.example` | EnvConfigService with typed getters |\n| `define-data-builder.ts.example` | Base builder class with faker |\n| `data-builder-example.ts.example` | Concrete builder example |\n| `errors.ts.example` | Full domain error hierarchy |\n| `ws-gateway-port.ts.example` | WsGatewayPort interface + TOKEN |\n\n## Principles\n\n- **CQRS-friendly, not CQRS-mandatory** — simple reads skip the bus\n- **Event-friendly, not event-mandatory** — events only for side effects\n- **No over-engineering** — 3 lines of code beats a premature abstraction\n- **Test-friendly** — data builders, in-memory repos, real integration tests\n- **Framework-agnostic domain/application** — exportable to other frameworks\n- **Microservice-friendly** — event-driven patterns enable future extraction\n\n## GSD Compatibility\n\nThe `create-subdomain` workflow maps directly to GSD phases. Each agent dispatch equals one GSD task.\n\n**Setup:** Run `nestjs-hexagonal:gsd-installer` to configure your project's CLAUDE.md with skill mappings and phase templates for GSD.\n\nThe installer adds:\n- Skill-to-agent mapping table for GSD executor agents\n- Architecture rules that GSD enforces during execution\n- Phase template for bounded context creation\n\n## Contributing\n\nCommunity contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [ROADMAP](ROADMAP.md) for open feature tracks and good first issues.\n\n1. Fork the repository\n2. Create a feature branch\n3. Follow the existing skill structure (SKILL.md + references/)\n4. Submit a pull request\n\n## License\n\nMIT\n",
  "bytes": 7799,
  "sha": "fd123e8d149a3495df9d300a1fcf1093320656918ade4dcbd812cb45a9edbeb9",
  "repo_slug": "softtor/nestjs-hexagonal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_softtor_nestjs_hexagonal_nestjs_hexagona_86e08d41/readme"
}