constella 0.1.0

package/skills/engineering/practices/code-optimization/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: code-optimization
+description: Making code faster the right way — measure first, fix algorithms before micro-optimizing, and validate with benchmarks.
+domain: engineering
+category: practices
+tags: [performance, optimization, profiling, benchmarking, algorithms]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/Performance
+  - https://en.algorithmica.org/hpc/
+verified: 2026-06-16
+---
+
+# Code Optimization
+
+## Overview
+Code optimization is making software faster or lighter without breaking correctness — but only where measurement shows it matters. Consult this when something is genuinely slow, before reaching for a rewrite. MDN's Web Performance pages cover measuring and budgeting on the web; Algorithmica's "Algorithms for Modern Hardware" covers profiling, benchmarking, and low-level optimization on modern CPUs.
+
+## Official sources
+- Docs (web performance): https://developer.mozilla.org/en-US/docs/Web/Performance
+- Docs (high-performance computing): https://en.algorithmica.org/hpc/
+- Repo (Algorithmica): https://github.com/algorithmica-org/algorithmica
+
+## Core concepts
+- **Measure first.** Before optimizing, establish a baseline with real tools and metrics; MDN's overarching guidance is to measure your actual performance before changing anything.
+- **Profiling vs. benchmarking.** Profiling finds *where* time goes (instrumentation, statistical sampling, machine-code analysis — covered in Algorithmica's profiling chapter); benchmarking measures *whether* a specific change actually helped.
+- **Algorithms still dominate, but not alone.** Asymptotic complexity (Big-O) is the first lever, yet Algorithmica stresses that on modern hardware it is no longer the sole deciding factor — constant factors and hardware behavior matter.
+- **The memory hierarchy / cache.** Access patterns and CPU caching often determine real speed; cache-friendly layouts can beat algorithmically "equal" code (Algorithmica devotes a section to caching and memory).
+- **Performance budgets.** MDN recommends setting budgets — explicit limits on metrics like load time or bundle size — to prevent regressions over time.
+- **Measure user-perceived performance.** MDN notes that what matters is how users perceive performance (RUM, perceived metrics), not just raw milliseconds.
+
+## Best practices
+- **Profile to find the real bottleneck, then optimize that.** Optimize the hot path the profiler identifies rather than guessing; most code is not on the critical path.
+- **Improve the algorithm/data structure before micro-optimizing.** A better Big-O usually beats hand-tuning a poor algorithm; reach for SIMD/cache tricks only after the algorithm is right.
+- **Benchmark every change.** Confirm each optimization is a real, repeatable speedup (and didn't regress correctness) before keeping it.
+- **Set and enforce a performance budget.** Use budgets in CI/monitoring so performance gains don't silently erode (MDN performance budgets).
+
+## Common pitfalls
+- **Optimizing without measuring** → profile first; intuition about the bottleneck is frequently wrong, and effort lands off the hot path.
+- **Micro-optimizing a bad algorithm** → fix the algorithm/data structure first; constant-factor tweaks can't fix a quadratic loop.
+- **Trusting a one-shot timing** → benchmark with repetition and a stable setup; noise and warm-up effects make single runs misleading.
+- **Sacrificing correctness/readability for speed off the hot path** → only trade clarity for performance where measurement proves it matters.
+
+## Examples
+```javascript
+// O(n^2): membership check inside a loop
+const dupes = a.filter(x => b.includes(x));   // includes scans b each time
+
+// O(n): hoist the lookups into a Set — algorithmic win, then measure
+const bSet = new Set(b);
+const dupes2 = a.filter(x => bSet.has(x));
+// Verify with a benchmark before assuming it's faster for your input sizes.
+```
+
+## Further reading
+- MDN — Measuring performance: https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Performance/Measuring_performance
+- Algorithmica — Profiling: https://en.algorithmica.org/hpc/profiling/
+
+## Related skills
+- ../clean-code — keep optimized code readable; document non-obvious perf tradeoffs
+- ../refactoring — restructure safely under test before/after optimizing

package/skills/engineering/practices/code-review-practices/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: code-review-practices
+description: How to review and author code changes — what reviewers look for, review speed, and writing useful, kind review comments.
+domain: engineering
+category: practices
+tags: [code-review, pull-request, review-checklist, collaboration]
+official_sources:
+  - https://google.github.io/eng-practices/review/
+  - https://github.com/google/eng-practices
+verified: 2026-06-16
+---
+
+# Code Review Practices
+
+## Overview
+Code review is the process where someone other than the change's author examines the code before it lands, primarily to keep the codebase healthy over time. Consult this when reviewing a pull/change request or preparing your own change for review. Google's Engineering Practices documentation is a well-known, freely published reference for both reviewers and change authors.
+
+## Official sources
+- Docs: https://google.github.io/eng-practices/review/
+- Repo: https://github.com/google/eng-practices
+
+## Core concepts
+- **Purpose of review.** Review exists to maintain the overall health of the codebase over time, not to demand perfection in every change.
+- **What reviewers look at.** Google's guide enumerates areas to examine: design, functionality (does it do what the author intended), complexity/simplicity, tests, naming, comments, style-guide compliance, and documentation updates.
+- **The reviewer/author split.** Google publishes two complementary guides — one for the *reviewer* (how to review) and one for the *change author* (how to get a change reviewed smoothly).
+- **Speed matters.** Reviews should be fast: slow reviews block authors, delay feedback, and degrade team velocity, so reviewers are expected to respond promptly even if a full review takes longer.
+- **Alternatives exist.** Pair programming and in-person review are valid substitutes for asynchronous review in some situations.
+
+## Best practices
+- **Review for design first, nits last.** Confirm the change is well-designed and does the right thing before quibbling over minor style (which a linter should catch anyway).
+- **Be prompt.** Respond to review requests quickly to keep authors unblocked, even when the change is large enough to need follow-up.
+- **Write kind, actionable comments.** Explain the reasoning behind a request, and clearly distinguish must-fix issues from optional suggestions (e.g. prefix non-blocking nits).
+- **Approve once it improves overall code health.** A change does not have to be perfect to be approved — only a net improvement to the codebase that is appropriately tested.
+
+## Common pitfalls
+- **Demanding perfection / endless rounds** → approve once the change improves code health; capture larger ideas as follow-up rather than blocking.
+- **Letting reviews sit for days** → prioritize prompt responses; slow reviews are a primary cause of team frustration and slowdown.
+- **Vague comments ("this is wrong")** → state the problem, why it matters, and a concrete suggested fix; mark optional items as optional.
+
+## Examples
+```text
+Review comment styles (author-friendly):
+
+  Blocking:   This query runs inside the loop, so it's O(n) round-trips.
+              Move it out of the loop or batch the IDs.
+
+  Optional:   Nit (non-blocking): `getUserData` could be `fetchUser` to
+              match the naming used elsewhere in this file.
+```
+
+## Further reading
+- The Standard of Code Review: https://google.github.io/eng-practices/review/reviewer/standard.html
+- How to write code review comments: https://google.github.io/eng-practices/review/reviewer/comments.html
+- The CL author's guide: https://google.github.io/eng-practices/review/developer/
+
+## Related skills
+- ../clean-code — many review checks (naming, cohesion) are clean-code concerns
+- ../git-workflow — PRs and commit hygiene that make changes reviewable

package/skills/engineering/practices/git-workflow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: git-workflow
+description: Day-to-day Git collaboration — branching, focused commits, pull requests, and Conventional Commits message format.
+domain: engineering
+category: practices
+tags: [git, version-control, branching, commits, conventional-commits, pull-request]
+official_sources:
+  - https://git-scm.com/docs
+  - https://www.conventionalcommits.org/en/v1.0.0/
+verified: 2026-06-16
+---
+
+# Git Workflow
+
+## Overview
+A Git workflow is the set of conventions a team uses for branching, committing, and integrating changes so history stays readable and changes stay reviewable. Consult this when deciding how to branch, how to structure commits, or how to format commit messages. Git's own reference manual defines the commands; the Conventional Commits spec defines a popular structured message format.
+
+## Official sources
+- Docs (Git reference manual): https://git-scm.com/docs
+- Pro Git book: https://git-scm.com/book
+- Conventional Commits spec: https://www.conventionalcommits.org/en/v1.0.0/
+
+## Core concepts
+- **Branches isolate work.** `git branch` / `git switch` create lightweight lines of development; do feature work on a branch and integrate via `git merge` or `git rebase` (both documented in the Git reference).
+- **Commits are the unit of history.** `git add` stages changes and `git commit` records them; a good commit captures one logical change with a message explaining what and why.
+- **Sharing.** `git push` publishes commits to a remote and `git pull` fetches and integrates remote changes; pull requests wrap a branch for review before integration.
+- **Conventional Commits structure.** The spec defines `<type>[optional scope]: <description>`, then an optional body and optional footer(s).
+- **Types & semver mapping.** `feat` (a new feature → MINOR) and `fix` (a bug fix → PATCH) are the core types; `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `style` are also recommended.
+- **Breaking changes.** Indicated either by a `!` after the type/scope (`feat!:`) or a `BREAKING CHANGE:` footer; both signal a MAJOR version bump.
+
+## Best practices
+- **Keep commits small and focused.** One logical change per commit makes review, revert, and `git bisect` tractable (separate refactoring from behavior change — see refactoring).
+- **Write meaningful messages.** Use an imperative description; for non-trivial changes, explain *why* in the body. Conventional Commits adds machine-readable type/scope so tools can generate changelogs and version bumps.
+- **Branch per change, integrate via review.** Open a pull request so a reviewer examines the change before it lands (see code-review-practices).
+- **Mark breaking changes explicitly.** Use `!` or a `BREAKING CHANGE:` footer so consumers and release tooling correctly bump the major version.
+
+## Common pitfalls
+- **Vague messages ("fix stuff", "wip")** → write a clear type/description and a body explaining why; future readers and changelog tooling depend on it.
+- **One huge commit mixing many concerns** → split into focused commits so each can be reviewed and reverted independently.
+- **Hiding a breaking change in a `feat` or `fix`** → use `feat!:`/`fix!:` or a `BREAKING CHANGE:` footer so it triggers a MAJOR bump rather than surprising consumers.
+
+## Examples
+```text
+feat(auth): add password reset endpoint
+
+Sends a single-use token by email and expires it after 15 minutes.
+
+Refs: #482
+
+# Breaking change variants:
+feat(api)!: drop deprecated v1 user fields
+# or, via footer:
+BREAKING CHANGE: the `username` field is removed from the user payload
+```
+
+## Further reading
+- Pro Git — Branching: https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
+- Conventional Commits spec (full): https://www.conventionalcommits.org/en/v1.0.0/
+
+## Related skills
+- ../code-review-practices — pull requests and reviewable change hygiene
+- ../refactoring — keeping structure-only commits separate from behavior commits

package/skills/engineering/practices/refactoring/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: refactoring
+description: Improving code's internal structure without changing observable behavior, via small steps verified by tests.
+domain: engineering
+category: practices
+tags: [refactoring, code-smells, tests, technical-debt]
+official_sources:
+  - https://refactoring.com/
+  - https://refactoring.com/catalog/
+verified: 2026-06-16
+---
+
+# Refactoring
+
+## Overview
+Refactoring is changing the internal structure of software to make it easier to understand and cheaper to modify — *without* changing its observable behavior. Consult this when cleaning up code before or after adding a feature, paying down technical debt, or making a change feel hard. Martin Fowler's refactoring.com defines the discipline and catalogs the named refactorings.
+
+## Official sources
+- Docs (definition): https://refactoring.com/
+- Catalog of named refactorings: https://refactoring.com/catalog/
+
+## Core concepts
+- **Definition (behavior-preserving).** Per Fowler, refactoring is "a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior."
+- **A series of small transformations.** The heart of refactoring is many tiny behavior-preserving steps; each does little, but the sequence produces a significant restructuring. Small steps make it less likely to go wrong.
+- **Keep the system working.** The system is kept fully working after each refactoring, which reduces the chance it gets seriously broken mid-change.
+- **Code smells.** Smells are easy-to-spot surface symptoms (e.g. long functions, duplicated code, large classes) that often point to a deeper problem worth refactoring. Fowler's catalog pairs common smells with the refactorings that address them.
+- **Tests as the safety net.** Running tests after each change is what makes refactoring predictable and safe; when automated refactoring tools are unavailable, frequent testing is how mistakes get caught.
+
+## Best practices
+- **Refactor under green tests.** Have a passing test suite first; refactor in small steps and re-run tests after each, so any break is localized to the last change.
+- **Separate refactoring from behavior change.** Do not mix a refactoring commit with a feature/bugfix commit — keep "tidy structure" and "change behavior" as distinct steps (and ideally distinct commits).
+- **Refactor when it makes the next change easier.** Tidy the area you are about to modify ("preparatory refactoring") rather than scheduling a big separate cleanup.
+- **Take small steps.** Prefer many tiny, reversible transformations over one large rewrite; this keeps the system shippable throughout.
+
+## Common pitfalls
+- **Refactoring without tests** → add characterization tests first; without a safety net you cannot tell whether behavior was preserved.
+- **Mixing refactoring with feature work in one big diff** → split into structure-only changes and behavior changes so reviewers (and `git bisect`) can reason about each.
+- **Big-bang rewrite instead of stepwise change** → break it into a sequence of small named refactorings, keeping the build green between each.
+
+## Examples
+```javascript
+// Smell: long function mixing extraction and formatting.
+// Step 1 — Extract Function (behavior preserved), run tests:
+function printOwing(invoice) {
+  printBanner();
+  const outstanding = calculateOutstanding(invoice); // extracted
+  printDetails(invoice, outstanding);                 // extracted
+}
+// Each extraction is a small step; tests stay green throughout.
+```
+
+## Further reading
+- Catalog of refactorings: https://refactoring.com/catalog/
+- Community: refactoring.guru groups smells/techniques into browsable categories (commercial site, not an official source): https://refactoring.guru/refactoring
+
+## Related skills
+- ../clean-code — the target state refactoring moves toward
+- ../code-review-practices — reviewers flag smells; refactoring resolves them

package/skills/engineering/security/appsec-fundamentals/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: appsec-fundamentals
+description: Application security fundamentals — OWASP Proactive Controls, input validation, output encoding, and secure-by-default design; consult when building any feature.
+domain: engineering
+category: security
+tags: [appsec, proactive-controls, input-validation, output-encoding, owasp]
+official_sources:
+  - https://top10proactive.owasp.org/
+  - https://cheatsheetseries.owasp.org/
+verified: 2026-06-16
+---
+
+# Application Security Fundamentals
+
+## Overview
+While the OWASP Top 10 describes what goes wrong, the OWASP Top 10 Proactive Controls describe what to build to prevent it. This skill summarizes the proactive controls and the foundational defenses (input validation, output/context-aware encoding, secure defaults) that every feature should apply by default. Read this at the start of building a feature, not after a vulnerability is found. For deep, topic-specific guidance, follow the linked OWASP Cheat Sheets.
+
+## Official sources
+- Proactive Controls (2024): https://top10proactive.owasp.org/
+- Proactive Controls repo: https://github.com/OWASP/www-project-proactive-controls/
+- Cheat Sheet Series (130+ topic guides): https://cheatsheetseries.owasp.org/
+- Cheat Sheet repo: https://github.com/OWASP/CheatSheetSeries
+- License: Creative Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
+
+## Core concepts
+The OWASP Top 10 Proactive Controls (2024) are the security techniques to include in every project:
+
+- **C1 Implement Access Control** — enforce authorization server-side, deny by default.
+- **C2 Use Cryptography to Protect Data** — protect data at rest and in transit with vetted algorithms and managed keys.
+- **C3 Validate all Input & Handle Exceptions** — treat all input as untrusted; fail safely on errors.
+- **C4 Address Security from the Start** — threat-model and design controls early (secure design).
+- **C5 Secure By Default Configurations** — ship hardened defaults rather than relying on later hardening.
+- **C6 Keep your Components Secure** — track and patch third-party dependencies.
+- **C7 Secure Digital Identities** — robust authentication, session, and credential handling.
+- **C8 Leverage Browser Security Features** — use headers/policies (CSP, cookie attributes) the browser enforces.
+- **C9 Implement Security Logging and Monitoring** — log security events and enable detection.
+- **C10 Stop Server Side Request Forgery** — validate and restrict outbound requests built from user input.
+
+Two cross-cutting defenses underpin several controls:
+- **Input validation** — prefer allow-list (positive) validation of type, length, format, and range; validation is defense-in-depth, not a substitute for safe APIs.
+- **Output / context-aware encoding** — encode untrusted data for the exact sink it lands in (HTML body, HTML attribute, JavaScript, URL, SQL) to neutralize injection.
+
+## Best practices
+- Use parameterized queries and safe APIs to stop injection at the boundary; treat input validation as an additional layer, not the primary defense.
+- Apply output encoding based on the output context, since the correct escaping differs between HTML, attributes, JavaScript, and URLs.
+- Adopt secure-by-default configuration (C5): least privilege, disabled debug endpoints, and minimal exposed surface from day one.
+- Consult the relevant OWASP Cheat Sheet for any non-trivial control rather than improvising (the series is the canonical implementation reference).
+
+## Common pitfalls
+- Relying on input validation alone to prevent injection → combine validation with parameterized queries and context-aware encoding.
+- Using a single "escape" function everywhere → encoding is context-specific; HTML-encoding a value placed into a JavaScript string is still unsafe.
+- Bolting on security after the build (skipping C4) → design controls in from the start; retrofitting access control and crypto is error-prone.
+
+## Examples
+```text
+# Context-aware output encoding (concept):
+HTML body      -> HTML entity encode  ( < becomes &lt; )
+HTML attribute -> attribute encode + quote the attribute
+JavaScript     -> JS string encode / avoid building JS from input
+URL parameter  -> URL/percent encode
+```
+
+## Further reading
+- Input Validation Cheat Sheet, Cross Site Scripting Prevention Cheat Sheet, Injection Prevention Cheat Sheet — https://cheatsheetseries.owasp.org/
+- Proactive Controls detailed pages — https://top10proactive.owasp.org/
+
+## Related skills
+- ../owasp-top-10 — the risks these controls prevent
+- ../owasp-asvs — testable requirements aligned to these controls
+- ../secure-auth-sessions — implementation detail for C7

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