@ryuenn3123/agentic-senior-core 1.8.0 → 1.8.1

package/.agent-context/blueprints/mobile-app.md

@@ -0,0 +1,21 @@
+# Mobile App Blueprint
+
+This blueprint defines the starter shape for a mobile product that needs a clean separation between UI, device integration, and backend contracts.
+
+## Structure
+
+- Transport: device events, navigation entry points, push notifications, and platform channels.
+- Service: orchestration, screen-level state, validation, and user-facing workflows.
+- Repository: remote API clients, local storage adapters, and persistence abstractions.
+
+## Starter Rules
+
+- Keep screens focused on rendering and user interaction only.
+- Move API access, caching, and serialization into adapter layers.
+- Use consistent error handling for offline, permission, and platform failures.
+- Add release checks for signing, packaging, and crash telemetry before shipping.
+
+## Recommended Stack Pairings
+
+- React Native for teams that want JavaScript or TypeScript alignment.
+- Flutter for teams that want a strongly structured UI toolkit.

package/.agent-context/review-checklists/frontend-skill-parity.md

@@ -0,0 +1,28 @@
+# Frontend Skill Parity Checklist
+
+Use this checklist to enforce mandatory frontend parity aligned with benchmark-driven standards from `MiniMax-AI/skills` `frontend-dev` profile.
+
+## Architecture and Composition
+- [ ] Frontend structure follows feature-driven organization.
+- [ ] Smart and dumb component separation is explicit and documented.
+- [ ] Server state and client state boundaries are documented and enforced.
+
+## Interaction and Motion
+- [ ] Primary user journey includes intentional animation without motion overload.
+- [ ] Reduced-motion fallback behavior is implemented and documented.
+- [ ] Transition timing and easing are consistent across key screens.
+
+## Accessibility and Responsiveness
+- [ ] Keyboard navigation works on all critical flows.
+- [ ] Contrast, typography scale, and focus visibility pass baseline checks.
+- [ ] Layout behavior is validated across mobile and desktop breakpoints.
+
+## UX Narrative and Conversion Clarity
+- [ ] Page hierarchy communicates value proposition within first viewport.
+- [ ] Primary calls to action are explicit and consistently placed.
+- [ ] Error and empty states contain actionable guidance.
+
+## Release Evidence
+- [ ] Frontend parity checklist artifact is attached to release evidence.
+- [ ] Frontend usability audit report is attached to release evidence.
+- [ ] Any parity waiver includes owner, expiry, and risk statement.

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

@@ -0,0 +1,63 @@
+# Skill Platform
+
+The skill platform is the internal skill system for Agentic-Senior-Core.
+
+## Design Goals
+- Unify skill content from benchmark repositories into one governed platform.
+- Make `advance` the default operating tier.
+- Keep `standard` only as a compatibility fallback.
+- Require evidence, validation, and release gates for every skill pack.
+
+## Tier Model
+
+### standard
+- Compatibility mode only.
+- Minimal guidance.
+- No default status for new work.
+
+### advance
+- Default operating tier.
+- Efficient, opinionated, and production-aware.
+- Used for normal feature delivery.
+
+### expert
+- For complex architecture, integration, and critical refactors.
+- Requires stronger evidence and review depth.
+
+### above
+- For release-critical, cross-domain, or enterprise governance work.
+- Requires full evidence bundle and explicit owner signoff.
+
+## Domain Packs
+- [Frontend](frontend/README.md)
+- [Backend](backend/README.md)
+- [Fullstack](fullstack/README.md)
+- [CLI](cli/README.md)
+- [Distribution](distribution/README.md)
+- [Review Quality](review-quality/README.md)
+
+## Folder Structure
+```text
+.agent-context/skills/
+├── README.md
+├── index.json
+├── frontend/
+├── backend/
+├── fullstack/
+├── cli/
+├── distribution/
+└── review-quality/
+```
+
+Each domain folder has its own README plus topic-level docs so the platform can scale like a curated skills library.
+
+## Benchmark Sources
+- sickn33/antigravity-awesome-skills
+- github/awesome-copilot
+- MiniMax-AI/skills
+
+## Platform Rules
+- Every skill pack must define purpose, inputs, outputs, validation, evidence, and fallback.
+- Every skill pack must state the default tier it targets.
+- Every release must include a skill parity check for the configured tiers.
+- Every deviation from the default tier must be justified in the evidence bundle.

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

