constellai 0.3.0

package/skills/engineering/security/dependency-supply-chain/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dependency-supply-chain
+description: Manage dependency and supply-chain risk — scan for known-vulnerable components (OWASP Dependency-Check) and verify build provenance with SLSA levels.
+domain: engineering
+category: security
+tags: [supply-chain, dependencies, sca, slsa, provenance, owasp]
+official_sources:
+  - https://owasp.org/www-project-dependency-check/
+  - https://slsa.dev/
+verified: 2026-06-16
+---
+
+# Dependency & Supply-Chain Security
+
+## Overview
+Most applications are mostly third-party code, so a vulnerable or tampered dependency is a direct path into your system (OWASP Top 10 A03 Software Supply Chain Failures). This skill covers two complementary defenses: detecting known-vulnerable components with Software Composition Analysis (OWASP Dependency-Check) and raising the integrity of how artifacts are built using the SLSA framework. Read it when adding dependencies, configuring CI/CD, or hardening a release pipeline.
+
+## Official sources
+- OWASP Dependency-Check (docs): https://owasp.org/www-project-dependency-check/
+- Dependency-Check repo: https://github.com/dependency-check/DependencyCheck
+- SLSA (docs): https://slsa.dev/
+- SLSA repo: https://github.com/slsa-framework/slsa (an OpenSSF project)
+- Licenses: Dependency-Check (Apache-2.0); SLSA spec (Community Specification License 1.0)
+
+## Install / setup
+OWASP Dependency-Check CLI quick start (verbatim from the official repo README; macOS via Homebrew):
+```bash
+$ brew update && brew install dependency-check
+$ dependency-check -h
+$ dependency-check --out . --scan [path to jar files to be scanned]
+```
+On other platforms, download the latest release from GitHub, then run the bundled script:
+```bash
+# *nix
+$ ./bin/dependency-check.sh -h
+$ ./bin/dependency-check.sh --out . --scan [path to jar files to be scanned]
+```
+```bat
+:: Windows
+> .\bin\dependency-check.bat -h
+> .\bin\dependency-check.bat --out . --scan [path to jar files to be scanned]
+```
+
+## Core concepts
+- **Software Composition Analysis (SCA).** Dependency-Check inventories a project's dependencies, derives CPE identifiers, and maps them to known CVEs from the National Vulnerability Database so you avoid shipping components with publicly disclosed vulnerabilities.
+- **Pipeline integration.** Dependency-Check runs as a CLI and ships plugins/integrations for Maven, Gradle, Ant, GitHub Actions, Jenkins, Azure DevOps, and Docker (some community-maintained), so scans can gate builds.
+- **SLSA framework.** SLSA ("Supply-chain Levels for Software Artifacts") is a checklist of standards and controls to prevent tampering and improve artifact integrity from source to service.
+- **Provenance.** Provenance is verifiable metadata describing what entity built an artifact, what process was used, and what the inputs were. Generating provenance is the first on-ramp to SLSA.
+- **SLSA build levels.** Build L0 = no guarantees; Build L1 = provenance exists (may be unsigned); Build L2 = signed provenance from a hosted build platform (prevents post-build tampering); Build L3 = hardened builds with strong isolation (prevents tampering during the build and cross-build interference).
+
+## Best practices
+- Run SCA (Dependency-Check) in CI and fail the build on newly introduced known-vulnerable dependencies, not just on a schedule.
+- Generate and verify build provenance; aim to progress up the SLSA build levels (start at L1, sign provenance for L2, harden the builder for L3).
+- Pin dependency versions and maintain a software bill of materials (SBOM) so you can quickly identify exposure when a new CVE drops.
+- Keep components current and patched (OWASP Proactive Control C6) rather than letting transitive dependencies drift.
+
+## Common pitfalls
+- Scanning only direct dependencies → transitive dependencies carry most known CVEs; scan the full resolved tree.
+- Trusting an artifact with no provenance → without signed provenance you cannot prove how or where it was built; require at least SLSA Build L1 and prefer L2+.
+- Treating a one-time scan as sufficient → vulnerability data changes daily; re-scan on every build and re-evaluate released artifacts as new CVEs are published.
+
+## Examples
+```yaml
+# Concept: gate a build on SCA results, then attest provenance
+steps:
+  - run: dependency-check --out reports --scan ./build/libs --failOnCVSS 7
+  - run: generate-and-sign-provenance   # work toward SLSA Build L2/L3
+```
+
+## Further reading
+- SLSA build levels specification: https://slsa.dev/spec/v1.0/levels (latest spec linked from slsa.dev)
+- OWASP Top 10 A03 Software Supply Chain Failures — ../owasp-top-10
+
+## Related skills
+- ../owasp-top-10 — A03 Software Supply Chain Failures
+- ../appsec-fundamentals — C6 Keep your Components Secure
+- ../secrets-management — protecting pipeline/build secrets

