@valentia-ai-skills/framework 1.0.0

package/skills/global/deployment/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: deployment
+description: >
+  Organization-wide deployment standards for CI/CD pipelines, environment
+  management, release processes, and rollback procedures. Use this skill
+  whenever writing, reviewing, or discussing deployment configurations,
+  CI/CD pipelines, Docker files, environment promotion, feature flags,
+  release management, or rollback strategies. Triggers on: "deploy",
+  "deployment", "CI/CD", "pipeline", "GitHub Actions", "Docker", "Dockerfile",
+  "container", "Kubernetes", "k8s", "helm", "terraform", "release",
+  "rollback", "staging", "production", "environment", "feature flag",
+  "blue-green", "canary", "rolling update". Applies to all teams.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Deployment Standards
+
+## Overview
+
+Consistent deployment practices ensure reliable, safe releases across all
+services. These standards cover CI/CD pipelines, environment management,
+containerization, and rollback procedures.
+
+## 1. Environment Promotion
+
+### Environment Ladder
+
+```
+Development → Staging → Production
+```
+
+| Environment | Purpose | Who Deploys | Auto/Manual |
+|-------------|---------|-------------|-------------|
+| Development | Feature testing, integration | Any developer | Auto on PR merge to dev |
+| Staging | Pre-production validation, QA | CI/CD pipeline | Auto on merge to main |
+| Production | Live users | CI/CD + manual approval | Manual gate after staging |
+
+### Rules
+- Code must pass through ALL environments in order — no skipping staging
+- Staging must mirror production configuration (same infra, same env vars pattern)
+- Production deployments require at least 1 manual approval
+- Exception: hotfix branches can fast-track with 2 approvals
+
+## 2. CI/CD Pipeline Structure
+
+### Required Pipeline Stages
+
+```yaml
+# Every service must implement these stages:
+
+stages:
+  # Stage 1: Quality Gates (runs on every PR)
+  - lint          # Code style, formatting
+  - typecheck     # TypeScript / mypy
+  - test:unit     # Unit tests with coverage
+  - security:scan # Dependency vulnerability scan
+  
+  # Stage 2: Build (runs on merge to main)
+  - build         # Compile, bundle, Docker build
+  - test:integration  # Integration tests against test DB
+  
+  # Stage 3: Deploy (runs after build succeeds)
+  - deploy:staging    # Auto-deploy to staging
+  - test:e2e          # E2E tests against staging
+  - deploy:production # Manual approval gate → production
+```
+
+### Rules
+- PRs cannot merge if any Stage 1 check fails
+- Build artifacts are created ONCE and promoted through environments
+- Never rebuild between staging and production — same artifact, different config
+- Pipeline must complete in under 15 minutes for Stage 1 (fast feedback)
+- Full pipeline (through staging E2E) under 30 minutes
+
+## 3. Containerization (Docker)
+
+### Dockerfile Standards
+
+```dockerfile
+# ── Stage 1: Dependencies ──
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+# ── Stage 2: Build ──
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --production
+
+# ── Stage 3: Production ──
+FROM node:20-alpine AS production
+WORKDIR /app
+
+# Security: run as non-root
+RUN addgroup -g 1001 appgroup && \
+    adduser -u 1001 -G appgroup -D appuser
+USER appuser
+
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/main.js"]
+```
+
+### Rules
+- Multi-stage builds always — keep production image minimal
+- Run as non-root user — never run as root in production
+- Include HEALTHCHECK in Dockerfile
+- Pin base image versions: `node:20.11-alpine` not `node:latest`
+- Use `.dockerignore` to exclude: node_modules, .git, .env, tests, docs
+- Production image should be under 200MB
+- No dev dependencies in production stage
+
+## 4. Environment Configuration
+
+### Config by Environment
+
+```
+# Pattern: same env var names, different values per environment
+DATABASE_URL=postgres://...    # different per environment
+LOG_LEVEL=debug                # development
+LOG_LEVEL=info                 # staging
+LOG_LEVEL=warn                 # production
+```
+
+### Rules
+- Same env var names across all environments
+- Secrets stored in secrets manager (not in CI/CD variables for production)
+- Environment-specific config via env vars, never via code branches
+- Every env var documented in README (see documentation skill)
+- Config validated at startup (see security-baseline skill)
+
+## 5. Release Strategy
+
+### Semantic Versioning
+```
+v{MAJOR}.{MINOR}.{PATCH}
+
+MAJOR: Breaking changes (API incompatibility)
+MINOR: New features (backward compatible)
+PATCH: Bug fixes (backward compatible)
+```
+
+### Release Process
+1. Merge to main → auto-deploy to staging
+2. QA validates on staging (manual or automated)
+3. Create GitHub Release with tag `v1.2.3`
+4. Release triggers production deployment (with manual approval gate)
+5. Monitor dashboards for 15 minutes post-deploy
+6. If issues: rollback immediately
+
+### Feature Flags
+For risky changes, use feature flags:
+
+```typescript
+// Feature flag pattern
+if (featureFlags.isEnabled("new-checkout-flow", { userId: user.id })) {
+  return newCheckoutFlow(order);
+} else {
+  return legacyCheckoutFlow(order);
+}
+```
+
+### Rules
+- Feature flags for any change affecting > 10% of users
+- Flags have an expiry date — clean up within 2 weeks of full rollout
+- Flag states stored in config service (not hardcoded)
+- Always have a kill switch that reverts to old behavior
+
+## 6. Rollback Procedures
+
+### Automated Rollback Triggers
+- Error rate > 5% for 2 minutes
+- p99 latency > 5s for 5 minutes
+- Health check failures on > 25% of instances
+
+### Manual Rollback Process
+```bash
+# Option 1: Revert to previous container image
+kubectl rollout undo deployment/my-service
+
+# Option 2: Deploy a specific known-good version
+kubectl set image deployment/my-service app=my-service:v1.2.2
+
+# Option 3: Disable via feature flag (fastest)
+# Toggle flag off in config service
+```
+
+### Rules
+- Every deployment must be rollback-ready before proceeding
+- Database migrations must be backward-compatible (new code works with old schema AND new schema)
+- Rollback should complete in under 5 minutes
+- Post-rollback: create incident ticket, investigate, fix forward
+- Never rollback database migrations in production — fix forward only
+
+## 7. Database Migration Safety
+
+### Safe Migration Patterns
+```
+✅ ADD a new column (nullable or with default)
+✅ ADD a new table
+✅ ADD a new index (CONCURRENTLY)
+✅ RENAME with a transition period (old name → alias → new name)
+
+❌ DROP a column (in same deploy as code change)
+❌ RENAME a column (without transition period)
+❌ CHANGE column type (without transition period)
+❌ ADD NOT NULL without default
+```
+
+### Two-Phase Migration Pattern
+For breaking schema changes:
+1. **Phase 1**: Deploy code that works with BOTH old and new schema. Run migration to add new structure.
+2. **Phase 2** (next release): Deploy code that uses only new schema. Remove old structure.
+
+## Checklist
+
+Before deploying:
+- [ ] All CI stages pass (lint, typecheck, unit tests, security scan)
+- [ ] Docker image is multi-stage, runs as non-root, under 200MB
+- [ ] Integration tests pass against staging
+- [ ] E2E tests pass against staging
+- [ ] Database migration is backward-compatible
+- [ ] Rollback plan documented and tested
+- [ ] Feature flags in place for risky changes
+- [ ] Monitoring dashboards ready for post-deploy observation
+- [ ] Manual approval obtained for production
+- [ ] Changelog updated

