constellai 0.3.0

package/skills/engineering/architecture/software-architecture-patterns/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: software-architecture-patterns
+description: Layered, hexagonal, event-driven, and microservices patterns plus cloud design patterns; read when choosing or structuring application architecture.
+domain: engineering
+category: architecture
+tags: [architecture-patterns, microservices, event-driven, layered, cloud-patterns]
+official_sources:
+  - https://martinfowler.com/architecture/
+  - https://learn.microsoft.com/azure/architecture/patterns/
+verified: 2026-06-16
+---
+
+# Software Architecture Patterns
+
+## Overview
+Architecture patterns are reusable, named solutions to recurring structural problems — how to separate concerns, communicate between components, and contain failure. Each pattern solves one problem and introduces trade-offs, so choose by the problem you face, not the technology you want. Read this when structuring a new service or evaluating a refactor.
+
+## Official sources
+- Martin Fowler's Software Architecture Guide: https://martinfowler.com/architecture/
+- Azure Architecture Center — Cloud Design Patterns catalog: https://learn.microsoft.com/azure/architecture/patterns/
+
+## Core concepts
+- **Layered (Presentation–Domain–Data)**: separate the UI, business logic, and data-access concerns so each can change independently; the dominant default for most applications.
+- **Hexagonal / Ports & Adapters**: isolate the domain core behind explicit ports, with adapters for UI, persistence, and external systems, so infrastructure is swappable and the core is testable.
+- **Event-driven architecture**: components communicate by emitting and reacting to events (often via Publisher-Subscriber), decoupling producers from consumers in time and identity.
+- **Microservices**: develop a single application as a suite of small services, each in its own process, communicating over lightweight mechanisms — independently deployable but distributed.
+- **Cloud design patterns**: technology-agnostic solutions (Circuit Breaker, Retry, Cache-Aside, CQRS, Saga, Bulkhead, Strangler Fig) that address reliability, scale, and integration in distributed systems.
+- **Patterns are composable**: real workloads apply several together (e.g. Retry + Circuit Breaker; Queue-Based Load Leveling + Competing Consumers).
+
+## Best practices
+- Choose a pattern from the problem and acceptable trade-offs, not from the technology — the Azure catalog explicitly advises starting from a constraint or risk in the workload.
+- Default to a well-structured monolith with clear layering; adopt microservices only when team/scale boundaries justify the distributed-systems cost.
+- Pair resilience patterns: combine Retry with Circuit Breaker so transient faults are retried but persistent faults stop hammering a failing dependency.
+- Use the Strangler Fig pattern to migrate legacy systems incrementally instead of a risky big-bang rewrite.
+
+## Common pitfalls
+- Adopting microservices for a small team or early product → you inherit network, consistency, and ops overhead without the scale benefit; keep a modular monolith until boundaries are clear.
+- Believing distributed systems are reliable, low-latency, and infinitely scalable (the fallacies of distributed computing) → design compensations (timeouts, retries, idempotency) for each fallacy.
+- Treating an antipattern as a pattern because it works at low load → re-evaluate designs that degrade as traffic grows.
+
+## Examples
+```text
+Resilient remote call (Azure pattern combo):
+  client -> [Retry with backoff] -> [Circuit Breaker] -> remote service
+  - Retry handles transient faults.
+  - Circuit Breaker opens after repeated failures, failing fast and shedding load.
+```
+
+## Further reading
+- Azure pattern catalog with per-pattern problem/trade-off pages: https://learn.microsoft.com/azure/architecture/patterns/
+- Fowler on microservices: https://martinfowler.com/articles/microservices.html
+
+## Related skills
+- ../message-queues-async — event-driven and async messaging foundations
+- ../scalability-reliability — resilience patterns under load
+- ../api-design-rest-graphql — designing the interfaces between services