package/skills/engineering/security/owasp-asvs/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: owasp-asvs
+description: OWASP Application Security Verification Standard 5.0 — testable security requirements organized by chapter and verification level; consult to define or verify appsec requirements.
+domain: engineering
+category: security
+tags: [owasp, asvs, security-requirements, verification, appsec]
+official_sources:
+  - https://owasp.org/www-project-application-security-verification-standard/
+  - https://github.com/OWASP/ASVS
+verified: 2026-06-16
+---
+
+# OWASP ASVS
+
+## Overview
+The Application Security Verification Standard (ASVS) is an OWASP flagship project that provides a comprehensive, testable list of application security requirements. Unlike the awareness-oriented Top 10, ASVS is meant to be used as a measurable standard: a basis for security requirements during design, a checklist for testing/verification, and a procurement contract baseline. Read this when you need concrete, citable requirements for what "secure enough" means at a chosen rigor level.
+
+## Official sources
+- Docs / project: https://owasp.org/www-project-application-security-verification-standard/
+- Repo: https://github.com/OWASP/ASVS
+- License: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+- Current stable: ASVS 5.0.0 (released May 2025 at Global AppSec EU Barcelona)
+
+## Core concepts
+- **Verification levels (L1, L2, L3).** Requirements are tiered by increasing rigor. In 5.0, L1 is scoped to first-layer / foundational defenses (a deliberately smaller set than 4.x to lower the adoption barrier); L2 raises the bar (e.g., requiring multi-factor authentication); L3 is the most advanced (e.g., hardware-backed, attested authentication). Choose the level by the application's risk and data sensitivity.
+- **Requirement identifiers.** Requirements use a `<chapter>.<section>.<requirement>` numbering scheme and should be cited with a version prefix, e.g. `v5.0.0-1.2.5`, so references stay unambiguous across editions.
+- **Chapter structure (V1-V17).** ASVS 5.0 organizes requirements into chapters such as Encoding and Sanitization, Validation and Business Logic, Web Frontend Security, API and Web Service, File Handling, Authentication, Session Management, Authorization, Self-contained Tokens, OAuth and OIDC, Cryptography, Secure Communication, Configuration, Data Protection, Secure Coding and Architecture, Security Logging and Error Handling, and WebRTC.
+- **Standard, not a tool.** ASVS defines *what* to verify; it does not prescribe a specific scanner or test method. Teams map each requirement to manual review, automated tests, or both.
+
+## Best practices
+- Pick a target level up front based on risk (data sensitivity, exposure, regulatory needs) and treat it as the verification floor for the whole application.
+- Use ASVS requirement IDs (with version prefix) directly in tickets, test cases, and acceptance criteria so coverage is auditable.
+- Integrate the relevant chapter requirements into design reviews early rather than testing for them only at the end.
+
+## Common pitfalls
+- Treating all of L1+L2+L3 as mandatory → each level is cumulative and chosen by risk; applying L3 everywhere wastes effort and slows delivery.
+- Citing version 4.0.3 requirement numbers in a 5.0 program → the structure and level scoping changed substantially in 5.0; always confirm the IDs against the version you target.
+- Using ASVS as awareness reading → it is a verification standard; pair it with the Top 10 for prioritization and with cheat sheets for implementation guidance.
+
+## Examples
+```text
+# Referencing an ASVS requirement in a security acceptance criterion:
+Given a login endpoint, it MUST satisfy ASVS v5.0.0 (Authentication, chapter V6)
+at the target verification level (e.g., L2 requires multi-factor authentication).
+```
+
+## Further reading
+- Downloads (PDF / Word / CSV) and bleeding-edge master branch: linked from the project page above
+- OWASP Top 10 for risk prioritization: ../owasp-top-10
+
+## Related skills
+- ../owasp-top-10 — awareness/prioritization input that ASVS makes testable
+- ../appsec-fundamentals — proactive controls aligned to ASVS chapters
+- ../secure-auth-sessions — implementation detail for ASVS V6 and V7