@@ -0,0 +1,68 @@
+# Backend Engineering Skills
+
+The backend domain covers server-side architecture, business logic, data access patterns, error handling, and operational concerns. Content consolidated from **antigravity-awesome-skills**, **awesome-copilot**, and **MiniMax-AI/skills**, with supercharging improvements ("above the line" automation and enforcement).
+
+## Topics
+
+- **[architecture.md](architecture.md)** - Layered design (Transport->Service->Repository), monolith vs microservices, SoC patterns, dependency management, strangler fig migrations
+- **[validation.md](validation.md)** - Input sanitization, schema validation at API boundary, parameterized queries, typed errors
+- **[data-access.md](data-access.md)** - Database design (3NF), query optimization (N+1 detection), safe zero-downtime migrations, indexing strategy
+- **[errors.md](errors.md)** - Typed error codes, recovery patterns, debugging protocols, logging + correlation IDs
+
+## What Makes Ours Different
+
+- Layered Architecture (awesome-copilot) + Microservices Decision Framework (antigravity) + Project Structure (minimax)
+- Dependency Auditor (ABOVE LINE) - Detect circular dependencies and enforce Transport->Service->Repository direction
+- Zero-Downtime Migration Validator (ABOVE LINE) - Scan migrations, flag risky patterns, and suggest remediation
+- Secrets Detector (ABOVE LINE) - Static scan for hardcoded API keys and database passwords
+
+## Recommended Reading Order
+
+1. `architecture.md` - Understand mental models (EXPERT tier)
+2. `validation.md` - Protect at boundaries (ADVANCE tier)
+3. `data-access.md` - Query strategy (EXPERT tier)
+4. `errors.md` - Error handling pipeline (ADVANCE tier)
+
+Then run:
+```bash
+npm run validate            # Ensure tier structure
+npm test                    # Verify examples compile
+agentic-senior-core skill backend --tier expert  # See consolidated content
+```
+
+## Tier Defaults per Topic
+
+| Topic | Default Tier | Focus |
+|-------|--------------|-------|
+| architecture | EXPERT | Layering, dependencies, monolith->microservices migration |
+| validation | ADVANCE | Boundary protection, Zod/Pydantic examples |
+| data-access | EXPERT | 3NF design, N+1 patterns, safe migrations, indexed FKs |
+| errors | ADVANCE | Typed codes, recovery, correlation IDs, logging |
+
+## Comparative Coverage vs Benchmarks
+
+| Aspect | antigravity | awesome-copilot | MiniMax | Ours |
+|--------|-------------|-----------------|---------|------|
+| Layered Architecture | Medium | High | Medium | High + policy enforcement |
+| Monolith to Microservices | High | Medium | Medium | High + migration strategy |
+| Database Design | Medium | High | Medium | High + guardrails |
+| Error Handling | High | Medium | Medium | High + typed recovery path |
+| Automation Tools | None | None | None | Dependency auditor, migration validator, secrets scanner |
+
+## How to Use
+
+**For init workflow:**
+```bash
+agentic-senior-core init --stack typescript --blueprint api-nextjs
+# Activates: frontend, fullstack, backend, cli skills
+# Default tier: advance
+```
+
+**For explicit skill selection:**
+```bash
+agentic-senior-core skill backend --tier expert
+# Outputs: architecture + validation + data-access + errors at EXPERT level
+```
+
+**For skill reference in .cursorrules:**
+Content from this domain automatically includes in `.cursorrules` when activated.

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

