constellai 0.3.0

package/skills/engineering/performance/database-query-optimization/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: database-query-optimization
+description: Speed up SQL with proper indexing and EXPLAIN — read query plans, understand B-tree index lookups, and fix slow access paths.
+domain: engineering
+category: performance
+tags: [sql, indexing, explain, query-plan, postgresql, b-tree, optimization]
+official_sources:
+  - https://use-the-index-luke.com/
+  - https://www.postgresql.org/docs/current/using-explain.html
+verified: 2026-06-16
+---
+
+# Database Query Optimization
+
+## Overview
+Most SQL performance problems are access-path problems: the right index turns a full scan into a targeted lookup, and `EXPLAIN` reveals which path the planner actually chose. Read this when a query is slow, when adding indexes, or when you need to interpret a query plan rather than guess. Material is grounded in Markus Winand's "Use The Index, Luke" and the official PostgreSQL documentation.
+
+## Official sources
+- SQL indexing guide: https://use-the-index-luke.com/
+- Why indexes can be slow: https://use-the-index-luke.com/sql/anatomy/slow-indexes
+- PostgreSQL Using EXPLAIN: https://www.postgresql.org/docs/current/using-explain.html
+- PostgreSQL source (mirror): https://github.com/postgres/postgres
+
+## Core concepts
+- **A B-tree index has structure.** An index is a balanced tree whose leaf nodes form a doubly linked list of sorted entries; a lookup does a tree traversal to the right leaf, then optionally follows the leaf chain.
+- **An index lookup has three steps.** Per use-the-index-luke: tree traversal, following the leaf node chain, and accessing the table rows. The third step (one table access per matching row) is usually what makes an "indexed" query still slow.
+- **Scan types map to those steps.** `INDEX UNIQUE SCAN` is tree traversal only; `INDEX RANGE SCAN` traverses and walks the leaf chain; `TABLE ACCESS BY INDEX ROWID` fetches the actual rows.
+- **EXPLAIN shows the plan; ANALYZE runs it.** `EXPLAIN` prints the planner's chosen tree of nodes with estimated cost, rows, and width; `EXPLAIN ANALYZE` executes the query and reports actual time, row counts, and (with `BUFFERS`) buffer usage.
+- **Cost estimates drive plan choice.** PostgreSQL estimates each node's cost from table statistics; bad statistics lead to bad plans (e.g. choosing a seq scan over an index, or vice versa).
+- **Selectivity decides whether an index helps.** Indexes win when they select a small fraction of rows; for low-selectivity predicates a sequential scan can legitimately be faster than many scattered table accesses.
+
+## Best practices
+- **Index for the WHERE clause and join columns.** Create indexes that cover the predicates that filter rows; column order in a composite index matters because the tree is sorted left-to-right.
+- **Read the actual plan, not your assumptions.** Use `EXPLAIN (ANALYZE, BUFFERS)` to compare estimated vs actual rows; a large gap signals stale statistics or a misjudged predicate.
+- **Keep statistics fresh.** Ensure `ANALYZE`/autovacuum keeps planner statistics current so cost estimates stay accurate.
+- **Prefer covering / index-only access for hot queries.** Include the selected columns in the index so the table-access step (the expensive third step) can be skipped where supported.
+- **Avoid functions/wrapping on indexed columns in predicates.** Applying a function to a column (or an implicit cast) prevents the plain index from being used; index the expression instead if needed.
+
+## Common pitfalls
+- **"It has an index, so it's fast"** → an `INDEX RANGE SCAN` over many matches plus one table access per row can be slower than a scan; check selectivity and the plan.
+- **Trusting estimated rows** → estimates can be wrong; `EXPLAIN ANALYZE` shows the real row counts and timing to confirm.
+- **Wrong composite index column order** → a leading column that isn't in the predicate makes the index unusable for that filter; order columns by how they are queried.
+- **Wrapping indexed columns in functions** → `WHERE lower(email) = ...` skips a plain index on `email`; create a matching expression index or store normalized values.
+
+## Examples
+```sql
+-- Inspect the real plan, not just the estimate
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, status
+FROM orders
+WHERE customer_id = 42 AND status = 'open';
+
+-- Composite index ordered to match the predicate (equality columns first)
+CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);
+```
+
+## Further reading
+- https://use-the-index-luke.com/sql/anatomy/slow-indexes — the three steps of a lookup in detail
+- https://www.postgresql.org/docs/current/using-explain.html — full EXPLAIN/ANALYZE reference
+- ./reference.md — join strategies and planner internals (loaded only when needed)
+
+## Related skills
+- ../backend-performance — eliminating N+1 access patterns that no index can fix
+- ../profiling-and-benchmarking — measuring query latency before and after indexing