package/skills/engineering/security/owasp-top-10/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: owasp-top-10
+description: The OWASP Top 10 web application security risks (2025 edition) and how to mitigate them; consult when threat-modeling or hardening web apps.
+domain: engineering
+category: security
+tags: [owasp, web-security, vulnerabilities, threat-modeling, appsec]
+official_sources:
+  - https://owasp.org/Top10/
+  - https://github.com/OWASP/Top10
+verified: 2026-06-16
+---
+
+# OWASP Top 10
+
+## Overview
+The OWASP Top 10 is the most widely referenced awareness document for web application security, ranking the most critical risks based on contributed data and a community survey. Read this when you need a shared vocabulary for the highest-impact classes of web vulnerabilities, when threat-modeling a feature, or when prioritizing remediation. The list is a starting point for awareness, not an exhaustive security standard (use ASVS for verification).
+
+## Official sources
+- Docs: https://owasp.org/Top10/ (redirects to the current 2025 edition at https://owasp.org/Top10/2025/)
+- Repo: https://github.com/OWASP/Top10
+- License: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+
+## Core concepts
+The 2025 edition defines ten categories (A01-A10). Each maps to a set of CWE weaknesses:
+
+- **A01:2025 Broken Access Control** — users acting outside their intended permissions (IDOR, missing authorization checks, privilege escalation).
+- **A02:2025 Security Misconfiguration** — insecure defaults, verbose errors, unpatched/exposed components, overly permissive settings.
+- **A03:2025 Software Supply Chain Failures** — risks from vulnerable, compromised, or tampered third-party components and build pipelines.
+- **A04:2025 Cryptographic Failures** — weak, missing, or misapplied cryptography exposing data in transit or at rest.
+- **A05:2025 Injection** — untrusted input interpreted as code/commands (SQLi, OS command injection, XSS is included here).
+- **A06:2025 Insecure Design** — flaws rooted in missing or ineffective security controls at the design stage.
+- **A07:2025 Authentication Failures** — weaknesses in identity confirmation and session handling (credential stuffing, weak recovery).
+- **A08:2025 Software or Data Integrity Failures** — unverified updates, insecure deserialization, untrusted CI/CD assumptions.
+- **A09:2025 Security Logging and Alerting Failures** — insufficient detection, logging, and timely alerting on attacks.
+- **A10:2025 Mishandling of Exceptional Conditions** — incorrect handling of errors and edge cases leading to failures or insecure states.
+
+## Best practices
+- Treat the Top 10 as an awareness baseline and pair it with a verification standard such as OWASP ASVS for testable requirements.
+- Address Broken Access Control (A01, consistently the top risk) by enforcing authorization server-side on every request and denying by default.
+- Prevent Injection (A05) with parameterized queries / prepared statements and context-aware output encoding rather than manual escaping.
+- Manage supply-chain risk (A03) with a software bill of materials (SBOM), dependency scanning, and verified provenance for build artifacts.
+
+## Common pitfalls
+- Relying on client-side checks for access control → enforce all authorization decisions on the server; never trust hidden fields or disabled UI.
+- Treating the Top 10 as a complete checklist → it is a prioritization aid, not a comprehensive security program; many real risks fall outside it.
+- Citing the outdated 2021 list (superseded) → reference the 2025 edition; category names and ordering changed (e.g., Injection moved, supply chain added).
+
+## Examples
+```sql
+-- A05 Injection: use a parameterized query, never string concatenation
+-- Vulnerable:  "SELECT * FROM users WHERE email = '" + input + "'"
+-- Safe (parameterized):
+SELECT * FROM users WHERE email = ?;  -- bind `input` as a parameter
+```
+
+## Further reading
+- Per-category detail pages: https://owasp.org/Top10/2025/
+- OWASP ASVS (testable verification requirements): ../owasp-asvs
+
+## Related skills
+- ../owasp-asvs — turns Top 10 awareness into verifiable, level-based requirements
+- ../appsec-fundamentals — proactive controls that prevent these risks by design
+- ../dependency-supply-chain — mitigates A03 Software Supply Chain Failures

