@ryuenn3123/agentic-senior-core 2.5.22 → 3.0.0

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

@@ -1,192 +0,0 @@
-# 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.3+ (Laravel 13 Baseline, 8.5 Recommended)
-
-Laravel 13 requires PHP 8.3+. Use PHP 8.5 when your runtime supports it, but avoid forcing 8.5-only syntax in shared packages unless project constraints explicitly require it.
-
-### 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+)
-```php
-// Readonly for DTOs and value objects
-readonly class CreateUserDto {
-    public function __construct(
-        public string $name,
-        public string $email,
-        public int $age,
-    ) {}
-}
-```
-
-### Optional on PHP 8.5+: Pipe Operator
-```php
-// Use when your project runtime is locked to 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 13 | Most productive PHP framework with AI SDK, JSON:API resources, and stronger security defaults |
-| 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 |
-
----
-
-## Laravel 13 Guardrails
-
-- Use `PreventRequestForgery` for explicit CSRF middleware references (old aliases still exist but are deprecated).
-- Ensure `upsert(..., uniqueBy: ...)` always passes a non-empty `uniqueBy` value.
-- Prefer first-party JSON:API resources when you need JSON:API-compliant responses.
-- If caching objects, configure `cache.serializable_classes` allow-list explicitly.
-- For AI-assisted Laravel projects, use `laravel/boost` `^2.0` and run `php artisan boost:install`.
-- Laravel 12 projects are still supported: keep `VerifyCsrfToken` and avoid 13-only API assumptions until framework upgrade is complete.
-
----
-
-## 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

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

package/.agent-context/stacks/react-native.md

@@ -1,16 +0,0 @@
-# React Native Stack
-
-Use this stack for cross-platform mobile applications built with React Native.
-
-## Core Guidance
-
-- Keep the app shell thin and delegate data fetching to dedicated service modules.
-- Treat navigation, device integration, and UI composition as separate concerns.
-- Prefer typed API contracts and isolate platform-specific code behind adapters.
-- Keep release gating strict because mobile packaging failures are expensive to recover from.
-
-## Recommended Pairings
-
-- `mobile-app` blueprint for the starter architecture.
-- `frontend` skill domain for UI composition, accessibility, and motion guidance.
-- `fullstack` skill domain when the app depends on backend contract orchestration.

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

@@ -1,80 +0,0 @@
-# Ruby on Rails Engineering Standards
-
-> Rails provides "Convention over Configuration," but convention does not mean "put all your business logic in ActiveRecord callbacks."
-
-## Core Tenets
-1. **Skinny Models, Skinny Controllers, Fat Services:** The default Rails MVC is insufficient for complex domains. Extract business logic into Service Objects (Interactors).
-2. **Death to N+1 Queries:** The `bullet` gem is mandatory in development and test environments. Any N+1 query is a blocker.
-3. **No Hidden Magic:** Avoid deeply nested or complex ActiveRecord callbacks (`before_save`, `after_commit`). They obscure the flow of data. If an action has side effects, orchestrate it in a Service Object.
-4. **Strong Parameters Only:** Never trust user input. Always permit explicit parameters in the controller layer before passing data down.
-
-## Architecture & Layering (The Service Object Pattern)
-Default Rails couples the HTTP request cycle tightly to the Database via the Model. We break this.
-
-### 1. Controllers (Transport Layer)
-- **Role:** Handle HTTP requests, parse parameters (Strong Params), authenticate/authorize the user, call the Service Object, and return the HTTP response/JSON.
-- **BANNED:** Calling `Model.create()`, `Model.update()`, or writing any business calculations in the controller.
-- **ALLOWED:** `MyService.call(params)`
-
-### 2. Service Objects (Application Layer)
-- **Role:** The orchestrator. Located in `app/services/`.
-- **Structure:** Usually plain Ruby objects (POROs) with a single public `call` method.
-- **Responsibility:** Executes the business transaction, handling database operations, sending emails, or enqueuing background jobs.
-
-### 3. Models (Domain & Persistence Layer)
-- **Role:** ActiveRecord models should only contain associations (`belongs_to`, `has_many`), scopes, and simple data validations (e.g., `validates :email, presence: true`).
-- **BANNED:** Complex business logic, sending emails, API calls to third parties.
-
-## Ecosystem & Dependencies (March 2026)
-- **API Mode:** Use `rails new my_api --api` for backend-only projects.
-- **Background Jobs:** `sidekiq` is the standard. Default `ActiveJob` should map to a Sidekiq backend (powered by Redis).
-- **Authentication/Authorization:** `devise` (if needed, though often overkill for raw APIs; consider `jwt` + custom auth) and `pundit` (mandatory for authorization). Avoid `cancancan`.
-- **Testing:** `rspec-rails` and `factory_bot_rails`. Default `minitest` and `fixtures` are explicitly banned for Agentic-Senior-Core projects.
-- **Linting:** `rubocop` is mandatory. The build must fail if RuboCop fails.
-
-## Anti-Patterns (Zero Tolerance)
-
-### 1. The Fat Model Callback Hell
-```ruby
-# ❌ BANNED: The model side-effect
-class User < ApplicationRecord
-  after_create :send_welcome_email
-
-  def send_welcome_email
-    UserMailer.welcome(self).deliver_now
-  end
-end
-
-# ✅ REQUIRED: The Service Object Orchestrator
-class Users::CreateService
-  def self.call(params)
-    user = User.new(params)
-    if user.save
-      UserMailer.welcome(user).deliver_later
-    end
-    user
-  end
-end
-```
-
-### 2. N+1 Queries in Responses
-```ruby
-# ❌ BANNED: Will execute 101 queries for 100 posts
-def index
-  @posts = Post.all
-  render json: @posts.map { |p| { title: p.title, author: p.author.name } }
-end
-
-# ✅ REQUIRED: Eager loading
-def index
-  @posts = Post.includes(:author).all
-  # ...
-end
-```
-
-### 3. Logic in Views/Serializers
-If using ActiveModelSerializers, Jbuilder, or Blueprinter, never perform database queries or heavy calculations in the serialization phase.
-
-## Background Jobs (Sidekiq)
-- **Rule:** Any operation taking longer than 300ms (e.g., sending an email, generating a PDF, calling an external API) **MUST** be pushed to a background job (`.deliver_later` or `MyWorker.perform_async`).
-- **Rule:** Background job parameters must be simple types (strings, integers, IDs). **NEVER** pass an ActiveRecord object directly to a Sidekiq worker (it might be stale when the job runs). Pass the `user_id` instead.

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

@@ -1,86 +0,0 @@
-# Rust Engineering Standards
-
-> Rust guarantees memory safety, but not logic safety. Write code that is as predictable as the compiler.
-
-## Core Tenets
-1. **Never Panic:** The use of `unwrap()`, `expect()`, or `panic!()` in production business logic is strictly banned.
-2. **Make Invalid States Unrepresentable:** Use Rust's powerful type system (enums, newtypes) to enforce business rules at compile time.
-3. **Explicit Errors:** Use `Result` for all fallible operations.
-4. **Fearless Concurrency:** Leverage `Send` and `Sync`. Avoid shared mutable state; prefer message passing or structured concurrency.
-
-## Ecosystem & Dependencies (March 2026)
-Adhere to the `efficiency-vs-hype` rule. The Rust ecosystem is robust; use community standards:
-
-### Backend / API
-- **Web Framework:** `axum` (Standard for new projects, built on `tokio` and `tower`). Avoid `actix-web` and `rocket` for new microservices unless migrating legacy code.
-- **Async Runtime:** `tokio` (Standard).
-- **Serialization:** `serde` + `serde_json`.
-
-### Data / Persistence
-- **Database:** `sqlx` (preferred for compile-time checked SQL) or `sea-orm` (if an ORM is strictly required). Avoid `diesel` (unless explicitly requested).
-- **Connection Pooling:** Built into `sqlx` (use `PgPool`, etc.).
-
-### Validation / Error Handling / Observability
-- **Error Handling:** `thiserror` (for libraries and domain boundaries) and `anyhow` (for application/binaries and controllers).
-- **Validation:** `validator` crate.
-- **Telemetry/Logging:** `tracing` + `tracing-subscriber`. `log` and `env_logger` are legacy.
-
-## Architecture & Layering
-Strict Clean Architecture / Hexagonal Architecture.
-
-1. **Transport (`/api` or `/transport`)**
-   - Axum routers and handlers.
-   - Responsible for extracting JSON/Path data, verifying auth claims, and calling the Domain/Service layer.
-   - **MUST:** Return standard HTTP status codes mapping to domain errors.
-
-2. **Application / Service (`/services` or `/app`)**
-   - Orchestrates business logic, database transactions, and external API calls.
-   - **NO** HTTP knowledge (Axum types do not cross this boundary).
-
-3. **Domain (`/domain`)**
-   - Pure Rust logic. Structs, Enums, Traits.
-   - **Must not** know about the database (SQL) or HTTP. Use traits (interfaces) to define repository contracts.
-
-4. **Infrastructure / Repository (`/repo` or `/infra`)**
-   - `sqlx` queries go here. Implements the traits defined in Domain.
-
-## Anti-Patterns (Zero Tolerance)
-
-### 1. The `unwrap()` Fallacy
-```rust
-// ❌ BANNED: Will crash the server if parsing fails
-let user_id = id_string.parse::<i32>().unwrap();
-
-// ✅ REQUIRED: Explicit error mapping
-let user_id = id_string.parse::<i32>().map_err(AppError::InvalidId)?;
-```
-
-### 2. Stringly-Typed Domain
-```rust
-// ❌ BANNED: Passing raw strings everywhere
-fn update_email(user_id: String, email: String) {}
-
-// ✅ REQUIRED: Newtypes and validated types
-struct UserId(uuid::Uuid);
-struct Email(String); // Should be validated on creation
-
-fn update_email(user_id: UserId, email: Email) {}
-```
-
-### 3. Cloning to Appease the Borrow Checker
-```rust
-// ❌ POOR PRACTICE: Cloning just to make it compile instead of designing lifetimes/ownership
-let name = user.name.clone();
-process_name(name);
-
-// ✅ REQUIRED: Pass by reference (borrowing)
-process_name(&user.name);
-```
-
-### 4. Catch-all `anyhow::Error` in Traits
-Traits defining contracts between layers (like Repositories) should return explicit errors (`thiserror`), not `anyhow::Error`, so the caller can systematically handle specific failures (e.g., `NotFound`, `ConstraintViolation`).
-
-## Testing Standards
-- **Unit Tests:** Inside the same file as the code (`#[cfg(test)] mod tests { ... }`).
-- **Integration Tests:** In the `tests/` directory at the root level.
-- **Mocking:** Use `mockall` or manually implement traits for test doubles. Avoid testing against a real database in unit tests; use them in integration tests using `sqlx::test`.