@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/backend-dev-guidelines.md

@@ -0,0 +1,342 @@
+---
+name: backend-dev-guidelines
+description: Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod validation, unifiedConfig, Sentry error tracking, async safety, and testing discipline.
+---
+
+# Backend Development Guidelines
+
+**(Node.js · Express · TypeScript · Microservices)**
+
+You are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.
+
+Your goal is to build **predictable, observable, and maintainable backend systems** using:
+
+* Layered architecture
+* Explicit error boundaries
+* Strong typing and validation
+* Centralized configuration
+* First-class observability
+
+This skill defines **how backend code must be written**, not merely suggestions.
+
+---
+
+## 1. Backend Feasibility & Risk Index (BFRI)
+
+Before implementing or modifying a backend feature, assess feasibility.
+
+### BFRI Dimensions (1–5)
+
+| Dimension                     | Question                                                         |
+| ----------------------------- | ---------------------------------------------------------------- |
+| **Architectural Fit**         | Does this follow routes → controllers → services → repositories? |
+| **Business Logic Complexity** | How complex is the domain logic?                                 |
+| **Data Risk**                 | Does this affect critical data paths or transactions?            |
+| **Operational Risk**          | Does this impact auth, billing, messaging, or infra?             |
+| **Testability**               | Can this be reliably unit + integration tested?                  |
+
+### Score Formula
+
+```
+BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)
+```
+
+**Range:** `-10 → +10`
+
+### Interpretation
+
+| BFRI     | Meaning   | Action                 |
+| -------- | --------- | ---------------------- |
+| **6–10** | Safe      | Proceed                |
+| **3–5**  | Moderate  | Add tests + monitoring |
+| **0–2**  | Risky     | Refactor or isolate    |
+| **< 0**  | Dangerous | Redesign before coding |
+
+---
+
+## 2. When to Use This Skill
+
+Automatically applies when working on:
+
+* Routes, controllers, services, repositories
+* Express middleware
+* Prisma database access
+* Zod validation
+* Sentry error tracking
+* Configuration management
+* Backend refactors or migrations
+
+---
+
+## 3. Core Architecture Doctrine (Non-Negotiable)
+
+### 1. Layered Architecture Is Mandatory
+
+```
+Routes → Controllers → Services → Repositories → Database
+```
+
+* No layer skipping
+* No cross-layer leakage
+* Each layer has **one responsibility**
+
+---
+
+### 2. Routes Only Route
+
+```ts
+// ❌ NEVER
+router.post('/create', async (req, res) => {
+  await prisma.user.create(...);
+});
+
+// ✅ ALWAYS
+router.post('/create', (req, res) =>
+  userController.create(req, res)
+);
+```
+
+Routes must contain **zero business logic**.
+
+---
+
+### 3. Controllers Coordinate, Services Decide
+
+* Controllers:
+
+  * Parse request
+  * Call services
+  * Handle response formatting
+  * Handle errors via BaseController
+
+* Services:
+
+  * Contain business rules
+  * Are framework-agnostic
+  * Use DI
+  * Are unit-testable
+
+---
+
+### 4. All Controllers Extend `BaseController`
+
+```ts
+export class UserController extends BaseController {
+  async getUser(req: Request, res: Response): Promise<void> {
+    try {
+      const user = await this.userService.getById(req.params.id);
+      this.handleSuccess(res, user);
+    } catch (error) {
+      this.handleError(error, res, 'getUser');
+    }
+  }
+}
+```
+
+No raw `res.json` calls outside BaseController helpers.
+
+---
+
+### 5. All Errors Go to Sentry
+
+```ts
+catch (error) {
+  Sentry.captureException(error);
+  throw error;
+}
+```
+
+❌ `console.log`
+❌ silent failures
+❌ swallowed errors
+
+---
+
+### 6. unifiedConfig Is the Only Config Source
+
+```ts
+// ❌ NEVER
+process.env.JWT_SECRET;
+
+// ✅ ALWAYS
+import { config } from '@/config/unifiedConfig';
+config.auth.jwtSecret;
+```
+
+---
+
+### 7. Validate All External Input with Zod
+
+* Request bodies
+* Query params
+* Route params
+* Webhook payloads
+
+```ts
+const schema = z.object({
+  email: z.string().email(),
+});
+
+const input = schema.parse(req.body);
+```
+
+No validation = bug.
+
+---
+
+## 4. Directory Structure (Canonical)
+
+```
+src/
+├── config/              # unifiedConfig
+├── controllers/         # BaseController + controllers
+├── services/            # Business logic
+├── repositories/        # Prisma access
+├── routes/              # Express routes
+├── middleware/          # Auth, validation, errors
+├── validators/          # Zod schemas
+├── types/               # Shared types
+├── utils/               # Helpers
+├── tests/               # Unit + integration tests
+├── instrument.ts        # Sentry (FIRST IMPORT)
+├── app.ts               # Express app
+└── server.ts            # HTTP server
+```
+
+---
+
+## 5. Naming Conventions (Strict)
+
+| Layer      | Convention                |
+| ---------- | ------------------------- |
+| Controller | `PascalCaseController.ts` |
+| Service    | `camelCaseService.ts`     |
+| Repository | `PascalCaseRepository.ts` |
+| Routes     | `camelCaseRoutes.ts`      |
+| Validators | `camelCase.schema.ts`     |
+
+---
+
+## 6. Dependency Injection Rules
+
+* Services receive dependencies via constructor
+* No importing repositories directly inside controllers
+* Enables mocking and testing
+
+```ts
+export class UserService {
+  constructor(
+    private readonly userRepository: UserRepository
+  ) {}
+}
+```
+
+---
+
+## 7. Prisma & Repository Rules
+
+* Prisma client **never used directly in controllers**
+* Repositories:
+
+  * Encapsulate queries
+  * Handle transactions
+  * Expose intent-based methods
+
+```ts
+await userRepository.findActiveUsers();
+```
+
+---
+
+## 8. Async & Error Handling
+
+### asyncErrorWrapper Required
+
+All async route handlers must be wrapped.
+
+```ts
+router.get(
+  '/users',
+  asyncErrorWrapper((req, res) =>
+    controller.list(req, res)
+  )
+);
+```
+
+No unhandled promise rejections.
+
+---
+
+## 9. Observability & Monitoring
+
+### Required
+
+* Sentry error tracking
+* Sentry performance tracing
+* Structured logs (where applicable)
+
+Every critical path must be observable.
+
+---
+
+## 10. Testing Discipline
+
+### Required Tests
+
+* **Unit tests** for services
+* **Integration tests** for routes
+* **Repository tests** for complex queries
+
+```ts
+describe('UserService', () => {
+  it('creates a user', async () => {
+    expect(user).toBeDefined();
+  });
+});
+```
+
+No tests → no merge.
+
+---
+
+## 11. Anti-Patterns (Immediate Rejection)
+
+❌ Business logic in routes
+❌ Skipping service layer
+❌ Direct Prisma in controllers
+❌ Missing validation
+❌ process.env usage
+❌ console.log instead of Sentry
+❌ Untested business logic
+
+---
+
+## 12. Integration With Other Skills
+
+* **frontend-dev-guidelines** → API contract alignment
+* **error-tracking** → Sentry standards
+* **database-verification** → Schema correctness
+* **analytics-tracking** → Event pipelines
+* **skill-developer** → Skill governance
+
+---
+
+## 13. Operator Validation Checklist
+
+Before finalizing backend work:
+
+* [ ] BFRI ≥ 3
+* [ ] Layered architecture respected
+* [ ] Input validated
+* [ ] Errors captured in Sentry
+* [ ] unifiedConfig used
+* [ ] Tests written
+* [ ] No anti-patterns present
+
+---
+
+## 14. Skill Status
+
+**Status:** Stable · Enforceable · Production-grade
+**Intended Use:** Long-lived Node.js microservices with real traffic and real risk
+---