package/skills/engineering/architecture/system-design-fundamentals/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: system-design-fundamentals
+description: Latency, throughput, partitioning, replication, CAP and consistency trade-offs for designing large-scale systems; read before sizing or scaling.
+domain: engineering
+category: architecture
+tags: [system-design, scalability, cap-theorem, distributed-systems, trade-offs]
+official_sources:
+  - https://github.com/donnemartin/system-design-primer
+  - https://aws.amazon.com/architecture/well-architected/
+verified: 2026-06-16
+---
+
+# System Design Fundamentals
+
+## Overview
+System design is the practice of reasoning about how a large-scale system meets functional and non-functional requirements (latency, throughput, availability, cost) under failure. Every choice is a trade-off: there is no single "correct" design, only one that is appropriate for the constraints. Read this before sizing a component, choosing a datastore, or proposing a scaling strategy.
+
+## Official sources
+- The System Design Primer (concepts, trade-offs, interview material): https://github.com/donnemartin/system-design-primer
+- AWS Well-Architected Framework (pillars and review methodology): https://aws.amazon.com/architecture/well-architected/
+
+## Core concepts
+- **Latency vs throughput**: latency is the time to perform one action; throughput is the number of actions per unit of time. Aim for maximal throughput within an acceptable latency budget — they are not the same dial.
+- **CAP theorem**: in a distributed system that may experience network partitions you must trade off between consistency and availability; you cannot fully guarantee all three of consistency, availability, and partition tolerance at once.
+- **Partitioning / sharding**: split data across nodes so each holds only a subset, improving capacity and performance, at the cost of cross-shard queries, rebalancing, and possible hotspots/skew.
+- **Replication and availability patterns**: copy data across nodes for read scaling and fault tolerance; fail-over comes in active-passive and active-active flavors, each trading complexity for recovery speed.
+- **Consistency models**: strong, eventual, and causal consistency offer different guarantees; eventual consistency buys availability and scale but requires the application to tolerate stale reads.
+- **Well-Architected pillars**: AWS frames sound design around Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, and Sustainability — use them as a review checklist.
+
+## Best practices
+- Quantify requirements first (expected QPS, data size, read/write ratio, latency SLO) before choosing technology — the numbers drive the design, per the System Design Primer's estimation approach.
+- Make trade-offs explicit and document them; the Well-Architected method is a structured review against the six pillars, not a single answer.
+- Design for failure: assume nodes, networks, and dependencies will fail and add replication, retries, and graceful degradation accordingly.
+- Prefer horizontal scaling and statelessness for the request path so you can add commodity capacity rather than relying on a single large machine.
+
+## Common pitfalls
+- Treating CAP as "pick any two freely" → during a partition you are really choosing between consistency and availability; partition tolerance is mandatory in real distributed systems.
+- Sharding on a key with skewed access → creates hotspots; choose a partition key with even distribution and plan for resharding.
+- Optimizing latency while ignoring throughput (or vice versa) → measure both and set explicit targets.
+
+## Examples
+```text
+Back-of-envelope sizing (per System Design Primer estimation):
+  10M daily active users x 10 requests/day = 100M req/day
+  100M / 86,400 s  ≈ 1,160 req/s average, ~3-5x peak ≈ ~5,000 req/s
+  Plan capacity, caching, and partitions against peak, not average.
+```
+
+## Further reading
+- AWS Well-Architected pillars overview: https://aws.amazon.com/architecture/well-architected/
+- System Design Primer index of topics: https://github.com/donnemartin/system-design-primer#index-of-system-design-topics
+
+## Related skills
+- ../scalability-reliability — SLOs, resilience, and failure handling at scale
+- ../caching-strategies — reduce latency and load with cache layers
+- ../data-modeling — how data shape interacts with partitioning

