@valentia-ai-skills/framework 1.0.0

package/skills/global/git-workflow/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: git-workflow
+description: >
+  Organization-wide Git workflow standards. Use this skill whenever the developer
+  is working with Git — creating branches, writing commit messages, preparing PRs,
+  merging code, resolving conflicts, or discussing branching strategy. Also triggers
+  when asked to "commit", "push", "merge", "create a PR", "branch off", "tag a
+  release", "cherry-pick", "rebase", or any other Git operation. Applies to all
+  teams and all repositories in the organization.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Git Workflow
+
+## Overview
+
+Standardized Git workflow that all teams follow. Ensures clean history, traceable
+changes, and smooth code review processes across 10+ teams working on different
+projects.
+
+## 1. Branching Strategy
+
+We use a **trunk-based development** model with short-lived feature branches.
+
+### Branch Naming Convention
+
+```
+{type}/{ticket-id}/{short-description}
+```
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| `feature/` | New functionality | `feature/PROJ-123/user-registration` |
+| `fix/` | Bug fixes | `fix/PROJ-456/login-timeout` |
+| `hotfix/` | Production emergency | `hotfix/PROJ-789/payment-crash` |
+| `chore/` | Maintenance, deps, config | `chore/PROJ-101/upgrade-node-20` |
+| `refactor/` | Code improvements | `refactor/PROJ-202/extract-auth-service` |
+| `docs/` | Documentation only | `docs/PROJ-303/api-endpoint-guide` |
+
+### Rules
+- Branch from `main` (or `develop` if your team uses GitFlow)
+- Branch lifetime: **maximum 3 days** — if longer, break the work into smaller PRs
+- Delete branches after merge
+- Never commit directly to `main`
+
+## 2. Commit Messages
+
+### Format
+
+```
+{type}({scope}): {short description}
+
+{optional body — explain WHY, not WHAT}
+
+{optional footer — ticket references, breaking changes}
+```
+
+### Types
+
+| Type | When |
+|------|------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code change that doesn't fix a bug or add a feature |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `chore` | Build, deps, CI config |
+| `style` | Formatting, whitespace (no logic change) |
+| `perf` | Performance improvement |
+
+### Examples
+
+✅ Good:
+```
+feat(auth): add password reset via email
+
+Users can now request a password reset link sent to their
+registered email. Link expires after 24 hours.
+
+Closes PROJ-123
+```
+
+```
+fix(cart): prevent duplicate items on rapid click
+
+Added debounce to add-to-cart handler. Previously, rapid
+clicking could add the same item multiple times before
+the UI updated.
+
+Fixes PROJ-456
+```
+
+❌ Bad:
+```
+fixed stuff                    // no type, no scope, vague
+update                         // meaningless
+WIP                           // don't commit WIP to shared branches
+feat: changes                 // no scope, no description
+```
+
+### Rules
+- Subject line: max 72 characters
+- Use imperative mood: "add feature" not "added feature"
+- No period at end of subject
+- Body wraps at 80 characters
+- Reference ticket numbers in footer
+
+## 3. Pull Requests
+
+### PR Title Format
+Same as commit message format:
+```
+feat(auth): add password reset via email
+```
+
+### PR Description Template
+Every PR must include:
+1. **What** — One sentence describing the change
+2. **Why** — Context for why this change is needed
+3. **How** — Key implementation decisions
+4. **Testing** — How you verified this works
+5. **Screenshots** — If UI changes (before/after)
+
+### PR Size Rules
+- **Target**: Under 400 lines changed
+- **Hard limit**: 800 lines — larger PRs must be split
+- Exception: Generated files, migrations, dependency updates
+
+### Review Requirements
+- Minimum 1 approval required
+- 2 approvals for: security-related changes, shared library changes, infrastructure changes
+- All CI checks must pass
+- No unresolved comments
+
+### Merge Strategy
+- **Squash merge** for feature branches (clean history)
+- **Merge commit** for release branches (preserve history)
+- Never force push to `main`
+
+## 4. Release Tagging
+
+### Version Format
+Semantic versioning: `vMAJOR.MINOR.PATCH`
+
+```
+v1.0.0   — initial release
+v1.1.0   — new feature added
+v1.1.1   — bug fix
+v2.0.0   — breaking change
+```
+
+### Tagging Process
+```bash
+git tag -a v1.2.0 -m "Release v1.2.0: Add user dashboard"
+git push origin v1.2.0
+```
+
+## 5. Git Hygiene
+
+- Pull and rebase before pushing: `git pull --rebase origin main`
+- Resolve conflicts locally, never in GitHub UI
+- Don't commit: `.env` files, `node_modules/`, build artifacts, IDE configs
+- Keep `.gitignore` up to date
+- Squash fixup commits before review
+
+## Checklist
+
+Before any Git operation, verify:
+- [ ] Branch name follows `{type}/{ticket}/{description}` format
+- [ ] Commit message follows conventional format with type and scope
+- [ ] PR is under 400 lines (or justified if larger)
+- [ ] PR description includes What/Why/How/Testing
+- [ ] No secrets, env files, or build artifacts committed
+- [ ] Branch is rebased on latest main