package/merged-commands/backend-development-feature-development.md

@@ -0,0 +1,180 @@
+---
+name: backend-development-feature-development
+description: "Orchestrate end-to-end backend feature development from requirements to deployment. Use when coordinating multi-phase feature delivery across teams and services."
+---
+
+Orchestrate end-to-end feature development from requirements to production deployment:
+
+[Extended thinking: This workflow orchestrates specialized agents through comprehensive feature development phases - from discovery and planning through implementation, testing, and deployment. Each phase builds on previous outputs, ensuring coherent feature delivery. The workflow supports multiple development methodologies (traditional, TDD/BDD, DDD), feature complexity levels, and modern deployment strategies including feature flags, gradual rollouts, and observability-first development. Agents receive detailed context from previous phases to maintain consistency and quality throughout the development lifecycle.]
+
+## Use this skill when
+
+- Coordinating end-to-end feature delivery across backend, frontend, and data
+- Managing requirements, architecture, implementation, testing, and rollout
+- Planning multi-service changes with deployment and monitoring needs
+- Aligning teams on scope, risks, and success metrics
+
+## Do not use this skill when
+
+- The task is a small, isolated backend change or bug fix
+- You only need a single specialist task, not a full workflow
+- There is no deployment or cross-team coordination involved
+
+## Instructions
+
+1. Confirm feature scope, success metrics, and constraints.
+2. Select a methodology and define phase outputs.
+3. Orchestrate implementation, testing, and security validation.
+4. Prepare rollout, monitoring, and documentation plans.
+
+## Safety
+
+- Avoid production changes without approvals and rollback plans.
+- Validate data migrations and feature flags in staging first.
+
+## Configuration Options
+
+### Development Methodology
+
+- **traditional**: Sequential development with testing after implementation
+- **tdd**: Test-Driven Development with red-green-refactor cycles
+- **bdd**: Behavior-Driven Development with scenario-based testing
+- **ddd**: Domain-Driven Design with bounded contexts and aggregates
+
+### Feature Complexity
+
+- **simple**: Single service, minimal integration (1-2 days)
+- **medium**: Multiple services, moderate integration (3-5 days)
+- **complex**: Cross-domain, extensive integration (1-2 weeks)
+- **epic**: Major architectural changes, multiple teams (2+ weeks)
+
+### Deployment Strategy
+
+- **direct**: Immediate rollout to all users
+- **canary**: Gradual rollout starting with 5% of traffic
+- **feature-flag**: Controlled activation via feature toggles
+- **blue-green**: Zero-downtime deployment with instant rollback
+- **a-b-test**: Split traffic for experimentation and metrics
+
+## Phase 1: Discovery & Requirements Planning
+
+1. **Business Analysis & Requirements**
+   - Use Task tool with subagent_type="business-analytics::business-analyst"
+   - Prompt: "Analyze feature requirements for: $ARGUMENTS. Define user stories, acceptance criteria, success metrics, and business value. Identify stakeholders, dependencies, and risks. Create feature specification document with clear scope boundaries."
+   - Expected output: Requirements document with user stories, success metrics, risk assessment
+   - Context: Initial feature request and business context
+
+2. **Technical Architecture Design**
+   - Use Task tool with subagent_type="comprehensive-review::architect-review"
+   - Prompt: "Design technical architecture for feature: $ARGUMENTS. Using requirements: [include business analysis from step 1]. Define service boundaries, API contracts, data models, integration points, and technology stack. Consider scalability, performance, and security requirements."
+   - Expected output: Technical design document with architecture diagrams, API specifications, data models
+   - Context: Business requirements, existing system architecture
+
+3. **Feasibility & Risk Assessment**
+   - Use Task tool with subagent_type="security-scanning::security-auditor"
+   - Prompt: "Assess security implications and risks for feature: $ARGUMENTS. Review architecture: [include technical design from step 2]. Identify security requirements, compliance needs, data privacy concerns, and potential vulnerabilities."
+   - Expected output: Security assessment with risk matrix, compliance checklist, mitigation strategies
+   - Context: Technical design, regulatory requirements
+
+## Phase 2: Implementation & Development
+
+4. **Backend Services Implementation**
+   - Use Task tool with subagent_type="backend-architect"
+   - Prompt: "Implement backend services for: $ARGUMENTS. Follow technical design: [include architecture from step 2]. Build RESTful/GraphQL APIs, implement business logic, integrate with data layer, add resilience patterns (circuit breakers, retries), implement caching strategies. Include feature flags for gradual rollout."
+   - Expected output: Backend services with APIs, business logic, database integration, feature flags
+   - Context: Technical design, API contracts, data models
+
+5. **Frontend Implementation**
+   - Use Task tool with subagent_type="frontend-mobile-development::frontend-developer"
+   - Prompt: "Build frontend components for: $ARGUMENTS. Integrate with backend APIs: [include API endpoints from step 4]. Implement responsive UI, state management, error handling, loading states, and analytics tracking. Add feature flag integration for A/B testing capabilities."
+   - Expected output: Frontend components with API integration, state management, analytics
+   - Context: Backend APIs, UI/UX designs, user stories
+
+6. **Data Pipeline & Integration**
+   - Use Task tool with subagent_type="data-engineering::data-engineer"
+   - Prompt: "Build data pipelines for: $ARGUMENTS. Design ETL/ELT processes, implement data validation, create analytics events, set up data quality monitoring. Integrate with product analytics platforms for feature usage tracking."
+   - Expected output: Data pipelines, analytics events, data quality checks
+   - Context: Data requirements, analytics needs, existing data infrastructure
+
+## Phase 3: Testing & Quality Assurance
+
+7. **Automated Test Suite**
+   - Use Task tool with subagent_type="unit-testing::test-automator"
+   - Prompt: "Create comprehensive test suite for: $ARGUMENTS. Write unit tests for backend: [from step 4] and frontend: [from step 5]. Add integration tests for API endpoints, E2E tests for critical user journeys, performance tests for scalability validation. Ensure minimum 80% code coverage."
+   - Expected output: Test suites with unit, integration, E2E, and performance tests
+   - Context: Implementation code, acceptance criteria, test requirements
+
+8. **Security Validation**
+   - Use Task tool with subagent_type="security-scanning::security-auditor"
+   - Prompt: "Perform security testing for: $ARGUMENTS. Review implementation: [include backend and frontend from steps 4-5]. Run OWASP checks, penetration testing, dependency scanning, and compliance validation. Verify data encryption, authentication, and authorization."
+   - Expected output: Security test results, vulnerability report, remediation actions
+   - Context: Implementation code, security requirements
+
+9. **Performance Optimization**
+   - Use Task tool with subagent_type="application-performance::performance-engineer"
+   - Prompt: "Optimize performance for: $ARGUMENTS. Analyze backend services: [from step 4] and frontend: [from step 5]. Profile code, optimize queries, implement caching, reduce bundle sizes, improve load times. Set up performance budgets and monitoring."
+   - Expected output: Performance improvements, optimization report, performance metrics
+   - Context: Implementation code, performance requirements
+
+## Phase 4: Deployment & Monitoring
+
+10. **Deployment Strategy & Pipeline**
+    - Use Task tool with subagent_type="deployment-strategies::deployment-engineer"
+    - Prompt: "Prepare deployment for: $ARGUMENTS. Create CI/CD pipeline with automated tests: [from step 7]. Configure feature flags for gradual rollout, implement blue-green deployment, set up rollback procedures. Create deployment runbook and rollback plan."
+    - Expected output: CI/CD pipeline, deployment configuration, rollback procedures
+    - Context: Test suites, infrastructure requirements, deployment strategy
+
+11. **Observability & Monitoring**
+    - Use Task tool with subagent_type="observability-monitoring::observability-engineer"
+    - Prompt: "Set up observability for: $ARGUMENTS. Implement distributed tracing, custom metrics, error tracking, and alerting. Create dashboards for feature usage, performance metrics, error rates, and business KPIs. Set up SLOs/SLIs with automated alerts."
+    - Expected output: Monitoring dashboards, alerts, SLO definitions, observability infrastructure
+    - Context: Feature implementation, success metrics, operational requirements
+
+12. **Documentation & Knowledge Transfer**
+    - Use Task tool with subagent_type="documentation-generation::docs-architect"
+    - Prompt: "Generate comprehensive documentation for: $ARGUMENTS. Create API documentation, user guides, deployment guides, troubleshooting runbooks. Include architecture diagrams, data flow diagrams, and integration guides. Generate automated changelog from commits."
+    - Expected output: API docs, user guides, runbooks, architecture documentation
+    - Context: All previous phases' outputs
+
+## Execution Parameters
+
+### Required Parameters
+
+- **--feature**: Feature name and description
+- **--methodology**: Development approach (traditional|tdd|bdd|ddd)
+- **--complexity**: Feature complexity level (simple|medium|complex|epic)
+
+### Optional Parameters
+
+- **--deployment-strategy**: Deployment approach (direct|canary|feature-flag|blue-green|a-b-test)
+- **--test-coverage-min**: Minimum test coverage threshold (default: 80%)
+- **--performance-budget**: Performance requirements (e.g., <200ms response time)
+- **--rollout-percentage**: Initial rollout percentage for gradual deployment (default: 5%)
+- **--feature-flag-service**: Feature flag provider (launchdarkly|split|unleash|custom)
+- **--analytics-platform**: Analytics integration (segment|amplitude|mixpanel|custom)
+- **--monitoring-stack**: Observability tools (datadog|newrelic|grafana|custom)
+
+## Success Criteria
+
+- All acceptance criteria from business requirements are met
+- Test coverage exceeds minimum threshold (80% default)
+- Security scan shows no critical vulnerabilities
+- Performance meets defined budgets and SLOs
+- Feature flags configured for controlled rollout
+- Monitoring and alerting fully operational
+- Documentation complete and approved
+- Successful deployment to production with rollback capability
+- Product analytics tracking feature usage
+- A/B test metrics configured (if applicable)
+
+## Rollback Strategy
+
+If issues arise during or after deployment:
+
+1. Immediate feature flag disable (< 1 minute)
+2. Blue-green traffic switch (< 5 minutes)
+3. Full deployment rollback via CI/CD (< 15 minutes)
+4. Database migration rollback if needed (coordinate with data team)
+5. Incident post-mortem and fixes before re-deployment
+
+Feature description: $ARGUMENTS