package/skills/engineering/backend/auth-and-authorization/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: backend/auth-and-authorization
+description: Authentication vs authorization, OAuth 2.0 roles and tokens, and access-control models (RBAC/ABAC) with OWASP enforcement guidance.
+domain: engineering
+category: engineering
+tags: [auth, authentication, authorization, oauth2, rbac, abac, security]
+official_sources:
+  - https://oauth.net/2/
+  - https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+verified: 2026-06-16
+---
+
+# Authentication and Authorization
+
+## Overview
+Authentication (AuthN) verifies *who* a caller is; authorization (AuthZ) decides *what* they are allowed to do. This skill covers that distinction, the OAuth 2.0 authorization framework and its tokens, the RBAC/ABAC access-control models, and OWASP's rules for enforcing authorization safely. Read it when designing login, API access control, or permission checks.
+
+## Official sources
+- OAuth 2.0: https://oauth.net/2/
+- OWASP Authorization Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+- OAuth 2.0 spec (RFC 6749): https://www.rfc-editor.org/rfc/rfc6749
+
+## Core concepts
+- **AuthN vs AuthZ.** Authentication confirms identity; authorization, per OWASP, "verif[ies] that a requested action or service is approved for a specific entity." An authenticated user may still lack authorization for a given resource.
+- **OAuth 2.0 is an authorization framework, not authentication.** It is "the industry-standard protocol for authorization," defining flows for web, mobile, desktop, and device clients (RFC 6749).
+- **OAuth roles.** Resource owner, client, authorization server, and resource server cooperate; the client obtains an **access token** to call the resource server on the owner's behalf.
+- **Tokens.** Access tokens (often Bearer tokens, RFC 6750) authorize API calls; refresh tokens obtain new access tokens. PKCE protects public clients, and OAuth 2.1 is an in-progress consolidation of OAuth 2.0 plus common extensions.
+- **RBAC.** Role-based access control ties permissions to roles assigned to users — simple to start, but can grow unwieldy as roles multiply.
+- **ABAC / ReBAC.** Attribute-based (subject/object/environment attributes + policies) and relationship-based access control support fine-grained, multi-tenant logic that RBAC handles poorly.
+
+## Best practices
+- Enforce authorization **server-side** on every request — never trust client-side checks alone (OWASP).
+- **Deny by default:** grant access only when a rule explicitly permits it, so logic gaps fail closed (OWASP).
+- Apply **least privilege:** give each entity the minimum permissions for its role, and audit periodically to prevent privilege creep (OWASP).
+- Check authorization on the **specific resource**, not just the route, and avoid exposing predictable object identifiers to prevent IDOR-style access (OWASP).
+
+## Common pitfalls
+- Treating authentication as if it grants authorization → always run a separate AuthZ check after identifying the user.
+- Relying on hidden fields or client-side role checks → enforce every decision on the server (OWASP).
+- Using OAuth 2.0 access tokens as proof of identity → use OpenID Connect for authentication; OAuth alone is for authorization.
+- Direct object references without a per-resource access check → verify the caller may act on *that* object (OWASP, IDOR).
+
+## Examples
+```http
+# Calling a protected API with an OAuth 2.0 Bearer access token (RFC 6750)
+GET /api/orders/1001 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+```text
+Deny-by-default authorization check (pseudocode):
+  if not policy.permits(subject, action, resource): return 403
+  proceed
+```
+
+## Further reading
+- OAuth 2.0 Bearer Token Usage (RFC 6750): https://www.rfc-editor.org/rfc/rfc6750
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+
+## Related skills
+- ./backend-fundamentals — the HTTP layer these checks protect
+- ./observability-logging — logging authorization failures for audit

package/skills/engineering/backend/backend-fundamentals/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: backend/backend-fundamentals
+description: Core backend ideas — HTTP request/response, statelessness, layered architecture, and the twelve-factor app methodology for cloud services.
+domain: engineering
+category: engineering
+tags: [backend, http, stateless, twelve-factor, architecture, web]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/HTTP
+  - https://12factor.net/
+verified: 2026-06-16
+---
+
+# Backend Fundamentals
+
+## Overview
+This skill covers the foundations every backend service rests on: how HTTP works as a stateless request/response protocol, why statelessness matters for scaling, how to layer an application, and the twelve-factor methodology for building portable cloud services. Read it before designing an API or deployment, and as a checklist when a service is hard to scale or configure across environments.
+
+## Official sources
+- HTTP (MDN): https://developer.mozilla.org/en-US/docs/Web/HTTP
+- The Twelve-Factor App: https://12factor.net/
+- Repo (twelve-factor): https://github.com/heroku/12factor
+
+## Core concepts
+- **HTTP is a stateless, application-layer protocol.** Per MDN, the server "does not keep any session data between two requests"; state is layered on top via cookies, tokens, or external stores.
+- **Request/response, client-server model.** A client opens a connection, sends a request (method + path + headers + optional body), and waits for a single response.
+- **Methods and status codes carry semantics.** Methods (GET, POST, PUT, PATCH, DELETE, …) express intent; status codes group as 1xx informational, 2xx success, 3xx redirect, 4xx client error, 5xx server error.
+- **Statelessness enables horizontal scale.** Twelve-factor says to "execute the app as one or more stateless processes" so any instance can serve any request and you scale by adding processes.
+- **Config lives in the environment.** Store deploy-specific config (URLs, credentials, flags) in environment variables, not in code, keeping the codebase portable and secrets out of version control.
+- **Layering.** Separate concerns into transport/routing, application/service logic, and data-access layers so each can change and be tested independently.
+- **Twelve factors at a glance.** Codebase, dependencies, config, backing services, build/release/run, processes, port binding, concurrency, disposability, dev/prod parity, logs, admin processes.
+
+## Best practices
+- Keep request handling stateless; persist session/state in a backing service (DB, cache) rather than in process memory (twelve-factor: processes, backing services).
+- Treat backing services (databases, queues, caches) as attached resources swappable via config, with no code change.
+- Build, release, and run as distinct stages so a release is an immutable artifact + config you can roll back.
+- Use the correct HTTP method and status code for each operation so caches, clients, and proxies behave correctly (MDN).
+
+## Common pitfalls
+- Storing session state in process memory → breaks under multiple instances; move it to a shared backing service.
+- Hardcoding environment-specific config or secrets in code → read them from the environment (twelve-factor: config).
+- Returning 200 for errors or overloading GET to mutate data → honor HTTP method and status-code semantics (MDN).
+
+## Examples
+```http
+GET /api/users/42 HTTP/1.1
+Host: api.example.com
+Accept: application/json
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{ "id": 42, "name": "Ada" }
+```
+```bash
+# Twelve-factor: config from the environment, not the code
+export DATABASE_URL="postgres://user:pass@host:5432/app"
+```
+
+## Further reading
+- MDN HTTP overview: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview
+- Twelve-factor — full factor list: https://12factor.net/
+
+## Related skills
+- ./auth-and-authorization — securing the requests these services receive
+- ./observability-logging — the "logs" factor and operating the service in production

package/skills/engineering/backend/observability-logging/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: backend/observability-logging
+description: Observability via the three signals (logs, metrics, traces) with OpenTelemetry, plus SRE practices like SLOs and the four golden signals.
+domain: engineering
+category: engineering
+tags: [observability, logging, metrics, tracing, opentelemetry, sre, slo]
+official_sources:
+  - https://opentelemetry.io/docs/
+  - https://sre.google/books/
+verified: 2026-06-16
+---
+
+# Observability and Logging
+
+## Overview
+Observability is the ability to understand a system's internal state from its outputs. This skill covers the three telemetry signals — logs, metrics, and traces — instrumented in a vendor-neutral way with OpenTelemetry, and the operational practices Google SRE uses to act on that data (SLIs/SLOs, error budgets, the four golden signals). Read it when adding instrumentation, choosing what to log, or defining what "healthy" means for a service.
+
+## Official sources
+- OpenTelemetry docs: https://opentelemetry.io/docs/
+- Repo (OpenTelemetry org): https://github.com/open-telemetry
+- Google SRE books (free online): https://sre.google/books/
+
+## Core concepts
+- **Three signals.** OpenTelemetry standardizes **traces** (the path of a request across services), **metrics** (numeric measurements over time), and **logs** (timestamped records of discrete events).
+- **OpenTelemetry is instrumentation, not a backend.** It is "a vendor-neutral open source Observability framework for instrumenting, generating, collecting, and exporting telemetry data" — it does not store or visualize data; you send it to a backend.
+- **The Collector.** A vendor-agnostic process to receive, process, and export telemetry, decoupling your app from any specific backend.
+- **OTLP and vendor neutrality.** A common wire protocol and broad vendor support (90+ observability vendors) let you switch tools without re-instrumenting, avoiding lock-in.
+- **SLIs and SLOs.** A Service Level Indicator is a measured quality (e.g. request latency); a Service Level Objective is a target for it. Error budgets quantify allowable unreliability against the SLO (Google SRE).
+- **The four golden signals.** Google SRE recommends monitoring **latency, traffic, errors, and saturation** as the primary health signals of a user-facing system.
+
+## Best practices
+- Emit structured logs (e.g. JSON with consistent fields) and correlate them with traces via trace/span IDs so you can pivot between signals.
+- Instrument with OpenTelemetry rather than vendor-specific SDKs so the backend stays swappable.
+- Define SLOs for the user-facing behaviors that matter and alert on SLO burn / the four golden signals, not on every raw metric (Google SRE).
+- Run the OpenTelemetry Collector to centralize processing (batching, attribute scrubbing, routing) instead of exporting directly from every service.
+
+## Common pitfalls
+- Treating OpenTelemetry as a storage/visualization product → it only generates and ships telemetry; pair it with a backend.
+- Logging unstructured free text → emit structured, queryable fields and avoid logging secrets/PII.
+- Alerting on raw resource metrics with no SLO → alert on user-impacting symptoms (golden signals / SLO burn) to cut noise (Google SRE).
+
+## Examples
+```text
+A single user request, observed across the three signals:
+  trace : frontend → orders-api → payments-api (spans with timing)
+  metric: http.server.duration, error.rate, queue.saturation
+  log   : {"level":"error","trace_id":"abc123","msg":"payment declined"}
+```
+```text
+Four golden signals to dashboard/alert on:
+  latency · traffic · errors · saturation
+```
+
+## Further reading
+- OpenTelemetry — what is observability: https://opentelemetry.io/docs/concepts/observability-primer/
+- SRE Book, Monitoring Distributed Systems (golden signals): https://sre.google/sre-book/monitoring-distributed-systems/
+
+## Related skills
+- ./backend-fundamentals — the "logs" twelve-factor concern and service operation
+- ./auth-and-authorization — logging authorization failures for audit

package/skills/engineering/frontend/accessibility-wcag/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: accessibility-wcag
+description: Meeting WCAG 2.2 success criteria and applying ARIA Authoring Practices for accessible UI; consult when building or auditing component accessibility.
+domain: engineering
+category: frontend
+tags: [accessibility, a11y, wcag, aria, w3c, wai]
+official_sources:
+  - https://www.w3.org/WAI/WCAG22/quickref/
+  - https://www.w3.org/WAI/ARIA/apg/
+  - https://github.com/w3c/wcag
+verified: 2026-06-16
+---
+
+# Accessibility (WCAG 2.2 & ARIA)
+
+## Overview
+WCAG (Web Content Accessibility Guidelines) is the W3C standard defining how to make web content accessible; the ARIA Authoring Practices Guide (APG) shows how to build accessible widgets with ARIA roles, states, and keyboard support. Read this when implementing interactive components, choosing semantics, or auditing a UI for conformance.
+
+## Official sources
+- WCAG 2.2 Quick Reference (How to Meet WCAG): https://www.w3.org/WAI/WCAG22/quickref/
+- ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/
+- Repo: https://github.com/w3c/wcag
+
+## Core concepts
+- **POUR principles.** WCAG organizes success criteria under four principles: Perceivable, Operable, Understandable, and Robust (w3.org/WAI/WCAG22/quickref).
+- **Conformance levels A / AA / AAA.** Each success criterion has a level; Level AA is the most commonly targeted baseline for sites and apps (w3.org/WAI/WCAG22/quickref).
+- **Techniques and failures.** Each criterion links sufficient techniques (ways to satisfy it), advisory techniques, and documented common failures to avoid (w3.org/WAI/WCAG22/quickref).
+- **Semantics first, ARIA second.** The APG covers ARIA roles, states, and properties for components that native HTML cannot express, but native HTML semantics are preferred where available (w3.org/WAI/ARIA/apg).
+- **Keyboard support.** APG patterns specify the expected keyboard interaction for each widget so it is operable without a mouse (w3.org/WAI/ARIA/apg).
+- **Landmark regions.** Use HTML sectioning elements and ARIA landmark roles to structure a page so assistive technology users can navigate it (w3.org/WAI/ARIA/apg/practices/landmark-regions).
+- **Accessible name and description.** Elements must expose a name (and optional description) that assistive technology can announce (w3.org/WAI/ARIA/apg).
+
+## Best practices
+- Target Level AA across the four POUR principles and use the Quick Reference's filters to track which criteria apply to your technologies (w3.org/WAI/WCAG22/quickref).
+- Reach for an established APG design pattern before inventing a custom widget; follow its required roles, states, and keyboard model exactly (w3.org/WAI/ARIA/apg).
+- Provide a meaningful accessible name for every interactive control and a landmark structure for every page (w3.org/WAI/ARIA/apg).
+- Validate against the sufficient techniques listed for each relevant success criterion rather than guessing (w3.org/WAI/WCAG22/quickref).
+
+## Common pitfalls
+- Adding ARIA roles to elements that already have native semantics → prefer the native HTML element; ARIA does not change behavior, only the exposed semantics (w3.org/WAI/ARIA/apg).
+- Building a custom widget (menu, dialog, tabs) without keyboard support → implement the keyboard interaction the matching APG pattern specifies (w3.org/WAI/ARIA/apg).
+
+## Examples
+```html
+<!-- Landmark + accessible name; native button needs no ARIA role. -->
+<nav aria-label="Primary">
+  <button type="button">Menu</button>
+</nav>
+```
+
+## Further reading
+- https://www.w3.org/WAI/ARIA/apg/patterns/ — full catalog of widget patterns
+- https://www.w3.org/WAI/standards-guidelines/wcag/ — WCAG standards overview
+
+## Related skills
+- ../frontend-architecture — where accessible components fit in the UI tree
+- ../state-management — managing widget state (open/selected) accessibly

package/skills/engineering/frontend/frontend-architecture/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: frontend-architecture
+description: Structuring component boundaries, data flow, and code-splitting in modern frontend apps; consult when designing or refactoring UI architecture.
+domain: engineering
+category: frontend
+tags: [components, data-flow, code-splitting, react, architecture, lazy-loading]
+official_sources:
+  - https://react.dev/learn
+  - https://www.patterns.dev/
+  - https://github.com/react/react
+verified: 2026-06-16
+---
+
+# Frontend Architecture
+
+## Overview
+Frontend architecture is how you split a UI into components, decide where data lives and how it flows, and control what code ships to the browser and when. Good structure keeps features local, props predictable, and bundles small. Read this when starting a new app, drawing component boundaries, or addressing slow initial loads.
+
+## Official sources
+- Docs: https://react.dev/learn
+- Patterns reference: https://www.patterns.dev/
+- Repo: https://github.com/react/react
+
+## Core concepts
+- **Components compose top-down.** A React component is a function returning markup; you nest components and pass data via props, building UI from small reusable pieces (react.dev/learn).
+- **One-way data flow.** Data flows down through props; child components do not mutate parent state directly, which makes data movement easy to trace (react.dev/learn).
+- **Lifting state up.** When two siblings need the same data, move that state to their closest common parent and pass it down, rather than duplicating it (react.dev/learn/sharing-state-between-components).
+- **Single source of truth.** State should not contain redundant or duplicated information; derive values during render instead of storing them (react.dev/learn/choosing-the-state-structure).
+- **Code-splitting with lazy loading.** `lazy` defers loading a component's code until it first renders, reducing the initial bundle; it must be paired with `<Suspense>` (react.dev/reference/react/lazy).
+- **Rendering / loading patterns.** patterns.dev catalogs reusable approaches such as bundle splitting, the PRPL pattern, and import-on-interaction to ship less JavaScript up front (patterns.dev).
+
+## Best practices
+- Push `'use client'` / interactive boundaries as deep into the tree as possible so static parts stay shippable and bundles stay small (react.dev/learn; patterns.dev performance patterns).
+- Keep state minimal and derived data computed in render, avoiding state you would have to keep in sync (react.dev/learn/choosing-the-state-structure).
+- Split routes and heavy, rarely-used components with `lazy` + `Suspense` so users only download what they need (react.dev/reference/react/lazy).
+- Co-locate state with the components that use it, lifting it only as far up as required by shared consumers (react.dev/learn/sharing-state-between-components).
+
+## Common pitfalls
+- Declaring a `lazy` component inside another component → declare it at module level; nesting it resets state on every re-render (react.dev/reference/react/lazy).
+- Storing redundant or duplicated state (e.g. a `fullName` alongside `firstName`/`lastName`) → compute it during render to avoid sync bugs (react.dev/learn/choosing-the-state-structure).
+- Prop-drilling shared data through many layers → reconsider component boundaries or use context where appropriate (react.dev/learn/passing-data-deeply-with-context).
+
+## Examples
+```jsx
+import { lazy, Suspense } from 'react';
+
+// Module-level: code is split and loaded on first render.
+const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
+
+export default function Editor() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <MarkdownPreview />
+    </Suspense>
+  );
+}
+```
+
+## Further reading
+- https://react.dev/learn/thinking-in-react — deriving component structure from a mockup
+- https://www.patterns.dev/ — rendering, design, and performance patterns
+
+## Related skills
+- ../state-management — choosing where state lives
+- ../rendering-strategies-ssr-csr — where components render

package/skills/engineering/frontend/rendering-strategies-ssr-csr/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: rendering-strategies-ssr-csr
+description: Trade-offs between SSR, CSR, static rendering, and streaming for web apps; consult when choosing where and when UI is rendered.
+domain: engineering
+category: frontend
+tags: [ssr, csr, ssg, streaming, hydration, rendering, nextjs]
+official_sources:
+  - https://web.dev/articles/rendering-on-the-web
+  - https://nextjs.org/docs/app/getting-started/server-and-client-components
+  - https://github.com/vercel/next.js
+verified: 2026-06-16
+---
+
+# Rendering Strategies (SSR / CSR / Static / Streaming)
+
+## Overview
+Where and when you render HTML — on the server, in the browser, at build time, or progressively streamed — affects first paint, interactivity, and the amount of JavaScript shipped. There is no single best choice; each strategy trades time-to-first-byte, first contentful paint, and interactivity differently. Read this when picking a rendering approach for a page or framework, or diagnosing slow loads.
+
+## Official sources
+- Google web.dev — Rendering on the Web: https://web.dev/articles/rendering-on-the-web
+- Next.js — Server and Client Components: https://nextjs.org/docs/app/getting-started/server-and-client-components
+- Repo (Next.js): https://github.com/vercel/next.js
+
+## Core concepts
+- **Server-side rendering (SSR).** Render the app on the server and send HTML; this gives fast first contentful paint and ships less JavaScript, but server work can delay time-to-first-byte (web.dev/articles/rendering-on-the-web).
+- **Client-side rendering (CSR).** Render in the browser with JavaScript modifying the DOM; large bundles can hurt interactivity (INP) (web.dev/articles/rendering-on-the-web).
+- **Static rendering (SSG).** Generate HTML at build time, one file per URL, for fast FCP and low blocking time; struggles when URLs are unpredictable (web.dev/articles/rendering-on-the-web).
+- **Hydration / rehydration.** Run client scripts to attach state and interactivity to server-rendered HTML; done poorly, a page can look interactive before it actually is (web.dev/articles/rendering-on-the-web).
+- **Streaming SSR.** Send HTML in chunks the browser renders progressively, improving perceived load (web.dev/articles/rendering-on-the-web).
+- **Server vs Client Components (Next.js).** Components default to the server for data fetching and smaller bundles; mark interactive ones with `'use client'`, and stream server-rendered chunks to the client (nextjs.org server-and-client-components).
+
+## Best practices
+- Measure where the bottleneck is (TTFB, FCP, INP) before choosing a strategy; the right answer depends on your content and audience (web.dev/articles/rendering-on-the-web).
+- Prefer server rendering for data-fetching and secret access, keeping API keys off the client and reducing shipped JavaScript (nextjs.org server-and-client-components).
+- Add `'use client'` to the smallest interactive components rather than large subtrees, so static parts stay server-rendered and bundles stay small (nextjs.org server-and-client-components).
+- Use streaming with `<Suspense>` boundaries so a fast shell renders while slower, dynamic content streams in (nextjs.org server-and-client-components).
+
+## Common pitfalls
+- Shipping a large CSR bundle for content that could be static or server-rendered → use SSR/SSG to cut JavaScript and improve FCP (web.dev/articles/rendering-on-the-web).
+- Marking large subtrees `'use client'` → every import in that file joins the client bundle; scope the directive to the interactive leaf (nextjs.org server-and-client-components).
+
+## Examples
+```tsx
+// Next.js App Router: Server Component fetches data; only the leaf is a Client Component.
+import LikeButton from './like-button'; // 'use client' lives in this file
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const post = await getPost(id); // runs on the server
+  return <article><h1>{post.title}</h1><LikeButton likes={post.likes} /></article>;
+}
+```
+
+## Further reading
+- https://web.dev/articles/rendering-on-the-web — full SSR/CSR/static/streaming trade-off guide
+- https://nextjs.org/docs/app/getting-started — Next.js App Router fundamentals
+
+## Related skills
+- ../frontend-architecture — code-splitting and component boundaries
+- ../state-management — hydrating and managing state across the server/client boundary

package/skills/engineering/frontend/state-management/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: state-management
+description: Choosing between local UI state, server/async state, and global state in React apps; consult when deciding where data should live and how it updates.
+domain: engineering
+category: frontend
+tags: [state, react, tanstack-query, server-state, context, reducers]
+official_sources:
+  - https://react.dev/learn/managing-state
+  - https://tanstack.com/query/latest
+  - https://github.com/TanStack/query
+verified: 2026-06-16
+---
+
+# State Management
+
+## Overview
+Frontend state falls into distinct kinds: local UI state (a component's own data), server/async state (remote data that is cached and can go stale), and shared/global state across components. Picking the right tool for each avoids over-engineering and sync bugs. Read this when deciding where a piece of data should live or which library, if any, to introduce.
+
+## Install / setup
+TanStack Query (React) — install command copied verbatim from the official installation page (tanstack.com/query/latest/docs/framework/react/installation):
+```bash
+npm i @tanstack/react-query
+```
+
+## Official sources
+- React state docs: https://react.dev/learn/managing-state
+- TanStack Query docs: https://tanstack.com/query/latest
+- Repo (TanStack Query): https://github.com/TanStack/query
+
+## Core concepts
+- **State drives the UI.** You describe UI as states and update state in response to input, letting React re-render rather than mutating the DOM imperatively (react.dev/learn/managing-state).
+- **Keep state structure lean.** Avoid redundant or duplicated state; compute derived values during render (react.dev/learn/choosing-the-state-structure).
+- **Lift state up to share it.** Move shared state to the closest common parent and pass it down via props (react.dev/learn/sharing-state-between-components).
+- **Reducers for complex logic.** `useReducer` consolidates many related state updates into one reducer, keeping event handlers clean (react.dev/learn/extracting-state-logic-into-a-reducer).
+- **Context for deep passing.** React context shares data deeply without prop-drilling and pairs with a reducer to scale up app state (react.dev/learn/scaling-up-with-reducer-and-context).
+- **Server state is different.** TanStack Query treats remote data as something with a cache and lifecycle — fetched, shared, cached, refetched, and sometimes intentionally stale — distinct from client state (tanstack.com/query/latest).
+
+## Best practices
+- Default to local component state; only lift it up or introduce context when multiple components genuinely need it (react.dev/learn/managing-state).
+- Use a dedicated server-state library like TanStack Query for fetching, caching, and synchronizing remote data instead of hand-rolling it in component state (tanstack.com/query/latest).
+- Reach for `useReducer` once a component juggles several interrelated state transitions (react.dev/learn/extracting-state-logic-into-a-reducer).
+- Don't store derived data in state — recompute it in render to prevent it from drifting out of sync (react.dev/learn/choosing-the-state-structure).
+
+## Common pitfalls
+- Caching server data in `useState`/context and manually refetching → use TanStack Query, which gives async data a cache and lifecycle (tanstack.com/query/latest).
+- Duplicating one source of truth across components → lift it to a common parent or context so there is a single owner (react.dev/learn/sharing-state-between-components).
+
+## Examples
+```jsx
+import { useQuery } from '@tanstack/react-query';
+
+function Todos() {
+  const { data, isPending, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then((r) => r.json()),
+  });
+  if (isPending) return <p>Loading…</p>;
+  if (error) return <p>Failed to load</p>;
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+## Further reading
+- https://react.dev/learn/choosing-the-state-structure — principles for shaping state
+- https://tanstack.com/query/latest/docs — caching, mutations, and invalidation
+
+## Related skills
+- ../frontend-architecture — component boundaries and data flow
+- ../rendering-strategies-ssr-csr — where state is hydrated and rendered

