@valentia-ai-skills/framework 1.0.0

package/skills/global/testing-standards/tests/test-prompts.md

@@ -0,0 +1,25 @@
+## Test 1: Unit Test Writing
+**Prompt**: "Write unit tests for a function that calculates order totals with discounts, tax, and shipping"
+**Expected**:
+- AAA pattern in each test
+- "should ... when ..." naming
+- Tests for: normal case, discount applied, free shipping threshold, zero items, negative values
+- Mocks for any external dependencies
+- Factory function for test orders
+
+## Test 2: Integration Test
+**Prompt**: "Write integration tests for a user registration API endpoint"
+**Expected**:
+- Full HTTP request/response cycle
+- Test database setup and cleanup
+- Happy path + validation errors + duplicate email
+- Verifies database state after creation
+- Proper status code assertions (201, 400, 409)
+
+## Test 3: Test Refactoring
+**Prompt**: "This test is fragile and hard to maintain: `it('test1', () => { const x = new UserService(db, cache, email, logger, config); ... })` — refactor it"
+**Expected**:
+- Descriptive test name with "should ... when ..."
+- Factory function or beforeEach for setup
+- Only mock what's needed for the specific test
+- Clear AAA structure

package/skills/onboarding/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: onboarding
+description: >
+  New developer onboarding for the AI Skills Framework. Use this skill when
+  a developer is new to the team, setting up their environment, asking about
+  conventions, or needs a walkthrough of how the AI-assisted development
+  workflow works. Triggers on: "new here", "just joined", "onboarding",
+  "getting started", "setup guide", "how does this work", "what are the rules",
+  "team conventions", "first task", or any indication the developer is
+  unfamiliar with the framework.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Developer Onboarding
+
+## Overview
+
+Welcome to the AI Skills Framework. This skill walks new developers through
+the setup process and teaches them how AI-assisted development works in
+this organization.
+
+## What Is This Framework?
+
+This organization uses AI agents (Claude Code and Claude.ai) to assist with
+software development. Rather than each developer prompting AI independently,
+we use **centralized Skills** — instruction sets that encode our coding standards,
+security practices, and architectural patterns.
+
+When you use Claude Code, it automatically reads these Skills and follows
+our conventions. This means:
+- Your code will be consistent with every other team
+- Security best practices are built in
+- You don't need to memorize all the conventions — the AI knows them
+
+## Setup Checklist
+
+### 1. Clone the Skills Repository
+```bash
+git clone git@github.com:YOUR_ORG/ai-skills-framework.git ~/ai-skills
+```
+
+### 2. Install Claude Code
+Follow the setup at https://docs.claude.com — install the CLI tool.
+
+### 3. Configure Your Skill Path
+In your project directory, create or edit `.claude/settings.json`:
+```json
+{
+  "permissions": {
+    "allow": ["Read ai-skills-framework/**"]
+  }
+}
+```
+
+Point Claude Code's skill path to the cloned repository.
+
+### 4. Know Your Team Config
+Check `team-overrides/{your-team}/team-config.yaml` to see:
+- Which skills are active for your team
+- Any team-specific overrides or conventions
+- Your team's stack and tooling preferences
+
+### 5. Pull Skills Regularly
+```bash
+cd ~/ai-skills && git pull origin main
+```
+Skills are updated regularly. Pull at least weekly.
+
+## How It Works Day-to-Day
+
+1. **Start your task** — work in your project as normal
+2. **Use Claude Code** — ask it to write code, review code, or help with tasks
+3. **Skills apply automatically** — Claude reads the active skills and follows them
+4. **Review the output** — verify the AI followed conventions (it usually will)
+5. **Commit and PR** — follow the git-workflow skill for commits and PRs
+
+## Your First AI-Assisted Task
+
+For your first task, follow this process:
+1. Pick a small, well-defined task (not a major feature)
+2. Use Claude Code to help implement it
+3. Review the output against the code-standards skill
+4. Have your Team Lead review before merging
+5. Share feedback — what worked, what didn't
+
+## Key Skills to Read First
+
+1. **code-standards** — Naming, structure, formatting (global/)
+2. **git-workflow** — Branches, commits, PRs (global/)
+3. **security-baseline** — Auth, validation, secrets (global/)
+4. Your team's stack skill (stack/{your-stack}/)
+
+## Getting Help
+
+- **Skill not working?** → Open a GitHub Issue in the skills repo
+- **Need a new skill?** → Use the "Skill Request" issue template
+- **Framework questions?** → Ask your Team Lead or the Framework Admin
+- **Want to contribute?** → Read CONTRIBUTING.md in the repo root
+
+## Checklist
+
+Verify your setup:
+- [ ] Skills repo cloned locally
+- [ ] Claude Code installed and configured
+- [ ] Can identify your team's config file
+- [ ] Have read code-standards, git-workflow, and security-baseline
+- [ ] Completed first AI-assisted task with Team Lead review

