@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/frontend-observability-rum-instrumentation/references/opentelemetry-web-tracing-wiring.md

@@ -0,0 +1,135 @@
+# OpenTelemetry Web Tracing Wiring
+
+Use this reference only when wiring or reviewing `WebTracerProvider`, `DocumentLoadInstrumentation`/`DocumentLoad`, `FetchInstrumentation`, or exporter configuration for browser-origin traces.
+
+> Version note: `@opentelemetry/sdk-trace-web` and instrumentation package APIs (constructor option shapes, plugin package names) are version-sensitive. Verify against Context7-fetched docs (`/open-telemetry/opentelemetry-js`) and the installed package versions before prescribing exact constructor syntax.
+
+## What people get wrong
+
+The naive story is:
+
+> "I'll create a `WebTracerProvider`, register it, and traces just work."
+
+Wrong. Official OpenTelemetry JS docs imply at least four separate concerns that must each be configured, not assumed:
+
+1. **Context propagation across async boundaries** — the browser's default context manager does not automatically follow promises/timers/event callbacks; `ZoneContextManager` (from `@opentelemetry/context-zone`) is the documented pattern for supporting asynchronous operations in `provider.register()`.
+2. **Instrumentation registration is separate from provider creation** — creating a `WebTracerProvider` does not, by itself, produce document-load or fetch/XHR spans. Instrumentations (`DocumentLoad`/`DocumentLoadInstrumentation`, `FetchInstrumentation`, `XMLHttpRequestInstrumentation`) must be explicitly registered via `registerInstrumentations({instrumentations: [...]})`.
+3. **Exporter and span-processor choice affects both delivery reliability and payload timing** — `SimpleSpanProcessor` exports each span as it ends (useful for local `ConsoleSpanExporter` debugging); `BatchSpanProcessor` batches and is the documented production pattern for network exporters like OTLP.
+4. **Trace-propagation format must match the backend** — the B3 propagator vs. W3C Trace Context are not interchangeable; using the example combination that doesn't match your collector/backend silently breaks distributed trace stitching.
+
+## Officially grounded wiring shape
+
+Minimal document-load + console-export setup (from `@opentelemetry/sdk-trace-web` docs):
+
+```javascript
+import {
+  ConsoleSpanExporter,
+  SimpleSpanProcessor,
+  WebTracerProvider,
+} from '@opentelemetry/sdk-trace-web';
+import { DocumentLoad } from '@opentelemetry/plugin-document-load';
+import { ZoneContextManager } from '@opentelemetry/context-zone';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+
+const provider = new WebTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
+});
+
+provider.register({
+  contextManager: new ZoneContextManager(),
+});
+
+registerInstrumentations({
+  instrumentations: [new DocumentLoad()],
+});
+```
+
+Production-shaped fetch instrumentation + OTLP export (batched):
+
+```javascript
+import {
+  BatchSpanProcessor,
+  WebTracerProvider,
+} from '@opentelemetry/sdk-trace-web';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch';
+import { ZoneContextManager } from '@opentelemetry/context-zone';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+
+const exporter = new OTLPTraceExporter({
+  url: '<opentelemetry-collector-url>/v1/traces',
+  headers: {},
+  concurrencyLimit: 10,
+});
+
+const provider = new WebTracerProvider({
+  spanProcessors: [
+    new BatchSpanProcessor(exporter, {
+      maxQueueSize: 100,
+      maxExportBatchSize: 10,
+      scheduledDelayMillis: 500,
+      exportTimeoutMillis: 30000,
+    }),
+  ],
+});
+
+provider.register({
+  contextManager: new ZoneContextManager(),
+});
+
+registerInstrumentations({
+  instrumentations: [new FetchInstrumentation()],
+});
+```
+
+Note the OTLP endpoint must end in `/v1/traces` per the exporter's documented contract.
+
+## Non-negotiable design rules
+
+### 1. Never ship `ConsoleSpanExporter`/`SimpleSpanProcessor` as the production pipeline
+
+These are debugging tools. Production browser tracing needs a network exporter (e.g., `OTLPTraceExporter`) paired with `BatchSpanProcessor` so span export is batched and rate-limited instead of firing one network request per span.
+
+### 2. Register a context manager that supports async work
+
+Without `ZoneContextManager` (or an equivalent async-aware context manager), span parent/child relationships across `await`, `setTimeout`, and event-handler boundaries can silently break, producing disconnected traces that look correct individually but don't stitch into one distributed trace.
+
+### 3. Treat sampling as a first-class config, not an afterthought
+
+A browser SDK with no sampler configured effectively samples at 100% by default in many setups — that is a cost and cardinality risk at scale. See `sampling-cardinality-pii-controls.md` for sizing `TraceIdRatioBasedSampler` against traffic volume.
+
+### 4. Do not put secrets or bearer tokens directly in exporter headers as the default pattern
+
+If the collector endpoint requires auth, treat exporter `headers` the same way you would treat any credential-bearing config: source it from a managed secret/config mechanism appropriate to the deployment target, not hardcoded inline in client-shipped JS (client-shipped JS is fully visible to end users — never place a durable secret there regardless of source).
+
+### 5. Match the propagation format to what the backend actually consumes
+
+Verify (via Context7 or the collector/backend's own docs) whether the destination expects W3C Trace Context or B3 headers before wiring a propagator; a mismatch silently drops trace correlation without an error.
+
+## Minimal safe implementation flow
+
+1. Confirm the target collector/backend endpoint and its expected trace-propagation header format.
+2. Create `WebTracerProvider` with a `BatchSpanProcessor` wrapping the production exporter (OTLP or equivalent) — not `SimpleSpanProcessor`/`ConsoleSpanExporter`.
+3. Register with `ZoneContextManager` (or confirmed async-aware equivalent) so cross-async-boundary spans stay connected.
+4. Register only the instrumentations actually needed (`DocumentLoad`, `FetchInstrumentation`, `XMLHttpRequestInstrumentation`) — registering unused instrumentations increases span volume without benefit.
+5. Configure sampling (see `sampling-cardinality-pii-controls.md`) before enabling in production, sized to stated traffic.
+6. Name any custom span/attribute per OpenTelemetry Semantic Conventions (see `sampling-cardinality-pii-controls.md`) rather than inventing ad-hoc keys.
+7. Run every attribute the instrumentation or custom spans emit through the PII check before enabling in production.
+
+## High-risk assumptions to kill
+
+- "Creating the provider means tracing already works" — instrumentations must be separately registered.
+- "The default context manager is fine for async code" — it is not; use `ZoneContextManager` or a verified equivalent.
+- "No sampler configured means it's fine for now" — unconfigured sampling at high traffic is a cost/cardinality incident waiting to happen.
+- "Fetch instrumentation only captures URLs, so it's automatically safe" — captured URLs can include query strings carrying tokens/PII; review `FetchInstrumentation` URL-capture behavior against the PII check.
+
+## When to push back
+
+Push back if the user asks for:
+
+- shipping `SimpleSpanProcessor` + a network exporter direct to production ("it's simpler"),
+- no sampler configuration for a stated high-traffic production app,
+- hardcoding a durable collector auth token into client-shipped exporter `headers`,
+- registering every available instrumentation "to be thorough" without a stated need.
+
+That is not "faster." It is a cost, correctness, and security liability.

package/skills/frontend/frontend-observability-rum-instrumentation/references/sampling-cardinality-pii-controls.md

@@ -0,0 +1,96 @@
+# Sampling, Cardinality, and PII Controls
+
+Use this reference when sizing a sampling rate against traffic/cost, naming attributes via OpenTelemetry Semantic Conventions, or auditing an existing RUM/tracing pipeline for PII leakage.
+
+## What people get wrong
+
+The naive story is:
+
+> "Sampling is just a knob you turn down if the bill gets too high."
+
+That treats sampling as a cost afterthought instead of a design input, and it ignores that unsampled, high-cardinality, or PII-bearing telemetry is a *data-governance* problem before it is a *cost* problem — a leaked attribute doesn't get cheaper at a lower sample rate, it gets leaked less often.
+
+## Non-negotiable design rules
+
+### 1. Sample deterministically by trace ID, not randomly per-request
+
+`TraceIdRatioBasedSampler` (from `@opentelemetry/sdk-trace-web` / `@opentelemetry/sdk-trace-base`) samples a percentage of traces determined deterministically by the trace ID — any trace sampled at a given ratio is also sampled at any higher ratio. This is the documented building block for consistent, traffic-proportional sampling:
+
+```javascript
+const {
+  WebTracerProvider,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} = require('@opentelemetry/sdk-trace-web');
+
+const provider = new WebTracerProvider({
+  sampler: new ParentBasedSampler({
+    root: new TraceIdRatioBasedSampler(0.1), // sample 10% of root traces
+  }),
+});
+```
+
+### 2. Wrap it in `ParentBasedSampler` unless you have a specific reason not to
+
+`ParentBasedSampler` respects an incoming trace's sampling decision by default and only delegates the *root*-span sampling decision to the wrapped sampler (e.g., `TraceIdRatioBasedSampler`). This keeps a single distributed trace's sampling decision consistent across service boundaries — a browser span sampled independently of its downstream backend spans produces incomplete, misleading traces.
+
+### 3. Size the ratio against stated traffic volume and the backend's cost/cardinality limits, not a guess
+
+Before recommending a ratio:
+
+- Get (or explicitly estimate and label as an estimate) the page's traffic volume (sessions/day or requests/day).
+- Get the backend's pricing/cardinality model (per-span cost, per-attribute cardinality limits, retention window).
+- Compute expected exported span volume at candidate ratios (e.g., 100k sessions/day × 5 spans/session × 0.1 ratio = 50k spans/day) and state that arithmetic explicitly in the recommendation — never hand back a bare percentage with no traffic math behind it.
+- Never recommend 100% (unsampled) export for a stated high-traffic production app without an explicit, logged cost review — treat that as the exception requiring justification, not the default.
+
+### 4. Name attributes with OpenTelemetry Semantic Conventions, not ad-hoc keys
+
+Use the standard attribute namespaces (e.g., `http.request.method`, `http.response.status_code`, `url.path`, `user_agent.original`) documented in the OpenTelemetry Semantic Conventions rather than inventing project-specific keys like `httpMethod` or `req_status`. Ad-hoc naming breaks cross-service correlation and makes backend queries/dashboards non-portable. When no standard convention covers a genuinely custom business attribute, prefix it clearly (e.g., a documented internal namespace) so it's visually distinguishable from standard conventions, rather than colliding with or shadowing a standard key name.
+
+### 5. Every custom attribute must pass a PII check before it ships
+
+Before adding any span attribute, metric label, or `web-vitals` attribution `generateTarget` output, check it against this list. If any apply, the attribute must be scrubbed, hashed, truncated, or dropped before export:
+
+- **Raw URLs with query strings** — query strings frequently carry session tokens, search terms, or user-identifying values. Capture path only (`url.path`), or explicitly strip known-sensitive query parameters before capturing `url.full`.
+- **User identifiers** — no raw email, username, account ID, or customer name as a plain attribute value. If correlation is needed, use an opaque, rotated, non-reversible identifier and document the mapping's access control separately.
+- **Free-text form input** — never capture form field values (search boxes, comment fields, addresses) as telemetry attributes.
+- **Precise geolocation** — no raw lat/long or street-level location; use coarse-grained (e.g., country/region) if location is genuinely needed for the stated purpose.
+- **DOM-derived strings that embed the above** — a CSS selector or `generateTarget` output can accidentally embed a customer name or ID if it's built from live `id`/`class`/`data-*` attributes that the DOM populates with user data; audit before trusting default stringification (see `web-vitals-attribution-wiring.md` rule 1).
+- **Auth headers/tokens** — never mirror `Authorization`, cookies, or bearer tokens into span attributes, even truncated; treat any such capture as a credential leak, not a debugging convenience.
+
+### 6. Cardinality is a cost multiplier independent of sampling
+
+A single high-cardinality attribute (e.g., a raw user ID or full URL used as a span attribute) can multiply backend storage/indexing cost regardless of the trace sampling ratio, because most backends index per-unique-attribute-value. Prefer bounded-cardinality attributes (enum-like values, coarse buckets) for anything intended to be an indexed/filterable dimension; keep genuinely high-cardinality values (if needed at all) as non-indexed payload fields, and confirm the plan against the destination backend's own cardinality documentation.
+
+## Minimal safe implementation flow
+
+1. Get or explicitly estimate traffic volume for the page/app in scope.
+2. Get the backend's pricing/cardinality/retention model (or state clearly that it's unknown and flag the gap).
+3. Propose a `TraceIdRatioBasedSampler` ratio wrapped in `ParentBasedSampler`, with the traffic-volume arithmetic shown.
+4. Enumerate every custom span attribute, metric label, and `generateTarget` output planned; run each through the PII check in rule 5.
+5. Map custom attributes to OpenTelemetry Semantic Conventions where a standard key exists; namespace the rest clearly.
+6. Flag any attribute that is both high-cardinality and unbounded (raw user input, raw URL) as an indexing/cost risk even if it passes the PII check.
+7. State the sampling ratio, PII findings, and cardinality findings together as one review output — do not split cost sizing from privacy review into separate, disconnected passes.
+
+## Adversarial checklist
+
+Before approving a RUM/tracing pipeline, answer these:
+
+- What is the actual (or explicitly estimated) traffic volume this sampling ratio is sized against?
+- Does the sampler respect parent sampling decisions (`ParentBasedSampler`), or will browser spans and backend spans disagree on what got sampled?
+- For every custom attribute: does it match a standard Semantic Convention key, or is it deliberately namespaced as custom?
+- For every attribute sourced from user-controllable input (URL, form, DOM content, `generateTarget`): has it been explicitly scrubbed, or is it being trusted "because it looked fine in testing"?
+- Which attributes are indexed/filterable in the destination backend, and are any of those unbounded-cardinality values?
+
+If these cannot be answered, the review is incomplete — say so rather than approving.
+
+## When to push back
+
+Push back if the user asks for:
+
+- 100% unsampled export "to not miss anything," on a stated high-traffic app, with no cost review,
+- capturing full request URLs or form values "just in case it's useful later,"
+- inventing custom attribute names that duplicate an existing Semantic Convention key under a different spelling,
+- skipping the PII check because "it's just internal telemetry" — internal-only access does not eliminate the need for a PII/data-governance review; it changes who is affected, not whether it matters.
+
+Those are not shortcuts. They are cost incidents and data-governance failures waiting to be found in an audit.

