opencastle 0.32.12 → 0.32.13

package/src/orchestrator/plugins/astro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: astro-framework
-description: "Astro framework best practices for content-driven sites, islands architecture, routing, integrations, and project structure. Use when creating or modifying Astro pages, layouts, components, or content collections."
+description: "Creates pages/layouts, defines content collections, configures hydration directives, and wires integrations. Use when adding or modifying Astro pages, layouts, components, or content collections. Trigger terms: Astro, content collection, client:load, client:visible, astro:content"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -21,23 +21,22 @@ src/
 └── assets/      # processed images
 ```
 
-## Component Model
+## Implement Components
 
-**Default: Zero JS** — `.astro` components render to HTML with no client-side JavaScript.
+**Default: Zero JS** — author `.astro` components that render HTML with no client-side JavaScript where possible.
 
-**Islands Architecture** — Interactive components use `client:*` directives to hydrate only where needed.
+**Islands Architecture** — hydrate interactivity only where needed using `client:*` directives.
 
-### Astro Component Example
+### Component Example (concise)
 
 ```astro
 ---
 interface Props { title: string; description?: string; }
 const { title, description = 'Default description' } = Astro.props;
-const data = await fetch('https://api.example.com/data').then(r => r.json());
 ---
 <section>
   <h2>{title}</h2>
-  {data.items.map((item: { name: string }) => <li>{item.name}</li>)}
+  <p>{description}</p>
 </section>
 <style>
   section { max-width: 800px; margin: 0 auto; }
@@ -46,18 +45,22 @@ const data = await fetch('https://api.example.com/data').then(r => r.json());
 
 ### Client Directives (Islands)
 
-| Directive | When It Hydrates | Use Case |
-|-----------|-----------------|----------|
-| `client:load` | Immediately on page load | Critical interactive UI |
-| `client:idle` | After page is idle | Non-critical UI (analytics widgets) |
-| `client:visible` | When element enters viewport | Below-the-fold components |
-| `client:media="(max-width: 768px)"` | When media query matches | Mobile-only interactivity |
-| `client:only="react"` | Client-only, no SSR | Components that can't server-render |
+Use only the hydration directive required by the interaction to minimize shipped JS. Typical mappings:
 
-## Content Collections
+- `client:load` — immediate hydration for critical interactive widgets
+- `client:idle` — non-critical behavior after page idle
+- `client:visible` — hydrate when visible (lazy)
+- `client:media` — hydrate on media match
+- `client:only` — last resort for non-SSR-able components
 
