@ryuenn3123/agentic-senior-core 2.5.22 → 3.0.0

package/.agent-context/blueprints/nestjs-logic.md

@@ -1,247 +0,0 @@
-# Blueprint: NestJS Module (Clean Architecture)
-
-> This blueprint defines how to scaffold a NestJS application or module.
-> Every module follows strict layering. No shortcuts.
-
-## Tech Stack
-- **Runtime:** Node.js 20+ / Bun
-- **Framework:** NestJS 10+
-- **Validation:** Zod + nestjs-zod (or class-validator)
-- **ORM:** Prisma (or Drizzle)
-- **Documentation:** @nestjs/swagger (OpenAPI auto-generated)
-- **Testing:** Vitest (or Jest)
-- **Logger:** nestjs-pino
-
-## Project Structure
-
-```
-project-name/
-├── src/
-│   ├── main.ts                         # Bootstrap + Swagger setup
-│   ├── app.module.ts                   # Root module
-│   │
-│   ├── modules/                        # Feature modules
-│   │   ├── user/
-│   │   │   ├── user.module.ts          # Module registration
-│   │   │   ├── user.controller.ts      # Transport layer (HTTP)
-│   │   │   ├── user.service.ts         # Application layer (business logic)
-│   │   │   ├── user.repository.ts      # Infrastructure layer (data access)
-│   │   │   ├── dto/
-│   │   │   │   ├── create-user.dto.ts  # Input validation schemas
-│   │   │   │   ├── update-user.dto.ts
-│   │   │   │   └── user-response.dto.ts # Output serialization
-│   │   │   ├── entities/
-│   │   │   │   └── user.entity.ts      # Domain entity
-│   │   │   ├── guards/
-│   │   │   │   └── user-owner.guard.ts # Authorization guard
-│   │   │   └── __tests__/
-│   │   │       ├── user.controller.spec.ts
-│   │   │       └── user.service.spec.ts
-│   │   │
-│   │   ├── auth/
-│   │   │   ├── auth.module.ts
-│   │   │   ├── auth.controller.ts
-│   │   │   ├── auth.service.ts
-│   │   │   ├── strategies/
-│   │   │   │   ├── jwt.strategy.ts
-│   │   │   │   └── local.strategy.ts
-│   │   │   └── guards/
-│   │   │       └── jwt-auth.guard.ts
-│   │   │
-│   │   └── health/
-│   │       ├── health.module.ts
-│   │       └── health.controller.ts
-│   │
-│   ├── shared/                         # Cross-cutting concerns
-│   │   ├── config/
-│   │   │   ├── app.config.ts           # Zod-validated config
-│   │   │   └── database.config.ts
-│   │   ├── errors/
-│   │   │   ├── app-error.ts            # Base error class
-│   │   │   └── http-exception.filter.ts # Global exception filter
-│   │   ├── interceptors/
-│   │   │   ├── logging.interceptor.ts   # Request logging
-│   │   │   └── transform.interceptor.ts # Response transformation
-│   │   ├── pipes/
-│   │   │   └── zod-validation.pipe.ts   # Zod validation pipe
-│   │   ├── decorators/
-│   │   │   └── current-user.decorator.ts
-│   │   └── lib/
-│   │       ├── prisma.service.ts        # Prisma client lifecycle
-│   │       └── logger.module.ts         # Pino logger module
-│   │
-│   └── common/
-│       └── types/
-│           └── api-response.ts          # Standardized API response type
-│
-├── prisma/
-│   ├── schema.prisma
-│   └── migrations/
-│
-├── test/                               # E2E tests
-│   └── app.e2e-spec.ts
-│
-├── .env.example
-├── nest-cli.json
-├── tsconfig.json                       # Strict mode!
-├── tsconfig.build.json
-├── vitest.config.ts
-└── package.json
-```
-
-## Module Pattern (The Law)
-
-```typescript
-// src/modules/user/user.module.ts
-import { Module } from '@nestjs/common';
-import { UserController } from './user.controller';
-import { UserService } from './user.service';
-import { UserRepository } from './user.repository';
-
-@Module({
-  controllers: [UserController],
-  providers: [UserService, UserRepository],
-  exports: [UserService],  // Only export the service — never the repository
-})
-export class UserModule {}
-```
-
-## Controller Pattern (Transport ONLY)
-
-```typescript
-// src/modules/user/user.controller.ts
-import { Controller, Get, Post, Body, Param, Query, UseGuards } from '@nestjs/common';
-import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth } from '@nestjs/swagger';
-import { UserService } from './user.service';
-import { CreateUserDto } from './dto/create-user.dto';
-import { UserResponseDto } from './dto/user-response.dto';
-import { JwtAuthGuard } from '@/shared/guards/jwt-auth.guard';
-
-@ApiTags('Users')
-@Controller('users')
-export class UserController {
-  constructor(private readonly userService: UserService) {}
-
-  @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({ status: 201, type: UserResponseDto })
-  @ApiResponse({ status: 400, description: 'Validation error' })
-  @ApiResponse({ status: 409, description: 'Email already exists' })
-  @Post()
-  async create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
-    // Controller does: validate input (via pipe) → call service → return response
-    // Controller does NOT: query database, check business rules, format data
-    return this.userService.create(dto);
-  }
-
-  @ApiBearerAuth()
-  @UseGuards(JwtAuthGuard)
-  @ApiOperation({ summary: 'List users with pagination' })
-  @Get()
-  async findAll(
-    @Query('page') page: number = 1,
-    @Query('limit') limit: number = 20,
-  ): Promise<UserResponseDto[]> {
-    return this.userService.findAll({ page, limit });
-  }
-}
-```
-
-## Service Pattern (Business Logic)
-
-```typescript
-// src/modules/user/user.service.ts
-import { Injectable, ConflictException } from '@nestjs/common';
-import { UserRepository } from './user.repository';
-import { CreateUserDto } from './dto/create-user.dto';
-import { hash } from 'bcrypt';
-
-@Injectable()
-export class UserService {
-  constructor(private readonly userRepository: UserRepository) {}
-
-  async create(dto: CreateUserDto): Promise<UserResponseDto> {
-    // Business rule: email must be unique
-    const existingUser = await this.userRepository.findByEmail(dto.email);
-    if (existingUser) {
-      throw new ConflictException('Email already registered');
-    }
-
-    // Business rule: hash password before storage
-    const hashedPassword = await hash(dto.password, 12);
-
-    return this.userRepository.create({
-      ...dto,
-      password: hashedPassword,
-    });
-  }
-}
-```
-
-## Repository Pattern (Data Access Only)
-
-```typescript
-// src/modules/user/user.repository.ts
-import { Injectable } from '@nestjs/common';
-import { PrismaService } from '@/shared/lib/prisma.service';
-import { User } from '@prisma/client';
-
-@Injectable()
-export class UserRepository {
-  constructor(private readonly prisma: PrismaService) {}
-
-  async findByEmail(email: string): Promise<User | null> {
-    return this.prisma.user.findUnique({ where: { email } });
-  }
-
-  async create(data: Omit<User, 'id' | 'createdAt' | 'updatedAt'>): Promise<User> {
-    return this.prisma.user.create({ data });
-  }
-
-  async findAll(params: { skip: number; take: number }): Promise<User[]> {
-    return this.prisma.user.findMany({
-      skip: params.skip,
-      take: params.take,
-      select: { id: true, email: true, name: true, createdAt: true },
-      // NEVER select password
-    });
-  }
-}
-```
-
-## Swagger Setup (Mandatory)
-
-```typescript
-// src/main.ts
-import { NestFactory } from '@nestjs/core';
-import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
-import { AppModule } from './app.module';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Swagger — auto-generates API documentation
-  const config = new DocumentBuilder()
-    .setTitle('API Documentation')
-    .setVersion('1.0')
-    .addBearerAuth()
-    .build();
-
-  const document = SwaggerModule.createDocument(app, config);
-  SwaggerModule.setup('docs', app, document);
-
-  await app.listen(3000);
-}
-bootstrap();
-```
-
-## Scaffolding Checklist
-
-- [ ] Every module follows Controller → Service → Repository layering
-- [ ] DTOs use Zod or class-validator for ALL input validation
-- [ ] Swagger decorators on every controller method
-- [ ] Global exception filter catches and formats all errors
-- [ ] Repository NEVER exposes raw Prisma client outside its module
-- [ ] Service is exported, Repository is NOT (module encapsulation)
-- [ ] Tests exist for service logic (unit) and controller routes (integration)
-- [ ] Environment variables validated with Zod at startup
-- [ ] Health check endpoint exists at `/health`

