@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/stacks/go.md

@@ -0,0 +1,181 @@
+# Go Stack Profile — Simple, Explicit, Fast
+
+> Go's superpower is simplicity. Don't fight it.
+> No magic, no abstractions for the sake of abstractions.
+
+## Core Principles
+
+1. **Accept interfaces, return structs** — keep APIs flexible, implementations concrete
+2. **Errors are values** — handle them explicitly, don't panic
+3. **Stdlib first** — Go's standard library is excellent, use it before reaching for packages
+4. **Small interfaces** — 1-2 methods max. `io.Reader` has one method for a reason
+
+---
+
+## Error Handling (The Go Way)
+
+### Rule: Always Check Errors, Never Ignore
+
+```go
+// BANNED: Ignoring errors
+result, _ := doSomething()
+json.Unmarshal(data, &out)  // Error silently ignored
+
+// REQUIRED: Handle every error
+result, err := doSomething()
+if err != nil {
+    return fmt.Errorf("failed to do something: %w", err)
+}
+```
+
+### Wrapping Errors for Context
+```go
+// BANNED: Bare error return
+if err != nil {
+    return err  // Caller has no idea where this came from
+}
+
+// REQUIRED: Wrap with context using %w
+if err != nil {
+    return fmt.Errorf("creating user %q: %w", req.Email, err)
+}
+// Produces: "creating user "jane@example.com": duplicate key value"
+```
+
+### Custom Error Types
+```go
+type NotFoundError struct {
+    Resource string
+    ID       string
+}
+
+func (e *NotFoundError) Error() string {
+    return fmt.Sprintf("%s not found: %s", e.Resource, e.ID)
+}
+
+// Check with errors.As
+var notFound *NotFoundError
+if errors.As(err, &notFound) {
+    http.Error(w, notFound.Error(), http.StatusNotFound)
+}
+```
+
+---
+
+## Project Structure
+
+```
+project-name/
+├── cmd/
+│   └── server/
+│       └── main.go                     # Entry point
+│
+├── internal/                           # Private application code
+│   ├── user/
+│   │   ├── handler.go                  # HTTP handlers (transport)
+│   │   ├── service.go                  # Business logic
+│   │   ├── repository.go              # Data access
+│   │   ├── model.go                    # Domain types
+│   │   └── user_test.go               # Tests alongside code
+│   │
+│   ├── order/
+│   │   └── ...
+│   │
+│   └── platform/                       # Cross-cutting infrastructure
+│       ├── config/
+│       │   └── config.go               # Env-validated configuration
+│       ├── database/
+│       │   └── postgres.go             # DB connection setup
+│       ├── logger/
+│       │   └── logger.go               # Structured logging (slog)
+│       └── middleware/
+│           ├── auth.go
+│           └── logging.go
+│
+├── api/                                # API definitions (OpenAPI, proto)
+│   └── openapi.yaml
+│
+├── go.mod
+├── go.sum
+├── Makefile                            # Build/test/lint commands
+└── Dockerfile
+```
+
+### Key Rule: `internal/` is Private
+Everything in `internal/` is invisible to external importers. This is Go's built-in encapsulation. Use it.
+
+---
+
+## Interface Design
+
+```go
+// BANNED: Large interfaces
+type UserService interface {
+    Create(ctx context.Context, req CreateUserReq) (*User, error)
+    Update(ctx context.Context, id string, req UpdateUserReq) (*User, error)
+    Delete(ctx context.Context, id string) error
+    GetByID(ctx context.Context, id string) (*User, error)
+    GetByEmail(ctx context.Context, email string) (*User, error)
+    ListAll(ctx context.Context) ([]*User, error)
+    // 10 more methods...
+}
+
+// REQUIRED: Small, focused interfaces (1-3 methods)
+type UserCreator interface {
+    Create(ctx context.Context, req CreateUserReq) (*User, error)
+}
+
+type UserFinder interface {
+    GetByID(ctx context.Context, id string) (*User, error)
+}
+```
+
+**Rule:** Define interfaces where they are CONSUMED, not where they are implemented.
+
+---
+
+## Context Usage
+
+```go
+// REQUIRED: First parameter is always context.Context
+func (s *UserService) Create(ctx context.Context, req CreateUserReq) (*User, error) {
+    // Pass context to all downstream calls
+    user, err := s.repo.Insert(ctx, req)
+    // ...
+}
+
+// BANNED: context.Background() deep inside application code
+// Use it ONLY at the entry point (main, HTTP handler setup, test setup)
+```
+
+---
+
+## Preferred Libraries
+
+| Need | Library | Why |
+|------|---------|-----|
+| HTTP router | `net/http` (Go 1.22+) / `chi` | Stdlib router is now excellent |
+| Logging | `log/slog` (stdlib) | Structured, leveled, built-in since Go 1.21 |
+| Configuration | `caarlos0/env` + struct tags | Simple, typed env parsing |
+| Database | `database/sql` + `pgx` / `sqlc` | `sqlc` generates type-safe Go from SQL |
+| Migration | `golang-migrate/migrate` | SQL-based, driver-agnostic |
+| Testing | stdlib `testing` + `testify` | `testify` for assertions only |
+| Validation | `go-playground/validator` | Struct tag validation |
+| HTTP client | `net/http` (stdlib) | Sufficient for most needs |
+| JSON | `encoding/json` (stdlib) / `json-iterator` | Stdlib first |
+| API docs | `swaggo/swag` | Auto-generates OpenAPI from comments |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| `_ = err` or ignoring error | Silent failures | Always handle `err` |
+| `panic()` in library code | Crashes the program | Return errors |
+| `init()` functions | Hidden side effects, hard to test | Explicit initialization |
+| Global mutable state | Concurrency bugs, untestable | Dependency injection |
+| `interface{}` / `any` everywhere | No type safety | Generics (Go 1.18+) or specific types |
+| ORM magic (GORM) | Hidden queries, N+1 traps | `sqlc` or raw `database/sql` |
+| Huge packages | Violates SRP | Split into focused packages |
+| Shared `utils` package | Kitchen sink, circular deps | Domain-specific helpers |

