@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/blueprints/infrastructure-as-code.md

@@ -0,0 +1,62 @@
+# Infrastructure as Code (IaC) Blueprint
+
+> ClickOps is a sin. If it's not in code, it doesn't exist. Treats your servers like cattle, not pets.
+
+## 1. Tooling (March 2026)
+- **Standard:** Terraform / OpenTofu (HCL) or Pulumi (TypeScript/Go/Python).
+- **BANNED:** AWS CloudFormation (verbose, slow, vendor-locked) unless mandated by enterprise policy. AWS CDK is acceptable but requires rigorous linting to prevent runaway loops.
+
+## 2. Directory Structure (Blast Radius Management)
+Never put all your infrastructure into a single `main.tf` or a single state file.
+- **BANNED:** Flat structure. A single mistake could destroy the database while updating an S3 bucket.
+- **REQUIRED (Component/Environment Split):**
+  ```
+  infrastructure/
+    modules/
+      vpc/
+      rds/
+      eks/
+    environments/
+      dev/
+        vpc/    (depends on modules/vpc)
+        rds/    (runs its own state file)
+      prod/
+        vpc/
+        rds/
+  ```
+
+## 3. Remote State & Locking
+State files contain sensitive data (passwords, IP addresses) and represent the source of truth for your physical architecture.
+- **Rule:** ALWAYS use a remote backend (S3, GCS, HCP Terraform) with state locking (DynamoDB, native GCS/HCP).
+- **BANNED:** Committing `terraform.tfstate` or `Pulumi.dev.yaml` to Git. Ensure `*.tfstate` is in `.gitignore`.
+
+## 4. Hardcoded Values & Secrets
+- **Rule:** NEVER hardcode ARNs, IPs, or passwords in your IaC.
+- **REQUIRED:** Pass variables via `.tfvars` (which are gitignored) or environment variables (`TF_VAR_db_password`). Use a Secret Manager (AWS Secrets Manager, HashiCorp Vault) and reference the secret dynamically.
+- **Example:**
+  ```hcl
+  # ❌ BANNED
+  password = "SuperSecretPassword123!"
+
+  # ✅ REQUIRED
+  data "aws_secretsmanager_secret_version" "db" {
+    secret_id = aws_secretsmanager_secret.db.id
+  }
+  password = jsondecode(data.aws_secretsmanager_secret_version.db.secret_string)["password"]
+  ```
+
+## 5. Principle of Least Privilege (IAM)
+- **Rule:** Wildcards (`*`) in IAM policies are strictly banned unless absolutely necessary (e.g., specific S3 actions).
+- **BANNED:** Assigning `AmazonS3FullAccess` to a worker node that only needs to read from one bucket.
+- **REQUIRED:** Explicit resource ARNs and explicit Actions.
+  ```hcl
+  statement {
+    effect    = "Allow"
+    actions   = ["s3:GetObject"]
+    resources = ["arn:aws:s3:::my-specific-bucket/uploads/*"]
+  }
+  ```
+
+## 6. Immutable Infrastructure
+- **Rule:** If a server is unhealthy, terminate it. Do not SSH into it to fix it.
+- **Rule:** Use Auto Scaling Groups (ASGs) even if the desired capacity is 1. This ensures the component is self-healing.

package/.agent-context/blueprints/kubernetes-manifests.md

@@ -0,0 +1,76 @@
+# Kubernetes Manifests Blueprint
+
+> Kubernetes is a declarative state machine. Tell it what you want, not how to do it.
+
+## 1. Bare Minimum Requirements
+Every application deployed to Kubernetes MUST include at minimum:
+1. `Deployment` (or `StatefulSet`/`DaemonSet`)
+2. `Service`
+3. `ConfigMap` (for non-sensitive config)
+4. `Secret` (managed externally, e.g., via ExternalSecrets)
+5. `Ingress` (or `Gateway APIRoute`)
+
+## 2. Resource Limits & Requests (Mandatory)
+A container without resource limits is a noisy neighbor that will eventually crash the node.
+- **Rule:** EVERY container in a Pod MUST have BOTH `requests` and `limits` defined for CPU and Memory.
+- **BANNED:** Omitting the `resources` block.
+- **REQUIRED:**
+  ```yaml
+  resources:
+    requests:
+      memory: "256Mi"
+      cpu: "100m"
+    limits:
+      memory: "512Mi"
+      cpu: "500m"
+  ```
+
+## 3. Liveness & Readiness Probes (Mandatory)
+Kubernetes needs to know when your app is ready to serve traffic and if it needs to be restarted.
+- **Rule:** EVERY container MUST define a `readinessProbe` and a `livenessProbe`.
+- **BANNED:** Assuming the container is ready just because the process started.
+- **REQUIRED:**
+  ```yaml
+  livenessProbe:
+    httpGet:
+      path: /healthz
+      port: 8080
+    initialDelaySeconds: 5
+    periodSeconds: 10
+  readinessProbe:
+    httpGet:
+      path: /ready
+      port: 8080
+    initialDelaySeconds: 5
+    periodSeconds: 5
+  ```
+
+## 4. The `latest` Tag Fallacy
+- **Rule:** NEVER use the `:latest` tag for container images in production.
+- **Why:** Deployments containing the `latest` tag cannot be easily rolled back, and nodes may cache different versions of `latest`.
+- **REQUIRED:** Use explicit semantic versioning (`:v1.2.3`) or Git SHA hashes (`:sha-7a8f9b`).
+
+## 5. Configuration & Secrets Management
+- **Rule:** Application configuration must be injected via Environment Variables originating from `ConfigMaps` or `Secrets`.
+- **BANNED:** Hardcoding environment variables in the `Deployment` manifest.
+- **BANNED:** Storing Base64-encoded `Secret` manifests in version control.
+- **REQUIRED:** Use tools like `External Secrets Operator` to pull secrets from AWS Secrets Manager / HashiCorp Vault into the cluster securely.
+  ```yaml
+  envFrom:
+    - configMapRef:
+        name: app-config
+    - secretRef:
+        name: app-secrets
+  ```
+
+## 6. Security Context
+By default, containers run as `root`. This is a massive security risk.
+- **Rule:** Containers MUST run as a non-root user. The filesystem should be read-only where possible.
+- **REQUIRED:**
+  ```yaml
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    readOnlyRootFilesystem: true
+    allowPrivilegeEscalation: false
+  ```