package/skills/engineering/performance/profiling-and-benchmarking/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: profiling-and-benchmarking
+description: Measure before optimizing — use CPU/memory profilers and benchmarks to find real bottlenecks instead of guessing; covers Node.js and Chrome DevTools.
+domain: engineering
+category: performance
+tags: [profiling, benchmarking, cpu-profile, flame-graph, nodejs, devtools, memory-leak]
+official_sources:
+  - https://nodejs.org/en/learn/getting-started/profiling
+  - https://developer.chrome.com/docs/devtools/performance
+verified: 2026-06-16
+---
+
+# Profiling and Benchmarking
+
+## Overview
+The first rule of optimization is to measure: profilers tell you where time and memory actually go, and benchmarks confirm whether a change helped. This skill covers sampling profilers, flame graphs, and runtime/memory analysis using the built-in Node.js profiler and the Chrome DevTools Performance panel. Read it before optimizing anything, so effort lands on the real bottleneck.
+
+## Official sources
+- Node.js profiling guide: https://nodejs.org/en/learn/getting-started/profiling
+- Chrome DevTools Performance panel: https://developer.chrome.com/docs/devtools/performance
+- Chrome DevTools memory problems: https://developer.chrome.com/docs/devtools/memory-problems
+- Node.js source (repo): https://github.com/nodejs/node
+
+## Core concepts
+- **Sampling profilers.** Node's `--prof` uses V8's built-in profiler to sample the call stack at intervals and record events as "ticks" in an `isolate-*.log`, processed with `--prof-process` into a human-readable summary.
+- **Bottom-up vs summary views.** The processed tick output groups time by Summary, C++, and a bottom-up profile, letting you trace which functions and their callers dominate CPU time.
+- **Flame graphs.** The DevTools Performance panel visualizes main-thread activity as a flame chart so you can spot wide (expensive) frames and long tasks.
+- **Runtime vs load performance.** Per Chrome, runtime performance is how a page behaves while running (Response, Animation, Idle phases of the RAIL model), distinct from initial load.
+- **Memory problem classes.** DevTools distinguishes memory leaks (steadily growing usage), memory bloat (using more than needed), and frequent garbage collection that pauses script execution.
+- **Benchmark vs profile.** A benchmark measures aggregate throughput/latency of a change; a profile attributes cost within a run. Use benchmarks to decide *whether* something is faster and profiles to learn *why*.
+
+## Best practices
+- **Measure before and after, with a baseline.** Establish a repeatable benchmark first; otherwise you cannot tell whether an optimization helped or hurt.
+- **Profile under production-like conditions.** Run Node profiling with `NODE_ENV=production` and realistic load, as the official guide demonstrates, so JIT and code paths match production.
+- **Find the dominant cost, then optimize that.** The Node guide's example showed synchronous `pbkdf2` consuming ~51.8% of CPU; switching to the async version raised throughput from 5.33 to 19.46 req/s — fix the biggest frame first.
+- **Use heap snapshots and the allocation timeline for leaks.** In DevTools, compare snapshots over time and watch for detached DOM nodes and steadily growing retained size.
+- **Keep benchmarks isolated and warmed up.** Exclude setup, warm the JIT, and run enough iterations to get stable numbers before comparing.
+
+## Common pitfalls
+- **Optimizing by intuition** → developers routinely guess the wrong hotspot; always confirm with a profile before changing code.
+- **Profiling a dev build or trivial workload** → results won't reflect production; profile production builds under representative load.
+- **Reporting a single run as a benchmark** → variance and JIT warmup distort one-shot numbers; run multiple warmed iterations and compare distributions.
+- **Confusing high GC frequency with a leak** → frequent GC may indicate excessive short-lived allocation (bloat), not retained memory; distinguish with the allocation timeline.
+
+## Examples
+```bash
+# Node.js: capture a CPU profile, then turn it into a readable report
+NODE_ENV=production node --prof app.js
+# ...generate load against the app, then stop it
+node --prof-process isolate-0xnnnnnnnnnnnn-v8.log > processed.txt
+```
+
+## Further reading
+- https://developer.chrome.com/docs/devtools/memory-problems — diagnosing leaks, bloat, and GC churn
+- https://nodejs.org/en/learn/getting-started/profiling — full Node.js profiling walkthrough
+- ./reference.md — flame-graph reading and benchmark harness tips (loaded only when needed)
+
+## Related skills
+- ../backend-performance — what to do once a bottleneck is found server-side
+- ../web-performance-core-vitals — field metrics that tell you what to profile on the front end