package/skills/global/deployment/tests/test-prompts.md

@@ -0,0 +1,27 @@
+## Test 1: Dockerfile Creation
+**Prompt**: "Write a Dockerfile for a Node.js Express API service with TypeScript compilation"
+**Expected**:
+- Multi-stage build (deps → build → production)
+- Non-root user
+- HEALTHCHECK instruction
+- Pinned base image version
+- Production-only dependencies in final stage
+- .dockerignore mentioned
+
+## Test 2: CI/CD Pipeline
+**Prompt**: "Set up a GitHub Actions workflow for a Python FastAPI service with linting, testing, Docker build, and deployment to staging"
+**Expected**:
+- Stages: lint → typecheck → test → build → deploy
+- Runs on PR and merge to main
+- Docker build with caching
+- Integration tests before deploy
+- Environment-specific secrets handling
+
+## Test 3: Database Migration Strategy
+**Prompt**: "I need to rename the 'username' column to 'display_name' in our users table. How do I do this safely?"
+**Expected**:
+- Two-phase migration approach
+- Phase 1: add display_name, backfill, deploy code that reads both
+- Phase 2: drop username column in next release
+- Never rename in a single deploy
+- Backward compatibility emphasized

package/skills/global/documentation/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: documentation
+description: >
+  Organization-wide documentation standards for all projects. Use this skill
+  whenever writing, reviewing, or generating documentation — READMEs, API docs,
+  architecture decision records, onboarding guides, runbooks, changelogs,
+  code comments, or any written technical content. Triggers on: "README",
+  "documentation", "docs", "API docs", "Swagger", "OpenAPI", "ADR",
+  "architecture decision", "runbook", "onboarding guide", "changelog",
+  "technical writing", "document this", "write docs for", "explain this code".
+  Applies to all teams and all stacks.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Documentation Standards
+
+## Overview
+
+Good documentation reduces onboarding time, prevents knowledge silos, and
+makes services maintainable long-term. Every project must maintain a minimum
+set of documentation. These standards define what, how, and when to document.
+
+## 1. README.md (Required for Every Repo)
+
+Every repository must have a README with these sections in this order:
+
+### Template
+```markdown
+# Project Name
+
+One-sentence description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+# Clone, install, run — copy-paste ready
+git clone ...
+npm install
+npm run dev
+\`\`\`
+
+## Overview
+
+2-3 paragraphs explaining:
+- What this service/app does
+- Who uses it (internal team, customers, other services)
+- Key technologies and architecture decisions
+
+## Prerequisites
+
+- Node.js >= 20
+- PostgreSQL 15+
+- Redis 7+
+
+## Setup
+
+Step-by-step local development setup. Assume a new developer
+with a blank machine.
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| DATABASE_URL | PostgreSQL connection string | Yes | — |
+| REDIS_URL | Redis connection string | Yes | — |
+| PORT | Server port | No | 3000 |
+
+## API Documentation
+
+Link to OpenAPI/Swagger docs or inline endpoint summary.
+
+## Testing
+
+\`\`\`bash
+npm test            # unit tests
+npm run test:e2e    # end-to-end tests
+npm run test:cov    # coverage report
+\`\`\`
+
+## Deployment
+
+How to deploy this service. Link to CI/CD pipeline.
+
+## Architecture
+
+Brief architecture overview or link to ADR documents.
+
+## Contributing
+
+Link to CONTRIBUTING.md or team-specific contributing guide.
+```
+
+### Rules
+- Quick Start must be copy-paste ready — a new developer runs 3 commands and the app starts
+- Environment variables table must list ALL required vars with descriptions
+- Setup assumes a fresh machine — don't skip steps
+- Update README when adding new env vars, endpoints, or setup steps
+
+## 2. API Documentation
+
+### OpenAPI / Swagger (Required for All APIs)
+
+Every API must have machine-readable documentation:
+
+```yaml
+# openapi.yaml structure
+openapi: 3.0.3
+info:
+  title: User Service API
+  version: 1.0.0
+  description: Manages user accounts and authentication
+paths:
+  /api/v1/users:
+    get:
+      summary: List users
+      description: Returns paginated list of users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListResponse'
+```
+
+### Rules
+- Auto-generate from code where possible (FastAPI does this, Express needs swagger-jsdoc)
+- Every endpoint documented with: summary, description, parameters, request body, responses
+- Include example request/response payloads
+- Document error responses (400, 401, 403, 404, 500)
+- Keep OpenAPI spec in sync with actual implementation — CI should validate this
+
+## 3. Architecture Decision Records (ADRs)
+
+When a significant technical decision is made, document it:
+
+### ADR Template
+```markdown
+# ADR-{number}: {Title}
+
+**Date**: YYYY-MM-DD
+**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-{n}
+**Decision makers**: Names
+
+## Context
+
+What is the issue? What forces are at play?
+
+## Decision
+
+What is the change we're making?
+
+## Consequences
+
+### Positive
+- What becomes easier or better?
+
+### Negative
+- What becomes harder or worse?
+
+### Risks
+- What could go wrong?
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Why Rejected |
+|--------|------|------|--------------|
+| Option A | ... | ... | ... |
+| Option B | ... | ... | ... |
+```
+
+### When to Write an ADR
+- Choosing a framework, database, or major library
+- Changing architecture patterns (monolith → microservices)
+- Changing API versioning strategy
+- Adding a new infrastructure component
+- Any decision that will be hard to reverse
+
+### Rules
+- Store in `docs/adrs/` directory in the relevant repo
+- Number sequentially: `001-choose-database.md`, `002-api-versioning.md`
+- Never delete ADRs — mark as Deprecated or Superseded
+- Review ADRs when the context changes significantly
+
+## 4. Inline Code Documentation
+
+### JSDoc / Docstrings for Public APIs
+
+Every exported function, class, or module must have a doc comment:
+
+```typescript
+/**
+ * Calculates the total price for an order including tax and discounts.
+ *
+ * @param items - Array of order line items
+ * @param taxRate - Tax rate as a decimal (e.g., 0.15 for 15%)
+ * @param discountCode - Optional discount code to apply
+ * @returns The calculated total in cents
+ * @throws {ValidationError} If items array is empty
+ * @throws {DiscountNotFoundError} If discount code is invalid
+ *
+ * @example
+ * const total = calculateOrderTotal(items, 0.15, "SAVE20");
+ */
+export function calculateOrderTotal(
+  items: OrderItem[],
+  taxRate: number,
+  discountCode?: string,
+): number {
+  // ...
+}
+```
+
+### Rules
+- Document all exported/public functions
+- Include `@param`, `@returns`, `@throws`, and `@example`
+- Internal/private functions: comment only if logic is non-obvious
+- Comments explain WHY, not WHAT (code explains what)
+- Delete stale comments — wrong comments are worse than no comments
+
+## 5. Changelog
+
+Every project maintains a CHANGELOG.md following Keep a Changelog format:
+
+```markdown
+# Changelog
+
+## [1.2.0] - 2026-03-19
+### Added
+- User profile photo upload endpoint
+- Rate limiting on auth endpoints
+
+### Changed
+- Increased password minimum length from 8 to 12
+
+### Fixed
+- Login timeout on slow connections
+
+## [1.1.0] - 2026-03-01
+### Added
+- ...
+```
+
+### Rules
+- Update changelog in the same PR as the code change
+- Group by: Added, Changed, Deprecated, Removed, Fixed, Security
+- Link version headers to git tags/releases
+- Write for humans — "Added user photo upload" not "Implemented PUT /users/:id/photo"
+
+## 6. Runbooks (Required for Production Services)
+
+Every service running in production needs a runbook:
+
+```markdown
+# Service Name — Runbook
+
+## Service Overview
+- What it does, who depends on it
+- Health check URL, dashboards, logs
+
+## Common Issues
+
+### Issue: High Response Latency
+**Symptoms**: p99 latency > 2s, alerts firing
+**Diagnosis**: Check database connection pool, Redis cache hit rate
+**Resolution**: Scale up DB pool, clear stale cache, check for slow queries
+
+### Issue: Out of Memory
+**Symptoms**: OOM kills in container logs
+**Diagnosis**: Check for memory leaks, large payload processing
+**Resolution**: Restart pods, increase memory limit, investigate leak
+
+## Escalation
+- L1: On-call engineer (check runbook, restart if needed)
+- L2: Service owner (investigate root cause)
+- L3: Platform team (infrastructure issues)
+```
+
+## Checklist
+
+Before finalizing documentation:
+- [ ] README has all required sections (Quick Start, Setup, Env Vars, etc.)
+- [ ] Quick Start is copy-paste ready and actually works
+- [ ] All API endpoints documented in OpenAPI format
+- [ ] ADRs written for significant technical decisions
+- [ ] Exported functions have JSDoc/docstrings
+- [ ] CHANGELOG updated with this PR's changes
+- [ ] Runbook exists for production services
+- [ ] No stale or outdated documentation

package/skills/global/documentation/tests/test-prompts.md

@@ -0,0 +1,26 @@
+## Test 1: README Generation
+**Prompt**: "Generate a README for a Node.js payment processing microservice that uses Express, PostgreSQL, Redis, and Stripe"
+**Expected**:
+- All required sections present (Quick Start through Contributing)
+- Copy-paste ready Quick Start commands
+- Environment variables table with DATABASE_URL, REDIS_URL, STRIPE_KEY, etc.
+- API documentation section
+- Testing commands
+
+## Test 2: ADR Writing
+**Prompt**: "We're deciding between PostgreSQL and MongoDB for our new e-commerce service. Write an ADR recommending PostgreSQL"
+**Expected**:
+- Follows ADR template: Context, Decision, Consequences, Alternatives
+- Pros/cons table comparing both options
+- Clear reasoning for the decision
+- Acknowledges tradeoffs
+- Proper status and metadata
+
+## Test 3: Function Documentation
+**Prompt**: "Add documentation to this function: `async function processRefund(orderId: string, amount: number, reason: string, isPartial: boolean)`"
+**Expected**:
+- JSDoc with @param for all 4 parameters
+- @returns describing the return value
+- @throws for possible errors
+- @example showing usage
+- Description of what the function does