package/.agent-context/blueprints/laravel-api.md

@@ -0,0 +1,223 @@
+# Blueprint: Laravel API
+
+> PHP backend API service using Laravel 12, PHP 8.5+, Form Requests, Eloquent, and Scribe for docs.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Laravel 12 |
+| Validation | Form Requests |
+| ORM | Eloquent |
+| Migration | Laravel Migrations |
+| Testing | Pest PHP |
+| Static analysis | PHPStan (level 8) |
+| Formatting | Laravel Pint |
+| API docs | Scribe |
+
+---
+
+## Project Structure
+
+```
+project-name/
+├── app/
+│   ├── Modules/
+│   │   └── User/
+│   │       ├── Controllers/
+│   │       │   └── UserController.php
+│   │       ├── Services/
+│   │       │   └── UserService.php
+│   │       ├── Repositories/
+│   │       │   └── UserRepository.php
+│   │       ├── Requests/
+│   │       │   ├── StoreUserRequest.php
+│   │       │   └── UpdateUserRequest.php
+│   │       ├── Resources/
+│   │       │   └── UserResource.php
+│   │       ├── Models/
+│   │       │   └── User.php
+│   │       ├── Policies/
+│   │       │   └── UserPolicy.php
+│   │       └── Exceptions/
+│   │           └── UserNotFoundException.php
+│   │
+│   ├── Shared/
+│   │   ├── Exceptions/
+│   │   │   └── Handler.php
+│   │   └── Traits/
+│   │       └── ApiResponse.php
+│   │
+│   └── Providers/
+│
+├── database/
+│   ├── factories/
+│   │   └── UserFactory.php
+│   ├── migrations/
+│   └── seeders/
+│
+├── routes/
+│   └── api.php
+│
+├── tests/
+│   ├── Feature/
+│   │   └── User/
+│   │       └── UserEndpointTest.php
+│   └── Unit/
+│       └── User/
+│           └── UserServiceTest.php
+│
+├── phpstan.neon
+├── .env.example
+├── composer.json
+└── Dockerfile
+```
+
+---
+
+## File Patterns
+
+### Controller — Thin Transport Layer
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\User\Controllers;
+
+use App\Modules\User\Requests\StoreUserRequest;
+use App\Modules\User\Resources\UserResource;
+use App\Modules\User\Services\UserService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Symfony\Component\HttpFoundation\Response;
+
+final class UserController
+{
+    public function __construct(
+        private readonly UserService $userService,
+    ) {}
+
+    public function store(StoreUserRequest $request): JsonResponse
+    {
+        $user = $this->userService->create($request->validated());
+
+        return (new UserResource($user))
+            ->response()
+            ->setStatusCode(Response::HTTP_CREATED);
+    }
+
+    public function index(): AnonymousResourceCollection
+    {
+        return UserResource::collection(
+            $this->userService->listPaginated()
+        );
+    }
+}
+```
+
+### Form Request — Boundary Validation
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\User\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+final class StoreUserRequest extends FormRequest
+{
+    /** @return array<string, array<int, string>> */
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:100'],
+            'email' => ['required', 'email', 'unique:users,email'],
+            'password' => ['required', 'string', 'min:8', 'confirmed'],
+        ];
+    }
+}
+```
+
+### Service — Business Logic
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\User\Services;
+
+use App\Modules\User\Models\User;
+use App\Modules\User\Repositories\UserRepository;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Log;
+
+final class UserService
+{
+    public function __construct(
+        private readonly UserRepository $userRepository,
+    ) {}
+
+    /** @param array{name: string, email: string, password: string} $data */
+    public function create(array $data): User
+    {
+        $data['password'] = Hash::make($data['password']);
+        $user = $this->userRepository->create($data);
+
+        Log::info('User created', ['user_id' => $user->id, 'email' => $user->email]);
+
+        return $user;
+    }
+
+    public function listPaginated(int $perPage = 15): LengthAwarePaginator
+    {
+        return $this->userRepository->paginate($perPage);
+    }
+}
+```
+
+### API Resource — Response Transformer
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Modules\User\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin \App\Modules\User\Models\User */
+final class UserResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->email,
+            'created_at' => $this->created_at?->toISOString(),
+        ];
+        // NEVER expose: password, remember_token, email_verified_at (unless needed)
+    }
+}
+```
+
+---
+
+## Scaffolding Checklist
+
+- [ ] Create Laravel project: `composer create-project laravel/laravel`
+- [ ] Set up modular structure under `app/Modules/`
+- [ ] Create shared error handler with consistent JSON responses
+- [ ] Create shared `ApiResponse` trait for standard response format
+- [ ] Install and configure PHPStan level 8
+- [ ] Install and configure Laravel Pint
+- [ ] Install Pest PHP for testing
+- [ ] Install Scribe for API documentation
+- [ ] Create first module following the pattern above
+- [ ] Create `.env.example` with all required variables
+- [ ] Run `php artisan test`, `./vendor/bin/phpstan`, `./vendor/bin/pint` — zero errors

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

@@ -0,0 +1,247 @@
+# 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`