@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/rules/architecture.md

@@ -0,0 +1,198 @@
+# Architecture — Separation of Concerns & Structure
+
+> If your service file imports an HTTP library, your architecture is broken.
+> If your controller contains SQL, you've already lost.
+
+## The Core Principle
+
+**Every layer has ONE job. Layer leaks are bugs — not "pragmatic shortcuts."**
+
+```
+┌─────────────────────────────────────────┐
+│         TRANSPORT / CONTROLLER          │  ← Parse input, validate shape, return response
+│         (HTTP, CLI, WebSocket, Queue)   │  ← NO business logic here. EVER.
+├─────────────────────────────────────────┤
+│         APPLICATION / SERVICE           │  ← Business rules, orchestration, transactions
+│         (Use cases, workflows)          │  ← NO HTTP, NO SQL, NO framework imports
+├─────────────────────────────────────────┤
+│         DOMAIN / ENTITY                 │  ← Pure business objects, value objects
+│         (Models, rules, calculations)   │  ← ZERO external dependencies
+├─────────────────────────────────────────┤
+│         INFRASTRUCTURE / REPOSITORY     │  ← Database, external APIs, file system
+│         (Data access, adapters)         │  ← NO business logic
+└─────────────────────────────────────────┘
+```
+
+## Layer Rules (Enforced)
+
+### Transport Layer (Controller / Handler / Route)
+**Allowed:**
+- Parse and validate incoming request (DTO/schema validation)
+- Call application/service layer
+- Format and return HTTP response (status code, headers)
+- Handle authentication/authorization middleware
+
+**BANNED:**
+- Database queries or ORM calls
+- Business logic (if/else on business rules)
+- Direct calls to external APIs
+- Transaction management
+
+### Application Layer (Service / Use Case)
+**Allowed:**
+- Orchestrate business operations
+- Call repository layer for data
+- Apply business rules and validations
+- Manage transactions
+- Emit domain events
+
+**BANNED:**
+- HTTP request/response objects
+- Framework-specific decorators (keep framework coupling minimal)
+- Direct SQL or raw database calls
+- UI/presentation logic
+
+### Domain Layer (Entity / Value Object)
+**Allowed:**
+- Business calculations and rules
+- Validation of domain invariants
+- Type definitions and interfaces
+
+**BANNED:**
+- ANY external dependency (database, HTTP, framework)
+- Side effects (logging, API calls, file I/O)
+- Infrastructure concerns
+
+### Infrastructure Layer (Repository / Adapter)
+**Allowed:**
+- Database queries (SQL, ORM, document queries)
+- External API calls (wrapped in adapters)
+- File system operations
+- Cache operations
+
+**BANNED:**
+- Business logic (no if/else on business rules in queries)
+- HTTP response formatting
+- Direct exposure to transport layer
+
+---
+
+## Dependency Direction
+
+Dependencies flow **inward only**:
+
+```
+Transport → Application → Domain ← Infrastructure
+                ↓
+          Infrastructure
+
+NEVER: Domain → Infrastructure (use interfaces/ports)
+NEVER: Application → Transport
+NEVER: Infrastructure → Application (except through interfaces)
+```
+
+The Domain layer depends on NOTHING. Everything depends on the Domain.
+
+---
+
+## Default Architecture: Modular Monolith
+
+Start with a **Modular Monolith**. Do NOT start with microservices.
+
+**Switch to microservices ONLY if 2+ of these triggers exist:**
+1. Frequent deploy conflicts across domains (teams blocking each other)
+2. Clear scale mismatch (one module needs 100x resources of another)
+3. Team ownership collision (multiple teams editing same module)
+4. Fault isolation requirement (one module crashing must not kill others)
+5. Stable contracts with clear data boundaries already exist
+
+If these triggers don't exist, microservices are **premature complexity**.
+
+---
+
+## Project Structure: Feature-Based Grouping
+
+### ❌ BANNED: Technical Grouping
+```
+src/
+  controllers/          ← 50 controllers in one flat folder?
+    userController.ts
+    orderController.ts
+    paymentController.ts
+  services/             ← Good luck finding related code
+    userService.ts
+    orderService.ts
+  repositories/
+    userRepository.ts
+    orderRepository.ts
+```
+
+### ✅ REQUIRED: Feature/Domain Grouping
+```
+src/
+  modules/                              ← Backend
+    user/
+      user.controller.ts               ← Transport
+      user.service.ts                   ← Application
+      user.repository.ts               ← Infrastructure
+      user.entity.ts                    ← Domain
+      user.dto.ts                       ← Data Transfer Objects
+      user.module.ts                    ← Module registration
+      __tests__/
+        user.service.test.ts
+    order/
+      order.controller.ts
+      order.service.ts
+      ...
+  shared/                               ← Cross-cutting concerns
+    config/
+    errors/
+    logging/
+    middleware/
+
+src/
+  features/                             ← Frontend
+    payment/
+      api/                              ← HTTP client + DTOs
+      hooks/                            ← React hooks / state
+      components/                       ← UI components
+      types/                            ← Type definitions
+      utils/                            ← Feature-specific utils
+      index.ts                          ← Public API barrel
+  components/
+    ui/                                 ← Shared UI primitives
+    layout/                             ← Layout components
+  lib/                                  ← Shared utilities
+  config/                               ← App configuration
+```
+
+---
+
+## Module Communication
+
+### Within a Monolith
+Modules communicate through **public interfaces only**:
+```
+// ✅ CORRECT: Import from module's public API
+import { UserService } from '@/modules/user';
+
+// ❌ BANNED: Reach into another module's internals
+import { UserRepository } from '@/modules/user/user.repository';
+```
+
+### Between Services (if microservices)
+- Use well-defined contracts (REST, gRPC, events)
+- Never share databases between services
+- Define schemas at boundaries (Protobuf, JSON Schema, Zod)
+
+---
+
+## The Architecture Smell Test
+
+Ask yourself these questions. If ANY answer is "yes", your architecture is broken:
+
+1. Can I change the database without touching business logic? (Must be YES)
+2. Can I switch from REST to GraphQL without rewriting services? (Must be YES)
+3. Can I test business logic without a running database? (Must be YES)
+4. Does each module have a clear, single responsibility? (Must be YES)
+5. Can a new developer find all related code in one directory? (Must be YES)