package/merged-commands/backend-development.md

@@ -0,0 +1,155 @@
+---
+name: backend-development
+description: Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
+source: wshobson/agents
+license: MIT
+---
+
+# Backend Development
+
+## API Design
+
+### RESTful Conventions
+```
+GET    /users          # List users
+POST   /users          # Create user
+GET    /users/:id      # Get user
+PUT    /users/:id      # Update user (full)
+PATCH  /users/:id      # Update user (partial)
+DELETE /users/:id      # Delete user
+
+GET    /users/:id/posts  # List user's posts
+POST   /users/:id/posts  # Create post for user
+```
+
+### Response Format
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100
+  }
+}
+```
+
+### Error Format
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      { "field": "email", "message": "Invalid format" }
+    ]
+  }
+}
+```
+
+## Database Patterns
+
+### Schema Design
+```sql
+-- Use UUIDs for public IDs
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  public_id UUID DEFAULT gen_random_uuid() UNIQUE,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Soft deletes
+ALTER TABLE users ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- Indexes
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_created ON users(created_at DESC);
+```
+
+### Query Patterns
+```sql
+-- Pagination with cursor
+SELECT * FROM posts
+WHERE created_at < $cursor
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- Efficient counting
+SELECT reltuples::bigint AS estimate
+FROM pg_class WHERE relname = 'users';
+```
+
+## Authentication
+
+### JWT Pattern
+```typescript
+interface TokenPayload {
+  sub: string;      // User ID
+  iat: number;      // Issued at
+  exp: number;      // Expiration
+  scope: string[];  // Permissions
+}
+
+function verifyToken(token: string): TokenPayload {
+  return jwt.verify(token, SECRET) as TokenPayload;
+}
+```
+
+### Middleware
+```typescript
+async function authenticate(req: Request, res: Response, next: Next) {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  try {
+    req.user = verifyToken(token);
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+## Caching Strategy
+
+```typescript
+// Cache-aside pattern
+async function getUser(id: string): Promise<User> {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findById(id);
+  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
+  return user;
+}
+
+// Cache invalidation
+async function updateUser(id: string, data: Partial<User>) {
+  await db.users.update(id, data);
+  await redis.del(`user:${id}`);
+}
+```
+
+## Rate Limiting
+
+```typescript
+const limiter = rateLimit({
+  windowMs: 60 * 1000,  // 1 minute
+  max: 100,             // 100 requests per window
+  keyGenerator: (req) => req.ip,
+  handler: (req, res) => {
+    res.status(429).json({ error: 'Too many requests' });
+  }
+});
+```
+
+## Observability
+
+- **Logging**: Structured JSON logs with request IDs
+- **Metrics**: Request latency, error rates, queue depths
+- **Tracing**: Distributed tracing with correlation IDs
+- **Health checks**: `/health` and `/ready` endpoints