package/skills/engineering/performance/web-performance-core-vitals/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: web-performance-core-vitals
+description: Measure and optimize Core Web Vitals (LCP, INP, CLS) for real-user front-end performance; consult when tuning page load and interactivity.
+domain: engineering
+category: performance
+tags: [web-vitals, lcp, inp, cls, frontend, rum, performance]
+official_sources:
+  - https://web.dev/articles/vitals
+  - https://github.com/GoogleChrome/web-vitals
+verified: 2026-06-16
+---
+
+# Web Performance: Core Web Vitals
+
+## Overview
+Core Web Vitals are the subset of Web Vitals that Google considers essential signals of real-user experience: loading (LCP), interactivity (INP), and visual stability (CLS). Read this when you need to measure page performance against objective field thresholds and prioritize fixes that affect actual users rather than synthetic lab scores alone.
+
+## Official sources
+- Docs: https://web.dev/articles/vitals
+- Optimize LCP guide: https://web.dev/articles/optimize-lcp
+- MDN performance hub: https://developer.mozilla.org/en-US/docs/Web/Performance
+- Repo (measurement library): https://github.com/GoogleChrome/web-vitals
+- Install / download: https://www.npmjs.com/package/web-vitals
+
+## Install / setup
+```bash
+npm install web-vitals
+```
+
+## Core concepts
+- **The three Core Web Vitals.** LCP (Largest Contentful Paint) measures loading, INP (Interaction to Next Paint) measures interactivity, and CLS (Cumulative Layout Shift) measures visual stability.
+- **"Good" thresholds at the 75th percentile.** Per web.dev: LCP within 2.5 s, INP of 200 ms or less, CLS of 0.1 or less — assessed at the 75th percentile of page loads, split across mobile and desktop.
+- **Field (RUM) vs lab data.** Core Web Vitals are defined against real-user (field) data such as the Chrome User Experience Report; lab tools like Lighthouse approximate but cannot replace field measurement.
+- **LCP load breakdown.** web.dev decomposes LCP into time to first byte, resource load delay, resource load duration, and element render delay — optimizing LCP is largely about loading the LCP resource sooner and faster.
+- **Layout shift scoring.** CLS sums layout shift scores (impact fraction x distance fraction) from unexpected shifts; shifts within 500 ms of user input are excluded.
+- **Performance APIs.** Browsers expose timing via the Navigation Timing, Resource Timing, and Long Animation Frame APIs (see MDN), which the web-vitals library reads through `PerformanceObserver`.
+
+## Best practices
+- **Measure with the official library on real users.** Use `web-vitals` (`onLCP`, `onINP`, `onCLS`) with its `buffered` PerformanceObserver flag so metrics match Chrome's own reporting; send results to your analytics endpoint.
+- **Make the LCP resource discoverable early.** Per the optimize-LCP guide, include it in the initial HTML, set appropriate `fetchpriority`, and avoid loading it via JavaScript that delays discovery.
+- **Reserve space to prevent CLS.** Set explicit `width`/`height` (or `aspect-ratio`) on images and media, and avoid inserting content above existing content after load.
+- **Reduce main-thread work for INP.** Break up long tasks and minimize JavaScript executed during interactions so the next paint after an input happens within 200 ms.
+- **Cut TTFB.** Minimize redirects and serve cacheable HTML from CDN edge servers, since TTFB is the floor for LCP.
+
+## Common pitfalls
+- **Optimizing only lab scores** → Lighthouse is a lab approximation; ship against field/CrUX data because that is what Core Web Vitals are measured on.
+- **Treating averages as the target** → thresholds are evaluated at the 75th percentile across devices; a good average can still fail at p75 on slow mobile.
+- **Lazy-loading the LCP image** → deferring the largest above-the-fold element delays its load and inflates LCP; eager-load it instead.
+- **Ignoring INP because FID looked fine** → INP replaced FID as a Core Web Vital and considers all interactions across the page lifecycle, not just the first input.
+
+## Examples
+```js
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+function send(metric) {
+  // metric: { name, value, rating, delta, id }
+  navigator.sendBeacon('/analytics', JSON.stringify(metric));
+}
+
+onLCP(send);
+onINP(send);
+onCLS(send);
+```
+
+## Further reading
+- https://web.dev/articles/optimize-lcp — optimizing LCP step by step
+- https://web.dev/articles/cls — understanding and reducing layout shift
+- https://developer.mozilla.org/en-US/docs/Web/Performance — MDN performance guides and APIs
+
+## Related skills
+- ../profiling-and-benchmarking — measuring before optimizing, browser profilers
+- ../backend-performance — server-side TTFB and load handling that feeds LCP

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

