@ryuenn3123/agentic-senior-core 1.8.0

package/.agent-context/rules/git-workflow.md

@@ -0,0 +1,200 @@
+# Git Workflow — Clean History, Atomic Commits
+
+> Your git log is a changelog. If it reads like gibberish, your team is lost.
+
+## Commit Message Format: Conventional Commits (Enforced)
+
+```
+<type>(<scope>): <description>
+
+[optional body — explain WHY, not WHAT]
+[optional footer — Breaking changes, issue references]
+```
+
+### Types (Strict Set)
+| Type | When | Example |
+|------|------|---------|
+| `feat` | New feature | `feat(auth): add JWT refresh token rotation` |
+| `fix` | Bug fix | `fix(payment): handle race condition in checkout` |
+| `refactor` | Code restructuring (no behavior change) | `refactor(user): extract validation to separate service` |
+| `docs` | Documentation only | `docs(api): add OpenAPI schema for /orders endpoint` |
+| `test` | Adding/fixing tests | `test(cart): add edge case for empty cart discount` |
+| `chore` | Build, CI, config, dependencies | `chore(deps): upgrade prisma to 5.x` |
+| `perf` | Performance improvement | `perf(search): add index on users.email column` |
+| `style` | Formatting, semicolons (no logic change) | `style: apply prettier formatting` |
+| `ci` | CI/CD changes | `ci: add Node 20 to test matrix` |
+
+### Rules
+1. **Type is mandatory.** No commits without a type prefix.
+2. **Scope is recommended.** Use the module/feature name.
+3. **Description is imperative mood.** "add", not "added" or "adds".
+4. **Max 72 characters** for the subject line.
+5. **Body explains WHY,** not what. The diff shows what.
+
+### ❌ BANNED Commit Messages
+```
+fix bug
+updates
+WIP
+asdf
+misc changes
+working now
+final fix
+fix fix fix
+```
+
+---
+
+## Branching Model
+
+### Main Branches
+| Branch | Purpose | Merge Strategy |
+|--------|---------|---------------|
+| `main` | Production-ready code | Merge commit or squash |
+| `develop` | Integration branch (if using GitFlow) | Merge commit |
+
+### Feature Branches
+```
+Pattern: <type>/<ticket-id>-<short-description>
+
+Examples:
+  feat/AUTH-123-jwt-refresh
+  fix/PAY-456-checkout-race-condition
+  refactor/USER-789-extract-validation
+  chore/INFRA-101-upgrade-node-20
+```
+
+### Rules
+1. Branch from `main` (or `develop` if using GitFlow)
+2. Keep branches short-lived (max 2-3 days)
+3. Rebase on `main` before creating PR — don't merge main into your branch
+4. Delete branch after merge
+
+---
+
+## Pull Request Standards
+
+### PR Size
+| Size | Lines Changed | Verdict |
+|------|--------------|---------|
+| Small | 1-100 | ✅ Ideal — easy to review |
+| Medium | 100-300 | ⚠️ Acceptable — split if possible |
+| Large | 300-500 | 🔶 Needs justification |
+| Massive | 500+ | ❌ MUST be split into smaller PRs |
+
+**Rule:** If a PR touches more than 5 files across different modules, it's doing too much. Split it.
+
+### PR Description Template
+```markdown
+## What
+Brief description of what this PR does.
+
+## Why
+Why this change is needed. Link to issue/ticket.
+
+## How
+High-level approach. Mention any non-obvious design decisions.
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Integration tests (if applicable)
+- [ ] Manual testing steps
+
+## Screenshots (if UI change)
+Before | After
+```
+
+### PR Review Rules
+1. Every PR needs at least 1 approval
+2. Author resolves all comments before merge
+3. CI must pass (lint, test, build)
+4. No `// TODO` without a linked issue
+5. No `console.log` debugging statements in production code
+
+---
+
+## Commit Atomicity
+
+### Rule: Each Commit Must Be a Complete, Working Unit
+
+```
+❌ BANNED sequence:
+1. feat(user): add user model          ← compiles? maybe
+2. fix: fix import                     ← fixing previous commit
+3. feat(user): add user service        ← compiles? probably
+4. fix: fix typo                       ← fixing previous commit
+5. feat(user): add user controller     ← finally works together
+
+✅ REQUIRED:
+1. feat(user): add user registration module
+   → Model, Service, Controller, Tests — all in one complete, working commit
+   → Or split into logical chunks that each compile and pass tests independently
+```
+
+**Rule:** Every commit on `main` should compile, pass lint, and pass tests. Use interactive rebase (`git rebase -i`) to squash fix-up commits before merging.
+
+---
+
+## .gitignore Standards
+
+### MUST Ignore
+```
+# Dependencies
+node_modules/
+vendor/
+venv/
+__pycache__/
+.gradle/
+target/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/settings.json
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Build output
+dist/
+build/
+out/
+*.min.js
+*.min.css
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+### MUST Commit
+```
+.env.example           # Template with placeholder values
+.editorconfig          # Consistent formatting across IDEs
+.prettierrc            # Formatter config
+.eslintrc.*            # Linter config
+tsconfig.json          # TypeScript config
+docker-compose.yml     # Dev environment
+Makefile / Taskfile    # Standard commands
+```
+
+---
+
+## The Git Health Check
+
+Before pushing:
+- [ ] All commits follow Conventional Commits format
+- [ ] No fixup commits (squash them)
+- [ ] Branch is rebased on latest main
+- [ ] CI passes locally (lint, test, build)
+- [ ] No secrets in any commit (check with `git log -p | grep -i "password\|secret\|key"`)
+- [ ] No merge commits in feature branch (rebase instead)

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

@@ -0,0 +1,174 @@
+# Microservices — When to Split, How to Split
+
+> Don't start with microservices. Earn them through pain.
+> A bad monolith becomes a distributed bad monolith faster than you think.
+
+## The Default: Modular Monolith
+
+**Start with a modular monolith. Always.** Microservices are a scaling strategy, not a design philosophy.
+
+A well-structured modular monolith can handle most applications indefinitely. Splitting prematurely creates distributed complexity without distributed benefits.
+
+---
+
+## The Split Decision Framework
+
+### Prerequisites (ALL Must Be True)
+
+Before even considering microservices, these must exist:
+
+1. **Mature CI/CD pipeline** — automated testing, deployment, rollback
+2. **Observability in place** — distributed tracing, centralized logging, metrics
+3. **Team maturity** — team understands distributed systems failure modes
+4. **Clear module boundaries** — modules already communicate through interfaces, not internals
+
+If any prerequisite is missing, **stop.** Fix the monolith first.
+
+### Trigger Conditions (2+ Required)
+
+Split a module into a service ONLY when **2 or more** of these triggers exist:
+
+| # | Trigger | Evidence |
+|---|---------|----------|
+| 1 | **Deploy conflicts** | Teams block each other on releases; merge queues exceed 24h |
+| 2 | **Scale mismatch** | One module needs 50-100x resources of another |
+| 3 | **Team ownership collision** | Multiple teams edit the same module weekly |
+| 4 | **Fault isolation** | One module crashing must not kill the entire system |
+| 5 | **Technology divergence** | Module genuinely requires a different runtime/language |
+| 6 | **Compliance boundary** | Regulatory requirement to isolate data processing (PCI, HIPAA) |
+
+```
+BANNED: "Let's use microservices because Netflix does"
+BANNED: "We might need to scale later"
+BANNED: "It's more modern"
+BANNED: "Each developer gets their own service"
+```
+
+---
+
+## How to Split (The Extraction Protocol)
+
+### Step 1: Identify the Seam
+
+Find the natural boundary in your modular monolith:
+```
+GOOD seams:
+  - Module communicates with others through a defined interface/API
+  - Module has its own database tables with no foreign keys to other modules
+  - Module can be deployed independently without breaking others
+
+BAD seams:
+  - Two modules share a database table
+  - Extracting requires duplicating business logic
+  - Module makes 10+ synchronous calls to other modules per request
+```
+
+### Step 2: Strangle, Don't Rewrite
+
+```
+❌ BANNED: "Let's rewrite everything as microservices"
+
+✅ REQUIRED: The Strangler Fig Pattern
+1. Build the new service alongside the monolith
+2. Route traffic to the new service gradually (feature flags, proxy rules)
+3. Verify the new service handles all cases correctly
+4. Remove the old code from the monolith
+5. Repeat for the next service, ONE AT A TIME
+```
+
+### Step 3: Define the Contract
+
+Before extracting, define the communication contract:
+
+```
+REQUIRED for every service boundary:
+- API contract (OpenAPI 3.1, Protobuf, or AsyncAPI for events)
+- Versioning strategy (URL versioning, header versioning)
+- Error contract (standardized error response format)
+- SLA definition (latency, availability, throughput)
+- Ownership (which team owns this service)
+```
+
+---
+
+## Communication Patterns
+
+### Synchronous (Request-Response)
+
+| Pattern | When | Watch Out |
+|---------|------|-----------|
+| REST/HTTP | Standard CRUD operations | Cascading failures, tight coupling |
+| gRPC | High-performance, internal services | Schema evolution, debugging complexity |
+
+**Rules:**
+- Always set timeouts (connection: 1s, request: 5s default)
+- Implement circuit breakers (fail-fast after N failures)
+- Never chain more than 3 synchronous calls
+- Implement retries with exponential backoff (transient errors only)
+
+### Asynchronous (Events)
+
+| Pattern | When | Watch Out |
+|---------|------|-----------|
+| Pub/Sub | One event, multiple consumers | Message ordering, at-least-once delivery |
+| Command Queue | Exactly-once processing needed | Dead letter queues, poison messages |
+| Event Sourcing | Full audit trail required | Complexity, event schema evolution |
+
+**Rules:**
+- Prefer async communication over sync between services
+- Events are facts (past tense): `OrderPlaced`, `PaymentProcessed`
+- Commands are requests (imperative): `ProcessPayment`, `ShipOrder`
+- Always handle duplicate messages (idempotency)
+
+---
+
+## Data Ownership
+
+### The Database-Per-Service Rule
+
+```
+❌ DEATH PENALTY: Shared databases between services
+   Service A → Database ← Service B
+   // One schema change breaks both services
+
+✅ REQUIRED: Each service owns its data
+   Service A → Database A
+   Service B → Database B
+   // Services communicate through APIs or events
+```
+
+### Data Consistency
+
+- **Accept eventual consistency** — strong consistency across services is extremely expensive
+- **Use the Saga pattern** for distributed transactions (choreography or orchestration)
+- **Never use distributed 2PC (two-phase commit)** in production — it doesn't scale
+
+---
+
+## Anti-Patterns (Instant Rejection)
+
+| Anti-Pattern | Why It's Dangerous |
+|-------------|-------------------|
+| **Distributed Monolith** | Services that must be deployed together defeat the purpose |
+| **Nano-services** | One function per service creates operational nightmare |
+| **Shared libraries with logic** | Tight coupling through shared code |
+| **Synchronous chains** | A→B→C→D means one failure kills everything |
+| **Shared database** | Schema changes break multiple services |
+| **"We'll figure out observability later"** | You won't find bugs without tracing. Ever. |
+
+---
+
+## The Microservices Readiness Checklist
+
+Before splitting ANY module:
+
+- [ ] 2+ trigger conditions met (documented with evidence)
+- [ ] All prerequisites in place (CI/CD, observability, team maturity)
+- [ ] Service boundary defined with clear ownership
+- [ ] API contract defined (OpenAPI, Protobuf, AsyncAPI)
+- [ ] Data ownership clear — no shared tables
+- [ ] Communication pattern chosen (sync vs async)
+- [ ] Failure handling designed (timeouts, circuit breakers, retries)
+- [ ] Monitoring and alerting planned
+- [ ] Rollback strategy defined
+- [ ] Team agrees this is the right decision (not just the architect)

package/.agent-context/rules/naming-conv.md

@@ -0,0 +1,141 @@
+# Naming Conventions — The "No Lazy Names" Standard
+
+> If your variable name needs a comment to explain it, the name is wrong.
+
+## Universal Rules (All Languages)
+
+### Variables: Nouns That Tell a Story
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+d                           durationInSeconds
+data                        userProfilePayload
+res                         httpResponse
+temp                        unsortedItems
+val                         discountPercentage
+info                        orderSummary
+item                        cartLineItem
+list                        activeSubscriptions
+obj                         paymentConfiguration
+```
+
+**Rule:** A variable name must answer "WHAT is this?" without reading surrounding code.
+
+### Functions: Verbs That Declare Intent
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+process()                   validatePaymentDetails()
+handle()                    routeIncomingWebhook()
+doStuff()                   calculateShippingCost()
+run()                       executeScheduledCleanup()
+getData()                   fetchActiveUsersByRegion()
+check()                     isEligibleForDiscount()
+```
+
+**Rule:** A function name must answer "WHAT does this do?" as a verb phrase. Generic verbs like `process`, `handle`, `manage` are BANNED unless suffixed with a specific noun (e.g., `handlePaymentFailure`).
+
+### Booleans: is/has/can/should Prefix
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+active                      isActive
+logged                      isLoggedIn
+admin                       hasAdminRole
+edit                        canEditDocument
+visible                     shouldRenderSidebar
+```
+
+**Rule:** Boolean variables MUST use `is`, `has`, `can`, or `should` prefix. No exceptions.
+
+### Constants: SCREAMING_SNAKE for True Constants
+```
+❌ BANNED                    ✅ REQUIRED
+─────────────────────────────────────────────
+maxRetries = 3              MAX_RETRY_COUNT = 3
+timeout = 5000              REQUEST_TIMEOUT_MS = 5000
+apiUrl = "..."              API_BASE_URL = "..."
+```
+
+**Rule:** Use SCREAMING_SNAKE_CASE for compile-time constants and config values. Include the unit in the name when applicable (`_MS`, `_BYTES`, `_COUNT`).
+
+### Single-Letter Variables
+**BANNED.** With exactly ONE exception:
+
+```
+// ALLOWED: Classic loop counter in simple iterations
+for (let i = 0; i < items.length; i++) { ... }
+
+// BANNED: Everything else
+const x = getPrice();        // ❌ What is x?
+const n = users.length;      // ❌ Use userCount
+arr.map(v => v.id);          // ❌ Use user => user.id
+```
+
+---
+
+## File & Directory Naming
+
+### Files
+| Type | Convention | Example |
+|------|-----------|---------|
+| Component (React/Vue) | PascalCase | `PaymentForm.tsx` |
+| Module/Service | camelCase or kebab-case | `paymentService.ts` or `payment-service.ts` |
+| Utility | camelCase or kebab-case | `formatCurrency.ts` or `format-currency.ts` |
+| Test | Same as source + `.test`/`.spec` | `paymentService.test.ts` |
+| Type/Interface | PascalCase | `PaymentTypes.ts` |
+| Constant file | SCREAMING_SNAKE or kebab-case | `constants.ts` or `api-endpoints.ts` |
+| Config | kebab-case | `database-config.ts` |
+
+**Rule:** Pick ONE convention per project and enforce it everywhere. Mixing `camelCase` and `kebab-case` in the same project is a code smell.
+
+### Directories
+- Always `kebab-case`: `user-management/`, `payment-processing/`
+- Never PascalCase for directories (except component folders in React convention)
+- No abbreviations: `auth/` → `authentication/` (unless universally understood like `api/`, `db/`)
+
+---
+
+## Abbreviation Policy
+
+### Allowed (Universal)
+`id`, `url`, `api`, `db`, `http`, `io`, `ui`, `dto`, `config`, `env`, `auth`, `admin`, `src`, `lib`, `pkg`, `cmd`, `ctx`, `err`, `req`, `res` (in HTTP handler context only)
+
+### Banned
+Everything else. Spell it out:
+```
+❌ usr → ✅ user
+❌ cnt → ✅ count
+❌ mgr → ✅ manager
+❌ btn → ✅ button
+❌ msg → ✅ message
+❌ impl → ✅ implementation
+❌ calc → ✅ calculate
+❌ proc → ✅ process
+```
+
+---
+
+## The Naming Decision Tree
+
+```
+Is it a boolean?
+  → Yes → Add is/has/can/should prefix
+  → No ↓
+
+Is it a function?
+  → Yes → Start with a verb (fetch, create, validate, calculate, is, has)
+  → No ↓
+
+Is it a constant?
+  → Yes → SCREAMING_SNAKE_CASE with unit suffix
+  → No ↓
+
+Is it a class/type/interface?
+  → Yes → PascalCase, noun, no prefix (not IUser, not UserInterface)
+  → No ↓
+
+It's a variable
+  → Descriptive noun, camelCase
+  → Must be understandable without context
+```

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

