@ryuenn3123/agentic-senior-core 1.8.0

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

@@ -0,0 +1,184 @@
+# Blueprint: Next.js API Project (App Router)
+
+> This blueprint defines how to scaffold a Next.js API project from scratch.
+> Follow this structure exactly. Do not deviate.
+
+## Tech Stack
+- **Runtime:** Node.js 20+ / Bun
+- **Framework:** Next.js 14+ (App Router)
+- **Validation:** Zod
+- **ORM:** Prisma (or Drizzle)
+- **Auth:** NextAuth.js v5 / Lucia Auth
+- **Testing:** Vitest
+
+## Project Structure
+
+```
+project-name/
+├── src/
+│   ├── app/                            # Next.js App Router
+│   │   ├── api/                        # API routes
+│   │   │   ├── auth/
+│   │   │   │   └── [...nextauth]/
+│   │   │   │       └── route.ts        # Auth handler
+│   │   │   ├── users/
+│   │   │   │   ├── route.ts            # GET /api/users, POST /api/users
+│   │   │   │   └── [id]/
+│   │   │   │       └── route.ts        # GET/PUT/DELETE /api/users/:id
+│   │   │   └── health/
+│   │   │       └── route.ts            # GET /api/health
+│   │   ├── layout.tsx                  # Root layout
+│   │   └── page.tsx                    # Root page
+│   │
+│   ├── modules/                        # Feature modules (domain-driven)
+│   │   ├── user/
+│   │   │   ├── user.service.ts         # Business logic
+│   │   │   ├── user.repository.ts      # Data access
+│   │   │   ├── user.schema.ts          # Zod schemas + DTOs
+│   │   │   ├── user.types.ts           # Type definitions
+│   │   │   └── __tests__/
+│   │   │       └── user.service.test.ts
+│   │   └── order/
+│   │       ├── order.service.ts
+│   │       ├── order.repository.ts
+│   │       ├── order.schema.ts
+│   │       └── order.types.ts
+│   │
+│   ├── shared/                         # Cross-cutting concerns
+│   │   ├── config/
+│   │   │   └── env.ts                  # Zod-validated environment variables
+│   │   ├── errors/
+│   │   │   ├── app-error.ts            # Base error class
+│   │   │   └── error-handler.ts        # Global error handler for API routes
+│   │   ├── middleware/
+│   │   │   ├── auth.ts                 # Auth middleware
+│   │   │   └── validate.ts             # Request validation middleware
+│   │   ├── lib/
+│   │   │   ├── prisma.ts              # Prisma client singleton
+│   │   │   └── logger.ts              # Pino logger setup
+│   │   └── types/
+│   │       └── api.ts                  # Shared API types (ApiResponse, etc.)
+│   │
+│   └── components/                     # UI components (if full-stack)
+│       ├── ui/                         # Primitives
+│       └── layout/                     # Layout components
+│
+├── prisma/
+│   ├── schema.prisma                   # Database schema
+│   └── migrations/                     # Database migrations
+│
+├── public/                             # Static assets
+├── .env.example                        # Environment template
+├── .eslintrc.json                      # ESLint config
+├── .prettierrc                         # Prettier config
+├── next.config.mjs                     # Next.js config
+├── tsconfig.json                       # TypeScript config (strict!)
+├── vitest.config.ts                    # Vitest config
+└── package.json
+```
+
+## API Route Handler Pattern
+
+```typescript
+// src/app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { CreateUserSchema } from '@/modules/user/user.schema';
+import { userService } from '@/modules/user/user.service';
+import { handleApiError } from '@/shared/errors/error-handler';
+
+export async function GET(request: NextRequest) {
+  try {
+    const searchParams = request.nextUrl.searchParams;
+    const page = Number(searchParams.get('page') ?? '1');
+    const limit = Number(searchParams.get('limit') ?? '20');
+
+    const users = await userService.findAll({ page, limit });
+    return NextResponse.json({ data: users });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const parsed = CreateUserSchema.safeParse(body);
+
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: { code: 'VALIDATION_ERROR', details: parsed.error.flatten() } },
+        { status: 400 },
+      );
+    }
+
+    const user = await userService.create(parsed.data);
+    return NextResponse.json({ data: user }, { status: 201 });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+```
+
+## Environment Validation Pattern
+
+```typescript
+// src/shared/config/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  DATABASE_URL: z.string().url(),
+  NEXTAUTH_SECRET: z.string().min(32),
+  NEXTAUTH_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+});
+
+export const env = envSchema.parse(process.env);
+export type Env = z.infer<typeof envSchema>;
+```
+
+## Error Handler Pattern
+
+```typescript
+// src/shared/errors/error-handler.ts
+import { NextResponse } from 'next/server';
+import { AppError } from './app-error';
+import { logger } from '@/shared/lib/logger';
+
+export function handleApiError(error: unknown): NextResponse {
+  if (error instanceof AppError) {
+    logger.warn('Application error', {
+      code: error.code,
+      message: error.message,
+      context: error.context,
+    });
+
+    return NextResponse.json(
+      { error: { code: error.code, message: error.message } },
+      { status: error.statusCode },
+    );
+  }
+
+  logger.error('Unhandled error', {
+    error: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+  });
+
+  return NextResponse.json(
+    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },
+    { status: 500 },
+  );
+}
+```
+
+## Scaffolding Checklist
+
+When using this blueprint, verify:
+- [ ] `tsconfig.json` has `"strict": true` and all recommended flags
+- [ ] `.env.example` exists with ALL required variables (placeholder values only)
+- [ ] Prisma client is a singleton (not re-created per request)
+- [ ] All API routes use Zod validation at the boundary
+- [ ] Error handler is used in every route (no unhandled errors)
+- [ ] Logger is configured (not `console.log`)
+- [ ] Path aliases (`@/`) are configured in tsconfig AND next.config
+- [ ] API documentation is generated or maintained alongside routes

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