package/.agent-context/rules/database-design.md

@@ -0,0 +1,202 @@
+# Database Design — Schema Is Your Foundation
+
+> A poorly designed schema is a bug factory.
+> You can fix bad code in hours. A bad schema takes weeks.
+
+## Normalization Rules
+
+### Third Normal Form (3NF) is the Default
+
+```
+❌ BANNED: Flat tables with repeated data
+Users:
+  | id | name  | order_id | order_total | product_name |
+  | 1  | Jane  | 101      | 99.99       | Widget       |
+  | 1  | Jane  | 102      | 49.99       | Gadget       |
+  → name is duplicated, update anomalies guaranteed
+
+✅ REQUIRED: Normalized to 3NF
+Users:    | id | name  | email          |
+Orders:   | id | user_id | total | status |
+Products: | id | name   | price |
+OrderItems: | order_id | product_id | quantity |
+  → Each fact is stored exactly once
+```
+
+### When to Denormalize
+
+Denormalization is allowed ONLY with documented justification:
+
+1. **Read-heavy query** that joins 4+ tables and is called >1000x/sec
+2. **Reporting/analytics** where query speed matters more than write consistency
+3. **CQRS read model** that is purpose-built for a specific query
+
+```
+REQUIRED for every denormalization:
+- Document WHY (link to performance evidence)
+- Document HOW it stays in sync (trigger, event, scheduled job)
+- Add a comment in the schema: "Denormalized for [query name], synced by [mechanism]"
+```
+
+---
+
+## Indexing Strategy
+
+### Rules of Indexing
+
+1. **Every foreign key gets an index** — joins on unindexed FKs are full table scans
+2. **Every WHERE clause in a frequent query gets evaluated** — if the column appears in WHERE and the table has >10K rows, consider an index
+3. **Composite indexes matter** — `INDEX(status, created_at)` ≠ `INDEX(created_at, status)`. Column order follows the query pattern (most selective first, or matching WHERE + ORDER BY)
+4. **Covering indexes** — include frequently selected columns to avoid table lookups
+
+### What to Index
+
+| Pattern | Index Type | Example |
+|---------|-----------|---------|
+| FK lookups | B-tree (default) | `orders.user_id` |
+| Status + date filters | Composite | `INDEX(status, created_at)` |
+| Full-text search | Full-text / GIN | `products.description` |
+| JSON queries | GIN (PostgreSQL) | `metadata->>'type'` |
+| Unique constraints | Unique | `users.email` |
+| Geospatial | Spatial / GiST | `locations.coordinates` |
+
+### What NOT to Index
+
+- Columns with very low cardinality on small tables (`is_active` with 2 values on 100 rows)
+- Tables with <1000 rows (index overhead > benefit)
+- Write-heavy tables where every INSERT updates 10+ indexes
+- Columns never used in WHERE, JOIN, or ORDER BY
+
+### Index Monitoring
+
+```
+REQUIRED:
+- Identify unused indexes monthly → DROP them (they slow writes)
+- Identify missing indexes → EXPLAIN ANALYZE on slow queries
+- Track index size vs table size → alarming if indexes > 3x table size
+```
+
+---
+
+## Migration Standards
+
+### Rules
+
+1. **Every schema change is a migration** — never modify production schemas manually
+2. **Migrations are versioned and sequential** — `001_create_users.sql`, `002_add_email_index.sql`
+3. **Migrations are idempotent** — running twice produces the same result
+4. **Migrations are reversible** — every UP has a DOWN (or document why rollback is impossible)
+5. **Migrations run in CI** — test against a real database, not just syntax checks
+
+### Safe Migration Patterns
+
+```
+✅ SAFE (no downtime):
+1. ADD COLUMN with default (nullable or with DEFAULT)
+2. CREATE INDEX CONCURRENTLY
+3. ADD new table
+4. Rename via view + synonym (transitional)
+
+❌ DANGEROUS (requires planned downtime or careful orchestration):
+1. DROP COLUMN (deploy code changes removing column usage FIRST)
+2. RENAME COLUMN (use gradual rename: add new → copy data → remove old)
+3. ALTER COLUMN TYPE (may lock table on large datasets)
+4. DROP TABLE (ensure no code references remain)
+```
+
+### The Expand-Contract Pattern
+
+For breaking schema changes in zero-downtime deployments:
+
+```
+Phase 1 (Expand): Add new column/table alongside old one
+   → Code writes to BOTH old and new
+Phase 2 (Migrate): Backfill data from old to new
+   → Verify data consistency
+Phase 3 (Contract): Remove old column/table
+   → Code reads/writes only new
+```
+
+---
+
+## Data Type Selection
+
+### Use the Right Type
+
+| Data | ❌ Wrong | ✅ Right | Why |
+|------|---------|---------|-----|
+| Money | `FLOAT` | `DECIMAL(19,4)` or integer cents | Floating point arithmetic is imprecise |
+| UUID | `VARCHAR(36)` | `UUID` native type | 16 bytes vs 36 bytes, indexing is faster |
+| Timestamps | `VARCHAR` | `TIMESTAMPTZ` | Timezone-aware, sortable, comparable |
+| IP addresses | `VARCHAR(45)` | `INET` (PostgreSQL) | Validation built-in, range queries |
+| Boolean | `INT` (0/1) | `BOOLEAN` | Semantic clarity |
+| Enums | `VARCHAR` | Database ENUM or CHECK constraint | Prevents invalid values |
+| JSON blobs | `TEXT` | `JSONB` (PostgreSQL) | Indexable, queryable, validated |
+
+### Column Naming
+
+```
+✅ REQUIRED:
+- snake_case for all column names
+- Descriptive: created_at, updated_at, deleted_at (not ts, mod, del)
+- Foreign keys: {referenced_table_singular}_id (e.g., user_id, order_id)
+- Boolean columns: is_active, has_verified_email, can_edit
+- Timestamps: {verb}_at (created_at, verified_at, shipped_at)
+- Amounts: {noun}_amount or {noun}_cents (total_amount, tax_cents)
+```
+
+---
+
+## Query Design Rules
+
+### Pagination (Mandatory for Lists)
+
+```
+❌ BANNED:
+SELECT * FROM orders;
+-- Returns 2 million rows, OOM crash
+
+✅ REQUIRED: Offset pagination (simple, okay for < 100K rows)
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 40;
+
+✅ PREFERRED: Cursor pagination (performant at any scale)
+SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+```
+
+**Rule:** Use cursor-based pagination for tables > 100K rows. Offset pagination degrades linearly with OFFSET value.
+
+### Soft Deletes vs Hard Deletes
+
+```
+Use soft deletes (deleted_at column) when:
+- Legal/compliance requires data retention
+- Users might want to "undelete"
+- Related data would break without the parent record
+
+Use hard deletes when:
+- GDPR/privacy requires actual data removal
+- Data has no business value after deletion
+- Storage cost of keeping data outweighs benefit
+
+If soft deleting:
+- Add deleted_at to ALL queries: WHERE deleted_at IS NULL
+- Add a partial index: WHERE deleted_at IS NULL (for performance)
+- Schedule periodic hard-delete of old soft-deleted records
+```
+
+---
+
+## The Database Design Checklist
+
+Before any schema goes to production:
+
+- [ ] Schema is normalized to 3NF (denormalization documented if present)
+- [ ] All foreign keys have indexes
+- [ ] Primary keys use appropriate type (UUID or BIGINT)
+- [ ] Timestamps use TIMESTAMPTZ (not VARCHAR)
+- [ ] Money uses DECIMAL or integer cents (never FLOAT)
+- [ ] Migration is versioned, reversible, and tested in CI
+- [ ] All list queries have LIMIT (pagination implemented)
+- [ ] Indexes justified with EXPLAIN ANALYZE on expected queries
+- [ ] Column naming follows convention (snake_case, descriptive)
+- [ ] Soft delete vs hard delete decision documented