@@ -0,0 +1,168 @@
+# Performance — Measure Before You Optimize
+
+> Premature optimization is the root of all evil.
+> But ignoring obvious performance traps is just incompetence.
+
+## The Performance Prime Directive
+
+**Do NOT optimize without evidence.** CPU time is cheap. Developer time is expensive.
+
+BUT — there are patterns so obviously bad that they don't need benchmarks to reject.
+Those are listed below as **Death Penalties**.
+
+---
+
+## Death Penalties (Always Reject)
+
+### 1. N+1 Queries
+```
+❌ INSTANT REJECTION:
+const users = await db.query('SELECT * FROM users');
+for (const user of users) {
+  user.orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [user.id]);
+  // This runs 1 + N queries. For 1000 users = 1001 database round trips.
+}
+
+✅ REQUIRED:
+const users = await db.query('SELECT * FROM users');
+const userIds = users.map(u => u.id);
+const orders = await db.query('SELECT * FROM orders WHERE user_id = ANY($1)', [userIds]);
+// 2 queries total, regardless of user count
+// Or use ORM eager loading / DataLoader pattern
+```
+
+**Rule:** If you see a query inside a loop, it is almost certainly an N+1 bug. Fix it with JOINs, batch queries, or DataLoader.
+
+### 2. Unbounded Queries
+```
+❌ INSTANT REJECTION:
+const allUsers = await db.query('SELECT * FROM users');
+// In production, "users" table has 2 million rows. Enjoy your OOM.
+
+✅ REQUIRED:
+const users = await db.query('SELECT * FROM users LIMIT $1 OFFSET $2', [pageSize, offset]);
+// Or use cursor-based pagination for large datasets
+```
+
+**Rule:** EVERY query that returns a list MUST have a LIMIT. APIs MUST support pagination. Default page size: 20-50.
+
+### 3. SELECT * in Production
+```
+❌ BANNED:
+SELECT * FROM users;  -- Fetches 30 columns when you need 3
+
+✅ REQUIRED:
+SELECT id, email, display_name FROM users;
+```
+
+**Rule:** Select only the columns you need. `SELECT *` wastes bandwidth, memory, and makes schema changes dangerous.
+
+### 4. Synchronous I/O in Async Context
+```
+❌ BANNED:
+// In an async Node.js server
+const data = fs.readFileSync('/path/to/file');
+const result = execSync('some-command');
+
+✅ REQUIRED:
+const data = await fs.promises.readFile('/path/to/file');
+const result = await exec('some-command');
+```
+
+**Rule:** In async environments (Node.js, Python asyncio), NEVER block the event loop with synchronous I/O.
+
+---
+
+## Optimize Only With Evidence
+
+For everything else, follow this protocol:
+
+### Step 1: Measure
+```
+// Use profiling tools, not guesses
+console.time('operation');
+await heavyOperation();
+console.timeEnd('operation');
+
+// Use proper APM: Datadog, New Relic, OpenTelemetry
+```
+
+### Step 2: Identify the Bottleneck
+- Is it CPU? Memory? I/O? Network?
+- Don't optimize CPU when the bottleneck is a slow database query
+
+### Step 3: Optimize the Bottleneck (Not Everything Else)
+- Fix the slowest thing first
+- Re-measure after each change
+- Stop when performance meets requirements
+
+---
+
+## Caching Rules
+
+### When to Cache
+- Data that is read frequently, written rarely
+- Expensive computations that produce the same result for same inputs
+- External API responses (respect their cache headers)
+
+### When NOT to Cache
+- Data that changes every request
+- Small, fast queries (cache overhead > query time)
+- When you can't define a clear invalidation strategy
+
+### The Caching Devil's Triangle
+You can have 2 of 3:
+1. **Fresh data** (always up-to-date)
+2. **Fast reads** (sub-millisecond)
+3. **Simple code** (no cache layer)
+
+Pick your 2 and document the trade-off.
+
+### Invalidation Strategy (MANDATORY)
+```
+❌ BANNED:
+cache.set('users', data);  // When does this expire? Who invalidates it? Nobody knows.
+
+✅ REQUIRED:
+cache.set('users:active', data, { ttl: 300 });  // 5 min TTL, explicit key
+// AND document: "Invalidated on user.created, user.deleted, user.deactivated events"
+```
+
+**Rule:** NEVER add a cache without documenting the invalidation strategy. "We'll figure it out later" means "we'll have stale data in production."
+
+---
+
+## Connection Management
+
+1. **Use connection pools** — never open/close connections per request
+2. **Set pool limits** — max connections based on infrastructure, not infinity
+3. **Implement timeouts** — connection timeout, query timeout, request timeout
+4. **Handle pool exhaustion** — fail fast with clear error, don't queue forever
+
+---
+
+## Frontend Performance (When Applicable)
+
+1. **Lazy load** routes and heavy components
+2. **Debounce** search inputs and scroll handlers (300ms minimum)
+3. **Virtualize** long lists (don't render 10,000 DOM nodes)
+4. **Optimize images** — WebP/AVIF, responsive sizes, lazy loading
+5. **Bundle analysis** — if your JS bundle exceeds 200KB gzipped, investigate
+
+---
+
+## The Performance Decision Framework
+
+```
+Is it a known Death Penalty pattern (N+1, unbounded, SELECT *, sync I/O)?
+  → Yes → Fix it now, no measurement needed
+  → No ↓
+
+Is there a measurable performance problem?
+  → No → Don't optimize. Ship it.
+  → Yes ↓
+
+Have you identified the specific bottleneck?
+  → No → Profile first
+  → Yes → Optimize ONLY that bottleneck, re-measure, stop when sufficient
+```