@cubis/foundry 0.3.66 → 0.3.68

package/workflows/skills/web-perf/SKILL.md

@@ -1,193 +1,66 @@
 ---
 name: web-perf
-description: Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (FCP, LCP, TBT, CLS, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed.
+description: "Use for measuring and improving web performance with Core Web Vitals, rendering-path analysis, bundle and network prioritization, and framework-aware delivery tradeoffs."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Web Performance Audit
+# Web Perf
 
-Audit web page performance using Chrome DevTools MCP tools. This skill focuses on Core Web Vitals, network optimization, and high-level accessibility gaps.
+## Purpose
 
-## FIRST: Verify MCP Tools Available
+Use for measuring and improving web performance with Core Web Vitals, rendering-path analysis, bundle and network prioritization, and framework-aware delivery tradeoffs.
 
-**Run this before starting.** Try calling `navigate_page` or `performance_start_trace`. If unavailable, STOP—the chrome-devtools MCP server isn't configured.
+## When to Use
 
-Ask the user to add this to their MCP config:
+- Auditing or improving Core Web Vitals and page-load behavior.
+- Investigating slow rendering, hydration cost, bundle growth, or network waterfalls.
+- Prioritizing frontend performance work by measured impact.
+- Reviewing whether framework choices are helping or hurting delivery performance.
 
-```json
-"chrome-devtools": {
-  "type": "local",
-  "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
-}
-```
+## Instructions
 
-## Key Guidelines
+1. Measure first and identify the user-visible bottleneck.
+2. Separate document, network, bundle, render, and interaction causes.
+3. Fix the highest-impact path before touching low-value micro-optimizations.
+4. Verify the tradeoff does not regress accessibility, caching, or maintainability.
+5. Re-measure and report impact in concrete terms.
 
-- **Be assertive**: Verify claims by checking network requests, DOM, or codebase—then state findings definitively.
-- **Verify before recommending**: Confirm something is unused before suggesting removal.
-- **Quantify impact**: Use estimated savings from insights. Don't prioritize changes with 0ms impact.
-- **Skip non-issues**: If render-blocking resources have 0ms estimated impact, note but don't recommend action.
-- **Be specific**: Say "compress hero.png (450KB) to WebP" not "optimize images".
-- **Prioritize ruthlessly**: A site with 200ms LCP and 0 CLS is already excellent—say so.
+### Baseline standards
 
-## Quick Reference
+- Prioritize LCP, INP, and CLS with real bottleneck evidence.
+- Keep critical resources discoverable and cacheable.
+- Reduce hydration and JavaScript cost when server rendering can do the work.
+- Treat bundle size, network order, and rendering behavior as one system.
+- Prefer targeted fixes over generic “optimize everything” advice.
 
-| Task | Tool Call |
-|------|-----------|
-| Load page | `navigate_page(url: "...")` |
-| Start trace | `performance_start_trace(autoStop: true, reload: true)` |
-| Analyze insight | `performance_analyze_insight(insightSetId: "...", insightName: "...")` |
-| List requests | `list_network_requests(resourceTypes: ["Script", "Stylesheet", ...])` |
-| Request details | `get_network_request(reqid: <id>)` |
-| A11y snapshot | `take_snapshot(verbose: true)` |
+### Constraints
 
-## Workflow
+- Avoid recommending changes with no measured impact.
+- Avoid fixating on bundle size while ignoring render path or network ordering.
+- Avoid using performance tooling output without codebase context.
+- Avoid trading correctness or accessibility for tiny synthetic wins.
 
-Copy this checklist to track progress:
-
-```
-Audit Progress:
-- [ ] Phase 1: Performance trace (navigate + record)
-- [ ] Phase 2: Core Web Vitals analysis (includes CLS culprits)
-- [ ] Phase 3: Network analysis
-- [ ] Phase 4: Accessibility snapshot
-- [ ] Phase 5: Codebase analysis (skip if third-party site)
-```
-
-### Phase 1: Performance Trace
-
-1. Navigate to the target URL:
-   ```
-   navigate_page(url: "<target-url>")
-   ```
-
-2. Start a performance trace with reload to capture cold-load metrics:
-   ```
-   performance_start_trace(autoStop: true, reload: true)
-   ```
-
-3. Wait for trace completion, then retrieve results.
-
-**Troubleshooting:**
-- If trace returns empty or fails, verify the page loaded correctly with `navigate_page` first
-- If insight names don't match, inspect the trace response to list available insights
-
-### Phase 2: Core Web Vitals Analysis
-
-Use `performance_analyze_insight` to extract key metrics.
-
-**Note:** Insight names may vary across Chrome DevTools versions. If an insight name doesn't work, check the `insightSetId` from the trace response to discover available insights.
-
-Common insight names:
-
-| Metric | Insight Name | What to Look For |
-|--------|--------------|------------------|
-| LCP | `LCPBreakdown` | Time to largest contentful paint; breakdown of TTFB, resource load, render delay |
-| CLS | `CLSCulprits` | Elements causing layout shifts (images without dimensions, injected content, font swaps) |
-| Render Blocking | `RenderBlocking` | CSS/JS blocking first paint |
-| Document Latency | `DocumentLatency` | Server response time issues |
-| Network Dependencies | `NetworkRequestsDepGraph` | Request chains delaying critical resources |
-
-Example:
-```
-performance_analyze_insight(insightSetId: "<id-from-trace>", insightName: "LCPBreakdown")
-```
-
-**Key thresholds (good/needs-improvement/poor):**
-- TTFB: < 800ms / < 1.8s / > 1.8s
-- FCP: < 1.8s / < 3s / > 3s
-- LCP: < 2.5s / < 4s / > 4s
-- INP: < 200ms / < 500ms / > 500ms
-- TBT: < 200ms / < 600ms / > 600ms
-- CLS: < 0.1 / < 0.25 / > 0.25
-- Speed Index: < 3.4s / < 5.8s / > 5.8s
-
-### Phase 3: Network Analysis
-
-List all network requests to identify optimization opportunities:
-```
-list_network_requests(resourceTypes: ["Script", "Stylesheet", "Document", "Font", "Image"])
-```
-
-**Look for:**
-
-1. **Render-blocking resources**: JS/CSS in `<head>` without `async`/`defer`/`media` attributes
-2. **Network chains**: Resources discovered late because they depend on other resources loading first (e.g., CSS imports, JS-loaded fonts)
-3. **Missing preloads**: Critical resources (fonts, hero images, key scripts) not preloaded
-4. **Caching issues**: Missing or weak `Cache-Control`, `ETag`, or `Last-Modified` headers
-5. **Large payloads**: Uncompressed or oversized JS/CSS bundles
-6. **Unused preconnects**: If flagged, verify by checking if ANY requests went to that origin. If zero requests, it's definitively unused—recommend removal. If requests exist but loaded late, the preconnect may still be valuable.
-
-For detailed request info:
-```
-get_network_request(reqid: <id>)
-```
-
-### Phase 4: Accessibility Snapshot
-
-Take an accessibility tree snapshot:
-```
-take_snapshot(verbose: true)
-```
-
-**Flag high-level gaps:**
-- Missing or duplicate ARIA IDs
-- Elements with poor contrast ratios (check against WCAG AA: 4.5:1 for normal text, 3:1 for large text)
-- Focus traps or missing focus indicators
-- Interactive elements without accessible names
-
-## Phase 5: Codebase Analysis
-
-**Skip if auditing a third-party site without codebase access.**
-
-Analyze the codebase to understand where improvements can be made.
-
-### Detect Framework & Bundler
-
-Search for configuration files to identify the stack:
-
-| Tool | Config Files |
-|------|--------------|
-| Webpack | `webpack.config.js`, `webpack.*.js` |
-| Vite | `vite.config.js`, `vite.config.ts` |
-| Rollup | `rollup.config.js`, `rollup.config.mjs` |
-| esbuild | `esbuild.config.js`, build scripts with `esbuild` |
-| Parcel | `.parcelrc`, `package.json` (parcel field) |
-| Next.js | `next.config.js`, `next.config.mjs` |
-| Nuxt | `nuxt.config.js`, `nuxt.config.ts` |
-| SvelteKit | `svelte.config.js` |
-| Astro | `astro.config.mjs` |
-
-Also check `package.json` for framework dependencies and build scripts.
-
-### Tree-Shaking & Dead Code
-
-- **Webpack**: Check for `mode: 'production'`, `sideEffects` in package.json, `usedExports` optimization
-- **Vite/Rollup**: Tree-shaking enabled by default; check for `treeshake` options
-- **Look for**: Barrel files (`index.js` re-exports), large utility libraries imported wholesale (lodash, moment)
-
-### Unused JS/CSS
+## Output Format
 
-- Check for CSS-in-JS vs. static CSS extraction
-- Look for PurgeCSS/UnCSS configuration (Tailwind's `content` config)
-- Identify dynamic imports vs. eager loading
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### Polyfills
+## References
 
-- Check for `@babel/preset-env` targets and `useBuiltIns` setting
-- Look for `core-js` imports (often oversized)
-- Check `browserslist` config for overly broad targeting
+Load on demand. Do not preload all reference files.
 
-### Compression & Minification
+| File | Load when |
+| --- | --- |
+| `references/core-web-vitals-triage.md` | You need a stronger playbook for CWV bottleneck isolation, bundle/network/render tradeoffs, and verification after a fix. |
 
-- Check for `terser`, `esbuild`, or `swc` minification
-- Look for gzip/brotli compression in build output or server config
-- Check for source maps in production builds (should be external or disabled)
+## Scripts
 
-## Output Format
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
-Present findings as:
+## Examples
 
-1. **Core Web Vitals Summary** - Table with metric, value, and rating (good/needs-improvement/poor)
-2. **Top Issues** - Prioritized list of problems with estimated impact (high/medium/low)
-3. **Recommendations** - Specific, actionable fixes with code snippets or config changes
-4. **Codebase Findings** - Framework/bundler detected, optimization opportunities (omit if no codebase access)
+- "Help me with web perf best practices in this project"
+- "Review my web perf implementation for issues"

package/workflows/skills/web-perf/references/core-web-vitals-triage.md

@@ -0,0 +1,20 @@
+# Core Web Vitals Triage
+
+Load this when web performance work needs a more explicit process.
+
+## Measure first
+
+- Start with real bottleneck evidence: LCP, INP, CLS, bundle, waterfall, or render trace.
+- Separate document, network, bundle, render, and interaction causes.
+
+## Fix selection
+
+- Prioritize the highest user-visible bottleneck.
+- Reduce hydration and JavaScript cost when server rendering can do the work.
+- Keep cacheability, preload strategy, and render path aligned.
+
+## Verification
+
+- Re-measure after every meaningful change.
+- Check accessibility and correctness did not regress.
+- Report impact in concrete user-visible terms, not only lab-score movement.

package/workflows/skills/webapp-testing/SKILL.md

@@ -1,187 +1,66 @@
 ---
 name: webapp-testing
-description: Web application testing principles. E2E, Playwright, deep audit strategies.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+description: "Use when choosing test depth for a web product, balancing unit, integration, browser, accessibility, and contract checks, or reviewing whether a change has the right verification shape before release."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
-# Web App Testing
+# Webapp Testing
 
-> Discover and test everything. Leave no route untested.
+## Purpose
 
-## 🔧 Runtime Scripts
+Use when choosing test depth for a web product, balancing unit, integration, browser, accessibility, and contract checks, or reviewing whether a change has the right verification shape before release.
 
-**Execute these for automated browser testing:**
+## When to Use
 
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `scripts/playwright_runner.py` | Basic browser test | `python scripts/playwright_runner.py https://example.com` |
-| | With screenshot | `python scripts/playwright_runner.py <url> --screenshot` |
-| | Accessibility check | `python scripts/playwright_runner.py <url> --a11y` |
+- Planning verification depth for a web feature, refactor, bug fix, or release candidate.
+- Choosing what belongs in unit, component, integration, contract, or browser coverage.
+- Reviewing gaps in coverage, flaky suites, or low-signal tests.
+- Auditing whether a frontend or API change has enough evidence to merge safely.
 
-**Requires:** `pip install playwright && playwright install chromium`
+## Instructions
 
----
-
-## 1. Deep Audit Approach
-
-### Discovery First
-
-| Target | How to Find |
-|--------|-------------|
-| Routes | Scan app/, pages/, router files |
-| API endpoints | Grep for HTTP methods |
-| Components | Find component directories |
-| Features | Read documentation |
-
-### Systematic Testing
-
-1. **Map** - List all routes/APIs
-2. **Scan** - Verify they respond
-3. **Test** - Cover critical paths
-
----
-
-## 2. Testing Pyramid for Web
-
-```
-        /\          E2E (Few)
-       /  \         Critical user flows
-      /----\
-     /      \       Integration (Some)
-    /--------\      API, data flow
-   /          \
-  /------------\    Component (Many)
-                    Individual UI pieces
-```
-
----
-
-## 3. E2E Test Principles
-
-### What to Test
-
-| Priority | Tests |
-|----------|-------|
-| 1 | Happy path user flows |
-| 2 | Authentication flows |
-| 3 | Critical business actions |
-| 4 | Error handling |
-
-### E2E Best Practices
-
-| Practice | Why |
-|----------|-----|
-| Use data-testid | Stable selectors |
-| Wait for elements | Avoid flaky tests |
-| Clean state | Independent tests |
-| Avoid implementation details | Test user behavior |
-
----
-
-## 4. Playwright Principles
-
-### Core Concepts
-
-| Concept | Use |
-|---------|-----|
-| Page Object Model | Encapsulate page logic |
-| Fixtures | Reusable test setup |
-| Assertions | Built-in auto-wait |
-| Trace Viewer | Debug failures |
+1. Map the change surface to business risk, user-visible impact, and regression blast radius.
+2. Put the cheapest reliable check at the lowest layer that can prove the behavior.
+3. Add browser coverage only for flows that need cross-layer confidence.
+4. Pair coverage with deterministic fixtures, contract clarity, and failure evidence.
+5. Call out what remains manual, unverified, or risky instead of hiding gaps behind suite size.
 
-### Configuration
+### Baseline standards
 
-| Setting | Recommendation |
-|---------|----------------|
-| Retries | 2 on CI |
-| Trace | on-first-retry |
-| Screenshots | on-failure |
-| Video | retain-on-failure |
+- Test behavior users or dependent systems care about, not implementation trivia.
+- Keep component and integration checks faster and more numerous than browser tests.
+- Include accessibility and error-state coverage in critical paths, not only happy paths.
+- Prefer contract or integration checks for API correctness before adding UI duplication.
+- Treat flaky tests as defects in the product, test, or environment, not a permanent condition.
 
----
-
-## 5. Visual Testing
-
-### When to Use
-
-| Scenario | Value |
-|----------|-------|
-| Design system | High |
-| Marketing pages | High |
-| Component library | Medium |
-| Dynamic content | Lower |
-
-### Strategy
-
-- Baseline screenshots
-- Compare on changes
-- Review visual diffs
-- Update intentional changes
-
----
-
-## 6. API Testing Principles
-
-### Coverage Areas
-
-| Area | Tests |
-|------|-------|
-| Status codes | 200, 400, 404, 500 |
-| Response shape | Matches schema |
-| Error messages | User-friendly |
-| Edge cases | Empty, large, special chars |
+### Constraints
 
----
-
-## 7. Test Organization
-
-### File Structure
+- Avoid one-size-fits-all coverage targets with no risk model.
+- Avoid using browser tests to compensate for missing contract or unit design.
+- Avoid counting snapshots or shallow assertions as evidence of behavior correctness.
+- Avoid treating manual QA as a substitute for repeatable regression protection on critical paths.
 
-```
-tests/
-├── e2e/           # Full user flows
-├── integration/   # API, data
-├── component/     # UI units
-└── fixtures/      # Shared data
-```
+## Output Format
 
-### Naming Convention
-
-| Pattern | Example |
-|---------|---------|
-| Feature-based | `login.spec.ts` |
-| Descriptive | `user-can-checkout.spec.ts` |
-
----
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-## 8. CI Integration
+## References
 
-### Pipeline Steps
+Load on demand. Do not preload all reference files.
 
-1. Install dependencies
-2. Install browsers
-3. Run tests
-4. Upload artifacts (traces, screenshots)
+| File | Load when |
+| --- | --- |
+| `references/browser-api-state-checklist.md` | You need a deeper playbook for test-layer selection, accessibility coverage, API-vs-UI duplication, flaky-suite triage, or release gating for web apps. |
 
-### Parallelization
+## Scripts
 
-| Strategy | Use |
-|----------|-----|
-| Per file | Playwright default |
-| Sharding | Large suites |
-| Workers | Multiple browsers |
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
 
----
-
-## 9. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Test implementation | Test behavior |
-| Hardcode waits | Use auto-wait |
-| Skip cleanup | Isolate tests |
-| Ignore flaky tests | Fix root cause |
-
----
+## Examples
 
-> **Remember:** E2E tests are expensive. Use them for critical paths only.
+- "Help me with webapp testing best practices in this project"
+- "Review my webapp testing implementation for issues"

package/workflows/skills/webapp-testing/references/browser-api-state-checklist.md

@@ -0,0 +1,55 @@
+# Browser, API, and State Coverage Checklist
+
+Use this when the question is "what should we test, at which layer, and why?"
+
+## Choose the lowest reliable layer
+
+- Unit or component tests:
+  - rendering variants
+  - pure logic
+  - formatting and validation rules
+  - state reducer behavior
+- Integration or contract tests:
+  - API handlers
+  - auth middleware
+  - database-backed service flows
+  - background job boundaries
+- Browser tests:
+  - sign-in and sign-out
+  - checkout or payment confirmation
+  - multi-step onboarding
+  - flows where routing, JS, CSS, network, and auth must work together
+
+## Avoid duplicate assertions
+
+- If contract tests already prove status codes and payload shape, browser tests should focus on the user-visible outcome.
+- If component tests already prove rendering branches, E2E should validate the business flow, not every branch again.
+- If accessibility smoke coverage exists at the component or page layer, browser tests should target the high-risk interactive journeys.
+
+## Accessibility coverage
+
+For critical flows, verify:
+
+- keyboard navigation
+- visible focus states
+- semantic labels for key inputs and actions
+- error messaging tied to the control that failed
+- loading and success states that remain understandable to assistive technology
+
+## Failure evidence
+
+When a test fails, keep:
+
+- failing command or suite name
+- minimal reproduction path
+- screenshots or trace artifacts if browser-based
+- whether the failure is product, test, fixture, or environment related
+
+## Release gating
+
+Before merge or release, state:
+
+1. which layer proved the change
+2. which critical paths remain untested
+3. whether any known flakes or quarantined tests still affect confidence
+4. whether manual checks are still required