package/skills/frontend/frontend-observability-rum-instrumentation/references/web-vitals-attribution-wiring.md

@@ -0,0 +1,87 @@
+# web-vitals Attribution Build Wiring
+
+Use this reference only when writing or reviewing the actual `onLCP`/`onINP`/`onCLS` (or `onFCP`/`onTTFB`) instrumentation call.
+
+> Version note: `web-vitals` API surface (attribution option shapes, default thresholds) is version-sensitive. Verify the installed package version against Context7-fetched docs (`/googlechrome/web-vitals`) before prescribing option names.
+
+## What people get wrong
+
+The naive story is:
+
+> "I'll import `onLCP` from `web-vitals` and send everything to analytics with `reportAllChanges: true` so I never miss a value."
+
+Wrong on two counts:
+
+1. The **standard build** (`web-vitals`) only returns the metric name, value, rating, and delta. It does **not** tell you *why* LCP was slow or *which* element shifted for CLS. For root-cause work you need the **attribution build** (`web-vitals/attribution`), which is a separate import path, not a flag on the standard build.
+2. `reportAllChanges: true` reports every intermediate value change (e.g., every CLS shift, every LCP candidate), not just the final value — this is a debugging tool that multiplies event volume in production, not a default-on setting.
+
+## Standard build vs. attribution build
+
+- **Standard build** (`import {onLCP, onINP, onCLS} from 'web-vitals'`): metric name, `value`, `rating` (`good`/`needs-improvement`/`poor`), `delta`, `id`. Use this for default production RUM export — it is the lower-cardinality, lower-payload choice.
+- **Attribution build** (`import {onLCP, onINP, onCLS} from 'web-vitals/attribution'`): adds a `metric.attribution` object with phase/target detail (e.g., LCP's `attribution.target`, `attribution.timeToFirstByte`, `attribution.resourceLoadDelay`; INP's `attribution.interactionTarget`, `attribution.inputDelay`, `attribution.processingDuration`, `attribution.presentationDelay`; CLS's `attribution.largestShiftTarget`, `attribution.largestShiftTime`).
+- Do not send the attribution build's full diagnostic payload to a blanket production analytics endpoint by default — route it to a debug/diagnostic destination or sample it separately, because its per-metric fields substantially increase payload size and can carry more surface area for accidental PII (e.g., a raw element attribute pulled into a target string).
+
+## Non-negotiable design rules
+
+### 1. Choose `generateTarget` deliberately, not by default
+
+`AttributionReportOpts.generateTarget` is `(el: Node | null) => string | undefined`. It overrides how a DOM node is stringified in attribution fields (e.g., `attribution.target`, `attribution.largestShiftTarget`, `attribution.interactionTarget`). Do not leave the default CSS-selector-based stringification unexamined if the DOM contains sensitive `id`/`class`/`data-*` values that could leak into telemetry (e.g., a selector embedding a customer name). A safe pattern prioritizes an intentional tracking attribute over the raw selector:
+
+```javascript
+import {onCLS, onINP, onLCP} from 'web-vitals/attribution';
+
+function generateTarget(el) {
+  // Prefer an explicit, reviewed tracking attribute.
+  if (el?.dataset.trackingId) {
+    return el.dataset.trackingId;
+  }
+  // Fall back to default CSS-selector logic only if that selector
+  // is known not to embed PII (audit before relying on this).
+  return undefined;
+}
+
+onLCP((metric) => sendToAnalytics(metric), {generateTarget});
+onCLS((metric) => sendToAnalytics(metric), {generateTarget});
+onINP((metric) => sendToAnalytics(metric), {generateTarget});
+```
+
+### 2. Tune `INPAttributionReportOpts` explicitly, don't accept silent defaults
+
+`onINP` in the attribution build accepts `durationThreshold` (default `40`ms — interactions shorter than this are not attributed) and `includeProcessedEventEntries` (default `true` — includes the full array of event-timing entries for the interaction frame). State both defaults explicitly in any review: a lower `durationThreshold` increases event volume by attributing more interactions; leaving `includeProcessedEventEntries: true` on a high-traffic page increases per-event payload size and should be weighed against export cost.
+
+### 3. Keep `reportAllChanges` off in production by default
+
+`reportAllChanges` (inherited from `ReportOpts`, default `false`) reports every intermediate metric change instead of just the final value. Only enable it for a scoped debugging session against a non-production or sampled destination — never as the default production wiring.
+
+### 4. Match the reporting transport to the page-lifecycle guarantee you need
+
+`web-vitals` callbacks can fire late in the page lifecycle (e.g., on visibility change or page unload for LCP/CLS finalization). Use a transport that survives page unload (e.g., `navigator.sendBeacon`, or `fetch` with `keepalive: true`) rather than a plain `fetch` call that can be cancelled when the page unloads mid-request.
+
+## Minimal safe implementation flow
+
+1. Decide standard vs. attribution build based on whether root-cause detail is needed for this rollout (default: standard build for blanket production RUM).
+2. If attribution build: define and review a `generateTarget` function before shipping — do not accept the default selector logic unreviewed.
+3. Explicitly set (or explicitly accept and document) `durationThreshold`/`includeProcessedEventEntries` for INP.
+4. Leave `reportAllChanges` at its default `false` unless a scoped debug session requires it, and route that debug payload separately.
+5. Choose an unload-safe transport (`sendBeacon` / `fetch` with `keepalive`).
+6. Run every attribution field emitted through the PII check in `sampling-cardinality-pii-controls.md` before it ships.
+
+## Adversarial checklist
+
+Before shipping any `web-vitals` wiring, answer these:
+
+- Which build (standard or attribution) is this, and does that match the stated purpose (production dashboard vs. active debugging)?
+- If attribution build: has `generateTarget` been reviewed against the actual DOM, or is the default selector logic unaudited?
+- Is `reportAllChanges` on, and if so, is that intentional and scoped to non-production/debug traffic?
+- What percentile will this data be aggregated to before it's called "the site's LCP/INP/CLS" (per CWV convention, p75)?
+- Does the reporting transport survive `visibilitychange`/unload, or will late-finalizing metrics be silently dropped?
+
+## When to push back
+
+Push back if the user asks for:
+
+- shipping the attribution build's full payload to production analytics "just in case," with no PII review of `generateTarget` output,
+- `reportAllChanges: true` as a permanent production default,
+- reporting a single lab run's LCP/INP/CLS value as if it were the field p75 the org will be judged on.
+
+Those are not shortcuts. They inflate cost, leak data, and misreport what users actually experience.

package/skills/frontend/frontend-platform-architecture-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: frontend-platform-architecture-review
+description: Reviews cross-cutting frontend architecture decisions (module boundaries, rendering topology, technology adoption) against a rewrite-averse, evidence-grounded standard before they are approved, producing an ADR-quality verdict rather than a stylistic opinion.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: architecture
+---
+
+# Frontend Platform Architecture Review
+
+## Purpose
+
+Review proposed or existing frontend architecture — module/package boundaries, monorepo topology, rendering-strategy choice, technology adoption — for duplication, migration safety, and cross-team consistency, without re-litigating implementation-level state-management, routing, API-contract, or SSR-mechanics detail in every response. This skill exists so those adjacent concerns stay out of scope and the review stays focused on the cross-cutting, org-level decision: should this architectural change be approved, and on what terms.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a proposal to adopt a new frontend framework, library, or build tool,
+- resolve two teams solving the same problem with different primitives (state management, routing, styling),
+- redraw a monorepo/polyrepo module boundary or ownership line,
+- review a rendering-strategy change (CSR to SSR, SSR to SSG/ISR/streaming/PPR),
+- audit an existing codebase for architectural entropy before a scaling or hiring push.
+
+Do not use this skill for:
+
+- implementation-level state-management review — route to `state-management-decision-review`,
+- routing/navigation-specific review — route to `routing-navigation-review`,
+- API-contract or data-fetching review — route to `api-integration-contract-review`,
+- SSR/hydration mechanics debugging — route to `ssr-hydration-streaming-diagnosis`,
+- responsive/visual UI design review — that needs a design-system/visual skill, not architecture review.
+
+## Context7 Documentation Protocol
+
+- Before evaluating any version-sensitive technical claim in the proposal (e.g., "Next.js Partial Prerendering lets us do X," "React 19 Suspense enables Y"), call `resolve-library-id` for the exact library, then `query-docs` against the repo's confirmed version — read `package.json` first to confirm the installed major version before trusting a claim about API availability.
+- Matched library IDs for this skill's default grounding: React is `/reactjs/react.dev`, Next.js is `/vercel/next.js`. Resolve fresh for any other framework named in a proposal (Angular, Vue, SvelteKit, etc.) rather than assuming these two cover every case.
+- Never approve a version-sensitive technical claim without Context7 verification. If Context7 is unavailable, mark the claim `documentation-based — unverified this session` in the verdict and require the proposer to confirm the claim before final approval.
+- Documentation proves what a framework *supports*; it does not prove the proposal's specific repo can adopt it safely. Pair every Context7-grounded capability claim with a repo-evidence check (actual installed version, actual existing patterns) before treating it as settled.
+
+## Lean operating rules
+
+- First classify the proposal: new capability, migration of an existing capability, or boundary redraw. Do not evaluate a migration as if it were greenfield.
+- Check for an existing in-repo equivalent before evaluating the proposal on its own terms. A proposal that duplicates a capability the repo already solves is a duplication defect regardless of how well-argued the new approach is.
+- Require at least two alternatives with tradeoffs before treating a single-option proposal as reviewable. A proposal with no alternatives considered is not ready for an architecture verdict — send it back.
+- Default against "rewrite" framing. If an incremental strangler-fig or boundary-first path exists, require it over a big-bang rewrite; do not accept "the codebase is too messy to migrate incrementally" without the proposer demonstrating why.
+- Treat accessibility and security posture as first-class, blocking review criteria — not items to defer to a follow-up ticket. An architecture proposal silent on a11y/security is incomplete, not merely imperfect.
+- Treat Core Web Vitals budget impact as mandatory for any rendering-strategy change; a proposal with no stated LCP/INP/CLS impact (lab or field) has not been evaluated for its primary tradeoff.
+- Never fabricate a performance or vitals number without a stated measurement source; label estimates `inference, not measured` and require the proposer to supply lab or field data before final approval.
+- Never execute, build, or run application code as part of this review; this is a static-review skill (Read/Grep/Glob only) — verdicts are based on document, code, and config evidence, not live measurement you generate yourself.
+- Flag any architecture proposal that stores secrets or tokens in client-reachable bundles or build-time-inlined env vars, allows postinstall scripts from unpinned/unaudited dependencies, or introduces a CSP-incompatible pattern (`unsafe-eval`, dynamic `Function()`) as a blocking finding, not a note — this cannot be approved-with-conditions into a later cleanup.
+
+## References
+
+Load these only when needed:
+
+- [Review workflow and ADR output contract](references/workflow-and-output.md) — use for the step-by-step review procedure, the approve/approve-with-conditions/reject decision tree, and the required ADR-format output shape.
+- [Rendering topology and cross-cutting budgets](references/rendering-topology-and-budgets.md) — load only when the proposal changes rendering strategy (CSR/SSR/SSG/ISR/streaming/PPR) or when Core Web Vitals, a11y, or security posture needs grounding against current framework/WCAG guidance.
+
+## Response minimum
+
+Return, at minimum:
+
+- the architectural change and files/modules/teams in scope,
+- duplication check result (existing in-repo equivalent found or none),
+- every version-sensitive claim labeled `Context7-verified` or `documentation-based — unverified this session`,
+- verdict (approve / approve-with-conditions / reject-with-reasoning) with the specific unresolved conditions if any,
+- rollback or incremental-migration path referenced explicitly,
+- open questions the review could not resolve from available evidence.

package/skills/frontend/frontend-platform-architecture-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "frontend-platform-architecture-review",
+  "name": "Frontend Platform Architecture Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews cross-cutting frontend architecture decisions (module boundaries, rendering topology, technology adoption) against a rewrite-averse, evidence-grounded standard before they are approved, using duplication checks, incremental-migration requirements, and Core Web Vitals/a11y/security gates loaded progressively and grounded via Context7 against the repo's confirmed framework versions.",
+  "source_type": "original",
+  "official_docs": [
+    "https://react.dev/learn/thinking-in-react",
+    "https://nextjs.org/docs/app/building-your-application/routing",
+    "https://web.dev/articles/vitals",
+    "https://www.w3.org/WAI/WCAG22/quickref/"
+  ],
+  "security_notes": "Static-review-only skill: it reads and greps proposal documents, config, and source but never executes, builds, or runs application code. Flag any architecture proposal that stores secrets/tokens in client-reachable bundles or build-time-inlined env vars, allows postinstall scripts from unpinned/unaudited dependencies, or introduces a CSP-incompatible pattern (unsafe-eval, dynamic Function()) as a blocking finding, not a note.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/frontend-platform-architecture-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/frontend-platform-architecture-review/references/rendering-topology-and-budgets.md

@@ -0,0 +1,61 @@
+# Rendering Topology and Cross-Cutting Budgets
+
+Use this reference only when the proposal changes rendering strategy (CSR → SSR, SSR → SSG/ISR/streaming/PPR) or when Core Web Vitals, accessibility, or security posture needs grounding against current framework and WCAG guidance. Do not load this for a pure module-boundary or dependency-adoption proposal that does not touch rendering.
+
+## What people get wrong
+
+The naive story is:
+
+> We're moving from SSR to PPR/streaming, so this is purely a performance upgrade — it's strictly better.
+
+Wrong. A rendering-topology change is a cross-cutting change to caching, hydration timing, focus/reading order, and the bundle's client-reachable surface — not an isolated performance knob. Officially, Next.js describes Partial Prerendering as combining a static prerendered shell with dynamic content streamed in via Suspense boundaries at request time; React's Suspense mechanism decides what streams and when. That means every dynamic region introduces a new hydration/streaming boundary that a11y (focus management, live-region announcements) and security (what's in the static shell vs. what's fetched dynamically, and with what auth context) both have to account for. Treating it as "just faster" skips the review this skill exists to force.
+
+## Officially grounded rendering-strategy shape (Context7-verified)
+
+- **Partial Prerendering (PPR)** — Next.js's glossary describes PPR as "a rendering optimization that combines prerendering and dynamic rendering in a single route. The static shell is served immediately while dynamic content streams in when ready." As of Next.js 16, PPR is enabled via `cacheComponents: true` in `next.config`, replacing the earlier `experimental_ppr` route-segment flag. Verify the repo's installed Next.js major before citing either mechanism — the config surface changed between versions.
+- **Static-shell-plus-streaming pattern** — implemented via a `<Suspense fallback={...}>` boundary wrapping the dynamic component; the fallback is prerendered as part of the static shell, and the wrapped component streams once its data resolves. Every such boundary is a place where the visible-but-not-yet-interactive gap (for a11y) and the deferred-fetch trust boundary (for security) both need explicit review.
+- **Component decomposition as the review's dependency, not its subject** — React's own "Thinking in React" guidance frames component splitting around separation of concerns ("a component should ideally only be concerned with one thing. If it ends up growing, it should be decomposed into smaller subcomponents"). This skill does not re-review component-level decomposition (that is `react-component-architecture-review`'s job); it uses this principle only to sanity-check that a proposed module/rendering boundary maps to a real separation of concerns rather than an arbitrary split.
+
+## Non-negotiable design rules
+
+1. **State the Core Web Vitals budget impact per route class, not per app.** LCP/INP/CLS impact differs by route (a marketing shell vs. an authenticated dashboard); a single app-wide estimate hides regressions in the routes that matter most.
+2. **Separate lab data from field data explicitly.** Lab data (Lighthouse, local traces) proves a route *can* meet budget under controlled conditions; field data (CrUX, RUM) proves it *does* for real users. A proposal citing only lab numbers as evidence of production impact is incomplete.
+3. **Every new streaming/hydration boundary must state its focus-management and live-region behavior.** Content that pops in after initial paint can silently move focus or fail to announce to assistive technology; this is not optional polish, it is the a11y consequence of the rendering choice.
+4. **State what's in the static shell vs. fetched dynamically, and under what auth context.** A static shell is often cached and served without per-request auth; if a proposal moves user-specific or sensitive data into a cached shell to hit a performance target, that is a security defect, not a clever optimization.
+6. **Treat framework version as load-bearing for every claim.** PPR's config surface, Suspense streaming semantics, and caching defaults have all changed across React and Next.js majors — a claim true for one major can be false or renamed in another. Confirm the installed version before citing a mechanism.
+
+## Adversarial checklist
+
+Before approving a rendering-topology change, answer these:
+
+- What is the LCP/INP/CLS budget for the specific route(s) affected, and is it lab data, field data, or an unmeasured estimate?
+- Which regions of the page are in the static shell, and which stream in dynamically?
+- Is any user-specific or sensitive data present in the static shell (which may be cached/shared across requests)?
+- What happens to keyboard focus and screen-reader announcements when a streamed region resolves after initial paint?
+- What is the fallback/loading state, and does it meet the same a11y bar as the resolved content (not just visually, but semantically)?
+- Does the target framework version actually support the mechanism being proposed, confirmed via Context7 against the installed version — not assumed from general familiarity with the framework?
+- If this fails or partially fails in production, what is the rollback — a config flag, a route-level revert, or a full redeploy?
+
+If these cannot be answered, the review is not ready for a verdict — send it back with the specific gaps named.
+
+## High-risk assumptions to kill
+
+- "Streaming is strictly additive — it can only make things faster, never worse."
+- "The static shell has no sensitive data because we didn't put user data there on purpose."
+- "PPR/ISR works the same way in this Next.js major as it did in the blog post I read."
+- "A11y is a component-level concern, so it's out of scope for a rendering-strategy review."
+- "We'll measure Core Web Vitals after launch" as a substitute for a stated budget before launch.
+
+Those are lazy assumptions. Each one has caused a real production regression in review histories this skill's design pattern is meant to catch.
+
+## When to push back
+
+Push back if the proposal:
+
+- states a performance goal with no route-level budget or measurement plan,
+- moves rendering strategy without naming the resulting static/dynamic data split,
+- treats accessibility of streamed content as a follow-up ticket rather than part of the design,
+- cites a framework capability without the installed version being confirmed against Context7-verified docs,
+- offers no rollback mechanism narrower than a full redeploy.
+
+That is not "shipping faster." It is deferring the review to production incidents.

package/skills/frontend/frontend-platform-architecture-review/references/workflow-and-output.md

@@ -0,0 +1,48 @@
+# Review Workflow and ADR Output Contract
+
+Use this reference for the step-by-step review procedure, the decision tree governing approve/approve-with-conditions/reject, and the required output shape. Load it for every review; it is the orchestration layer the other reference does not cover.
+
+## What people get wrong
+
+The naive story is:
+
+> The proposer already explained why this is a good idea, so my job is to sanity-check their reasoning.
+
+Wrong. The proposer's framing is evidence, not a starting truth. A reviewer who only checks internal consistency of the proposal will approve a well-argued duplication, a well-argued rewrite, and a well-argued a11y-deferral, because those things can all be argued well. The job is to check the proposal against the repo's actual state and against enterprise standards the proposer did not necessarily consider — not to grade the proposal's own essay.
+
+## Step-by-step workflow
+
+1. **Classify the proposal.** New capability, migration of an existing capability, or boundary redraw. This determines which checks apply — a new capability has no prior art to compare against; a migration must justify the replacement of what exists; a boundary redraw must show who owns what after the change.
+2. **Check for an existing in-repo equivalent.** Search the repo (Grep/Glob) for the capability the proposal claims to introduce. If one exists, the proposal must explicitly justify why the existing one cannot be extended — silence on this is a duplication defect.
+3. **Verify every version-sensitive technical claim via Context7.** Resolve the library, confirm the repo's installed major version from `package.json` or lockfile, then query docs for that version. Label each claim `Context7-verified` or `documentation-based — unverified this session`.
+4. **Require at least two alternatives considered with tradeoffs.** A single-option proposal is not ready for a verdict; send it back with this specific gap named rather than guessing at alternatives on the proposer's behalf.
+5. **Require an incremental migration plan with a rollback path.** Reject "big bang" proposals by default. If the proposer argues incremental migration is infeasible, that argument itself needs evidence (e.g., tight coupling that genuinely cannot be strangled), not just assertion.
+6. **Confirm a11y and security posture are explicitly addressed.** Not assumed, not deferred to "we'll handle it in implementation." A rendering or module-boundary change that affects focus order, hydration timing, or bundle boundaries has a11y and security surface area; the proposal must name it.
+7. **Confirm Core Web Vitals budget impact is stated for any rendering-strategy change.** Lab or field data, or an explicit estimate labeled `inference, not measured` with a commitment to measure post-launch. Silence is not acceptable for a rendering change.
+8. **Issue a verdict.** Approve, approve-with-conditions, or reject-with-reasoning, using the decision tree below.
+
+## Decision tree
+
+- Proposal duplicates an existing capability → **reject** unless the proposer justifies why the existing one cannot be extended.
+- Proposal has no rollback path → **reject-with-conditions**, requiring one before re-review.
+- Proposal is framed as a rewrite but an incremental strangler-fig path plausibly exists → **reject the rewrite framing**; request an incremental plan, do not simply approve the rewrite because it is well-written.
+- A11y or security posture is unaddressed → **reject-with-conditions**; this is never waived even if the proposer considers it out of scope.
+- Rendering-strategy change with no stated Core Web Vitals impact → **reject-with-conditions**; require lab or field data, or an explicit measurement commitment.
+- None of the above triggers apply → **approve** or **approve-with-conditions** based on any remaining, narrower gaps (e.g., missing ownership documentation, unresolved naming collision).
+
+## ADR-format output contract
+
+Every verdict must be returned in this shape:
+
+1. **Context** — what is being proposed, which teams/modules are affected, why now.
+2. **Decision recommendation** — approve / approve-with-conditions / reject-with-reasoning, stated plainly in the first line.
+3. **Duplication check** — existing in-repo equivalent found (with file/module evidence) or none found, and the search performed.
+4. **Alternatives considered** — the two or more options and their tradeoffs, as supplied by the proposer or explicitly flagged as missing.
+5. **Version-sensitive claims** — each claim labeled `Context7-verified` (with the library/version queried) or `documentation-based — unverified this session`.
+6. **Consequences** — what this decision commits the org to, including maintenance burden and the "third way to do X" cost if a competing capability now exists.
+7. **Rollback / incremental migration plan** — the specific mechanism (feature flag, route-level cutover, strangler-fig boundary), or its absence flagged as a blocking condition.
+8. **A11y and security posture** — explicit statement of impact and mitigation, or flagged as a blocking condition if silent.
+9. **Core Web Vitals budget impact** — for rendering-strategy changes only; lab/field data or a labeled estimate with a measurement commitment.
+10. **Unresolved conditions** — the specific, named items blocking full approval, if any.
+
+Do not compress this into prose paragraphs when the proposal is non-trivial; use the numbered shape so gaps are visible at a glance to the next reviewer.

package/skills/frontend/frontend-testing-strategy-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: frontend-testing-strategy-review
+description: Reviews frontend test-pyramid shape, critical-path coverage, and flaky-test governance across unit, component, integration, and E2E layers (Vitest/Jest, Testing Library, Playwright/Cypress), loading framework references only when the task needs them.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: delivery
+---
+
+# Frontend Testing Strategy Review
+
+## Purpose
+
+A green CI badge does not prove a critical user journey works. This skill exists to separate "tests exist" from "tests exercise the actual failure modes that matter" — test-pyramid shape, critical-path coverage, and flaky-test governance — without dumping every testing-library's full API surface into every review.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review or design a frontend test strategy across unit, component, integration, and E2E layers,
+- diagnose why a test suite is slow, flaky, or not catching regressions,
+- decide whether a given assertion belongs at the unit, component, or E2E layer,
+- audit critical-user-journey coverage (checkout, auth, forms) before a release,
+- evaluate a proposed test-framework migration (Jest to Vitest, Cypress to Playwright).
+
+## Context7 Documentation Protocol
+
+Test-runner and testing-library APIs (retry semantics, coverage-threshold config, query priority, selector strategy) change across majors and are documented, not folklore — never assert a flag, config shape, or "best practice" from memory.
+
+1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if not already loaded in this session.
+2. Call `mcp__Context7__resolve-library-id` for the framework in question: `/microsoft/playwright` for Playwright, `/vitest-dev/vitest` for Vitest, `/testing-library/testing-library-docs` for Testing Library, `/cypress-io/cypress-documentation` for Cypress. Prefer these resolved IDs over guessing a library name.
+3. Call `mcp__Context7__query-docs` for the specific claim in question — e.g. "coverage threshold configuration", "web-first assertion retry behavior", "getByRole query priority", "avoid fixed waits" — before stating it as fact. Do this per review, not once from a prior session's memory.
+4. Prefer the official docs URLs in `official_docs` for primary normative statements (e.g. exact CLI flags, exact config shape); use Context7 to ground and cross-check the claim before writing it into a finding.
+5. If Context7 is unavailable or returns no relevant match, fall back to the `official_docs` URLs and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+6. Never invent a config key, CLI flag, matcher name, or API method that no queried source confirms.
+
+## Lean operating rules
+
+- Classify the pyramid shape first (unit:component:E2E ratio, counted from actual test files/CI artifacts, not the user's description of it) before recommending any specific test; a shape problem needs a rebalancing plan, not one more test.
+- Treat coverage percentage as a weak signal; require evidence the suite asserts on error states, loading states, and accessibility tree for critical paths, not just the happy-path DOM. A file at 100% line coverage with no error-path assertion is not "well tested."
+- Treat flaky-test quarantine (`.skip`, `test.fixme`, `it.skip`, `describe.skip`, Cypress `{retries: N}` used to paper over root cause) as a tracked liability with an owner and expiry, never a silent, permanent state.
+- Prefer official, version-specific docs (via Context7) over memory for any framework API claim — Playwright, Vitest, Cypress, and Testing Library APIs and retry/wait semantics change across majors.
+- Never request or accept real user credentials, session cookies, or production API keys as test fixtures; require synthetic data or network mocking (MSW, `cy.intercept`, Playwright route interception).
+- Do not recommend a framework migration (Jest→Vitest, Cypress→Playwright) without a measured baseline (suite duration, ESM/native-TS support gap, current flake rate) and a rollback path; framework preference alone is not a migration justification.
+- Distinguish "flaky because of the test" (missing await, race on network mock, unstable selector) from "flaky because of the app" (real timing bug, unhandled async state) — the fix differs and misdiagnosis just hides a production bug behind a retry.
+- Load references only for the layer/framework in scope; do not load the Playwright reference for a pure Vitest unit-coverage question, and do not load the pyramid-shape reference for a single flaky-test triage.
+
+## References
+
+Load these only when needed:
+
+- [Test pyramid shape and critical-path coverage](references/pyramid-shape-and-coverage.md) — use when classifying unit:component:E2E ratio, deciding which layer an assertion belongs at, or auditing critical-user-journey coverage.
+- [Flaky-test diagnosis and governance](references/flaky-test-governance.md) — use when triaging a flaky or slow suite, reviewing quarantine (`.skip`/`fixme`) usage, or setting a flake-tracking policy.
+- [Playwright and Cypress E2E review](references/e2e-framework-review.md) — use for E2E-layer specifics: locator/selector strategy, web-first assertions and retry semantics, test isolation, and Jest/Cypress-to-Playwright migration evidence requirements.
+- [Vitest and Testing Library unit/component review](references/unit-component-framework-review.md) — use for unit/component-layer specifics: query priority (`getByRole` over test IDs), mocking boundaries, and coverage-threshold configuration.
+
+## Response minimum
+
+Return, at minimum:
+
+- the test-pyramid shape observed (unit/component/E2E counts or ratio, with the file/CI-artifact evidence it came from, not an estimate),
+- critical-user-journey coverage gaps, cited to a specific file/line or CI-artifact,
+- flaky-test inventory status for any `.skip`/`fixme`/retry-suppressed test found (owner, expiry, or "untracked liability"),
+- a minimal, prioritized diff-level test plan (not a full-suite rewrite),
+- evidence level (`live evidence`, `repo evidence`, `documentation-based`, `inference`) for every claim, and explicit flag when a claim is `documentation-based (Context7 unavailable)`.