@ryuenn3123/agentic-senior-core 1.8.0

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

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

@@ -0,0 +1,218 @@
+# 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/policies/llm-judge-threshold.json

@@ -0,0 +1,20 @@
+{
+  "selectedProfile": "balanced",
+  "profileThresholds": {
+    "beginner": {
+      "blockingSeverities": ["critical"],
+      "failOnMalformedResponse": false,
+      "failOnProviderError": false
+    },
+    "balanced": {
+      "blockingSeverities": ["critical", "high"],
+      "failOnMalformedResponse": true,
+      "failOnProviderError": false
+    },
+    "strict": {
+      "blockingSeverities": ["critical", "high", "medium"],
+      "failOnMalformedResponse": true,
+      "failOnProviderError": true
+    }
+  }
+}

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

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

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

@@ -0,0 +1,13 @@
+# Team Profile Pack: Regulated
+
+slug: regulated
+displayName: Regulated Team
+description: Compliance-first defaults with strict policy and locked CI guardrails.
+defaultProfile: strict
+defaultStack: typescript.md
+defaultBlueprint: api-nextjs.md
+ciGuardrails: true
+lockCi: true
+blockingSeverities: critical, high, medium
+owner: governance-office
+lastUpdated: 2026-03-19

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

@@ -0,0 +1,13 @@
+# Team Profile Pack: Startup
+
+slug: startup
+displayName: Startup Team
+description: Fast iteration with balanced guardrails and quick onboarding defaults.
+defaultProfile: balanced
+defaultStack: typescript.md
+defaultBlueprint: api-nextjs.md
+ciGuardrails: true
+lockCi: false
+blockingSeverities: critical, high
+owner: product-engineering
+lastUpdated: 2026-03-19

package/.agent-context/prompts/init-project.md

@@ -0,0 +1,86 @@
+# Prompts: Initialize Project
+
+> Copy-paste one of these prompts to your AI agent (Cursor, Windsurf, Copilot, Antigravity) right after cloning this repository.
+> V1.4 recommendation: run `bunx @fatidaprilian/agentic-senior-core init` first to compile dynamic governance context.
+
+---
+
+## Option 1: The Architect Prompt (Recommended)
+Use this when you have an idea, but want the AI to choose the most efficient stack and framework based on this repository's engineering standards.
+
+```text
+I want to build a [DESCRIBE YOUR PROJECT AND MAIN FEATURES HERE].
+
+Context: You are a Principal Software Architect operating in a workspace with strict engineering standards.
+
+Step 1: Context Gathering
+1. Read `AGENTS.md` to understand your role and available knowledge base.
+2. Scan all files in `.agent-context/rules/` to understand our mandatory engineering laws.
+3. Review the available technology stacks in `.agent-context/stacks/` and blueprints in `.agent-context/blueprints/`.
+
+Step 2: Architecture Proposal
+Based strictly on my project description and our repository's existing rules (especially `efficiency-vs-hype.md`):
+1. Propose the most efficient technology stack from our approved profiles.
+2. Explain WHY this stack is the best choice for this specific project.
+3. Draft a high-level architecture plan.
+
+Do not write any application code yet. Write your proposal and wait for my approval. Once I approve, you will scaffold the project using the relevant blueprint.
+```
+
+---
+
+## Option 2: The Direct Blueprint Prompt
+Use this when you already know exactly which framework you want to use from the available blueprints.
+
+```text
+I want to build [PROJECT NAME].
+
+Before writing any code:
+1. Read `AGENTS.md` to understand your role.
+2. Read ALL files in `.agent-context/rules/` to understand our engineering standards.
+3. Read `.agent-context/stacks/[STACK].md` for language-specific guidelines.
+4. Read `.agent-context/blueprints/[BLUEPRINT].md` for the project structure.
+
+Now scaffold the initial project structure following the blueprint exactly:
+- Create all directories and files from the blueprint
+- Set up the environment config and validation (e.g., Zod, Pydantic, FluentValidation)
+- Set up the error handling foundation (base error class + global handler)
+- Set up the logger
+- Create a health check endpoint
+- Initialize the ORM/Database connection
+
+Every file MUST follow the naming conventions from rules/naming-conv.md.
+Every module MUST follow the architecture from rules/architecture.md.
+Every dependency MUST be justified per rules/efficiency-vs-hype.md.
+```
+
+---
+
+## Available Stacks & Blueprints Reference
+
+### Stacks (`[STACK].md`)
+- `typescript`
+- `python`
+- `java`
+- `php`
+- `go`
+- `csharp`
+- `rust`
+- `ruby`
+
+### Blueprints (`[BLUEPRINT].md`)
+| Blueprint | Use When |
+|-----------|----------|
+| `api-nextjs` | Next.js App Router API project |
+| `nestjs-logic` | NestJS backend service |
+| `fastapi-service` | Python FastAPI backend service |
+| `laravel-api` | PHP Laravel 12 API |
+| `spring-boot-api`| Java Spring Boot 4 API |
+| `go-service` | Go chi HTTP service |
+| `aspnet-api` | C# ASP.NET Minimal API |
+| `ci-github-actions`| GitHub Actions CI/CD pipeline |
+| `ci-gitlab`      | GitLab CI/CD pipeline |
+| `observability`  | OpenTelemetry stack |
+| `graphql-grpc-api` | GraphQL / gRPC API definitions |
+| `infrastructure-as-code` | Infrastructure as Code (Terraform | Pulumi) |
+| `kubernetes-manifests` | Kubernetes manifests structure |