package/skills/engineering/performance/backend-performance/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: backend-performance
+description: Design resilient, high-throughput backends — timeouts, retries with backoff, connection pooling, concurrency limits, and avoiding N+1 queries.
+domain: engineering
+category: performance
+tags: [backend, concurrency, timeouts, retries, connection-pool, n+1, scalability]
+official_sources:
+  - https://aws.amazon.com/builders-library/
+  - https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+verified: 2026-06-16
+---
+
+# Backend Performance
+
+## Overview
+Backend performance is about sustaining throughput and low latency under real load and partial failure, not just making a single request fast. This skill covers concurrency control, connection management, retry/timeout discipline, and data-access patterns (especially the N+1 problem), grounded in the Amazon Builders' Library and SQL indexing literature. Read it when designing services that must stay responsive under contention or overload.
+
+## Official sources
+- Amazon Builders' Library (hub): https://aws.amazon.com/builders-library/
+- Timeouts, retries, backoff with jitter: https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+- Avoiding fallback in distributed systems: https://aws.amazon.com/builders-library/avoiding-fallback-in-distributed-systems/
+- SQL indexing / N+1 background: https://use-the-index-luke.com/
+
+## Core concepts
+- **Timeouts bound waiting.** Every remote call needs a timeout; the Builders' Library recommends setting it from downstream latency metrics (e.g. a high percentile like p99.9) so legitimate slow requests are tolerated but stuck calls fail fast.
+- **Retries are "selfish."** Per AWS, retries consume extra server resources and amplify load during overload; they help transient failures but can turn a brownout into an outage if applied blindly.
+- **Exponential backoff with jitter.** Spacing retries exponentially and adding randomness prevents synchronized "retry storms" where all clients hammer a recovering service at once.
+- **Connection pooling.** Reusing a bounded pool of connections (DB, HTTP) avoids per-request handshake cost and caps concurrency against downstreams; pool size is itself a concurrency limit.
+- **Concurrency limits / load shedding.** Bounding in-flight work and shedding excess load keeps latency stable; unbounded concurrency causes queue buildup and cascading latency under load.
+- **The N+1 query problem.** Fetching a list then issuing one query per item (1 + N) multiplies round-trips and table accesses; batch or join instead. use-the-index-luke explains how scattered per-row table access makes even indexed lookups slow.
+- **Avoid fallbacks as the happy path.** AWS argues fallback code is rarely exercised, hard to test, and often amplifies failures; prefer strengthening the primary path and letting callers retry.
+
+## Best practices
+- **Set timeouts everywhere and tune from data.** Derive timeout values from observed downstream latency percentiles rather than guessing; a missing timeout is an unbounded resource leak.
+- **Retry only transient/idempotent operations, with capped exponential backoff and jitter.** Add a retry budget/circuit breaker so retries cannot dominate traffic during incidents.
+- **Bound concurrency explicitly.** Size connection pools and worker concurrency to the downstream's capacity; shed or queue with limits instead of accepting unbounded work.
+- **Eliminate N+1 access.** Batch loads (join, `IN (...)`, or a dataloader) so a list view is O(1)–O(2) queries, not O(N); verify with query-count assertions in tests.
+- **Make work cancelable and propagate deadlines.** Pass a deadline/cancellation token down the call chain so a client timeout actually stops downstream work.
+
+## Common pitfalls
+- **No timeout on a remote call** → one slow dependency exhausts threads/connections; always bound the wait and fail fast.
+- **Naive immediate retries** → synchronized retry storms re-create the congestion that caused the failure; use exponential backoff with jitter and a retry budget.
+- **Hidden N+1 from lazy ORM relations** → looping over a collection triggers a query per element; eager-load or batch and assert query counts.
+- **Treating fallback paths as safe** → seldom-exercised fallbacks fail when finally triggered; per AWS, exercise them continuously or remove them and rely on retries.
+
+## Examples
+```python
+# Capped exponential backoff with full jitter for an idempotent call
+import random, time
+
+def call_with_retry(do, *, attempts=5, base=0.05, cap=2.0, timeout=1.0):
+    for attempt in range(attempts):
+        try:
+            return do(timeout=timeout)          # always bound the wait
+        except TransientError:
+            if attempt == attempts - 1:
+                raise
+            backoff = min(cap, base * 2 ** attempt)
+            time.sleep(random.uniform(0, backoff))  # full jitter
+```
+
+## Further reading
+- https://aws.amazon.com/builders-library/avoiding-fallback-in-distributed-systems/ — why fallbacks backfire
+- https://aws.amazon.com/builders-library/ — operational excellence essays (load shedding, fairness, caching)
+- ./reference.md — deeper patterns (loaded only when needed)
+
+## Related skills
+- ../database-query-optimization — fixing the queries behind N+1 and slow access
+- ../profiling-and-benchmarking — locating the real bottleneck before tuning