package/skills/engineering/security/secrets-management/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: secrets-management
+description: Store, rotate, and never commit secrets — vaults over source/env vars, encryption, least privilege, rotation, and secret detection per OWASP guidance.
+domain: engineering
+category: security
+tags: [secrets, vault, rotation, credentials, owasp]
+official_sources:
+  - https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
+  - https://github.com/OWASP/CheatSheetSeries
+verified: 2026-06-16
+---
+
+# Secrets Management
+
+## Overview
+Secrets (API keys, database credentials, tokens, certificates, encryption keys) are the keys to the kingdom, and leaked secrets are a leading cause of breaches. This skill summarizes the OWASP Secrets Management Cheat Sheet: where secrets should live, how to rotate and revoke them, and how to keep them out of source code. Read it before wiring any credential into an application, CI/CD pipeline, or infrastructure-as-code.
+
+## Official sources
+- Secrets Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
+- Repo: https://github.com/OWASP/CheatSheetSeries
+- License: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+
+## Core concepts
+- **Use a secrets manager, not source code.** Store secrets in a dedicated solution (cloud services like AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or platform-agnostic tools like HashiCorp Vault), and inject them at deploy time via the orchestrator rather than hardcoding them.
+- **Lifecycle: creation, rotation, revocation, expiration.** Generate cryptographically strong secrets with least privilege, rotate them regularly so stolen credentials are short-lived, revoke compromised secrets immediately, and set expirations that force rotation.
+- **Encryption at rest and in transit.** Encrypt stored secrets with strong algorithms and never transmit them in plaintext (use TLS). Consider envelope encryption, keeping the encryption keys separate from the secrets they protect.
+- **Least privilege access.** Apply fine-grained, secret-level permissions; engineers should not have access to all secrets, and CI/CD systems should reach only the secrets they require. Prefer identity-based access (role assumption) over shared static credentials.
+- **Dynamic vs static secrets.** Prefer short-lived dynamic secrets (generated per session/deployment, auto-expiring) where supported; reserve static long-lived secrets for cases that require them, with rigorous rotation.
+- **Detect secrets in code.** Use automated detection (e.g., detect-secrets) with pre-commit hooks and IDE/shift-left scanning to catch secrets before they are committed.
+
+## Best practices
+- Keep secrets out of source code, container images, and environment variables baked into images; resolve them at runtime from a manager.
+- Automate rotation and minimize direct human interaction with raw secret values to reduce error and exposure.
+- Scope access per secret and per identity; audit and monitor access rather than granting broad blanket permissions.
+- Use distinct test secrets in detection tooling to reduce false positives while still catching real leaks.
+
+## Common pitfalls
+- Committing a secret to git → it persists in history; rotate/revoke the secret immediately and scrub history; add pre-commit secret scanning.
+- Treating environment variables as a secure store → they can leak via logs, process listings, and child processes; prefer a managed secrets solution.
+- Long-lived, never-rotated credentials → set expirations and rotate; prefer dynamic, short-lived secrets where possible.
+- Giving every engineer or every CI job access to all secrets → enforce least privilege at the individual-secret level.
+
+## Examples
+```text
+# Resolve a secret at runtime instead of hardcoding (concept):
+1. App authenticates to the secrets manager using its workload identity (no static key).
+2. Manager returns a short-lived, scoped secret (e.g., a dynamic DB credential).
+3. App uses it; the credential auto-expires and is rotated by the manager.
+```
+
+## Further reading
+- Secrets Management Cheat Sheet (full lifecycle and tooling detail) — link above
+- ASVS chapter V11 Cryptography and V13 Configuration — ../owasp-asvs
+
+## Related skills
+- ../appsec-fundamentals — C2 Use Cryptography to Protect Data
+- ../secure-auth-sessions — secrets back credential/session security
+- ../dependency-supply-chain — pipeline secrets and build integrity