package/.agent-context/stacks/java.md

@@ -0,0 +1,135 @@
+# Java Stack Profile — Enterprise Without the Bloat
+
+> Java can be clean. It just needs discipline.
+> Stop writing 200-line classes for a 10-line operation.
+
+## Language Version: Java 25+ (LTS)
+
+Java 25 is the latest LTS release (September 2025, supported until 2033). Use modern Java features aggressively. Do not write pre-Java 21 style code.
+
+### Records Over POJOs
+```java
+// BANNED: 80-line POJO with getters, setters, equals, hashCode
+public class UserDto {
+    private String name;
+    private String email;
+    public String getName() { return name; }
+    public void setName(String name) { this.name = name; }
+    // ... 60 more lines of boilerplate
+}
+
+// REQUIRED: Record (immutable, auto-generates equals/hashCode/toString)
+public record UserDto(String name, String email) {}
+```
+
+### Sealed Classes for Domain Variants
+```java
+// Model fixed set of states or outcomes
+public sealed interface PaymentResult
+    permits PaymentResult.Success, PaymentResult.Failed, PaymentResult.Pending {
+
+    record Success(String transactionId, BigDecimal amount) implements PaymentResult {}
+    record Failed(String reason, String errorCode) implements PaymentResult {}
+    record Pending(String retryAfter) implements PaymentResult {}
+}
+```
+
+### Pattern Matching
+```java
+// Use switch expressions with pattern matching (Java 21)
+return switch (result) {
+    case Success s -> ResponseEntity.ok(s);
+    case Failed f -> ResponseEntity.badRequest().body(f.reason());
+    case Pending p -> ResponseEntity.accepted().body(p);
+};
+```
+
+---
+
+## Validation at Boundaries: Jakarta Bean Validation
+
+```java
+public record CreateUserRequest(
+    @NotBlank @Size(max = 100) String name,
+    @NotBlank @Email String email,
+    @Min(13) @Max(150) int age
+) {}
+
+@PostMapping("/users")
+public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest request) {
+    // request is validated by the framework before reaching this method
+    return ResponseEntity.status(201).body(userService.create(request));
+}
+```
+
+---
+
+## Project Structure (Spring Boot 4)
+
+```
+project-name/
+├── src/main/java/com/example/project/
+│   ├── Application.java                    # Entry point
+│   │
+│   ├── modules/
+│   │   ├── user/
+│   │   │   ├── UserController.java         # Transport (REST)
+│   │   │   ├── UserService.java            # Business logic
+│   │   │   ├── UserRepository.java         # Data access (Spring Data)
+│   │   │   ├── dto/
+│   │   │   │   ├── CreateUserRequest.java  # Input validation (record)
+│   │   │   │   └── UserResponse.java       # Output (record)
+│   │   │   ├── entity/
+│   │   │   │   └── UserEntity.java         # JPA entity
+│   │   │   └── exception/
+│   │   │       └── UserNotFoundException.java
+│   │   └── order/
+│   │       └── ...
+│   │
+│   └── shared/
+│       ├── config/                          # Configuration classes
+│       ├── exception/
+│       │   └── GlobalExceptionHandler.java  # @ControllerAdvice
+│       ├── security/                        # Security config
+│       └── util/                            # Cross-cutting utilities
+│
+├── src/main/resources/
+│   ├── application.yml
+│   └── db/migration/                        # Flyway migrations
+│
+└── src/test/java/com/example/project/
+    └── modules/user/
+        └── UserServiceTest.java
+```
+
+---
+
+## Preferred Libraries
+
+| Need | Library | Why |
+|------|---------|-----|
+| Framework | Spring Boot 4.x (Spring Framework 7) | Industry standard, virtual threads native support |
+| Validation | Jakarta Bean Validation | Built into Spring Boot |
+| ORM | Spring Data JPA / Hibernate | Standard, powerful |
+| Migration | Flyway | SQL-based, version controlled |
+| Mapping | MapStruct | Compile-time, type-safe DTO mapping |
+| Testing | JUnit 5 + Mockito + Testcontainers | Standard stack |
+| HTTP client | Spring RestClient / WebClient | RestClient (sync, new in Boot 4), WebClient (reactive) |
+| Logging | SLF4J + Logback (or Log4j2) | Standard, structured JSON output |
+| Build | Gradle (Kotlin DSL) or Maven | Gradle preferred for modern projects |
+| API docs | springdoc-openapi | Auto-generates OpenAPI from code |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| Raw `String` for IDs | No type safety | `UUID` or typed ID wrapper |
+| `null` returns | NullPointerException bait | `Optional<T>` for query results |
+| Checked Exception abuse | Forces catch-or-throw chains | Unchecked `RuntimeException` subclasses |
+| Field injection (`@Autowired`) | Hidden deps, untestable | Constructor injection |
+| `System.out.println` | Not structured, not configurable | SLF4J logger |
+| Deep class hierarchies | Fragile, hard to reason | Composition + interfaces |
+| God services (500+ lines) | Violates SRP | Split into focused services |
+| `@Transactional` on controller | Layer leak | Only on service methods |