package/.agent-context/rules/efficiency-vs-hype.md

@@ -0,0 +1,143 @@
+# Efficiency vs. Hype — Choose Stable, Not Shiny
+
+> Every dependency is a liability. Every `npm install` is a trust decision.
+> The best dependency is the one you don't need.
+
+## The Dependency Decision Framework
+
+Before adding ANY dependency, answer these 5 questions:
+
+### 1. Can You Do It Without a Library? (The stdlib-first Rule)
+```
+❌ OVER-ENGINEERING:
+npm install is-odd        # 1 line of code: n % 2 !== 0
+npm install left-pad      # Already in String.prototype.padStart
+npm install is-number     # typeof x === 'number' && !isNaN(x)
+npm install array-flatten # Array.prototype.flat() exists since ES2019
+
+✅ USE THE LANGUAGE:
+const isOdd = (n: number) => n % 2 !== 0;
+const padded = str.padStart(10, '0');
+const flat = nested.flat(Infinity);
+```
+
+**Dependency Defense:** If the user asks to install a new library, or if you feel the need to use one, evaluate it against the "stdlib-first" rule. If the functionality can be implemented safely in under 20 lines of code, write it yourself. If a dependency is strictly necessary, you MUST justify it by providing its bundle size, maintenance status, and why the standard library is insufficient.
+
+### 2. Is It Maintained? (The Pulse Check)
+| Signal | 🟢 Healthy | 🔴 Dead |
+|--------|-----------|---------|
+| Last commit | < 6 months ago | > 2 years ago |
+| Open issues | Actively triaged | 500+ unread |
+| Downloads/week | Growing or stable | Declining |
+| Bus factor | > 3 maintainers | 1 maintainer, inactive |
+| Security | No known CVEs | Unpatched vulnerabilities |
+
+**Rule:** If a library has a bus factor of 1 and no commit in 12+ months, it is a risk. Find an alternative or vendor-fork it.
+
+### 3. What's the Cost? (The Weight Check)
+```
+Before: npm install moment     # 289KB minified, entire library for date formatting
+After:  npm install date-fns   # 12KB for just the functions you use (tree-shakeable)
+Better: Intl.DateTimeFormat    # 0KB — built into the runtime
+```
+
+**Rule:** Check the bundle impact. Use [bundlephobia.com](https://bundlephobia.com) for JS packages. If a library adds > 50KB to your bundle for a simple feature, find a lighter alternative or implement it yourself.
+
+### 4. Is It the Community Standard? (The Ecosystem Rule)
+Prefer packages that the ecosystem has settled on:
+
+| Need | ✅ Standard | ❌ Avoid |
+|------|-----------|---------|
+| HTTP client (Node) | `undici` (built-in) / native `fetch` / `ky` | `axios` (declining, CVE-2025-58754, bloated) |
+| Validation | `zod` | `joi` (heavier), `yup` (less type-safe) |
+| ORM (Node) | `prisma`, `drizzle` | `sequelize` (legacy API), `typeorm` (decorator hell) |
+| Date handling | `date-fns`, `dayjs`, `Temporal` (when stable) | `moment` (deprecated, massive) |
+| Testing | `vitest` (new projects), `jest` (existing) | `mocha` + `chai` + `sinon` (3 deps for what 1 does) |
+| Password hashing | `argon2` (OWASP primary), `bcrypt` (legacy) | Custom crypto (NEVER) |
+| Env loading | `dotenv` (if needed) | Custom `.env` parser |
+
+**Note:** These are current recommendations as of March 2026. Evaluate against this framework; don't blindly follow.
+
+### 5. Can You Remove It Later? (The Exit Strategy)
+```
+❌ HIGH LOCK-IN:
+// Decorators from a specific framework scattered across 200 files
+@Controller() @Injectable() @Guard() // In every file — framework is your entire architecture
+
+✅ LOW LOCK-IN:
+// Framework stays at the edges; business logic is framework-free
+// Switching from Express to Fastify only changes the transport layer
+```
+
+**Rule:** Wrap external dependencies that touch > 5 files. If you need to replace a library, it should only affect the wrapper, not your entire codebase.
+
+---
+
+## The Hype Trap (AI-Generated Code Alert)
+
+AI agents love suggesting trendy libraries because they appear frequently in training data. Watch for:
+
+### Red Flags
+1. **"Just install X"** without explaining why → ASK: Can I do this with the stdlib?
+2. **Library does one thing** that's 5 lines of code → REJECT: Write it yourself
+3. **Library is in alpha/beta** with < 1 year of releases → REJECT: Not production-ready
+4. **Library has a cooler API** but the current one works fine → REJECT: "Cool" is not a business requirement
+5. **"Everyone is using it"** → SO WHAT: Popularity is not a quality signal
+
+### The Agent Must Justify Dependencies
+When an AI agent suggests adding a new dependency, it MUST provide:
+```
+📦 DEPENDENCY JUSTIFICATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Package: [name@version]
+Purpose: [what it does in 1 sentence]
+Stdlib Alternative: [why it's insufficient — or "none"]
+Bundle Size: [minified + gzipped]
+Maintenance: [last release date, maintainer count]
+Lock-in Risk: [low/medium/high — how many files would it touch]
+Exit Strategy: [how to remove it if needed]
+```
+
+---
+
+## Dependency Update Strategy
+
+1. **Pin exact versions** in lockfiles (already default with package-lock.json, bun.lockb)
+2. **Review changelogs** before major updates — never blindly `npm update`
+3. **Update in isolation** — one dependency per PR, with tests passing
+4. **Security patches immediately** — don't wait for the sprint
+5. **Monthly audit** — run `npm audit` / `bun audit` and address findings
+
+---
+
+## The Zero-Dependency Ideal
+
+The best packages are those with zero or minimal dependencies themselves:
+- `zod` — 0 dependencies ✅
+- `date-fns` — 0 dependencies ✅
+- `nanoid` — 0 dependencies ✅
+- `bcrypt` — 1 native dependency (justified for crypto) ✅
+
+A package that pulls in 50 transitive dependencies for a simple feature is a supply chain attack waiting to happen.
+
+---
+
+## Quick Decision Tree
+
+```
+Do I need this functionality?
+  → No → Don't install anything
+  → Yes ↓
+
+Can I write it in < 20 lines?
+  → Yes → Write it yourself
+  → No ↓
+
+Does the language/runtime provide it?
+  → Yes → Use the built-in
+  → No ↓
+
+Is there a well-maintained, lightweight, community-standard package?
+  → Yes → Install it, add justification comment
+  → No → Build a minimal internal implementation, consider vendoring
+```