package/skills/engineering/security/secure-auth-sessions/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: secure-auth-sessions
+description: Safe authentication and session management per OWASP cheat sheets — passwords, MFA, session IDs, secure cookies, regeneration, and timeouts.
+domain: engineering
+category: security
+tags: [authentication, sessions, mfa, cookies, owasp]
+official_sources:
+  - https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+  - https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
+verified: 2026-06-16
+---
+
+# Secure Authentication & Session Management
+
+## Overview
+Authentication confirms who a user is; session management keeps them authenticated across requests without re-proving identity each time. Both are high-value targets and appear in the OWASP Top 10 (A07 Authentication Failures). This skill distills the OWASP Authentication and Session Management cheat sheets into the decisions you most often get wrong. Read it when designing login, registration, password reset, or any stateful session.
+
+## Official sources
+- Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+- Session Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
+- Repo: https://github.com/OWASP/CheatSheetSeries
+- License: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+
+## Core concepts
+- **Passwords.** Enforce a minimum length (OWASP guidance: at least 8 characters with MFA, 15 without) and a generous maximum (at least 64 characters to allow passphrases). Allow all characters including Unicode and whitespace, and avoid arbitrary composition rules and mandatory periodic rotation.
+- **Breached-password and MFA.** Block common and previously breached passwords (e.g., via a Pwned Passwords-style check). Multi-factor authentication is the single strongest defense against password-related attacks.
+- **Generic error messages.** Use identical responses for failed login regardless of cause (e.g., "Login failed; Invalid user ID or password") so attackers cannot enumerate valid accounts.
+- **Secure password storage.** Never store plaintext or reversible passwords; use a dedicated password-hashing function (see the Password Storage Cheat Sheet) rather than a general-purpose hash.
+- **Session IDs.** Generate session IDs with at least 64 bits of entropy, keep their value meaningless (no embedded data), and rename framework defaults (PHPSESSID, JSESSIONID) to a generic name like `id`.
+- **Session lifecycle.** Regenerate the session ID on any privilege change, especially at login (prevents session fixation). Enforce both an idle timeout and an absolute timeout, and provide a server-side logout that invalidates the session.
+
+## Best practices
+- Set cookie attributes `Secure`, `HttpOnly`, and `SameSite=Strict` (or `Lax`); for the strongest binding use the `__Host-` cookie name prefix (requires Secure, Path=/, and no Domain).
+- Regenerate the session identifier immediately after successful authentication and after any privilege escalation.
+- Keep authentication responses and timing uniform to avoid username/account enumeration.
+- Prefer MFA for any account with meaningful access, and verify against breached-password lists at registration and password change.
+
+## Common pitfalls
+- Reusing the pre-login session ID after authentication → regenerate it on login to prevent session fixation.
+- Distinct "user not found" vs "wrong password" messages → return one generic failure message and avoid timing oracles.
+- Storing passwords with a fast/general hash (or imposing complexity rules and forced rotation) → use a proper password-hashing algorithm and follow modern length-over-complexity guidance.
+- Omitting `HttpOnly`/`Secure`/`SameSite` on the session cookie → enables XSS theft, plaintext interception, and CSRF.
+
+## Examples
+```http
+Set-Cookie: __Host-id=<64-bit-entropy-value>; Secure; HttpOnly; SameSite=Strict; Path=/
+```
+
+## Further reading
+- Password Storage Cheat Sheet, Forgot Password Cheat Sheet, Multifactor Authentication Cheat Sheet — https://cheatsheetseries.owasp.org/
+- ASVS chapters V6 (Authentication) and V7 (Session Management) — ../owasp-asvs
+
+## Related skills
+- ../owasp-asvs — testable auth/session requirements (V6, V7)
+- ../appsec-fundamentals — C7 Secure Digital Identities
+- ../secrets-management — protecting the credentials and keys behind auth