package/skills/global/git-workflow/tests/test-prompts.md

@@ -0,0 +1,11 @@
+## Test 1: Branch Creation
+**Prompt**: "I need to start working on a new user dashboard feature, ticket DASH-42"
+**Expected**: Suggests `feature/DASH-42/user-dashboard` branch name, shows git checkout command
+
+## Test 2: Commit Message Writing
+**Prompt**: "Write a commit message for: I updated the login page to show an error when the password is wrong"
+**Expected**: `fix(auth): show error message on incorrect password` with body explaining context
+
+## Test 3: PR Preparation
+**Prompt**: "Help me prepare a PR for my authentication refactor that moved from JWT to session-based auth"
+**Expected**: PR title in conventional format, description with What/Why/How/Testing sections, notes about breaking change

package/skills/global/security-baseline/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: security-baseline
+description: >
+  Organization-wide security standards for all code. Use this skill whenever
+  writing code that handles: authentication, authorization, passwords, tokens,
+  API keys, secrets, user input, database queries, file uploads, HTTP requests,
+  CORS, headers, cookies, sessions, encryption, hashing, or any security-sensitive
+  operation. Also triggers on: "login", "signup", "auth", "validate", "sanitize",
+  "encrypt", "hash", "permission", "role", "access control", "secret", "API key",
+  "environment variable", ".env", "OWASP", "vulnerability", "injection",
+  "XSS", "CSRF", or "security review". Applies to ALL stacks.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Security Baseline
+
+## Overview
+
+Non-negotiable security standards that every developer and every AI-generated
+piece of code must follow. These rules prevent the most common vulnerability
+classes (OWASP Top 10) and protect user data.
+
+## 1. Secret Management
+
+### NEVER Hardcode Secrets
+
+Secrets must NEVER appear in code, config files, or version control.
+
+✅ Good:
+```typescript
+const dbUrl = process.env.DATABASE_URL;
+const apiKey = process.env.STRIPE_API_KEY;
+```
+
+❌ Bad:
+```typescript
+const dbUrl = "postgres://admin:password123@db.example.com/prod";
+const apiKey = "sk_live_abc123xyz789";
+```
+
+### Rules
+- All secrets go in environment variables
+- Use `.env.example` with placeholder values (never real secrets)
+- `.env` must be in `.gitignore` — verify this exists
+- Use a secrets manager (Vault, AWS SSM, etc.) for production
+- Rotate secrets on any suspected exposure
+- Never log secrets — even partially
+
+### Pre-Commit Check
+If generating any config or setup code, always include:
+```gitignore
+# .gitignore — MUST include:
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+```
+
+## 2. Input Validation
+
+### Validate ALL User Input
+
+Never trust input from clients, APIs, forms, URLs, or any external source.
+
+### Rules
+- Validate at the boundary (API endpoint / form handler)
+- Use schema validation (Zod, Joi, class-validator, Pydantic)
+- Validate types, lengths, formats, and ranges
+- Reject invalid input — don't try to "fix" it
+- Return clear error messages without exposing internals
+
+✅ Good:
+```typescript
+import { z } from "zod";
+
+const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100),
+  age: z.number().int().min(13).max(150),
+  role: z.enum(["user", "admin"]),
+});
+
+function createUser(req, res) {
+  const result = createUserSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: "Invalid input", details: result.error.issues });
+  }
+  // proceed with validated data: result.data
+}
+```
+
+❌ Bad:
+```typescript
+function createUser(req, res) {
+  const { email, name, age, role } = req.body;
+  // directly using unvalidated input
+  db.users.insert({ email, name, age, role });
+}
+```
+
+## 3. SQL Injection Prevention
+
+### ALWAYS Use Parameterized Queries
+
+Never concatenate user input into SQL strings.
+
+✅ Good:
+```typescript
+// Parameterized query
+const user = await db.query("SELECT * FROM users WHERE email = $1", [email]);
+
+// ORM (also safe)
+const user = await User.findOne({ where: { email } });
+```
+
+❌ Bad:
+```typescript
+// SQL INJECTION VULNERABILITY
+const user = await db.query(`SELECT * FROM users WHERE email = '${email}'`);
+const user = await db.query("SELECT * FROM users WHERE email = '" + email + "'");
+```
+
+## 4. Authentication
+
+### Password Rules
+- Hash with bcrypt (cost factor ≥ 12) or Argon2
+- Never store plaintext passwords
+- Never log passwords — even hashed
+- Minimum 8 characters, check against breached password lists
+
+✅ Good:
+```typescript
+import bcrypt from "bcrypt";
+
+const SALT_ROUNDS = 12;
+
+async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+```
+
+### Token Rules
+- Use short-lived access tokens (15-60 minutes)
+- Use refresh tokens for session extension
+- Store tokens in httpOnly, secure, sameSite cookies
+- Never store tokens in localStorage (XSS vulnerable)
+
+✅ Good:
+```typescript
+res.cookie("token", jwt, {
+  httpOnly: true,      // not accessible via JavaScript
+  secure: true,        // HTTPS only
+  sameSite: "strict",  // CSRF protection
+  maxAge: 15 * 60 * 1000, // 15 minutes
+});
+```
+
+❌ Bad:
+```typescript
+localStorage.setItem("token", jwt);  // XSS vulnerable
+res.cookie("token", jwt);            // missing security flags
+```
+
+## 5. Authorization
+
+- Check permissions on EVERY protected endpoint
+- Never rely on client-side checks alone
+- Use role-based (RBAC) or attribute-based (ABAC) access control
+- Verify resource ownership: user can only access THEIR data
+
+```typescript
+// Always verify ownership
+async function getOrder(req, res) {
+  const order = await Order.findById(req.params.id);
+  
+  if (!order) return res.status(404).json({ error: "Not found" });
+  if (order.userId !== req.user.id) return res.status(403).json({ error: "Forbidden" });
+  
+  return res.json(order);
+}
+```
+
+## 6. XSS Prevention
+
+- Escape all user-generated content before rendering in HTML
+- Use framework-provided escaping (React auto-escapes, etc.)
+- Never use `dangerouslySetInnerHTML` (React) or `v-html` (Vue) with user content
+- Set `Content-Security-Policy` headers
+
+## 7. Dependency Security
+
+- Run `npm audit` / `pip audit` in CI pipeline
+- No known critical/high vulnerabilities in production
+- Pin dependency versions (use lockfiles)
+- Review dependencies before adding — prefer well-maintained packages
+
+## 8. Logging & Error Handling
+
+- Never log: passwords, tokens, API keys, credit cards, SSNs, PII
+- Log: failed auth attempts, permission denials, validation failures
+- Don't expose stack traces to users in production
+- Return generic error messages to clients
+
+✅ Good:
+```typescript
+// Log for debugging (server-side only)
+logger.error("Payment failed", { userId: user.id, orderId: order.id, error: err.code });
+
+// Return to client (generic)
+res.status(500).json({ error: "Payment processing failed. Please try again." });
+```
+
+❌ Bad:
+```typescript
+// Exposes internals to client
+res.status(500).json({ error: err.stack, query: sql, dbPassword: config.db.password });
+```
+
+## Checklist
+
+Before finalizing any code that touches security:
+- [ ] No hardcoded secrets — all from environment variables
+- [ ] .env is in .gitignore
+- [ ] All user input is validated with schema validation
+- [ ] SQL queries are parameterized
+- [ ] Passwords are hashed (bcrypt/Argon2, cost ≥ 12)
+- [ ] Tokens are in httpOnly secure cookies (not localStorage)
+- [ ] Authorization checks on every protected endpoint
+- [ ] No user content rendered via dangerouslySetInnerHTML or equivalent
+- [ ] Error messages don't expose internals
+- [ ] No PII in logs