package/.agent-context/stacks/php.md

@@ -0,0 +1,178 @@
+# PHP Stack Profile — Modern PHP, Not Legacy PHP
+
+> PHP 8.x is a different language from PHP 5.
+> If your AI writes PHP without type declarations, reject it immediately.
+
+## Language Version: PHP 8.5+ (Latest Stable)
+
+PHP 8.5 is stable since November 2025. Use modern PHP features including the pipe operator (`|>`), `Clone With`, and readonly classes.
+
+### Strict Types Everywhere
+```php
+<?php
+// REQUIRED: First line of EVERY PHP file
+declare(strict_types=1);
+```
+
+### Typed Properties, Parameters, and Returns
+```php
+// BANNED: Untyped PHP
+function getUser($id) {
+    $user = $this->db->find($id);
+    return $user;
+}
+
+// REQUIRED: Full type declarations
+function getUser(int $id): ?User {
+    return $this->userRepository->find($id);
+}
+```
+
+### Enums (PHP 8.1+)
+```php
+// BANNED: Magic strings
+$status = 'pending';
+
+// REQUIRED: Backed enums
+enum OrderStatus: string {
+    case Pending = 'pending';
+    case Confirmed = 'confirmed';
+    case Shipped = 'shipped';
+    case Delivered = 'delivered';
+}
+```
+
+### Readonly Properties and Classes (PHP 8.2+) and Pipe Operator (PHP 8.5+)
+```php
+// Readonly for DTOs and value objects
+readonly class CreateUserDto {
+    public function __construct(
+        public string $name,
+        public string $email,
+        public int $age,
+    ) {}
+}
+
+// Pipe operator for cleaner function chains (PHP 8.5)
+$result = $input
+    |> 'trim'
+    |> 'strtolower'
+    |> fn($s) => str_replace(' ', '-', $s);
+```
+
+---
+
+## Validation at Boundaries: Laravel Form Requests
+
+```php
+// BANNED: Validating in controller body
+public function store(Request $request) {
+    $data = $request->all();  // Raw, unvalidated!
+    User::create($data);      // Mass assignment vulnerability!
+}
+
+// REQUIRED: Form Request class
+class StoreUserRequest extends FormRequest {
+    public function rules(): array {
+        return [
+            'name' => ['required', 'string', 'max:100'],
+            'email' => ['required', 'email', 'unique:users'],
+            'age' => ['required', 'integer', 'min:13', 'max:150'],
+        ];
+    }
+}
+
+public function store(StoreUserRequest $request): JsonResponse {
+    $user = $this->userService->create($request->validated());
+    return response()->json($user, 201);
+}
+```
+
+---
+
+## Project Structure (Laravel)
+
+```
+project-name/
+├── app/
+│   ├── Modules/                        # Feature-based grouping
+│   │   ├── User/
+│   │   │   ├── Controllers/
+│   │   │   │   └── UserController.php  # Transport
+│   │   │   ├── Services/
+│   │   │   │   └── UserService.php     # Business logic
+│   │   │   ├── Repositories/
+│   │   │   │   └── UserRepository.php  # Data access
+│   │   │   ├── Requests/
+│   │   │   │   └── StoreUserRequest.php
+│   │   │   ├── Resources/
+│   │   │   │   └── UserResource.php    # API response transformer
+│   │   │   ├── Models/
+│   │   │   │   └── User.php            # Eloquent model
+│   │   │   └── Policies/
+│   │   │       └── UserPolicy.php      # Authorization
+│   │   └── Order/
+│   │       └── ...
+│   │
+│   ├── Shared/
+│   │   ├── Exceptions/
+│   │   │   └── Handler.php
+│   │   └── Middleware/
+│
+├── database/migrations/
+├── routes/api.php
+├── tests/
+│   ├── Feature/
+│   └── Unit/
+├── phpstan.neon                         # Static analysis config
+└── composer.json
+```
+
+---
+
+## Standards
+
+### PSR Compliance
+- **PSR-4:** Autoloading (Composer handles this)
+- **PSR-12:** Coding style (use PHP-CS-Fixer or Pint)
+
+### Static Analysis: PHPStan Level 8+
+```neon
+# phpstan.neon
+parameters:
+    level: 8
+    paths:
+        - app
+```
+
+---
+
+## Preferred Libraries
+
+| Need | Library | Why |
+|------|---------|-----|
+| Framework | Laravel 12 | Most productive PHP framework, auto eager loading, GraphQL |
+| Validation | Laravel Form Requests | Built-in, declarative |
+| ORM | Eloquent | Convention over configuration |
+| Testing | PHPUnit / Pest | Pest preferred for readability |
+| Static analysis | PHPStan (level 8+) | Catch type errors at build time |
+| Formatting | Laravel Pint | Zero-config PSR-12 formatter |
+| API resources | Laravel API Resources | Clean response transformation |
+| Auth | Laravel Sanctum / Passport | Token-based auth |
+| Queue | Laravel Queues | Built-in, multiple drivers |
+| API docs | Scribe or L5-Swagger | Auto-generated OpenAPI |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| Missing `declare(strict_types=1)` | Loose type coercion | Always declare |
+| `$request->all()` in `create()` | Mass assignment vulnerability | `$request->validated()` |
+| Raw SQL with concatenation | SQL injection | Eloquent or query builder with bindings |
+| `dd()` / `dump()` in production | Debug leak | Structured logging |
+| God controllers (500+ lines) | Violates SRP | Thin controllers, fat services |
+| Business logic in models | Model becomes unmaintainable | Service layer |
+| `try { } catch (\Exception $e) { }` | Swallows everything | Specific exception types |
+| Dynamic properties (deprecated 8.2) | Runtime errors | Declared typed properties |