package/skills/engineering/testing/tdd-and-coverage/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: testing/tdd-and-coverage
+description: Test-driven development's red-green-refactor cycle and how to read code coverage as a guide rather than a goal.
+domain: engineering
+category: engineering
+tags: [tdd, testing, refactoring, coverage, red-green-refactor]
+official_sources:
+  - https://martinfowler.com/bliki/TestDrivenDevelopment.html
+  - https://martinfowler.com/bliki/TestCoverage.html
+verified: 2026-06-16
+---
+
+# TDD and Meaningful Coverage
+
+## Overview
+Test-driven development (TDD) is a workflow where you write a failing test before the production code, make it pass, then refactor — the red-green-refactor cycle. This skill pairs that discipline with a sober view of code coverage: a useful signal for finding untested code, but a poor target to optimize blindly. Read it when adopting TDD on a feature or when a team is being pressured by a coverage number.
+
+## Official sources
+- Bliki — Test Driven Development: https://martinfowler.com/bliki/TestDrivenDevelopment.html
+- Bliki — Test Coverage: https://martinfowler.com/bliki/TestCoverage.html
+
+## Core concepts
+- **Red — green — refactor.** Write a test that fails (red), write the minimum code to pass it (green), then improve the structure of new and old code without changing behavior (refactor). Repeat.
+- **List the cases first.** Fowler describes writing out a list of test cases up front, then picking one and applying red-green-refactor to it before moving to the next.
+- **Self-testing code.** Because functional code only exists to satisfy a passing test, TDD produces a suite that lets you change code with confidence.
+- **Design pressure.** Writing the test first "forces us to think about the interface to the code first," encouraging a clean separation of interface from implementation.
+- **Coverage is a tool, not a target.** Coverage shows which lines/branches ran during tests; high coverage does not prove the tests assert the right things, and a fixed coverage percentage as a quality *gate* tends to be counterproductive (Fowler).
+
+## Best practices
+- Never skip the refactor step — Fowler calls neglecting it "the most common way... to screw up TDD," leaving a messy aggregation of code fragments.
+- Keep each cycle small: one test, the simplest passing change, then clean up.
+- Use coverage to *find* untested behavior and obvious gaps, not to chase 100%; review the uncovered lines, do not just read the number.
+- Write tests that assert meaningful behavior and outcomes, so coverage reflects real verification rather than mere execution.
+
+## Common pitfalls
+- Treating a coverage percentage as the goal → use it diagnostically; high coverage with weak assertions is false comfort.
+- Writing tests after the fact and calling it TDD → the value comes from test-first design pressure and the red step proving the test can fail.
+- Dropping the refactor step once tests pass → schedule the cleanup as part of the same cycle, not "later."
+
+## Examples
+```ts
+// 1. RED — write the failing test first
+import { expect, test } from 'vitest'
+import { slugify } from './slugify'
+test('lowercases and hyphenates', () => {
+  expect(slugify('Hello World')).toBe('hello-world')
+})
+
+// 2. GREEN — minimal implementation to pass
+export const slugify = (s: string) =>
+  s.toLowerCase().replace(/\s+/g, '-')
+
+// 3. REFACTOR — improve structure/edge handling, keep tests green
+```
+
+## Further reading
+- Test Coverage (Fowler): https://martinfowler.com/bliki/TestCoverage.html
+- Self-Testing Code (Fowler): https://martinfowler.com/bliki/SelfTestingCode.html
+
+## Related skills
+- ../testing-strategy-pyramid — where TDD's unit tests sit in the portfolio
+- ../unit-integration-e2e — the runners (Vitest) used to execute the cycle

