@ryuenn3123/agentic-senior-core 1.8.0 → 1.8.1

package/.agent-context/skills/backend/data-access.md

@@ -0,0 +1,231 @@
+# Database Patterns & Query Optimization
+
+**Tier:** EXPERT | **Source:** awesome-copilot (schema design) + antigravity (N+1 patterns) + minimax (Django ORM)
+
+## Part 1: Schema Design (3NF Normalization)
+
+### The Problem: Data Redundancy
+
+ **Denormalized (redundant):**
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_name VARCHAR(255),      -- Redundant: can look up from customers table
+  customer_email VARCHAR(255),     -- Redundant
+  customer_tier VARCHAR(50),       -- Redundant
+  amount DECIMAL(10,2),
+  created_at TIMESTAMP
+);
+```
+
+Problem: Update customer name -> must update in `orders` table too (data inconsistency risk).
+
+###  **3NF (Normalized):**
+
+```sql
+CREATE TABLE customers (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255),
+  email VARCHAR(255),
+  tier VARCHAR(50),
+  created_at TIMESTAMP
+);
+
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_id UUID NOT NULL REFERENCES customers(id),
+  amount DECIMAL(10,2),
+  created_at TIMESTAMP
+);
+
+-- To get order with customer name:
+SELECT o.id, o.amount, c.name
+FROM orders o
+JOIN customers c ON o.customer_id = c.id;
+```
+
+**Benefits:**
+- Single source of truth (customer name in one place)
+- Updates atomic (change name, not duplicated)
+- Consistent joins
+
+### When to Break 3NF (Denormalization)
+
+Denormalize **only if** profiling shows JOIN is bottleneck:
+
+```sql
+-- ONLY if "SELECT ... JOIN customers" is slow:
+ALTER TABLE orders ADD COLUMN customer_name VARCHAR(255);
+
+-- Keep redundancy in sync with trigger:
+CREATE TRIGGER sync_customer_name
+AFTER UPDATE ON customers
+FOR EACH ROW
+UPDATE orders SET customer_name = NEW.name WHERE customer_id = NEW.id;
+```
+
+---
+
+## Part 2: Indexes (FK + Query Optimization)
+
+### Rule: Always Index Foreign Keys
+
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_id UUID NOT NULL REFERENCES customers(id),
+  created_at TIMESTAMP,
+  
+  -- Foreign key queries need fast lookup
+  INDEX idx_customer_id (customer_id),
+  -- Query by date also common
+  INDEX idx_created_at (created_at)
+);
+```
+
+Without index on `customer_id`, query `SELECT * FROM orders WHERE customer_id = ?` scans entire table (O(n)).
+
+With index, it's O(log n) via B-tree lookup.
+
+### Composite Indexes (When Queries Filter by Multiple Columns)
+
+```sql
+-- If queries often filter by (customer_id, created_at > date):
+INDEX idx_customer_date (customer_id, created_at DESC);
+
+-- Good for: SELECT * FROM orders WHERE customer_id = ? AND created_at > ?
+-- Bad for: SELECT * FROM orders WHERE created_at > ? (first column must match)
+```
+
+---
+
+## Part 3: Query Patterns (Anti-Patterns)
+
+### Anti-Pattern #1: N+1 Query Problem
+
+ **WRONG:**
+```javascript
+const customers = await db.query('SELECT * FROM customers');
+for (const customer of customers) {
+  customer.orders = await db.query(
+    'SELECT * FROM orders WHERE customer_id = $1',
+    [customer.id]  // <- Executes once per customer (N+1 queries!)
+  );
+}
+```
+
+**Cost:** 1 query (customers) + N queries (orders per customer) = **N+1 total**. If 100 customers, 101 queries.
+
+ **CORRECT (JOIN):**
+```javascript
+const results = await db.query(`
+  SELECT 
+    c.id as customer_id,
+    c.name,
+    o.id as order_id,
+    o.amount
+  FROM customers c
+  LEFT JOIN orders o ON c.id = o.customer_id
+`);
+
+// Post-process to group
+const customersWithOrders = {};
+for (const row of results) {
+  if (!customersWithOrders[row.customer_id]) {
+    customersWithOrders[row.customer_id] = {
+      id: row.customer_id,
+      name: row.name,
+      orders: []
+    };
+  }
+  if (row.order_id) {
+    customersWithOrders[row.customer_id].orders.push({ id: row.order_id, amount: row.amount });
+  }
+}
+```
+
+**Cost:** 1 JOIN query (fast).
+
+### Anti-Pattern #2: SELECT * (Load Unnecessary Columns)
+
+ **WRONG:**
+```javascript
+const customer = await db.one('SELECT * FROM customers WHERE id = $1', [id]);
+console.log(customer.name);  // But loaded email, phone, address too
+```
+
+ **CORRECT (Project columns):**
+```javascript
+const customer = await db.one(
+  'SELECT id, name, email FROM customers WHERE id = $1',
+  [id]  // Only load what's needed
+);
+```
+
+---
+
+## Part 4: Safe Zero-Downtime Migrations
+
+### The Problem: Data Migrations Block Requests
+
+```sql
+ALTER TABLE customers ADD COLUMN phone VARCHAR(20);
+-- ^ Blocks all INSERT/UPDATE on customers table during migration (can be seconds~minutes for large tables)
+```
+
+### Strategy: Backward-Compatible Migrations
+
+**Step 1: Add column (no default = already nullable):**
+```sql
+ALTER TABLE customers ADD COLUMN phone VARCHAR(20);
+```
+
+**Step 2: Backfill data (in batches to avoid lock):**
+```javascript
+// Run offline / in background job
+const BATCH_SIZE = 10000;
+let offset = 0;
+while (true) {
+  const updated = await db.query(`
+    UPDATE customers 
+    SET phone = ''
+    WHERE id IN (
+      SELECT id FROM customers 
+      WHERE phone IS NULL
+      LIMIT $1
+    )
+  `, [BATCH_SIZE]);
+  if (updated.rowCount === 0) break;
+  offset += BATCH_SIZE;
+  await sleep(1000);  // Rate limit to avoid overwhelming DB
+}
+```
+
+**Step 3: Code deployment (app handles both old + new):**
+```javascript
+// Service layer reads/writes phone
+if (newCustomer.phone) {
+  await customerRepo.update(customerId, { phone: newCustomer.phone });
+}
+```
+
+Old code still works (ignores phone), new code uses it.
+
+**Step 4: After migration successful, remove the column (or rename old):**
+```sql
+-- Keep old column renamed for rollback safety
+ALTER TABLE customers RENAME COLUMN phone_old TO phone_deprecated;
+```
+
+---
+
+## Checklist
+
+- [ ] All tables in 3NF
+- [ ] Foreign keys indexed
+- [ ] JOIN queries avoid N+1 (load related data in one query)
+- [ ] SELECT projects specific columns (not *)
+- [ ] Indexes match WHERE + ORDER BY + JOIN ON patterns
+- [ ] Migrations backward-compatible + batched
+- [ ] Query performance profiled (EXPLAIN ANALYZE)
+- Watch for N+1 and hidden coupling.