@@ -0,0 +1,61 @@
+---
+name: clean-code
+description: Writing readable, consistent code — naming, small focused functions, cohesion, and following a project style guide.
+domain: engineering
+category: practices
+tags: [clean-code, readability, naming, style-guide, functions]
+official_sources:
+  - https://google.github.io/styleguide/
+  - https://github.com/google/styleguide
+verified: 2026-06-16
+---
+
+# Clean Code
+
+## Overview
+Clean code is code optimized for the human reader, not just the compiler: clear names, small focused units, and a consistent style so a large codebase stays understandable as it grows. Consult this when naming things, splitting up large functions, or deciding which conventions to adopt for a project. The Google Style Guides are a concrete, widely-used reference for the "consistency" half of the problem.
+
+## Official sources
+- Docs: https://google.github.io/styleguide/
+- Repo: https://github.com/google/styleguide
+
+## Core concepts
+- **Consistency beats personal preference.** As the Google Style Guides note, a large codebase is much easier to understand when all its code follows a single consistent style; the guide itself is "sometimes arbitrary" by design, because agreeing on *a* convention matters more than the convention.
+- **A style guide is a set of conventions.** Each major project defines its own rules for formatting, naming, and structure (Google publishes per-language guides for C++, Java, Python, JavaScript, Go, and more).
+- **Readable names.** Names should reveal intent so the reader does not have to trace the implementation to understand what a variable, function, or class is for.
+- **Small, focused functions.** A function that does one thing at one level of abstraction is easier to name, test, and reuse than a long multi-purpose block.
+- **Cohesion.** Group code that changes together; a class or module should have a single, clear responsibility rather than a grab-bag of unrelated behavior.
+
+## Best practices
+- **Adopt and enforce a style guide.** Pick an existing published guide (e.g. Google's per-language guide) rather than inventing one, and enforce it with a formatter/linter so style stops being a review topic.
+- **Name for intent, not implementation.** Prefer descriptive names that a reviewer can understand without context (one of Google's stated code-review checks is whether names clearly communicate intent — see code-review-practices).
+- **Keep functions short and single-purpose.** Extract sub-steps into well-named helpers so each function reads top-to-bottom at one level of abstraction.
+- **Comment the "why", not the "what".** Use comments to explain rationale and non-obvious decisions; let clear names and structure express the "what".
+
+## Common pitfalls
+- **Bikeshedding over formatting in reviews** → automate formatting with a tool so humans review behavior and design, not whitespace.
+- **One giant function / "god" class** → split by responsibility into smaller cohesive units; low cohesion makes change risky and testing hard.
+- **Cryptic or misleading names** (`tmp`, `data2`, names that lie about behavior) → rename to reflect actual intent; a rename is a cheap, safe refactoring (see refactoring).
+
+## Examples
+```python
+# Unclear: what is processed, and what comes back?
+def proc(d):
+    r = []
+    for x in d:
+        if x[1] > 0:
+            r.append(x[0])
+    return r
+
+# Clean: intent-revealing names, one job
+def names_of_in_stock_products(products):
+    return [name for name, quantity in products if quantity > 0]
+```
+
+## Further reading
+- Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html
+- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html
+
+## Related skills
+- ../refactoring — how to safely improve unclean code
+- ../code-review-practices — what reviewers check for, including naming and clarity

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