package/skills/engineering/testing/testing-strategy-pyramid/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: testing/testing-strategy-pyramid
+description: How to balance a test portfolio across unit, integration, and end-to-end layers using the test pyramid (and the testing-trophy alternative).
+domain: engineering
+category: engineering
+tags: [testing, test-pyramid, strategy, e2e, unit-tests, integration]
+official_sources:
+  - https://martinfowler.com/bliki/TestPyramid.html
+  - https://martinfowler.com/articles/practical-test-pyramid.html
+verified: 2026-06-16
+---
+
+# Testing Strategy: The Test Pyramid
+
+## Overview
+The test pyramid is a heuristic for shaping an automated test portfolio so that most checks are cheap, fast, low-level tests and only a few are slow, broad, end-to-end tests. Read this when deciding how many tests to write at each layer, or when an existing suite is slow and brittle (a sign of an inverted "ice-cream cone"). It frames the cost/speed/confidence tradeoffs that the sibling tooling and TDD skills then implement.
+
+## Official sources
+- Bliki — Test Pyramid: https://martinfowler.com/bliki/TestPyramid.html
+- Article — The Practical Test Pyramid (Ham Vocke): https://martinfowler.com/articles/practical-test-pyramid.html
+
+## Core concepts
+- **Three layers.** A broad base of many fast **unit tests**, a middle band of **service / integration tests** that exercise components through APIs (subcutaneously, bypassing the UI), and a thin top of **UI / end-to-end tests**.
+- **Cost and speed rise with the layer.** Per Fowler, tests that run end-to-end through the UI are "brittle, expensive to write, and time consuming to run," so higher layers should hold fewer tests.
+- **Granularity drives the count.** The higher a test sits, the more integration it covers per test, so fewer are needed to cover the same ground; lower-level tests isolate behavior and pinpoint failures.
+- **The pyramid is a heuristic, not a law.** Exact layer names and counts matter less than the principle: push tests down to the cheapest level that still gives the confidence you need.
+- **The ice-cream cone anti-shape.** A suite dominated by UI automation with few unit tests inverts the pyramid and becomes slow and fragile.
+- **Testing trophy (community alternative).** A widely discussed alternative weights integration tests more heavily than a strict pyramid; treat it as a perspective, not an official Fowler model (see Further reading).
+
+## Best practices
+- Write the bulk of automated tests at the unit level and use end-to-end tests as a "second line of test defense" (Fowler).
+- When a higher-level test catches a bug, reproduce it with a lower-level unit test before fixing, so the regression is guarded cheaply and locally.
+- Keep end-to-end tests focused on a few critical user journeys rather than re-checking logic already covered by unit tests.
+- Push assertions to the lowest layer that can make them; reserve UI tests for things only the UI can verify.
+
+## Common pitfalls
+- Inverting the pyramid (ice-cream cone): over-investing in UI/e2e tests → rebalance toward fast unit and service tests.
+- Treating layer labels as rigid rules → focus on the cost/speed/confidence tradeoff the shape represents, not the vocabulary.
+- Duplicating the same business logic across every layer → cover logic once at the cheapest layer, integrate (not re-test) above it.
+
+## Examples
+```text
+        /\        few   UI / end-to-end tests   (slow, broad, brittle)
+       /  \
+      /----\      some  service / integration tests
+     /      \
+    /--------\    many  unit tests              (fast, isolated, cheap)
+```
+
+## Further reading
+- The Practical Test Pyramid: https://martinfowler.com/articles/practical-test-pyramid.html
+- Testing Trophy (community, Kent C. Dodds): https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications
+
+## Related skills
+- ../unit-integration-e2e — the tooling that implements each layer
+- ../tdd-and-coverage — writing the low-level tests first and measuring meaningful coverage