@@ -0,0 +1,361 @@
+# Backend Architecture
+
+**Tier:** EXPERT | **Source:** awesome-copilot (layering) + antigravity (microservices) + minimax (project structure)
+
+## Overview
+
+Backend architecture defines how code is organized, how concerns separate, and how services scale. Three critical decisions:
+1. **Layered separation** - Transport (HTTP) vs Service (logic) vs Repository (data)
+2. **Monolith or microservices** - When to split, when to keep together
+3. **Dependency direction** - Which layers can import which
+
+Wrong choices here create spaghetti code, circular dependencies, and costly rewrites. Right choices enable independent scaling, testing, and team autonomy.
+
+---
+
+## Part 1: Layered Architecture (Transport -> Service -> Repository)
+
+### The Model
+
+Clean architecture separates concerns into independent layers:
+
+```
+┌─────────────────────────────────┐
+│  HTTP / Handlers / Middleware   │ <- TRANSPORT LAYER
+├─────────────────────────────────┤
+│  Business Logic / Orchestration │ <- SERVICE LAYER
+├─────────────────────────────────┤
+│  Data Access / Queries / Caching│ <- REPOSITORY LAYER
+├─────────────────────────────────┤
+│  External APIs / Databases      │ <- INFRASTRUCTURE
+└─────────────────────────────────┘
+```
+
+**Dependency Rule:** Layer below can NEVER import layer above.
+- Transport CAN import Service 
+- Service CAN import Repository 
+- Repository can NEVER import Service 
+- Service can NEVER import Transport 
+
+### TRANSPORT LAYER (HTTP Handlers, Middleware)
+
+**Responsibility:** Parse HTTP requests, serialize responses, handle authentication, logging middleware.
+
+**What goes here:**
+- Request validation (type, format checks)
+- Middleware (auth, CORS, rate limiting, logging)
+- Route handlers (receive request -> call service -> return response)
+- Response serialization (JSON, XML, protobuf)
+
+**What does NOT go here:**
+- Business logic (validation rules, calculations, state transitions)
+- Database queries
+- Feature flags, configuration decisions
+
+**Example (Node.js + Express):**
+```javascript
+//  CORRECT: Transport layer
+app.post('/payments/charge', 
+  authenticate,                    // Middleware
+  validateRequest(chargeSchema),   // Format check
+  async (req, res) => {
+    const result = await paymentService.charge({
+      amount: req.body.amount,
+      customerId: req.body.customerId,
+      idempotencyKey: req.headers['idempotency-key']
+    });
+    res.json(result);
+  }
+);
+
+// Service layer has business logic:
+async function charge({ amount, customerId, idempotencyKey }) {
+  // Check customer credit, calculate fees, call repository
+  // NO HTTP HERE
+}
+```
+
+**Anti-Pattern:** Business logic in handler
+
+```javascript
+//  WRONG: Business logic in transport
+app.post('/payments/charge', async (req, res) => {
+  const customer = await db.query('SELECT * FROM customers WHERE id = ?', customerId);
+  if (customer.balance < amount) throw new Error('Insufficient funds');  // <- Logic?
+  const fee = amount * 0.03 + 0.30;  // <- Math in handler?
+  const charged = await db.query('UPDATE customers SET balance = balance - ?', amount + fee);
+  // ...
+});
+```
+
+### SERVICE LAYER (Business Logic, Orchestration)
+
+**Responsibility:** Business rules, data transformations, orchestration across repositories, feature flags, error handling.
+
+**What goes here:**
+- Validation rules (customer eligibility, amount limits)
+- Business calculations (fees, commissions, discounts)
+- Orchestration (call repo A, then repo B, handle failure)
+- Idempotency keys for distributed transactions
+- Feature flags / circuit breakers
+
+**What does NOT go here:**
+- Database queries (use Repository)
+- HTTP parsing, serialization (use Transport)
+- External API calls directly (wrap in Repository-like abstraction)
+
+**Example:**
+```javascript
+class PaymentService {
+  constructor(customerRepo, paymentRepo, ledgerRepo) {
+    this.customerRepo = customerRepo;
+    this.paymentRepo = paymentRepo;
+    this.ledgerRepo = ledgerRepo;
+  }
+
+  async charge({ amount, customerId, idempotencyKey }) {
+    // Check idempotency first (prevent double-charge)
+    const existing = await this.paymentRepo.findByIdempotencyKey(idempotencyKey);
+    if (existing) return existing;  // Already charged
+
+    // Business validation
+    const customer = await this.customerRepo.findById(customerId);
+    if (!customer) throw new NotFoundError('Customer not found');
+    if (customer.status !== 'active') throw new BusinessError('Account inactive');
+    if (amount < 50 || amount > 100000) throw new ValidationError('Amount out of range');
+
+    // Calculate fees
+    const fee = this._calculateFee(amount, customer.tier);
+    const total = amount + fee;
+
+    // Orchestrate transaction
+    try {
+      const payment = await this.paymentRepo.create({
+        customerId,
+        amount,
+        fee,
+        total,
+        idempotencyKey,
+        status: 'pending'
+      });
+
+      await this.ledgerRepo.debit({
+        customerId,
+        amount: total,
+        reason: `Payment ${payment.id}`,
+        paymentId: payment.id
+      });
+
+      await this.paymentRepo.update(payment.id, { status: 'completed' });
+      return payment;
+    } catch (err) {
+      await this.paymentRepo.update(payment.id, { status: 'failed', error: err.message });
+      throw err;
+    }
+  }
+
+  _calculateFee(amount, tier) {
+    const baseRate = { silver: 0.029, gold: 0.019, platinum: 0.009 }[tier];
+    const flatFee = { silver: 0.50, gold: 0.30, platinum: 0 }[tier];
+    return Math.round(amount * baseRate * 100) / 100 + flatFee;
+  }
+}
+```
+
+### REPOSITORY LAYER (Data Access, Queries)
+
+**Responsibility:** Data retrieval, persistence, query optimization, caching, connection pooling.
+
+**What goes here:**
+- Database queries (SELECT, INSERT, UPDATE, DELETE)
+- Prepared statements, parameterized queries
+- Indexes, query optimization
+- Batch operations
+- Query caching (cache-aside, write-through)
+- Connection pooling
+
+**What does NOT go here:**
+- Business logic (decisions based on data)
+- HTTP handling
+- External API calls (unless wrapping as data source)
+
+**Example:**
+```javascript
+class PaymentRepository {
+  constructor(db) {
+    this.db = db;
+  }
+
+  async findByIdempotencyKey(key) {
+    return this.db.one(
+      'SELECT * FROM payments WHERE idempotency_key = $1',
+      [key]  // Parameterized query 
+    );
+  }
+
+  async create(payment) {
+    return this.db.one(
+      `INSERT INTO payments 
+       (customer_id, amount, fee, total, idempotency_key, status, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6, NOW())
+       RETURNING *`,
+      [payment.customerId, payment.amount, payment.fee, payment.total, 
+       payment.idempotencyKey, payment.status]
+    );
+  }
+
+  async update(id, updates) {
+    const fields = [];
+    const values = [];
+    let paramCount = 1;
+    for (const [key, val] of Object.entries(updates)) {
+      fields.push(`${key} = $${paramCount++}`);
+      values.push(val);
+    }
+    values.push(id);
+    return this.db.one(
+      `UPDATE payments SET ${fields.join(', ')} WHERE id = $${paramCount} RETURNING *`,
+      values
+    );
+  }
+}
+```
+
+---
+
+## Part 2: Monolith vs Microservices (Decision Framework)
+
+### When to Stay Monolithic
+
+**Keep monolith if:**
+- Team < 30 people (communication overhead still low)
+- Feature dependencies high (changing one feature requires touching multiple areas)
+- Deployment frequency < weekly (update entire system at once is acceptable)
+- Data strongly coupled (customers, orders, payments in one domain)
+- Performance latency-sensitive < 100ms (in-process calls beat RPC)
+
+**Monolith advantages:**
+- Single deployment unit (easier to roll forward/back)
+- ACID transactions easy (in same database)
+- Debugging simpler (logs in one place, single memory space)
+- Performance: in-memory function calls vs HTTP RPC
+
+**Example: Monolithic e-commerce platform**
+```
+monolith/
+├── transport/
+│   ├── auth.js
+│   ├── products.js
+│   ├── orders.js
+│   └── payments.js
+├── services/
+│   ├── authService.js
+│   ├── productService.js
+│   ├── orderService.js
+│   └── paymentService.js
+└── repositories/
+    ├── userRepo.js
+    ├── productRepo.js
+    ├── orderRepo.js
+    └── paymentRepo.js
+```
+
+All services run in same process, same database. Easy to refactor, deploy, test.
+
+### When to Split to Microservices
+
+**Split ONLY if:**
+- Team > 30 people (need autonomy + independent deployments)
+- Services truly independent (different databases, different deployment cadences)
+- You can tolerate 100-500ms RPC latency between services
+- Each service has independent scaling needs
+
+**Microservices disadvantages:**
+- Distributed transactions (eventual consistency or sagas)
+- Debugging spans multiple services/logs (correlation IDs mandatory)
+- RPC latency adds up (cascade failures likely)
+- Ops complexity increases 10x (monitoring, health checks, circuit breakers)
+
+**Trigger for splitting:** When layered architecture + teamwork alignment breaks down.
+
+**NOT OK to split:**
+- Customer service and Order service can't be truly independent (customers have orders)
+- Payment and Order service tightly coupled (can't process payment independent of order state)
+
+**OK to split:**
+- User authentication (separate service, used by many)
+- Notification service (email/SMS, independent of order flow)
+- Analytics service (read-only, independent queries)
+
+**Strangler Fig Pattern (low-risk migration):**
+
+Start monolithic. When it's time to extract Payment service:
+1. Keep monolith running
+2. Create Payment microservice alongside
+3. Route new Payment requests -> new service
+4. Keep old requests going to monolith's PaymentService
+5. Over months, migrate & retire old code
+6. Remove dependency from monolith
+
+```javascript
+// Monolith, gradually being strangled:
+async function charge(customerId, amount) {
+  if (featureFlags.usePaymentMicroservice) {
+    // Call remote service
+    return await paymentMicroservice.charge({ customerId, amount });
+  } else {
+    // Old in-process service
+    return await paymentService.charge({ customerId, amount });
+  }
+}
+```
+
+---
+
+## Part 3: Dependency Management (ABOVE LINE)
+
+### The Problem
+
+As codebases grow, circular dependencies emerge:
+- Service imports Repository 
+- Repository imports utility in Service  (closes circle)
+- Creates tight coupling, hard to test, risky refactors
+
+### The Solution: Dependency Auditor
+
+**Enforce dependency direction at build time** (ABOVE LINE improvement not in any benchmark repo).
+
+**Check:**
+1. Transport layer files import only Transport + Service
+2. Service layer files import only Service + Repository
+3. Repository layer files import only Repository (no Service)
+4. No circular imports within layer
+
+**Tool:**
+```bash
+npm run audit:dependencies  # Pre-commit gate
+```
+
+---
+
+## Checklist: Did You Get Architecture Right?
+
+Before shipping a new service, verify:
+
+- [ ] **Layer separation:** Transport doesn't contain business logic
+- [ ] **Dependency direction:** No circles (Service imports Repo only, not vice versa)
+- [ ] **Repository abstraction:** No business logic in SQL queries
+- [ ] **Service orchestration:** Complex flows live in Service, not Transport
+- [ ] **Error handling:** Errors typed + recovery strategies clear
+- [ ] **Idempotency:** Distributed transactions have idempotency keys
+- [ ] **Feature-based:** Related code lives together, not scattered across service/util folders
+- [ ] **Testing:** Unit tests mock Repository (test business logic), no DB
+- [ ] **Documentation:** README explains layer separation for this service
+
+---
+
+## References
+
+- [Awesome-Copilot Architecture](https://github.com/github/awesome-copilot)
+- [Antigravity Microservices](https://github.com/sickn33/antigravity-awesome-skills)
+- [MiniMax Fullstack Structure](https://github.com/MiniMax-AI/skills)