package/.agent-context/blueprints/observability.md

@@ -1,227 +0,0 @@
-# Blueprint: Observability Stack (OpenTelemetry)
-
-> If you can't see it, you can't fix it.
-> Observability is not optional — it's infrastructure.
-
-## Tech Stack
-
-| Pillar | Standard | Why |
-|--------|----------|-----|
-| **Tracing** | OpenTelemetry SDK | Vendor-neutral, W3C Trace Context |
-| **Metrics** | OpenTelemetry SDK | OTLP export, histogram/counter/gauge |
-| **Logging** | Structured JSON + OTel correlation | traceId in every log line |
-| **Collector** | OpenTelemetry Collector | Pipeline: receive → process → export |
-| **Backend** | Jaeger / Tempo (traces), Prometheus / Mimir (metrics), Loki (logs) | Or cloud: Datadog, Grafana Cloud, New Relic |
-| **Dashboards** | Grafana | Universal visualization |
-
-## The Three Pillars
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                    Your Application                       │
-│                                                          │
-│  Traces: "What path did this request take?"              │
-│  Metrics: "How is the system performing overall?"        │
-│  Logs: "What exactly happened at this moment?"           │
-│                                                          │
-│  ── All connected by traceId / spanId ──                 │
-└────────────────────┬─────────────────────────────────────┘
-                     │ OTLP (gRPC/HTTP)
-           ┌─────────▼──────────┐
-           │  OTel Collector    │
-           │  (receive/process/ │
-           │   export)          │
-           └────┬────┬────┬─────┘
-                │    │    │
-          ┌─────▼┐ ┌─▼──┐ ┌▼────┐
-          │Jaeger│ │Prom│ │Loki │
-          │Tempo │ │    │ │     │
-          └──────┘ └────┘ └─────┘
-                     │
-              ┌──────▼──────┐
-              │   Grafana    │
-              │ (Dashboards) │
-              └─────────────┘
-```
-
-## Instrumentation Standards
-
-### Auto-Instrumentation First
-
-Start with auto-instrumentation for common libraries (HTTP servers, DB clients, message brokers). Add manual instrumentation for business-critical paths.
-
-```typescript
-// Node.js: Initialize OpenTelemetry EARLY (before other imports)
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
-
-const sdk = new NodeSDK({
-  traceExporter: new OTLPTraceExporter({
-    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-  }),
-  metricReader: new PeriodicExportingMetricReader({
-    exporter: new OTLPMetricExporter(),
-  }),
-  instrumentations: [getNodeAutoInstrumentations()],
-  serviceName: process.env.OTEL_SERVICE_NAME,
-  serviceVersion: process.env.APP_VERSION,
-});
-
-sdk.start();
-```
-
-### Manual Spans for Business Logic
-
-```typescript
-import { trace } from '@opentelemetry/api';
-
-const tracer = trace.getTracer('order-service');
-
-async function processOrder(order: Order): Promise<void> {
-  return tracer.startActiveSpan('processOrder', async (span) => {
-    try {
-      span.setAttribute('order.id', order.id);
-      span.setAttribute('order.total', order.total);
-      span.setAttribute('order.item_count', order.items.length);
-
-      await validateInventory(order);
-      await processPayment(order);
-      await updateInventory(order);
-
-      span.setStatus({ code: SpanStatusCode.OK });
-    } catch (error) {
-      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-      span.recordException(error);
-      throw error;
-    } finally {
-      span.end();
-    }
-  });
-}
-```
-
-### Metric Instruments
-
-| Type | When | Example |
-|------|------|---------|
-| **Counter** | Monotonically increasing count | `http.requests.total` |
-| **Histogram** | Distribution of values | `http.request.duration` |
-| **Gauge** | Current snapshot value | `system.memory.usage` |
-| **UpDownCounter** | Value that can go up and down | `queue.depth` |
-
-### Structured Logging
-
-```typescript
-// REQUIRED: Include traceId and spanId in every log
-logger.info('Order processed', {
-  traceId: span.spanContext().traceId,
-  spanId: span.spanContext().spanId,
-  orderId: order.id,
-  userId: order.userId,
-  durationMs: Date.now() - startTime,
-  itemCount: order.items.length,
-});
-```
-
-## Naming Conventions (Semantic Conventions)
-
-Follow OpenTelemetry semantic conventions:
-
-```
-Metrics:    {namespace}.{component}.{metric}
-            http.server.request.duration
-            db.client.operation.duration
-            messaging.publish.duration
-
-Spans:      {operation} {target}
-            GET /api/users
-            SELECT users
-            PUBLISH order.created
-
-Attributes: {namespace}.{attribute}
-            http.request.method
-            db.system
-            service.name
-            service.version
-```
-
-## Alerting Strategy
-
-### Golden Signals (Monitor These)
-
-| Signal | Metric | Alert When |
-|--------|--------|------------|
-| **Latency** | `http.server.request.duration` p99 | > 500ms for 5 min |
-| **Traffic** | `http.server.request.total` rate | Sudden drop > 50% |
-| **Errors** | `http.server.request.error_ratio` | > 1% for 5 min |
-| **Saturation** | CPU, memory, connection pool | > 80% for 10 min |
-
-### Alert Rules
-
-1. **Page** (wake someone up): Service is DOWN, error rate > 5%, data loss risk
-2. **Alert** (respond this shift): Latency degradation, resource saturation > 80%
-3. **Inform** (check next business day): Slow queries, disk space trending
-
-## Collector Configuration
-
-```yaml
-# otel-collector-config.yaml
-receivers:
-  otlp:
-    protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
-      http:
-        endpoint: 0.0.0.0:4318
-
-processors:
-  batch:
-    timeout: 5s
-    send_batch_size: 1024
-  memory_limiter:
-    limit_mib: 512
-    spike_limit_mib: 128
-  attributes:
-    actions:
-      - key: environment
-        value: ${ENVIRONMENT}
-        action: upsert
-
-exporters:
-  otlphttp/traces:
-    endpoint: http://jaeger:4318
-  prometheus:
-    endpoint: 0.0.0.0:8889
-  loki:
-    endpoint: http://loki:3100/loki/api/v1/push
-
-service:
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [memory_limiter, batch]
-      exporters: [otlphttp/traces]
-    metrics:
-      receivers: [otlp]
-      processors: [memory_limiter, batch]
-      exporters: [prometheus]
-    logs:
-      receivers: [otlp]
-      processors: [memory_limiter, batch, attributes]
-      exporters: [loki]
-```
-
-## Scaffolding Checklist
-
-- [ ] Install OpenTelemetry SDK for your language
-- [ ] Configure auto-instrumentation for HTTP, DB, messaging
-- [ ] Set `OTEL_SERVICE_NAME` and `OTEL_EXPORTER_OTLP_ENDPOINT` env vars
-- [ ] Add manual spans to business-critical paths
-- [ ] Ensure structured logs include `traceId` and `spanId`
-- [ ] Deploy OpenTelemetry Collector with batch + memory limiter
-- [ ] Configure exporters for traces, metrics, and logs
-- [ ] Set up Grafana dashboards for golden signals
-- [ ] Define alert rules for latency, errors, saturation
-- [ ] Enable W3C Trace Context propagation across services

package/.agent-context/blueprints/spring-boot-api.md

@@ -1,218 +0,0 @@
-# Blueprint: Spring Boot API
-
-> Java backend API service using Spring Boot 4.x, Java 25+, Spring Data JPA, and Flyway.
-
-## Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Framework | Spring Boot 4.x (Spring Framework 7) |
-| Language | Java 25+ (LTS) |
-| Validation | Jakarta Bean Validation |
-| ORM | Spring Data JPA (Hibernate) |
-| Migration | Flyway |
-| Testing | JUnit 5 + Mockito + Testcontainers |
-| DTO mapping | MapStruct |
-| Logging | SLF4J + Logback (JSON) |
-| API docs | springdoc-openapi (Swagger/Scalar) |
-| Build | Gradle (Kotlin DSL) |
-
----
-
-## Project Structure
-
-```
-project-name/
-├── src/main/java/com/example/project/
-│   ├── Application.java
-│   │
-│   ├── modules/
-│   │   └── user/
-│   │       ├── UserController.java
-│   │       ├── UserService.java
-│   │       ├── UserRepository.java
-│   │       ├── UserMapper.java              # MapStruct
-│   │       ├── dto/
-│   │       │   ├── CreateUserRequest.java   # record + validation
-│   │       │   └── UserResponse.java        # record
-│   │       ├── entity/
-│   │       │   └── UserEntity.java          # JPA entity
-│   │       └── exception/
-│   │           └── UserNotFoundException.java
-│   │
-│   └── shared/
-│       ├── config/
-│       │   ├── SecurityConfig.java
-│       │   └── OpenApiConfig.java
-│       ├── exception/
-│       │   ├── AppException.java
-│       │   ├── ErrorCode.java               # Enum
-│       │   ├── ErrorResponse.java           # record
-│       │   └── GlobalExceptionHandler.java  # @ControllerAdvice
-│       └── util/
-│           └── LogContext.java
-│
-├── src/main/resources/
-│   ├── application.yml
-│   ├── application-dev.yml
-│   └── db/migration/
-│       └── V1__create_users_table.sql
-│
-├── src/test/java/com/example/project/
-│   └── modules/user/
-│       ├── UserServiceTest.java            # Unit
-│       └── UserControllerIT.java           # Integration
-│
-├── build.gradle.kts
-├── settings.gradle.kts
-├── Dockerfile
-└── .env.example
-```
-
----
-
-## File Patterns
-
-### Controller — Thin Transport
-```java
-@RestController
-@RequestMapping("/api/v1/users")
-@Tag(name = "Users")
-public class UserController {
-    private final UserService userService;
-
-    public UserController(UserService userService) {
-        this.userService = userService;
-    }
-
-    @PostMapping
-    @ResponseStatus(HttpStatus.CREATED)
-    @Operation(summary = "Create a user account")
-    @ApiResponse(responseCode = "201", description = "User created")
-    @ApiResponse(responseCode = "400", description = "Validation error")
-    @ApiResponse(responseCode = "409", description = "Email already exists")
-    public UserResponse create(@Valid @RequestBody CreateUserRequest request) {
-        return userService.create(request);
-    }
-
-    @GetMapping
-    @Operation(summary = "List users with pagination")
-    public Page<UserResponse> list(Pageable pageable) {
-        return userService.list(pageable);
-    }
-}
-```
-
-### DTOs — Records with Validation
-```java
-public record CreateUserRequest(
-    @NotBlank @Size(max = 100)
-    @Schema(description = "Display name", example = "Jane Doe")
-    String name,
-
-    @NotBlank @Email
-    @Schema(description = "Unique email address", example = "jane@example.com")
-    String email,
-
-    @NotBlank @Size(min = 8)
-    String password
-) {}
-
-public record UserResponse(
-    UUID id,
-    String name,
-    String email,
-    Instant createdAt
-) {}
-```
-
-### Service — Business Logic
-```java
-@Service
-@Transactional
-public class UserService {
-    private static final Logger log = LoggerFactory.getLogger(UserService.class);
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-    private final PasswordEncoder passwordEncoder;
-
-    public UserService(UserRepository userRepository, UserMapper userMapper,
-                       PasswordEncoder passwordEncoder) {
-        this.userRepository = userRepository;
-        this.userMapper = userMapper;
-        this.passwordEncoder = passwordEncoder;
-    }
-
-    public UserResponse create(CreateUserRequest request) {
-        if (userRepository.existsByEmail(request.email())) {
-            throw new AppException(ErrorCode.USER_ALREADY_EXISTS,
-                "Email already registered: " + request.email());
-        }
-
-        UserEntity entity = userMapper.toEntity(request);
-        entity.setPassword(passwordEncoder.encode(request.password()));
-
-        UserEntity saved = userRepository.save(entity);
-        log.info("User created: id={}, email={}", saved.getId(), saved.getEmail());
-
-        return userMapper.toResponse(saved);
-    }
-
-    @Transactional(readOnly = true)
-    public Page<UserResponse> list(Pageable pageable) {
-        return userRepository.findAll(pageable).map(userMapper::toResponse);
-    }
-}
-```
-
-### Global Error Handler
-```java
-@ControllerAdvice
-public class GlobalExceptionHandler {
-
-    @ExceptionHandler(AppException.class)
-    public ResponseEntity<ErrorResponse> handleAppException(AppException ex) {
-        return ResponseEntity
-            .status(ex.getHttpStatus())
-            .body(new ErrorResponse(ex.getCode().name(), ex.getMessage()));
-    }
-
-    @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
-        var details = ex.getFieldErrors().stream()
-            .map(e -> new ErrorResponse.FieldError(e.getField(), e.getDefaultMessage()))
-            .toList();
-        return ResponseEntity.badRequest()
-            .body(new ErrorResponse("VALIDATION_ERROR", "Invalid input", details));
-    }
-}
-
-public record ErrorResponse(
-    String code,
-    String message,
-    List<FieldError> details
-) {
-    public ErrorResponse(String code, String message) {
-        this(code, message, List.of());
-    }
-
-    public record FieldError(String field, String message) {}
-}
-```
-
----
-
-## Scaffolding Checklist
-
-- [ ] Initialize with Spring Initializr (Web, JPA, Validation, Security, Flyway)
-- [ ] Set up modular structure under `modules/`
-- [ ] Configure `application.yml` with profiles (dev, staging, prod)
-- [ ] Create `GlobalExceptionHandler` with `@ControllerAdvice`
-- [ ] Create `AppException` + `ErrorCode` enum
-- [ ] Set up Flyway with initial migration
-- [ ] Configure springdoc-openapi for API docs
-- [ ] Create first module following the pattern
-- [ ] Set up MapStruct for DTO mapping
-- [ ] Create unit + integration tests
-- [ ] Run `./gradlew test` — zero failures

package/.agent-context/profiles/platform.md

@@ -1,13 +0,0 @@
-# Team Profile Pack: Platform
-
-slug: platform
-displayName: Platform Team
-description: Reliability-oriented defaults for shared platform modules across teams.
-defaultProfile: balanced
-defaultStack: go.md
-defaultBlueprint: go-service.md
-ciGuardrails: true
-lockCi: false
-blockingSeverities: critical, high
-owner: platform-foundation
-lastUpdated: 2026-03-19