package/skills/engineering/testing/unit-integration-e2e/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: testing/unit-integration-e2e
+description: The three test layers and the tooling that implements them — Vitest for unit/integration and Playwright for end-to-end browser tests.
+domain: engineering
+category: engineering
+tags: [testing, vitest, playwright, e2e, integration, unit-tests]
+official_sources:
+  - https://vitest.dev/guide/
+  - https://playwright.dev/docs/intro
+verified: 2026-06-16
+---
+
+# Unit, Integration, and End-to-End Tests
+
+## Overview
+This skill maps the three test layers to concrete tooling: **unit** and **integration** tests with Vitest (a Vite-native test runner) and **end-to-end** browser tests with Playwright. Read it when setting up a test suite in a Vite/TypeScript stack and deciding which framework runs which layer. The strategy for how many tests live at each layer is covered by the sibling test-pyramid skill.
+
+## Official sources
+- Docs: Vitest — https://vitest.dev/guide/ ; Playwright — https://playwright.dev/docs/intro
+- Repo: https://github.com/vitest-dev/vitest ; https://github.com/microsoft/playwright
+- Install: https://vitest.dev/guide/ ; https://playwright.dev/docs/intro
+
+## Install / setup
+```bash
+# Unit & integration tests (Vitest)
+npm install -D vitest
+
+# End-to-end browser tests (Playwright) — scaffolds config, tests/, browsers
+npm init playwright@latest
+```
+
+## Core concepts
+- **Unit tests** isolate a single function/module, run in milliseconds, and pinpoint failures. In Vitest they live in `*.test.ts` / `*.spec.ts` files and use the `expect` matcher API.
+- **Integration tests** exercise several units together (e.g. a service plus its DB or HTTP layer). Vitest runs these through the same runner; choose an environment such as `node` or `jsdom`/`happy-dom` for DOM-dependent code.
+- **End-to-end (e2e) tests** drive a real browser through real user journeys. Playwright is "an end-to-end test framework for modern web apps" that runs across Chromium, Firefox, and WebKit.
+- **Vitest is Vite-native:** it reads your `vite.config.*` by default, so existing Vite plugins and aliases work in tests out of the box (requires Vite >=6 and Node >=20).
+- **Playwright runs cross-browser in parallel,** headless by default, with a headed mode and an interactive UI Mode for debugging, plus an HTML reporter.
+- **Auto-waiting:** Playwright waits for elements to be actionable before acting, reducing flaky timing-based failures common in older e2e tools.
+
+## Best practices
+- Run unit/integration tests with Vitest in watch mode during development (`vitest`) and once in CI (`vitest run`).
+- Keep e2e tests few and focused on critical paths; they are the slow, broad top of the pyramid.
+- Prefer Playwright's web-first locators and auto-waiting assertions over manual sleeps to avoid flaky tests.
+- Run Playwright across the browsers your users actually use; it is supported on Windows, Linux, and macOS, locally or in CI.
+
+## Common pitfalls
+- Using Playwright (or any e2e tool) for logic that a Vitest unit test could check → push the assertion down to the cheapest layer.
+- Mixing the `@vitest/browser` Playwright provider with a separate `@playwright/test` install in one project can conflict → pick one driver per project (per upstream issues).
+- Forgetting to select a DOM environment in Vitest for component/DOM tests → set `environment: 'jsdom'` (or `happy-dom`) so `document` exists.
+
+## Examples
+```ts
+// Vitest unit test — sum.test.ts
+import { expect, test } from 'vitest'
+import { sum } from './sum'
+test('adds numbers', () => {
+  expect(sum(2, 3)).toBe(5)
+})
+```
+```ts
+// Playwright e2e test — example.spec.ts
+import { test, expect } from '@playwright/test'
+test('homepage has title', async ({ page }) => {
+  await page.goto('https://example.com')
+  await expect(page).toHaveTitle(/Example/)
+})
+```
+
+## Further reading
+- Vitest config reference: https://vitest.dev/config/
+- Playwright writing tests: https://playwright.dev/docs/writing-tests
+
+## Related skills
+- ../testing-strategy-pyramid — how many tests to write per layer
+- ../tdd-and-coverage — red-green-refactor and measuring coverage