package/.agent-context/skills/backend/errors.md

@@ -0,0 +1,138 @@
+# Error Handling & Recovery
+
+**Tier:** ADVANCE | **Source:** awesome-copilot (typed errors) + antigravity (recovery patterns) + minimax (error boundary)
+
+## Rule: Never Swallow Errors
+
+ **WRONG:**
+```javascript
+try {
+  const payment = await processPayment();
+} catch (err) {
+  console.log('oops');  // <- Error lost, no recovery
+}
+```
+
+ **CORRECT:**
+```javascript
+try {
+  const payment = await processPayment();
+} catch (err) {
+  if (err instanceof PaymentDeclinedError) {
+    // KNOWN: Card declined, user can try again with different card
+    throw err;
+  } else if (err instanceof NetworkTimeoutError) {
+    // MAYBE TEMPORARY: Retry with exponential backoff
+    return await retryWithBackoff(() => processPayment());
+  } else {
+    // UNKNOWN: Log + alert ops team
+    logger.error({ err, context: { customerId, amount } });
+    throw new InternalServerError('Payment processing failed');
+  }
+}
+```
+
+---
+
+## Typed Error Codes
+
+Instead of generic "Error", use specific, typed errors:
+
+### Node.js + Custom Error Classes
+
+```javascript
+class ApplicationError extends Error {
+  constructor(code, message, statusCode = 500, details = {}) {
+    super(message);
+    this.code = code;  // Machine-readable
+    this.statusCode = statusCode;  // HTTP status
+    this.details = details;
+  }
+}
+
+class PaymentDeclinedError extends ApplicationError {
+  constructor(reason) {
+    super('PAYMENT_DECLINED', `Card declined: ${reason}`, 402, { reason });
+  }
+}
+
+// Usage in service:
+if (customer.balance < amount) {
+  throw new PaymentDeclinedError('Insufficient funds');
+}
+
+// Transport layer catches and responds:
+app.post('/payments/charge', async (req, res) => {
+  try {
+    const result = await paymentService.charge(req.body);
+    res.json(result);
+  } catch (err) {
+    if (err instanceof ApplicationError) {
+      res.status(err.statusCode).json({
+        error: err.code,
+        message: err.message,
+        details: err.details
+      });
+    } else {
+      res.status(500).json({ error: 'INTERNAL_SERVER_ERROR' });
+    }
+  }
+});
+```
+
+---
+
+## Correlation IDs (Debug Multi-Service Requests)
+
+When requests span multiple services, trace them with correlation IDs:
+
+```javascript
+// Transport layer: Generate or receive correlation ID
+app.use((req, res, next) => {
+  req.correlationId = req.headers['x-correlation-id'] || generateUUID();
+  res.setHeader('x-correlation-id', req.correlationId);
+  next();
+});
+
+// Service layer: Attach to all logs
+logger.info({
+  message: 'Processing payment',
+  correlationId: req.correlationId,
+  customerId,
+  amount
+});
+
+// Logs across all services will have same correlationId
+```
+
+---
+
+## Retry Strategy
+
+```javascript
+async function retryWithBackoff(fn, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt === maxAttempts) throw err;
+      if (!(err instanceof NetworkTimeoutError)) throw err;
+      
+      const delay = Math.pow(2, attempt - 1) * 1000;  // 1s, 2s, 4s
+      await sleep(delay);
+    }
+  }
+}
+```
+
+---
+
+## Checklist
+
+- [ ] All caught errors are typed (not generic `Error`)
+- [ ] All errors have machine-readable code
+- [ ] Production errors logged with context (correlationId, userId)
+- [ ] Retry logic only for transient failures (timeouts, 5xx)
+- [ ] User-level errors have helpful messages (no SQL/stack traces)
+- [ ] Critical errors alert ops (Slack, PagerDuty)
+- Keep retry and rollback behavior explicit.