package/skills/stack/devops/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: devops-patterns
+description: >
+  Infrastructure and DevOps patterns for platform and infrastructure teams.
+  Use this skill whenever writing, reviewing, or designing infrastructure
+  configurations, monitoring, alerting, logging, or cloud resource management.
+  Triggers on: "Terraform", "CloudFormation", "Pulumi", "infrastructure as code",
+  "IaC", "Kubernetes", "k8s", "helm chart", "monitoring", "alerting",
+  "Prometheus", "Grafana", "Datadog", "CloudWatch", "load balancer", "autoscaling",
+  "VPC", "networking", "DNS", "SSL/TLS", "certificate", "backup", "disaster recovery",
+  "SLA", "SLO", "SLI", "observability", "tracing", "metrics". Applies to DevOps teams.
+version: "1.0.0"
+scope: stack
+stack: devops
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# DevOps Patterns
+
+## Overview
+
+Infrastructure standards that ensure reliability, observability, and security
+across all services. These patterns apply to whoever manages the platform —
+whether a dedicated DevOps team or embedded platform engineers.
+
+**Prerequisites**: `global/security-baseline` and `global/deployment` apply.
+This skill adds infrastructure-specific patterns.
+
+## 1. Infrastructure as Code (IaC)
+
+### Rules
+- ALL infrastructure must be defined in code — no manual console changes
+- Use Terraform (preferred) or Pulumi for cloud resources
+- Use Helm for Kubernetes manifests
+- Store IaC in version control (separate repo or `infra/` directory)
+- Plan before apply: always review `terraform plan` output
+- State files stored remotely (S3 + DynamoDB lock, not local)
+
+### Terraform Structure
+```
+infra/
+  modules/               # Reusable modules
+    database/
+      main.tf
+      variables.tf
+      outputs.tf
+    cache/
+    networking/
+  environments/          # Per-environment configs
+    staging/
+      main.tf            # References modules
+      terraform.tfvars
+    production/
+      main.tf
+      terraform.tfvars
+  global/                # Shared resources (DNS, IAM)
+    main.tf
+```
+
+### Rules
+- Separate state per environment (staging and production never share state)
+- Tag all resources: `team`, `environment`, `service`, `managed-by=terraform`
+- Use modules for any resource used by 2+ services
+- Pin provider versions: `required_providers { aws = "~> 5.0" }`
+
+## 2. Monitoring & Observability
+
+### Three Pillars
+
+| Pillar | Tool | What It Captures |
+|--------|------|-----------------|
+| Metrics | Prometheus / Datadog | Numeric measurements over time (latency, error rate, throughput) |
+| Logs | ELK / CloudWatch / Loki | Structured event records |
+| Traces | Jaeger / Datadog APM | Request flow across services |
+
+### Required Metrics (Every Service)
+
+```
+# RED method — for every service endpoint:
+- Rate:     requests per second
+- Errors:   error rate (4xx, 5xx)
+- Duration: response time (p50, p95, p99)
+
+# USE method — for infrastructure:
+- Utilization: CPU %, memory %, disk %
+- Saturation: queue depth, thread pool usage
+- Errors:      hardware/system errors
+```
+
+### Standard Dashboard Layout
+Every service dashboard must include:
+1. **Request rate** — requests/sec over time
+2. **Error rate** — 4xx and 5xx separately
+3. **Latency** — p50, p95, p99 response times
+4. **Saturation** — CPU, memory, connections
+5. **Dependencies** — upstream service health
+6. **Business metrics** — service-specific KPIs
+
+## 3. Alerting
+
+### Alert Severity Levels
+
+| Level | Response Time | Examples |
+|-------|--------------|---------|
+| Critical (P1) | 5 minutes | Service down, data loss risk, security breach |
+| Warning (P2) | 30 minutes | Error rate elevated, resource nearing limit |
+| Info (P3) | Next business day | Disk usage growing, certificate expiring in 30 days |
+
+### Rules
+- Every alert must have a runbook link
+- No alert without a clear action — if you can't act on it, it's not an alert
+- Alert on symptoms (high error rate) not causes (CPU spike)
+- Page only for P1 — Slack/email for P2/P3
+- Review and tune alerts monthly — alert fatigue kills response quality
+
+### Alert Template
+```yaml
+alert: HighErrorRate
+expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
+for: 2m
+labels:
+  severity: critical
+  team: "{{ $labels.team }}"
+annotations:
+  summary: "High 5xx error rate on {{ $labels.service }}"
+  description: "Error rate is {{ $value | humanizePercentage }} (threshold: 5%)"
+  runbook: "https://wiki.company.com/runbooks/high-error-rate"
+```
+
+## 4. Service Level Objectives (SLOs)
+
+Every production service defines:
+
+| SLI (Indicator) | SLO (Objective) | Measurement |
+|-----------------|-----------------|-------------|
+| Availability | 99.9% (43 min downtime/month) | Successful requests / total requests |
+| Latency | p99 < 500ms | 99% of requests complete in < 500ms |
+| Throughput | Handles 1000 rps | Load test verified quarterly |
+
+### Error Budget
+- Error budget = 100% - SLO = 0.1% allowed failure
+- If budget is exhausted: freeze feature work, focus on reliability
+- Track budget monthly with the team
+
+## 5. Kubernetes Standards
+
+### Pod Configuration
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+spec:
+  replicas: 3                    # minimum 2 for HA
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 1
+      maxSurge: 1
+  template:
+    spec:
+      containers:
+        - name: app
+          image: myapp:v1.2.3    # pinned tag, never :latest
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 15
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 5
+```
+
+### Rules
+- Always set resource requests AND limits
+- Always define liveness AND readiness probes
+- Minimum 2 replicas for any production service
+- Never use `:latest` tag — always pinned versions
+- Use PodDisruptionBudget for critical services
+- Secrets via Kubernetes Secrets or external secrets operator (never ConfigMaps)
+
+## 6. Backup & Disaster Recovery
+
+### Database Backups
+- Automated daily backups with 30-day retention
+- Weekly backup restore test (automated)
+- Cross-region backup replication for production
+- Recovery Point Objective (RPO): < 1 hour
+- Recovery Time Objective (RTO): < 4 hours
+
+### Rules
+- Backups are tested regularly — untested backups are not backups
+- Document the full restore procedure in the service runbook
+- Encrypt backups at rest and in transit
+- Backup retention: 30 days daily, 12 months monthly
+
+## Checklist
+
+Before deploying infrastructure changes:
+- [ ] All infrastructure defined in code (no manual changes)
+- [ ] Terraform plan reviewed before apply
+- [ ] Resources tagged: team, environment, service, managed-by
+- [ ] Monitoring dashboard with RED metrics in place
+- [ ] Alerts configured with runbook links
+- [ ] SLOs defined for the service
+- [ ] K8s pods have resource limits, health probes, ≥ 2 replicas
+- [ ] Backups configured and restore tested
+- [ ] No :latest tags in any configuration
+- [ ] Secrets in secrets manager (not plaintext in configs)

package/skills/stack/devops/tests/test-prompts.md

@@ -0,0 +1,29 @@
+## Test 1: Terraform Module
+**Prompt**: "Create a Terraform module for a PostgreSQL RDS instance with read replicas, automated backups, and monitoring"
+**Expected**:
+- Module structure: main.tf, variables.tf, outputs.tf
+- Resource tagging (team, environment, service, managed-by)
+- Backup retention configured
+- CloudWatch alarms for CPU, connections, storage
+- Encryption at rest enabled
+- Security group with restricted access
+
+## Test 2: Kubernetes Deployment
+**Prompt**: "Write a Kubernetes deployment manifest for a Node.js API with autoscaling, health checks, and resource limits"
+**Expected**:
+- Resource requests AND limits set
+- Liveness AND readiness probes on /health
+- Minimum 2 replicas
+- Pinned image tag (not :latest)
+- HPA for autoscaling
+- RollingUpdate strategy
+- PodDisruptionBudget
+
+## Test 3: Monitoring Setup
+**Prompt**: "Set up monitoring and alerting for a payment processing service"
+**Expected**:
+- RED metrics: rate, errors, duration
+- Dashboard with required sections
+- Alerts for: high error rate, high latency, service down
+- Each alert has severity level and runbook link
+- SLOs defined: availability, latency targets

package/skills/stack/node-backend/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: node-backend-patterns
+description: >
+  Node.js backend development patterns and conventions. Use this skill whenever
+  writing, reviewing, or designing Node.js backend services, APIs, middleware,
+  database access layers, queue consumers, or microservices. Triggers on:
+  "Express", "Fastify", "NestJS", "Koa", "Node.js backend", "middleware",
+  "controller", "service layer", "repository pattern", "database migration",
+  "Prisma", "TypeORM", "Drizzle", "Knex", "Redis", "queue", "worker",
+  "cron", "microservice", "health check", "graceful shutdown".
+  Applies to backend teams using Node.js/TypeScript.
+version: "1.0.0"
+scope: stack
+stack: node-backend
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Node.js Backend Patterns
+
+## Overview
+
+Standardized backend architecture for Node.js services. These patterns ensure
+every backend service is structured consistently, testable, and production-ready.
+
+**Prerequisites**: `global/code-standards`, `global/security-baseline`, and
+`global/api-design` all apply. This skill adds backend-specific patterns.
+
+## 1. Service Architecture — Layered Pattern
+
+Every backend service follows a 4-layer architecture:
+
+```
+┌──────────────────────────────┐
+│  Routes / Controllers        │  ← HTTP handling, validation, response formatting
+├──────────────────────────────┤
+│  Services                    │  ← Business logic, orchestration
+├──────────────────────────────┤
+│  Repositories / Data Access  │  ← Database queries, cache, external APIs
+├──────────────────────────────┤
+│  Models / Types              │  ← Data structures, validation schemas
+└──────────────────────────────┘
+```
+
+### Rules
+- Controllers handle HTTP — never contain business logic
+- Services contain business logic — never touch HTTP request/response objects
+- Repositories handle data access — never contain business logic
+- Each layer only calls the layer directly below it
+
+```
+src/
+  routes/              # Express/Fastify route definitions
+    user-routes.ts
+  controllers/         # Request handling, validation, response
+    user-controller.ts
+  services/            # Business logic
+    user-service.ts
+  repositories/        # Database access
+    user-repository.ts
+  middleware/           # Auth, logging, error handling
+    auth-middleware.ts
+    error-handler.ts
+  models/              # Prisma/TypeORM models or Zod schemas
+    user-model.ts
+  config/              # Configuration loading
+    index.ts
+    database.ts
+  lib/                 # Shared utilities (logger, cache client)
+    logger.ts
+    cache.ts
+  types/               # TypeScript type definitions
+    index.ts
+```
+
+## 2. Dependency Injection
+
+Services receive their dependencies through constructor injection:
+
+```typescript
+// ✅ Good: Dependencies injected
+class UserService {
+  constructor(
+    private userRepo: UserRepository,
+    private emailService: EmailService,
+    private logger: Logger,
+  ) {}
+
+  async createUser(data: CreateUserInput): Promise<User> {
+    const user = await this.userRepo.create(data);
+    await this.emailService.sendWelcome(user.email);
+    this.logger.info("User created", { userId: user.id });
+    return user;
+  }
+}
+
+// ❌ Bad: Hard-coded dependencies
+class UserService {
+  async createUser(data: CreateUserInput): Promise<User> {
+    const user = await prisma.user.create({ data });  // direct DB access
+    await sendgrid.send({ ... });                      // direct service call
+    console.log("User created");                       // no structured logging
+    return user;
+  }
+}
+```
+
+### Why
+- Testable: inject mocks in tests
+- Flexible: swap implementations without changing business logic
+- Clear: dependencies are explicit, not hidden
+
+## 3. Error Handling
+
+### Custom Error Classes
+```typescript
+// Base application error
+class AppError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public code: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+// Specific errors
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} with id ${id} not found`, 404, "NOT_FOUND");
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(details: Array<{ field: string; message: string }>) {
+    super("Validation failed", 400, "VALIDATION_ERROR", details);
+  }
+}
+
+class ConflictError extends AppError {
+  constructor(message: string) {
+    super(message, 409, "CONFLICT");
+  }
+}
+```
+
+### Global Error Handler (Express example)
+```typescript
+function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+      },
+    });
+  }
+
+  // Unexpected errors
+  logger.error("Unhandled error", { error: err.message, stack: err.stack });
+  return res.status(500).json({
+    error: {
+      code: "INTERNAL_ERROR",
+      message: "An unexpected error occurred",
+    },
+  });
+}
+```
+
+### Rules
+- Throw domain-specific errors from services
+- Catch and format in the error handler middleware
+- Never expose stack traces in production responses
+- Always log unexpected errors with full context
+
+## 4. Database Access
+
+### Migration Rules
+- Always use migrations for schema changes (never manual SQL)
+- Migrations are forward-only in production
+- Migration files have timestamps: `20260319_add_user_email_index`
+- Test migrations against a copy of production data before deploying
+
+### Query Patterns
+```typescript
+// Repository pattern — encapsulates all DB access
+class UserRepository {
+  constructor(private db: PrismaClient) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.db.user.findUnique({ where: { id } });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.db.user.findUnique({ where: { email } });
+  }
+
+  async create(data: CreateUserInput): Promise<User> {
+    return this.db.user.create({ data });
+  }
+
+  async updateLastLogin(id: string): Promise<void> {
+    await this.db.user.update({
+      where: { id },
+      data: { lastLoginAt: new Date() },
+    });
+  }
+}
+```
+
+### Rules
+- All DB queries go through repositories — controllers never touch the DB
+- Use transactions for multi-step operations
+- Always set query timeouts
+- Index columns used in WHERE and JOIN clauses
+
+## 5. Configuration
+
+```typescript
+// config/index.ts — single source of truth
+import { z } from "zod";
+
+const configSchema = z.object({
+  NODE_ENV: z.enum(["development", "staging", "production"]),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+export const config = configSchema.parse(process.env);
+```
+
+### Rules
+- Validate all env vars at startup — fail fast if missing
+- Use Zod for config validation (same as request validation)
+- Never use `process.env` directly in service code — only through the config module
+- Different `.env.example` entries for each environment
+
+## 6. Health Checks & Graceful Shutdown
+
+Every service must implement:
+
+```typescript
+// Health check endpoint
+app.get("/health", async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    uptime: process.uptime(),
+  };
+  
+  const isHealthy = Object.values(checks).every(c => c !== false);
+  res.status(isHealthy ? 200 : 503).json({ status: isHealthy ? "ok" : "degraded", checks });
+});
+
+// Graceful shutdown
+function gracefulShutdown(signal: string) {
+  logger.info(`Received ${signal}, shutting down gracefully...`);
+  
+  server.close(async () => {
+    await prisma.$disconnect();
+    await redis.quit();
+    logger.info("Server shut down cleanly");
+    process.exit(0);
+  });
+
+  // Force exit after 30 seconds
+  setTimeout(() => {
+    logger.error("Forced shutdown after timeout");
+    process.exit(1);
+  }, 30_000);
+}
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+```
+
+## 7. Logging
+
+- Use structured logging (JSON format): `pino` or `winston`
+- Always include: timestamp, level, message, request ID, service name
+- Log at appropriate levels: debug (development only), info (normal operations),
+  warn (recoverable issues), error (failures requiring attention)
+- Never log PII, passwords, tokens, or full request bodies in production
+
+## Checklist
+
+Before finalizing backend code:
+- [ ] 4-layer architecture: routes → controllers → services → repositories
+- [ ] Dependencies injected via constructor (testable)
+- [ ] Custom error classes with proper status codes
+- [ ] Global error handler catches all errors
+- [ ] DB access through repositories only
+- [ ] Config validated at startup with Zod
+- [ ] Health check endpoint at /health
+- [ ] Graceful shutdown handler
+- [ ] Structured logging (no console.log in production)
+- [ ] No PII in logs, no stack traces in responses