@@ -0,0 +1,247 @@
+# Blueprint: ASP.NET Minimal API (.NET 10)
+
+> Minimal APIs are not "simple APIs". They're production-ready APIs with less ceremony.
+> Controller bloat is not a feature.
+
+## Tech Stack
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Runtime | .NET 10 LTS | Latest LTS (Nov 2025) |
+| Language | C# 14 | Records, primary constructors, required members |
+| API Style | Minimal APIs with `MapGroup` | Less boilerplate, same power |
+| Validation | FluentValidation | Fluent, testable, powerful |
+| ORM | EF Core 10 | Mature, LINQ-to-SQL, migrations |
+| Auth | ASP.NET Identity + Passkeys | Built-in, modern auth |
+| API Docs | Swashbuckle / NSwag + Scalar | OpenAPI 3.1 generation |
+| Testing | xUnit + NSubstitute + Verify | Community standard |
+| Logging | Serilog + OpenTelemetry | Structured, correlated |
+| Cloud | .NET Aspire (optional) | Service orchestration, dev containers |
+
+## Project Structure
+
+```
+MyApp.sln
+├── src/
+│   ├── MyApp.Api/                      # Presentation layer
+│   │   ├── Program.cs                  # Entry point + DI + middleware
+│   │   ├── Endpoints/                  # Minimal API endpoint groups
+│   │   │   ├── UserEndpoints.cs
+│   │   │   └── OrderEndpoints.cs
+│   │   ├── Filters/                    # Endpoint filters (auth, validation)
+│   │   ├── Models/                     # Request/response DTOs
+│   │   │   ├── Requests/
+│   │   │   └── Responses/
+│   │   ├── appsettings.json
+│   │   └── MyApp.Api.csproj
+│   │
+│   ├── MyApp.Application/             # Business logic layer
+│   │   ├── Services/
+│   │   │   ├── IUserService.cs
+│   │   │   └── UserService.cs
+│   │   ├── Validators/
+│   │   │   └── CreateUserValidator.cs
+│   │   ├── Mappings/                   # Entity ↔ DTO mapping
+│   │   └── MyApp.Application.csproj
+│   │
+│   ├── MyApp.Domain/                   # Core domain (zero dependencies)
+│   │   ├── Entities/
+│   │   │   ├── User.cs
+│   │   │   └── Order.cs
+│   │   ├── ValueObjects/
+│   │   ├── Enums/
+│   │   ├── Errors/
+│   │   │   └── DomainErrors.cs
+│   │   └── MyApp.Domain.csproj
+│   │
+│   └── MyApp.Infrastructure/          # Data access + external services
+│       ├── Persistence/
+│       │   ├── AppDbContext.cs
+│       │   ├── Configurations/         # EF Core entity configs
+│       │   │   └── UserConfiguration.cs
+│       │   ├── Repositories/
+│       │   │   └── UserRepository.cs
+│       │   └── Migrations/
+│       ├── Services/                   # External service adapters
+│       └── MyApp.Infrastructure.csproj
+│
+├── tests/
+│   ├── MyApp.UnitTests/
+│   ├── MyApp.IntegrationTests/
+│   └── MyApp.ArchitectureTests/        # Enforce layer boundaries
+│
+├── Directory.Build.props               # Central package versions
+├── .editorconfig
+└── Dockerfile
+```
+
+## Key Patterns
+
+### Endpoint Groups with MapGroup
+
+```csharp
+// Endpoints/UserEndpoints.cs
+public static class UserEndpoints
+{
+    public static RouteGroupBuilder MapUserEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/users")
+            .WithTags("Users")
+            .RequireAuthorization();
+
+        group.MapGet("/", GetAllUsers)
+            .WithName("GetAllUsers")
+            .WithSummary("Get all users with pagination")
+            .Produces<PagedResponse<UserResponse>>(200);
+
+        group.MapGet("/{id:guid}", GetUserById)
+            .WithName("GetUserById")
+            .Produces<UserResponse>(200)
+            .ProducesProblem(404);
+
+        group.MapPost("/", CreateUser)
+            .WithName("CreateUser")
+            .Produces<UserResponse>(201)
+            .ProducesValidationProblem();
+
+        return group;
+    }
+
+    private static async Task<IResult> GetUserById(
+        Guid id,
+        IUserService userService,
+        CancellationToken ct)
+    {
+        var user = await userService.GetByIdAsync(id, ct);
+        return user is not null
+            ? TypedResults.Ok(user.ToResponse())
+            : TypedResults.Problem(statusCode: 404, title: "User not found");
+    }
+
+    private static async Task<IResult> CreateUser(
+        CreateUserRequest request,
+        IValidator<CreateUserRequest> validator,
+        IUserService userService,
+        CancellationToken ct)
+    {
+        var validation = await validator.ValidateAsync(request, ct);
+        if (!validation.IsValid)
+            return TypedResults.ValidationProblem(validation.ToDictionary());
+
+        var user = await userService.CreateAsync(request, ct);
+        return TypedResults.Created($"/api/users/{user.Id}", user.ToResponse());
+    }
+}
+```
+
+### Program.cs (Clean Composition Root)
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Service registration (extension methods from each layer)
+builder.Services.AddApplicationServices();
+builder.Services.AddInfrastructureServices(builder.Configuration);
+builder.Services.AddApiServices();
+
+// OpenTelemetry
+builder.Services.AddOpenTelemetry()
+    .WithTracing(tracing => tracing
+        .AddAspNetCoreInstrumentation()
+        .AddEntityFrameworkCoreInstrumentation()
+        .AddOtlpExporter())
+    .WithMetrics(metrics => metrics
+        .AddAspNetCoreInstrumentation()
+        .AddOtlpExporter());
+
+var app = builder.Build();
+
+// Middleware pipeline
+app.UseExceptionHandler();
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Map endpoints
+app.MapUserEndpoints();
+app.MapOrderEndpoints();
+app.MapHealthChecks("/health");
+
+// Scalar API docs
+app.MapScalarApiReference();
+
+app.Run();
+```
+
+### Domain Entity (Record-Based)
+
+```csharp
+// Domain/Entities/User.cs
+public sealed class User
+{
+    public required Guid Id { get; init; }
+    public required string Email { get; init; }
+    public required string DisplayName { get; set; }
+    public DateTimeOffset CreatedAt { get; init; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset? DeletedAt { get; private set; }
+
+    public void SoftDelete() => DeletedAt = DateTimeOffset.UtcNow;
+}
+```
+
+### FluentValidation
+
+```csharp
+// Application/Validators/CreateUserValidator.cs
+public sealed class CreateUserValidator : AbstractValidator<CreateUserRequest>
+{
+    public CreateUserValidator()
+    {
+        RuleFor(x => x.Email)
+            .NotEmpty()
+            .EmailAddress()
+            .MaximumLength(256);
+
+        RuleFor(x => x.DisplayName)
+            .NotEmpty()
+            .MinimumLength(1)
+            .MaximumLength(100);
+    }
+}
+```
+
+## .NET Aspire (Optional, for Multi-Service)
+
+For projects with multiple services, databases, and caches:
+
+```csharp
+// AppHost/Program.cs
+var builder = DistributedApplication.CreateBuilder(args);
+
+var postgres = builder.AddPostgres("db")
+    .AddDatabase("myapp");
+
+var redis = builder.AddRedis("cache");
+
+builder.AddProject<Projects.MyApp_Api>("api")
+    .WithReference(postgres)
+    .WithReference(redis);
+
+builder.Build().Run();
+```
+
+## Scaffolding Checklist
+
+- [ ] Create solution with 4 projects (Api, Application, Domain, Infrastructure)
+- [ ] Configure `Directory.Build.props` for shared package versions
+- [ ] Set up `Program.cs` with clean service registration
+- [ ] Create endpoint groups using `MapGroup` pattern
+- [ ] Configure EF Core with typed `DbContext` and entity configurations
+- [ ] Add FluentValidation with automatic registration
+- [ ] Set up Serilog with structured logging
+- [ ] Configure OpenTelemetry tracing and metrics
+- [ ] Add Scalar or Swagger for OpenAPI documentation
+- [ ] Create health check endpoint (`/health`)
+- [ ] Set up xUnit test projects with NSubstitute
+- [ ] Add architecture tests (enforce layer boundaries)
+- [ ] Create `Dockerfile` (multi-stage build)
+- [ ] Enable nullable reference types project-wide

package/.agent-context/blueprints/ci-github-actions.md

@@ -0,0 +1,226 @@
+# Blueprint: GitHub Actions CI/CD Pipeline
+
+> Automate everything. Trust nothing. Ship with confidence.
+
+## Tech Stack
+
+| Layer | Tool |
+|-------|------|
+| CI/CD | GitHub Actions |
+| Runners | GitHub-hosted (ubuntu-latest) |
+| Caching | actions/cache, setup-node cache |
+| Security | OIDC for cloud auth, pinned action SHAs |
+| Artifacts | actions/upload-artifact |
+
+## Pipeline Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    PR / Push Trigger                      │
+├──────────┬──────────┬──────────┬──────────┬─────────────┬─────────────┤
+│   Lint   │  Build   │   Test   │ Security │   Docs      │  LLM Judge  │
+│ (ESLint/ │ (tsc /   │ (Vitest/ │ (Audit / │ (OpenAPI    │ (Checklist  │
+│  ruff)   │  build)  │  pytest) │  Trivy)  │  validate)  │ enforcement)│
+├──────────┴──────────┴──────────┴──────────┴─────────────┴─────────────┤
+│              Gate: All jobs must pass                     │
+├─────────────────────────────────────────────────────────┤
+│              Deploy (on main only)                       │
+│  Staging → Smoke Tests → Production (manual approval)   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Required Workflows
+
+### 1. CI Workflow (`ci.yml`)
+
+Runs on every PR and push to main.
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run type-check
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test -- --coverage
+      - uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: coverage
+          path: coverage/
+
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - run: npm audit --audit-level=high
+      # Add Trivy, CodeQL, or Snyk as needed
+
+  build:
+    needs: [lint, test, security]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@<pin-sha>
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: build
+          path: dist/
+
+  llm-judge:
+    needs: [lint, test, security, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 12
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+      GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      GITHUB_HEAD_SHA: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@<pin-sha>
+        with:
+          fetch-depth: 0   # Full history required for accurate git diff
+      - uses: actions/setup-node@<pin-sha>
+        with:
+          node-version: '22'
+      - name: Run LLM Judge
+        run: node scripts/llm-judge.mjs
+      - name: Upload LLM Judge machine report
+        if: always()
+        uses: actions/upload-artifact@<pin-sha>
+        with:
+          name: llm-judge-report
+          path: .agent-context/state/llm-judge-report.json
+```
+
+### 2. Deploy Workflow (`deploy.yml`)
+
+Runs on push to main (after CI passes).
+
+```yaml
+name: Deploy
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  id-token: write   # OIDC
+  contents: read
+
+jobs:
+  deploy-staging:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      # Authenticate via OIDC — no static secrets
+      # Deploy to staging
+      # Run smoke tests against staging
+
+  deploy-production:
+    needs: deploy-staging
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: https://your-app.com
+    steps:
+      # Deploy to production
+      # Run health checks
+      # Notify team (Slack, Discord)
+```
+
+## Security Rules
+
+1. **Pin actions to commit SHA** — not `@v3`, not `@latest`
+2. **Use OIDC** for cloud provider auth — delete static credentials
+3. **Minimal permissions** — set `permissions:` at workflow level, least privilege
+4. **Never print secrets** — GitHub masks them in logs, but don't `echo` them
+5. **Restrict self-hosted runners** — ephemeral containers only, never persistent VMs
+6. **Require PR approval** for workflows from forks
+7. **Minimize prompt scope** — send diff + checklist only, never full secret-bearing config
+
+## LLM Judge Annotation Contract
+
+The judge emits a machine-friendly payload line and artifact that can be consumed by annotation scripts:
+
+- Log line: `JSON_REPORT: { ... }`
+- Artifact file: `.agent-context/state/llm-judge-report.json`
+- Normalized severity values: `critical`, `high`, `medium`, `low`
+- Override artifact path (optional): `LLM_JUDGE_OUTPUT_PATH`
+
+## Efficiency Rules
+
+1. **Cache dependencies** — `actions/cache` or setup-action built-in cache
+2. **Use concurrency** — cancel previous runs on the same branch
+3. **Set timeouts** — prevent stuck jobs from burning minutes
+4. **Matrix builds** for multi-platform/version testing
+5. **Reusable workflows** — centralize common pipelines in a `.github` repo
+6. **Skip unnecessary jobs** — use path filters for targeted CI
+
+```yaml
+# Example: Only run frontend tests when frontend code changes
+on:
+  push:
+    paths:
+      - 'src/frontend/**'
+      - 'package.json'
+```
+
+## Scaffolding Checklist
+
+When setting up GitHub Actions for a new project:
+
+- [ ] Create `.github/workflows/ci.yml` with lint, test, build, security
+- [ ] Create `.github/workflows/deploy.yml` with staging + production
+- [ ] Pin ALL third-party actions to commit SHA
+- [ ] Set `permissions: contents: read` at workflow level
+- [ ] Configure `concurrency` to cancel in-progress runs
+- [ ] Add `timeout-minutes` to every job
+- [ ] Set up caching for package manager
+- [ ] Configure environment protection rules for production
+- [ ] Create `.nvmrc` or `.tool-versions` for runtime version
+- [ ] Configure branch protection: require CI pass before merge
+- [ ] Add `llm-judge` job that evaluates PR against `pr-checklist.md`