package/.agent-context/skills/backend/validation.md

@@ -0,0 +1,117 @@
+# Input Validation & Parameterized Queries
+
+**Tier:** ADVANCE | **Source:** awesome-copilot (boundaries) + antigravity (security halt) + minimax (validation patterns)
+
+## Why Validation at Boundaries Matters
+
+Rule: **All external input is untrusted.** Validate at API entry point before touching business logic or database.
+
+Common vulnerabilities when skipped:
+- SQL injection: Unparameterized queries with user input
+- Type confusion: String input treated as number
+- Business logic bypass: Missing eligibility checks
+- Data corruption: Invalid state transitions
+
+**SECURITY HALT:** If you find unvalidated input directly in database queries, stop feature development. Fix first.
+
+---
+
+## Layer 1: HTTP Request Validation
+
+Validate shape, type, required fields **before** touching service layer.
+
+### Node.js + Zod (Type-Safe)
+
+```javascript
+import { z } from 'zod';
+
+const chargeSchema = z.object({
+  amount: z.number().min(50).max(100000),
+  customerId: z.string().uuid(),
+  cardToken: z.string().min(10).max(1000),
+});
+
+app.post('/payments/charge', async (req, res) => {
+  // Validate shape + types
+  const parsed = chargeSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({
+      error: 'Invalid request',
+      details: parsed.error.errors
+    });
+  }
+
+  // Now safe to pass to service
+  const result = await paymentService.charge(parsed.data);
+  res.json(result);
+});
+```
+
+### Python + Pydantic
+
+```python
+from pydantic import BaseModel, Field
+
+class ChargeRequest(BaseModel):
+    amount: float = Field(..., ge=50, le=100000)
+    customer_id: str = Field(..., min_length=36, max_length=36)
+    card_token: str = Field(..., min_length=10, max_length=1000)
+
+@app.post("/payments/charge")
+async def charge_payment(req: ChargeRequest):
+    result = await payment_service.charge(req.dict())
+    return result
+```
+
+---
+
+## Layer 2: SQL Query Parameterization
+
+###  WRONG (SQL Injection)
+
+```javascript
+const customerId = req.body.customerId;
+const query = `SELECT * FROM customers WHERE id = '${customerId}'`;
+// Input: '; DROP TABLE customers; --'
+```
+
+###  CORRECT (Parameterized)
+
+```javascript
+await db.one(
+  'SELECT * FROM customers WHERE id = $1',
+  [customerId]  // Parameterized
+);
+```
+
+---
+
+## Layer 3: Business Logic Validation
+
+```javascript
+async charge({ amount, customerId, cardToken }) {
+  // Already validated: amount in range, customerId is UUID
+
+  // Now validate business rules
+  const customer = await customerRepo.findById(customerId);
+  if (!customer) throw new NotFoundError('Customer');
+  if (customer.status !== 'active') throw new BusinessError('Account suspended');
+  if (customer.dailyLimit && customer.dailySpent + amount > customer.dailyLimit) {
+    throw new BusinessError('Daily limit exceeded');
+  }
+
+  // Safe to proceed
+}
+```
+
+---
+
+## Checklist
+
+- [ ] All route handlers validate request shape (Zod/Pydantic)
+- [ ] All database queries use parameterized statements
+- [ ] All external API responses validated before use
+- [ ] Business rules checked in Service layer
+- [ ] Error messages safe (no SQL leaked to client)
+- [ ] Tests cover invalid inputs
+- Keep validation deterministic and testable.