-Define in `src/content.config.ts` (Astro v5+) using the Content Layer API:
+## Content Collections — Quick Workflow: add a new collection
+1. Add collection schema in `src/content.config.ts` using `defineCollection` and Zod validators.
+2. Create the folder under `src/content/<collection>` and add one sample `.md` or `.mdx` content file with frontmatter.
+3. Run `pnpm build` and `pnpm dev` → run `node scripts/validate-content.js` (or your project's validation script) to verify typed collection imports.
+4. Add a smoke query in a page that imports the collection (e.g., `const posts = await getCollection('blog')`) and confirm build-time typing.
+5. Validation: ensure `pnpm build` exits zero and TypeScript reports no errors for collection types.
 
+Define collections in `src/content.config.ts` (Astro v5+) using `astro:content` and export typed collections.
 ```ts
 import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
@@ -117,16 +120,6 @@ Use `astro add` for react, tailwind, mdx, sitemap, node, vercel, netlify, cloudf
 - **API routes**: Export `GET`/`POST` handlers from `src/pages/api/*.ts` returning `new Response(...)`.
 - **Actions**: Use `defineAction` in `src/actions/index.ts` for type-safe server mutations with Zod validation.
 
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Wrong | Do This Instead |
-|-------------|---------------|-----------------|
-| `client:load` on every component | Defeats zero-JS benefit, bloats bundle | Use `client:idle` or `client:visible` for non-critical UI |
-| Importing large JS libraries in `.astro` | Runs at build but bundles nothing useful | Import in framework components with `client:*` |
-| Skipping content collections for blog/docs | Manual file handling is error-prone | Use content collections with typed schemas |
-| Hardcoding data in pages | Not maintainable, no type safety | Use content collections or fetch from APIs |
-| Using `client:only` when SSR works | Loses SEO benefits and fast first paint | Use `client:load` or `client:visible` instead |
-| Giant monolithic pages | Hard to maintain and test | Split into layouts + reusable components |
-| Ignoring `astro add` for integrations | Manual config is error-prone | Use `astro add` for official integrations |
-| Missing `alt` on images | Accessibility violation | Always provide descriptive `alt` text |
-| Not using `astro:assets` for images | Missing optimization | Use `<Image>` from `astro:assets` |
+## Anti-Patterns (moved to REFERENCE.md)
+
+Extracted anti-patterns and SSR configuration details are available in `REFERENCE.md` in this directory to keep this skill focused and concise.

package/src/orchestrator/plugins/chrome-devtools/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Chrome DevTools MCP commands and responsive checklist
+
+- Full MCP command table with parameter examples and common payload shapes
+- Responsive verification scripts and `evaluate_script()` snippets
+- Performance trace capture and analysis commands

package/src/orchestrator/plugins/chrome-devtools/SKILL.md

@@ -1,27 +1,14 @@
 ---
 name: browser-testing
-description: "Chrome DevTools MCP automation patterns for validating UI changes in real browsers. Use when performing E2E browser testing, validating visual changes, testing user interactions, or debugging UI issues with Chrome DevTools."
+description: "Drive real browsers via Chrome DevTools MCP: navigate pages, capture snapshots, run responsive checks, and collect console/perf traces. Use when the user mentions: 'validate UI change in Chrome', 'capture a screenshot', 'run responsive checks', or 'collect console logs'. Trigger terms: browser testing, DevTools, console logs, screenshot, responsive testing"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Browser Testing with Chrome DevTools MCP
 
-Generic browser testing methodology using Chrome DevTools MCP. For project-specific test app, selectors, suites, and breakpoint config, see [testing-config.md](../../.opencastle/stack/testing-config.md).
+For project-specific test app, selectors, suites, and breakpoint config, see [testing-config.md](../../.opencastle/stack/testing-config.md).
 
-## Purpose
-
-After any UI change, validate in a real browser:
-1. Start dev server if not running.
-2. Navigate to affected pages.
-3. Interact with UI elements (click, fill, filter).
-4. Validate behavior and appearance.
-5. Test edge cases (empty states, errors, boundaries).
-6. Document findings with screenshots and pass/fail.
-
-## Pre-Test Build Verification
-
-**CRITICAL: Always build before browser testing.** Testing stale code wastes time. See [testing-config.md](../../.opencastle/stack/testing-config.md) for the specific build and serve commands.
 
 ## Chrome MCP Tools Reference
 
@@ -85,30 +72,27 @@ mcp_chrome-devtoo_performance_analyze_insight({ insightSetId: 'set_id', insightN
 
 ### 1. Setup
 
-Start the dev server (see [testing-config.md](../../.opencastle/stack/testing-config.md) for app and port).
+Start the dev server.
 
 ### 2. Initial State
 
 ```javascript
 mcp_chrome-devtoo_navigate_page({ type: 'url', url: 'http://localhost:<port>/places' })
 mcp_chrome-devtoo_wait_for({ text: 'places' })
+// If wait_for times out: verify dev server is running and URL is correct
 mcp_chrome-devtoo_evaluate_script({
   function: '() => ({ url: window.location.href, title: document.title })'
 })
 ```
 
-### 3. Test Interactions
+### 3–4. Test Interactions & Edge Cases
 
 ```javascript
 mcp_chrome-devtoo_click({ uid: 'filter_uid' })
 mcp_chrome-devtoo_evaluate_script({
   function: '() => document.querySelectorAll(".place-card").length'
 })
-```
-
-### 4. Test Edge Cases
 
-```javascript
 mcp_chrome-devtoo_navigate_page({
   type: 'url', url: 'http://localhost:<port>/places?q=nonexistent-venue-xyz'
 })
@@ -121,11 +105,12 @@ mcp_chrome-devtoo_evaluate_script({
 
 ```javascript
 mcp_chrome-devtoo_list_console_messages()
+// If errors found: fix source, rebuild, reload page, and re-run from step 2
 ```
 
-### 6. Responsive Breakpoint Testing (MANDATORY)
+### 6. Responsive Breakpoint Testing
 
-**Every UI change MUST be tested at all responsive breakpoints.** Do not test at desktop only — most layout bugs surface at smaller viewports. Define your breakpoints in your project's testing config (e.g., `testing-config.md`).
+Test every UI change at all responsive breakpoints — most layout bugs surface at smaller viewports. Define breakpoints in your project's testing config.
 
 #### How to Resize
 
@@ -138,24 +123,8 @@ mcp_chrome-devtoo_resize_page({ width: 1440, height: 900 })  // Desktop
 
 #### Per-Breakpoint Verification
 
-#### Per-Breakpoint Verification
-
-At **each** breakpoint, check:
-
-- [ ] Layout adapts correctly — no horizontal overflow
-- [ ] Text truncates or wraps cleanly — no overlap
-- [ ] Interactive elements have adequate spacing and touch targets
-- [ ] Navigation and panels collapse/expand as expected
-- [ ] Images and cards resize proportionally
-
-#### Responsive Testing Anti-Patterns
-
-| Anti-Pattern | Correct Approach |
-|---|---|
-| Testing only at desktop width | Test at all project-defined breakpoints |
-| Skipping resize because "it uses Tailwind" | Tailwind classes can be wrong — always verify visually |
-| Only checking layout, not interactions | Test filter drawers, dropdowns, and modals at each size |
-| Taking 3 screenshots (one per breakpoint) | Use `evaluate_script()` to check layout; save screenshots for failures |
+- Verify interactions at each size (not layout only)
+- Prefer `evaluate_script()` assertions over screenshots; reserve screenshots for failures
 
 ## Regression Re-Test Workflow
 
@@ -169,20 +138,6 @@ When re-testing after a fix:
 
 If any test still fails: analyze, fix, repeat. Do NOT stop.
 
-## Validation Checklist
-
-- [ ] Page loads without errors (check console)
-- [ ] Changed component renders correctly
-- [ ] Interactive elements respond to clicks/input
-- [ ] Filters/sorting produce correct results
-- [ ] URL parameters sync with UI state
-- [ ] Empty states display when appropriate
-- [ ] Error states handle gracefully
-- [ ] Loading states appear during async operations
-- [ ] Keyboard navigation works, focus is visible
-- [ ] **Responsive: Tested at Mobile, Tablet, and Desktop breakpoints**
-- [ ] **Responsive: No horizontal overflow at any breakpoint**
-- [ ] **Responsive: Interactions work at every breakpoint (drawers, dropdowns, modals)**
 
 ## Context Management
 

package/src/orchestrator/plugins/contentful/REFERENCE.md

@@ -0,0 +1,16 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Contentful Reference (REFERENCE.md)
+
+Last Updated: 2026-03-31
+
+## Migration & Rollback Patterns
+
+- Best safe rollback: perform migrations in a sandbox environment and validate before promoting to `master`. If a migration is faulty, delete the sandbox and recreate it from `master` then re-run a corrected migration.
+- Advanced rollback: write reverse migrations that undo schema changes (when feasible) and test them in sandbox.
+
+## Validation Checklist
+
+1. Query a representative sample of entries after migration and confirm required fields and unique constraints.
+2. Run the site's build against sandbox content to catch runtime rendering issues.
+3. Run integration tests that depend on the modified content types.

package/src/orchestrator/plugins/contentful/SKILL.md

@@ -1,45 +1,85 @@
 ---
 name: contentful-cms
-description: "Contentful CMS development patterns, GraphQL/REST API usage, content modeling, and migration best practices. Use when working with Contentful content types, entries, assets, or the Management API."
+description: "Creates Contentful content types, queries entries via GraphQL/REST, runs CLI migrations, and manages assets and locales. Use when building or modifying Contentful content models, writing queries, or migrating content."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Contentful CMS
 
-Generic Contentful CMS development methodology. For project-specific configuration, content types, and API keys, see [cms-config.md](../../.opencastle/stack/cms-config.md).
-
-## Critical Development Rules
-
-1. **Always use Content Types** — define structured content types before creating entries
-2. **Prefer GraphQL API** — use the GraphQL Content API for typed, efficient queries
-3. **Handle localization** — Contentful fields can be localized; always specify locale in queries
-4. **Use environments** — develop in sandbox environments, promote to master via migrations
-5. **Migration scripts** — use the Contentful CLI migration tool for schema changes, never modify content types manually in production
-6. **Rich Text rendering** — use `@contentful/rich-text-react-renderer` for React apps
-7. **Asset handling** — use Contentful's Image API for responsive images with transformations
-8. **Webhook-driven** — use webhooks for cache invalidation and rebuild triggers
-9. **Rate limiting** — respect API rate limits (Content Delivery: 78 req/s, Management: 10 req/s)
-10. **Keep queries in shared library** — queries belong in a shared queries library, never inline in components
+For project-specific configuration, content types, and API keys, see [cms-config.md](../../.opencastle/stack/cms-config.md).
 
 ## Query Patterns
 
 ### GraphQL Content API
-- Use typed GraphQL queries with code generation
 - Leverage `sys.publishedAt` for cache invalidation
 - Use `include` parameter to control link resolution depth
-- Filter with `where` clauses for efficient data fetching
 
-### REST Content Delivery API
-- Use `content_type` parameter to filter by type
-- Use `select` to limit returned fields
-- Use `links_to_entry` for reverse lookups
-- Handle pagination with `skip` and `limit`
+```typescript
+// Example: Typed GraphQL query
+const BLOG_POSTS_QUERY = `
+  query BlogPosts($limit: Int!, $locale: String!) {
+    blogPostCollection(limit: $limit, locale: $locale) {
+      items {
+        sys { id publishedAt }
+        title
+        slug
+        body { json }
+        featuredImage { url width height }
+      }
+    }
+  }
+`;
+```
 
 ## Content Modeling
 
-- Use **references** for relationships between content types
-- Prefer **short text** over **long text** for searchable fields
-- Use **JSON fields** sparingly — prefer structured content types
-- Design for **reusability** — create component content types for shared UI patterns
-- Use **validation rules** on fields to enforce data quality
+```javascript
+// Reference field with validation
+blogPost.createField('author')
+  .type('Link').linkType('Entry')
+  .validations([{ linkContentType: ['person'] }]);
+```
+
+Prefer typed content types over JSON fields; add validation rules to all required fields.
+
+## Migration Workflow
+
+1. Create a sandbox environment using the Contentful web UI or API.
+2. Write a migration script using the Contentful migration library (example below).
+3. Run the migration against the sandbox:
+
+```bash
+contentful space migration --space-id <SPACE_ID> --environment-id sandbox migration.js
+```
+
+4. Validate changes:
+  - Run a small validation script that queries a sample of affected entries and ensures required fields exist.
+   - If validation fails: roll back by deleting the sandbox and recreate from `master` (safe rollback), or write a reverse migration and run it.
+5. When sandbox validation passes, promote the environment or run the migration against `master` during a maintenance window.
+
+```javascript
+// Example: Migration script (migration.js)
+module.exports = function (migration) {
+  const blogPost = migration.createContentType('blogPost')
+    .name('Blog Post')
+    .displayField('title');
+  blogPost.createField('title').type('Symbol').required(true);
+  blogPost.createField('slug').type('Symbol').required(true).validations([{ unique: true }]);
+  blogPost.createField('body').type('RichText');
+};
+```
+
+Validation script example (node):
+
+```js
+// validate.js — exits non-zero on missing fields
+const res = await fetch(`https://cdn.contentful.com/spaces/${SPACE}/environments/sandbox/entries?content_type=blogPost`, {
+  headers: { Authorization: `Bearer ${TOKEN}` },
+});
+const { items } = await res.json();
+for (const item of items) {
+  if (!item.fields.slug) throw new Error(`Missing slug on ${item.sys.id}`);
+}
+console.log('OK —', items.length, 'entries validated');
+```
+
+For longer migration patterns and rollback options see [REFERENCE.md](REFERENCE.md).

package/src/orchestrator/plugins/convex/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Convex patterns and safety checks
+
+- Schema migration checklist and `npx convex deploy` notes
+- Query/mutation examples with `returns` validators
+- Backup/rollback using `npx convex export` / `npx convex import`

package/src/orchestrator/plugins/convex/SKILL.md

@@ -7,7 +7,7 @@ description: "Convex reactive database patterns, schema design, real-time querie
 
 # Convex Database
 
-Generic Convex development methodology. For project-specific schema, functions, and deployment details, see [database-config.md](../../.opencastle/stack/database-config.md).
+For project-specific schema, functions, and deployment details, see [database-config.md](../../.opencastle/stack/database-config.md).
 
 ## Critical Development Rules
 
@@ -106,3 +106,15 @@ export const create = mutation({
 - Use `npx convex dev` for local development with hot reload
 - Schema changes are automatically migrated
 - Use `npx convex import` / `npx convex export` for data management
+
+## Quick Workflow: Implement a schema change and deploy
+1. Add or modify schema in `convex/schema.ts` and run `npx convex dev` locally; confirm the dev server starts and responds (checkpoint: `http://localhost:8888` or the configured port). Run a small validation script or sample queries to verify schema changes (validation checkpoint).
+2. Write queries/mutations with `returns` validators and unit test against the dev server.
+3. Run `npx convex deploy` to push the change to production.
+4. Verify real-time queries in the app, run a small data migration if required (`convex import/export`), and run a quick smoke check against your app (example):
+
+```bash
+curl -fsS https://<APP_URL>/health || (echo "health check failed" && exit 1)
+```
+
+If an issue occurs: roll back via `npx convex import` of the last good export, fix locally, and re-deploy. After a rollback, re-run the same smoke check to confirm services are restored.

package/src/orchestrator/plugins/cypress/REFERENCE.md

@@ -0,0 +1,5 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Cypress REFERENCE: CI snippets, extended `cypress.config.ts` examples, and selector strategies.
+
+Use this file for large examples referenced from `SKILL.md` to keep the skill concise.

package/src/orchestrator/plugins/cypress/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: cypress-testing
-description: "Cypress E2E and component testing patterns, commands, selectors, and CI configuration. Use when writing E2E tests, component tests, or configuring Cypress in CI pipelines."
+description: "Writes Cypress E2E/component tests, configures `cy.intercept()` and `cy.session()`, authors custom commands, and wires CI artifacts. Use when creating E2E specs, component tests, or CI test pipelines. Trigger terms: cypress, e2e, component test, cy.intercept, cy.session"
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Cypress Testing
 
 Cypress-specific E2E and component testing patterns. For project-specific test configuration and breakpoints, see [testing-config.md](../../.opencastle/stack/testing-config.md).
@@ -12,46 +10,36 @@ Cypress-specific E2E and component testing patterns. For project-specific test c
 ## Commands
 
 ```bash
-npx cypress open                   # Open interactive test runner
-npx cypress run                    # Run tests headlessly (CI)
-npx cypress run --spec "cypress/e2e/auth/**"  # Run specific specs
-npx cypress run --browser chrome   # Specify browser
-npx cypress run --headed           # Run with visible browser
-npx cypress run --component        # Run component tests only
-npx cypress run --record           # Record to Cypress Cloud
+# Interactive runner
+npx cypress open
+
+# Headless run (CI) — target a specific spec with --spec when needed
+npx cypress run
 ```
 
+## Workflow (install → add data-testid → write → run → CI)
+
+1. Install and verify: `npm install --save-dev cypress` then `npx cypress verify`.
+2. Add `data-testid` attributes to key elements. Write custom commands in `cypress/support/commands.ts`, configure `cy.intercept()` stubs, and author fixtures under `cypress/fixtures/`.
+3. Write focused tests under `cypress/e2e/` using `data-testid` selectors. After authoring a spec, validate the setup by running a single spec: `npx cypress run --spec "cypress/e2e/auth/login.cy.ts" --headed` (quick smoke check).
+4. Run locally: `npx cypress open` (interactive) or `npx cypress run` (headless). If a spec fails, re-run the failing spec directly and inspect `cypress/screenshots/` and `cypress/videos/` for evidence.
+5. CI: `npx cypress run` — assert exit code 0; upload videos/screenshots on failures.
+
+
 ## Test Structure
 
-```
-cypress/
-├── e2e/                     # E2E test specs
-│   ├── auth/
-│   │   ├── login.cy.ts
-│   │   └── signup.cy.ts
-│   └── dashboard/
-│       └── overview.cy.ts
-├── fixtures/                # Test data (JSON)
-│   └── users.json
-├── support/
-│   ├── commands.ts          # Custom commands
-│   ├── e2e.ts               # E2E support file
-│   └── component.ts         # Component test support
-└── downloads/               # Downloaded files during tests
-```
+Tests: `cypress/e2e/`  •  Fixtures: `cypress/fixtures/`  •  Commands: `cypress/support/commands.ts`
 
 ## Writing Tests
 
-### E2E Test Pattern
+### E2E Test Pattern (single focused spec)
 
 ```typescript
 // cypress/e2e/auth/login.cy.ts
 describe('Login', () => {
-  beforeEach(() => {
-    cy.visit('/login');
-  });
+  beforeEach(() => cy.visit('/login'));
 
-  it('should log in with valid credentials', () => {
+  it('logs in with valid credentials and lands on dashboard', () => {
     cy.get('[data-testid="email-input"]').type('user@example.com');
     cy.get('[data-testid="password-input"]').type('password123');
     cy.get('[data-testid="login-button"]').click();
@@ -59,14 +47,6 @@ describe('Login', () => {
     cy.url().should('include', '/dashboard');
     cy.get('[data-testid="user-menu"]').should('be.visible');
   });
-
-  it('should show error for invalid credentials', () => {
-    cy.get('[data-testid="email-input"]').type('wrong@example.com');
-    cy.get('[data-testid="password-input"]').type('wrong');
-    cy.get('[data-testid="login-button"]').click();
-
-    cy.get('[data-testid="error-message"]').should('contain', 'Invalid credentials');
-  });
 });
 ```
 
@@ -87,59 +67,15 @@ Cypress.Commands.add('login', (email: string, password: string) => {
 
 ## Selector Strategy
 
-Priority order for selecting elements:
-
-1. `data-testid` attributes — most resilient to UI changes
-2. `aria-label` or `role` — accessible and meaningful
-3. Dedicated CSS classes — avoid styling classes
-4. **Never** use tag names, auto-generated classes, or fragile CSS paths
-
-## Best Practices
-
-- Use `cy.intercept()` to stub/spy on API calls — don't depend on backend state
-- Use `cy.session()` for authentication — avoid logging in before every test
-- Avoid `cy.wait(ms)` — use `cy.intercept()` with aliases instead
-- Assert on visible elements — Cypress auto-retries, so assertions are resilient
-- Keep tests independent — each test should set up its own state
-- Use fixtures for test data — avoid hardcoding values in tests
-- Add `data-testid` attributes to components during development, not retroactively
-
-## CI Configuration
-
-```yaml
-# GitHub Actions example
-cypress:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: cypress-io/github-action@v6
-      with:
-        build: npm run build
-        start: npm run start
-        wait-on: 'http://localhost:3000'
-        browser: chrome
-```
+Priority: prefer `data-testid`, then `aria-*` attributes or `role`. Avoid fragile selectors (auto-generated classes, deep CSS paths). See [REFERENCE.md](REFERENCE.md) for CI selector consistency rules.
 
-## Configuration (cypress.config.ts)
+## Best Practices (Cypress-specific and non-obvious)
 
-```typescript
-import { defineConfig } from 'cypress';
-
-export default defineConfig({
-  e2e: {
-    baseUrl: 'http://localhost:3000',
-    viewportWidth: 1280,
-    viewportHeight: 720,
-    video: false,
-    screenshotOnRunFailure: true,
-    defaultCommandTimeout: 10000,
-    retries: { runMode: 2, openMode: 0 },
-  },
-  component: {
-    devServer: {
-      framework: 'next',
-      bundler: 'webpack',
-    },
-  },
-});
-```
+- Prefer `cy.intercept()` with deterministic fixture payloads over test-time seeding for flaky network scenarios
+- Use `cy.session()` with serialized auth state to speed repeatable suites; persist and reuse tokens across related specs
+- Use route alias scoping (unique `@alias` names per spec) to avoid cross-test waits when running in parallel
+
+
+For CI pipeline examples and `cypress.config.ts` snippets, see [REFERENCE.md](REFERENCE.md).
+
+For advanced configuration examples and CI optimizations, see [REFERENCE.md](REFERENCE.md).

package/src/orchestrator/plugins/figma/REFERENCE.md

@@ -0,0 +1,18 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+### Figma → CSS Translation Rules (reference)
+
+| Figma Concept | Code Equivalent |
+|---------------|----------------|
+| Auto Layout → horizontal | `display: flex; flex-direction: row` |
+| Auto Layout → vertical | `display: flex; flex-direction: column` |
+| Auto Layout gap | `gap: Npx` |
+| Auto Layout padding | `padding: top right bottom bottom` |
+| Fill → Hug contents | `width: auto` or `width: fit-content` |
+| Fill → Fixed | `width: Npx` |
+| Fill → Fill container | `flex: 1` or `width: 100%` |
+| Corner radius | `border-radius: Npx` |
+| Drop shadow | `box-shadow: x y blur spread color` |
+| Opacity | `opacity: N` |
+
+Examples and extended mapping (spacing, typography, effects) live here for agent consumption.