package/.agent-context/stacks/python.md

@@ -0,0 +1,153 @@
+# Python Stack Profile — Explicit is Better Than Implicit
+
+> Python's readability is a gift. Don't waste it with sloppy typing and god functions.
+
+## Type System (Enforced)
+
+### Type Hints Everywhere (Python 3.12+)
+```python
+# BANNED: Untyped function signatures
+def process_data(data, options):
+    ...
+
+# REQUIRED: Full type annotations
+def process_order(order: Order, options: ProcessingOptions) -> OrderResult:
+    ...
+```
+
+**Rule:** Every function MUST have type annotations for all parameters and return types. Use `mypy --strict` or `pyright` in strict mode.
+
+### No `Any` (Same Rule as TypeScript)
+```python
+# BANNED
+def handle(data: Any) -> Any: ...
+result: dict[str, Any] = get_response()
+
+# REQUIRED
+def handle(data: OrderPayload) -> OrderResult: ...
+result: OrderResponse = get_response()
+```
+
+---
+
+## Validation at Boundaries: Pydantic
+
+### Rule: ALL External Data MUST Pass Through Pydantic
+
+```python
+# BANNED: Trusting raw dicts
+@app.post("/users")
+async def create_user(request: Request):
+    data = await request.json()  # Could be anything!
+    return await user_service.create(data)
+
+# REQUIRED: Pydantic model at the boundary
+from pydantic import BaseModel, EmailStr, Field
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    email: EmailStr
+    age: int = Field(ge=13, le=150)
+
+@app.post("/users")
+async def create_user(payload: CreateUserRequest) -> UserResponse:
+    return await user_service.create(payload)
+```
+
+### Pydantic Best Practices
+- Use `Field()` with constraints (`min_length`, `ge`, `le`, `pattern`)
+- Use `model_config = ConfigDict(strict=True)` to prevent type coercion
+- Derive response models from base models: `class UserResponse(UserBase):`
+- Use `model_validator` for cross-field validation
+
+---
+
+## Project Structure
+
+```
+project-name/
+├── src/
+│   ├── __init__.py
+│   ├── main.py                       # Application entry point
+│   ├── config.py                     # Pydantic Settings (env validation)
+│   │
+│   ├── modules/                      # Feature modules
+│   │   ├── user/
+│   │   │   ├── __init__.py
+│   │   │   ├── router.py             # Transport (API routes)
+│   │   │   ├── service.py            # Business logic
+│   │   │   ├── repository.py         # Data access
+│   │   │   ├── schemas.py            # Pydantic models (DTOs)
+│   │   │   ├── models.py             # SQLAlchemy/ORM models
+│   │   │   └── exceptions.py         # Domain-specific errors
+│   │   └── order/
+│   │       └── ...
+│   │
+│   └── shared/
+│       ├── errors.py                 # Base error classes
+│       ├── middleware.py              # Auth, logging, error handling
+│       ├── database.py               # DB session management
+│       └── logger.py                 # Structured logging (structlog)
+│
+├── tests/
+│   ├── conftest.py                   # Fixtures
+│   ├── factories.py                  # Test data factories
+│   └── modules/
+│       └── user/
+│           └── test_user_service.py
+│
+├── pyproject.toml                    # Project config (single source)
+├── .env.example
+└── Dockerfile
+```
+
+---
+
+## Async Patterns
+
+```python
+# BANNED: Sync I/O in async context
+import requests  # Blocks the event loop!
+response = requests.get("https://api.example.com")
+
+# REQUIRED: Use async HTTP client
+import httpx
+async with httpx.AsyncClient() as client:
+    response = await client.get("https://api.example.com")
+```
+
+**Rule:** In async applications (FastAPI, etc.), NEVER use synchronous I/O libraries (`requests`, `time.sleep`, `open()` for large files). Use `httpx`, `asyncio.sleep`, `aiofiles`.
+
+---
+
+## Preferred Libraries (2025)
+
+| Need | Library | Why |
+|------|---------|-----|
+| Web framework | `fastapi` | Async, type-safe, auto OpenAPI docs |
+| Validation | `pydantic` v2 | Fast, Rust-powered, zero compromise |
+| ORM | `sqlalchemy` 2.0+ / `sqlmodel` | Mature, async support. SQLModel wraps SQLAlchemy + Pydantic |
+| HTTP client | `httpx` | Async-native, requests-compatible API |
+| Testing | `pytest` + `pytest-asyncio` | Standard, plugin-rich |
+| Linting | `ruff` | 10-100x faster than flake8+isort+black combined |
+| Formatting | `ruff format` (or `black`) | Consistent, zero-config |
+| Type checking | `mypy --strict` or `pyright` | Catch type errors before runtime |
+| Logging | `structlog` | Structured, JSON-ready, contextvars |
+| Env config | `pydantic-settings` | Type-safe env with validation |
+| Password | `passlib[bcrypt]` or `argon2-cffi` | Proven, secure |
+| Migration | `alembic` | SQLAlchemy migration standard |
+
+---
+
+## Banned Patterns
+
+| Pattern | Why | Alternative |
+|---------|-----|-------------|
+| `Any` type | Defeats type checking | Specific types or `Unknown` protocol |
+| `requests` in async | Blocks event loop | `httpx` |
+| `print()` for logging | No structure, no levels | `structlog` or `logging` |
+| `except Exception: pass` | Swallows every error | Specific exceptions, always log |
+| `from module import *` | Namespace pollution | Explicit imports |
+| Mutable default args | Shared state bug | `def f(items: list | None = None):` |
+| Global state | Untestable, concurrency bugs | Dependency injection |
+| `os.environ["KEY"]` | Crashes with KeyError | `pydantic-settings` with defaults |