package/.agent-context/skills/backend.md

@@ -0,0 +1,29 @@
+# Backend Skill Pack
+
+Default tier: `advance`
+
+## Purpose
+Build backend systems with strict layer separation, typed boundaries, and operational safety.
+
+## In Scope
+- Transport, service, repository, and domain separation
+- Validation at boundaries
+- Error handling and observability
+- Data access and transaction safety
+- API and event contract design
+
+## Must-Have Checks
+- No business logic in transport layer
+- No HTTP objects in application layer
+- No raw SQL in controllers or services
+- All external input validated before business logic
+- Typed errors and explicit failure paths
+
+## Evidence
+- Unit and integration tests
+- API contract docs
+- Validation schemas
+- Release gate output
+
+## Fallback
+- Standard mode is allowed only for legacy compatibility and must be flagged in release evidence.

package/.agent-context/skills/cli/README.md

@@ -0,0 +1,50 @@
+# CLI Engineering Skills
+
+Default tier: `advance`
+
+This domain covers command design, safe mutation workflows, and machine-readable output conventions for automation.
+
+## Topics
+- [Init Flow](init.md) - Deterministic project initialization with explicit write plans
+- [Upgrade Flow](upgrade.md) - Safe upgrades with dry-run, rollback, and compatibility checks
+- [Machine-Readable Output](output.md) - Stable JSON output and deterministic exit semantics
+
+## Operating Model
+- Use `advance` for normal command work.
+- Escalate to `expert` when commands mutate user state or require migration safety.
+
+## Above-Line Additions
+- Mandatory dry-run support for mutating commands.
+- Structured error payloads for CI/CD and bots.
+- Explicit rollback plans for upgrade paths.
+- Plug-and-play init presets for common stacks and blueprints.
+
+## Installation and Entry Paths
+
+Choose the path that fits your workflow:
+
+- `agentic-senior-core launch` for a numbered interactive chooser.
+- `npm install -g @fatidaprilian/agentic-senior-core` for a global command.
+- `npm exec --yes @fatidaprilian/agentic-senior-core init` for a one-off run.
+- `npx @fatidaprilian/agentic-senior-core init` for a package-managed local run.
+- GitHub template for zero-install project bootstrap.
+
+## Preset Starts
+
+Use presets when you want fewer choices at the start:
+
+- `frontend-web` - TypeScript + API Next.js + balanced profile.
+- `backend-api` - Python + FastAPI + balanced profile.
+- `fullstack-product` - TypeScript + API Next.js + balanced profile.
+- `platform-governance` - Go + Go service + strict profile.
+- `mobile-react-native` - React Native + mobile app + balanced profile.
+- `mobile-flutter` - Flutter + mobile app + balanced profile.
+- `observability-platform` - Go + observability + strict profile.
+
+Example:
+
+```bash
+agentic-senior-core init --preset frontend-web
+agentic-senior-core init --preset backend-api --ci true
+agentic-senior-core launch
+```

package/.agent-context/skills/cli/init.md