package/.agent-context/prompts/refactor.md

@@ -0,0 +1,45 @@
+# Prompt: Refactor Code
+
+> Copy-paste this prompt when code needs restructuring to follow the rules.
+
+---
+
+## The Prompt
+
+```
+Refactor the following code (or module) to comply with our engineering standards.
+
+Before making changes:
+1. Read .agent-context/rules/architecture.md — ensure proper layer separation.
+2. Read .agent-context/rules/naming-conv.md — fix all naming violations.
+3. Read .agent-context/rules/error-handling.md — fix error handling patterns.
+4. Read .agent-context/stacks/typescript.md — fix TypeScript-specific issues.
+
+For every change you make, provide a Reasoning Chain:
+- What was wrong (rule reference)
+- Why it was wrong (explain the risk/problem)
+- What you changed (show the improvement)
+
+Maintain ALL existing functionality. This is a refactor, not a rewrite.
+Add or update tests if the refactored code changes behavior contracts.
+```
+
+## Extract Module Prompt
+
+```
+Extract [FEATURE_NAME] into its own module following .agent-context/rules/architecture.md:
+
+1. Create the module directory: src/modules/[feature-name]/
+2. Separate into layers:
+   - controller (transport — HTTP in/out only)
+   - service (business logic — no HTTP, no SQL)
+   - repository (data access — no business rules)
+   - dto (Zod schemas for input validation)
+   - types (type definitions)
+3. Create barrel export (index.ts) exposing ONLY the public API
+4. Update imports in consuming modules to use the new module path
+5. Add unit tests for the service layer
+
+Follow naming-conv.md for all file and variable names.
+Provide a Reasoning Chain for every structural decision.
+```

package/.agent-context/prompts/review-code.md

@@ -0,0 +1,47 @@
+# Prompt: Review Code
+
+> Copy-paste this prompt when you want the AI to self-review its own code
+> or review code you've written.
+
+---
+
+## The Prompt
+
+```
+Run a comprehensive code review on the current codebase (or the files I'm about to show you).
+
+Use these checklists:
+1. Read .agent-context/review-checklists/pr-checklist.md — apply every item.
+2. Read .agent-context/review-checklists/security-audit.md — apply every item.
+
+For EVERY violation found:
+- State the exact file and line
+- Reference the specific rule (file + section)
+- Explain WHY it's a problem (not just "it violates the rule")
+- Provide the corrected code
+
+Output format:
+## PR REVIEW RESULTS
+✅ [Item] — Passes
+❌ [Item] — FAILS (with Reasoning Chain)
+
+## SECURITY AUDIT RESULTS
+🔴/🟠/🟡/🟢 [Finding] — severity + fix
+
+VERDICT: PASS / FAIL
+```
+
+## Quick Review (Subset)
+
+If you want a faster review focusing on the most critical items:
+
+```
+Quick review the current code. Check ONLY:
+1. Any use of `any` type? (rules/stacks/typescript.md)
+2. Any empty catch blocks? (rules/error-handling.md)
+3. Any N+1 queries? (rules/performance.md)
+4. Any hardcoded secrets? (rules/security.md)
+5. Any missing input validation? (rules/security.md)
+
+Use the Reasoning Clause for every finding.
+```