package/skills/global/security-baseline/tests/test-prompts.md

@@ -0,0 +1,23 @@
+## Test 1: Login Endpoint
+**Prompt**: "Write a login endpoint that takes email and password, checks the database, and returns a session token"
+**Expected**:
+- Input validation with schema (Zod/Joi)
+- bcrypt password comparison (not plaintext)
+- Token in httpOnly secure cookie (not localStorage)
+- Generic error message ("Invalid credentials" not "Password wrong" vs "User not found")
+- Rate limiting mentioned or implemented
+
+## Test 2: Database Query with User Input
+**Prompt**: "Write a search endpoint that finds products by name from a query parameter"
+**Expected**:
+- Parameterized query (not string concatenation)
+- Input validation on query param (length, format)
+- No SQL injection vectors
+
+## Test 3: Configuration Setup
+**Prompt**: "Set up the database connection and Stripe API configuration for our app"
+**Expected**:
+- All credentials from process.env
+- .env.example file with placeholders
+- .gitignore includes .env
+- No real secrets in any code

package/skills/global/testing-standards/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: testing-standards
+description: >
+  Organization-wide testing standards and patterns. Use this skill whenever
+  writing, reviewing, or discussing tests — unit tests, integration tests,
+  e2e tests, test coverage, mocking, stubbing, fixtures, test utilities,
+  or QA processes. Triggers on: "test", "spec", "coverage", "mock", "stub",
+  "fixture", "assertion", "expect", "describe", "it", "jest", "vitest",
+  "pytest", "cypress", "playwright", "testing-library", "TDD", "BDD",
+  "unit test", "integration test", "e2e", "end-to-end", "test plan",
+  "regression", "smoke test", "QA". Applies to all stacks.
+version: "1.0.0"
+scope: global
+author: Framework Admin
+last_reviewed: 2026-03-19
+---
+
+# Testing Standards
+
+## Overview
+
+Every team must write tests. These standards define what to test, how to test,
+and what quality bar to maintain. The goal is confidence in deployments —
+not 100% coverage for its own sake.
+
+## 1. Coverage Targets
+
+| Test Type | Minimum Coverage | Target Coverage |
+|-----------|-----------------|-----------------|
+| Unit Tests | 70% | 85% |
+| Integration Tests | Key flows covered | All critical paths |
+| E2E Tests | Happy paths | Happy + top 5 error paths |
+
+### What Counts as "Covered"
+- Lines of code executed during tests
+- Branch coverage (both if/else paths)
+- Coverage measured per-service, not org-wide
+
+### What to Skip
+- Generated code, type definitions, config files
+- Third-party library wrappers (test the library's behavior, not its internals)
+
+## 2. Test File Organization
+
+### File Naming
+```
+src/
+  services/
+    user-service.ts
+    user-service.test.ts          # co-located unit tests
+  
+tests/
+  integration/
+    user-registration.test.ts     # integration tests
+  e2e/
+    login-flow.spec.ts            # e2e tests
+  fixtures/
+    users.ts                      # shared test data
+  helpers/
+    test-db.ts                    # test utilities
+```
+
+### Rules
+- Unit tests: co-located next to source file (`.test.ts`)
+- Integration tests: in `tests/integration/`
+- E2E tests: in `tests/e2e/` with `.spec.ts` extension
+- Fixtures: in `tests/fixtures/`
+- Shared helpers: in `tests/helpers/`
+
+## 3. Test Structure — AAA Pattern
+
+Every test follows **Arrange → Act → Assert**:
+
+```typescript
+describe("UserService", () => {
+  describe("createUser", () => {
+    it("should create a user with valid data", async () => {
+      // Arrange — set up test data and dependencies
+      const userData = { email: "alice@example.com", name: "Alice" };
+      const mockRepo = { save: vi.fn().mockResolvedValue({ id: "usr_123", ...userData }) };
+      const service = new UserService(mockRepo);
+
+      // Act — call the function being tested
+      const result = await service.createUser(userData);
+
+      // Assert — verify the outcome
+      expect(result.id).toBe("usr_123");
+      expect(result.email).toBe("alice@example.com");
+      expect(mockRepo.save).toHaveBeenCalledWith(userData);
+    });
+
+    it("should throw ValidationError for invalid email", async () => {
+      // Arrange
+      const userData = { email: "not-an-email", name: "Alice" };
+      const service = new UserService(mockRepo);
+
+      // Act & Assert
+      await expect(service.createUser(userData)).rejects.toThrow(ValidationError);
+    });
+  });
+});
+```
+
+## 4. Naming Conventions
+
+### Describe Blocks
+- Top level: class or module name
+- Nested: method or function name
+
+### Test Names
+Use the pattern: **"should {expected behavior} when {condition}"**
+
+✅ Good:
+```typescript
+it("should return 404 when user does not exist")
+it("should hash password before saving")
+it("should send welcome email after registration")
+it("should retry 3 times on network failure")
+```
+
+❌ Bad:
+```typescript
+it("test user creation")          // vague, no expected behavior
+it("works")                       // meaningless
+it("createUser")                  // just the function name
+it("should work correctly")       // no specific behavior
+```
+
+## 5. Mocking Rules
+
+### What to Mock
+- External HTTP calls (APIs, third-party services)
+- Database connections (for unit tests only)
+- File system operations
+- Time-dependent functions (Date.now, setTimeout)
+- Email/notification services
+
+### What NOT to Mock
+- The code under test itself
+- Simple utility functions
+- Data transformations
+- Type conversions
+
+### Mock Discipline
+```typescript
+// ✅ Good: Mock at the boundary
+const mockEmailService = { send: vi.fn().mockResolvedValue(true) };
+const service = new UserService(mockEmailService);
+
+// ❌ Bad: Mocking implementation details
+vi.spyOn(service, 'validateEmail');  // testing internal method
+```
+
+### Rules
+- Reset mocks between tests: `beforeEach(() => vi.clearAllMocks())`
+- Verify mock calls when the side effect IS the behavior being tested
+- Don't over-mock — if you're mocking more than 3 things, the code may need refactoring
+
+## 6. Integration Test Standards
+
+Integration tests verify that components work together correctly.
+
+```typescript
+describe("User Registration Flow", () => {
+  let app: Express;
+  let db: TestDatabase;
+
+  beforeAll(async () => {
+    db = await createTestDatabase();
+    app = createApp({ database: db });
+  });
+
+  afterAll(async () => {
+    await db.cleanup();
+  });
+
+  it("should register user and send confirmation email", async () => {
+    const response = await request(app)
+      .post("/api/v1/users")
+      .send({ email: "alice@test.com", name: "Alice", password: "SecureP@ss1" });
+
+    expect(response.status).toBe(201);
+    expect(response.body.data.email).toBe("alice@test.com");
+    
+    // Verify side effects
+    const userInDb = await db.users.findByEmail("alice@test.com");
+    expect(userInDb).toBeTruthy();
+  });
+});
+```
+
+### Rules
+- Use a dedicated test database (never the real one)
+- Clean up after each test suite
+- Test the full request/response cycle
+- Verify database state changes
+- Test error paths, not just happy paths
+
+## 7. E2E Test Standards
+
+E2E tests simulate real user workflows through the UI.
+
+### Rules
+- Use Playwright or Cypress (team choice, be consistent)
+- Test the top 5 user journeys (login, core workflows, payment if applicable)
+- Use data-testid attributes for selectors (not CSS classes or text)
+- Each test should be independent — no test-ordering dependencies
+- Keep E2E suite under 10 minutes total runtime
+
+```typescript
+// ✅ Good: stable selector
+await page.click('[data-testid="submit-button"]');
+
+// ❌ Bad: fragile selectors
+await page.click('.btn-primary');           // CSS class changes break this
+await page.click('text=Submit Order');      // text changes break this
+```
+
+## 8. Test Data
+
+### Factories Over Fixtures
+Use factory functions that generate test data with sensible defaults:
+
+```typescript
+function createTestUser(overrides = {}) {
+  return {
+    id: `usr_${Math.random().toString(36).slice(2)}`,
+    email: `test-${Date.now()}@example.com`,
+    name: "Test User",
+    role: "user",
+    isActive: true,
+    ...overrides,
+  };
+}
+
+// Usage
+const admin = createTestUser({ role: "admin", name: "Admin" });
+const inactive = createTestUser({ isActive: false });
+```
+
+### Rules
+- Use unique data per test (no shared mutable state)
+- Factory functions > static fixtures
+- Use realistic but fake data (not "test", "foo", "bar")
+
+## Checklist
+
+Before submitting any code:
+- [ ] Unit tests for all new functions/methods
+- [ ] Tests follow AAA pattern (Arrange, Act, Assert)
+- [ ] Test names use "should ... when ..." pattern
+- [ ] Mocks reset between tests
+- [ ] No test-ordering dependencies
+- [ ] Integration tests for API endpoints
+- [ ] Coverage meets minimum thresholds (70% unit, critical paths integration)
+- [ ] E2E selectors use data-testid
+- [ ] Test data uses factories, not shared mutable fixtures