@@ -0,0 +1,38 @@
+# Init Flow
+
+Tier: ADVANCE
+
+Initialization commands must be deterministic, reversible where possible, and explicit about filesystem mutations.
+
+## Design Principles
+
+- Predictable output for identical input flags.
+- Safe defaults when users omit options.
+- Preflight summary before any file write.
+
+## Required Init Sequence
+
+1. Validate prerequisites (runtime, permissions, existing files).
+2. Resolve stack/profile/blueprint selection.
+3. Print write plan summary.
+4. Apply scaffold atomically.
+5. Emit machine-readable onboarding report.
+
+## Write Safety
+
+- Refuse to overwrite existing files without explicit flag.
+- Use idempotent initialization where feasible.
+- Keep generated files grouped by feature intent, not random dump.
+
+## Anti-Patterns
+
+- Hidden writes without disclosure.
+- Interactive-only flow with no non-interactive equivalent.
+- Ambiguous defaults that vary by environment.
+
+## Review Checklist
+
+- [ ] Preflight checks are explicit and actionable.
+- [ ] Generated file set is deterministic.
+- [ ] Dry-run preview exists for init planning.
+- [ ] Exit codes distinguish validation vs runtime failures.

package/.agent-context/skills/cli/output.md

@@ -0,0 +1,36 @@
+# Machine-Readable Output
+
+Tier: ADVANCE
+
+CLI output must support both human readability and automation reliability.
+
+## Output Contract
+
+- Human mode: concise narrative and actionable next steps.
+- JSON mode: deterministic schema, stable field names, and clear status.
+
+## JSON Schema Guidelines
+
+- Include `version`, `timestamp`, `status`, and `summary`.
+- Include `artifacts` list for produced files.
+- Include `errors` array with machine-readable codes.
+- Avoid embedding plain stack traces in public payloads.
+
+## Exit Code Conventions
+
+- `0`: success
+- `1`: validation or runtime failure
+- `2`: policy/gate failure
+
+## Determinism Rules
+
+- Stable key ordering where practical.
+- No random IDs unless explicitly requested.
+- Timestamps in ISO 8601 format.
+
+## Review Checklist
+
+- [ ] JSON output passes schema validation.
+- [ ] Exit codes match documented behavior.
+- [ ] Error payload includes code and remediation hint.
+- [ ] Human output remains concise and useful.

package/.agent-context/skills/cli/upgrade.md

@@ -0,0 +1,38 @@
+# Upgrade Flow
+
+Tier: ADVANCE
+
+Upgrade commands must prioritize compatibility, transparency, and recovery.
+
+## Required Controls
+
+- Dry-run mode to preview changes.
+- Compatibility checks before mutation.
+- Backup or rollback path for critical files.
+
+## Upgrade Sequence
+
+1. Read current version and target version.
+2. Evaluate compatibility matrix.
+3. Produce migration plan (files to add/change/remove).
+4. Execute with transactional mindset.
+5. Emit post-upgrade report with changed artifacts.
+
+## Failure Handling
+
+- On partial failure, rollback modified artifacts or provide deterministic recovery instructions.
+- Never leave silent half-upgraded state.
+- Exit with explicit status code and structured error payload.
+
+## Anti-Patterns
+
+- In-place mutation without preview.
+- Version bump without migration note.
+- Breaking changes in minor release without contract guard.
+
+## Review Checklist
+
+- [ ] Dry-run output is complete and stable.
+- [ ] Upgrade report captures all changed files.
+- [ ] Rollback path is tested.
+- [ ] Compatibility failures block mutation.

package/.agent-context/skills/cli.md

@@ -0,0 +1,29 @@
+# CLI Skill Pack
+
+Default tier: `advance`
+
+## Purpose
+Create smart command-line workflows that guide users efficiently and safely.
+
+## In Scope
+- Interactive initialization and upgrade flows
+- Safe defaults and confirmation steps
+- Machine-readable output for automation
+- Validation and self-healing hooks
+- Cross-platform shell behavior
+
+## Must-Have Checks
+- Explicit command help and examples
+- Deterministic output format for automation
+- Safe destructive-action guards
+- Validation before mutation
+- Exit codes reflect success and failure clearly
+
+## Evidence
+- CLI smoke tests
+- Machine-readable report output
+- Upgrade dry-run output
+- Cross-platform execution notes
+
+## Fallback
+- Standard mode can remain available for compatibility, but advance is the default user experience.