@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/plan-writing/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
+allowed-tools: Read, Glob, Grep
+---
+
+# Plan Writing
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
+
+## Task Breakdown Principles
+
+### 1. Small, Focused Tasks
+- Each task should take 2-5 minutes
+- One clear outcome per task
+- Independently verifiable
+
+### 2. Clear Verification
+- How do you know it's done?
+- What can you check/test?
+- What's the expected output?
+
+### 3. Logical Ordering
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Phase X: Verification is always LAST**
+
+### 4. Dynamic Naming in Project Root
+- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
+- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- **NEVER** inside `.claude/`, `docs/`, or temp folders
+
+## Planning Principles (NOT Templates!)
+
+> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+
+### Principle 1: Keep It SHORT
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+
+> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+
+---
+
+### Principle 2: Be SPECIFIC, Not Generic
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Set up project" | "Run `npx create-next-app`" |
+| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
+| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
+
+> **Rule:** Each task should have a clear, verifiable outcome.
+
+---
+
+### Principle 3: Dynamic Content Based on Project Type
+
+**For NEW PROJECT:**
+- What tech stack? (decide first)
+- What's the MVP? (minimal features)
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Scripts Are Project-Specific
+
+> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
+
+| Project Type | Relevant Scripts |
+|--------------|------------------|
+| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
+| Backend/API | `api_validator.py`, `security_scan.py` |
+| Mobile | `mobile_audit.py` |
+| Database | `schema_validator.py` |
+| Full-stack | Mix of above based on what you touched |
+
+**Wrong:** Adding all scripts to every plan
+**Right:** Only scripts relevant to THIS task
+
+---
+
+### Principle 5: Verification is Simple
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
+| "Test the API" | "curl localhost:3000/api/users returns 200" |
+| "Check styles" | "Open browser, verify dark mode toggle works" |
+
+---
+
+## Plan Structure (Flexible, Not Fixed!)
+
+```
+# [Task Name]
+
+## Goal
+One sentence: What are we building/fixing?
+
+## Tasks
+- [ ] Task 1: [Specific action] → Verify: [How to check]
+- [ ] Task 2: [Specific action] → Verify: [How to check]
+- [ ] Task 3: [Specific action] → Verify: [How to check]
+
+## Done When
+- [ ] [Main success criteria]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+> Keep it minimal. Add complexity only when required.
+
+## Notes
+[Any important considerations]
+```
+
+---
+
+## Best Practices (Quick Reference)
+
+1. **Start with goal** - What are we building/fixing?
+2. **Max 10 tasks** - If more, break into multiple plans
+3. **Each task verifiable** - Clear "done" criteria
+4. **Project-specific** - No copy-paste templates
+5. **Update as you go** - Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/playwright-expert/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: playwright-expert
+description: Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke for browser automation, E2E tests, Page Object Model, test flakiness, visual testing.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: quality
+  triggers: Playwright, E2E test, end-to-end, browser testing, automation, UI testing, visual testing
+  role: specialist
+  scope: testing
+  output-format: code
+  related-skills: test-master, react-expert, devops-engineer
+---
+
+# Playwright Expert
+
+Senior E2E testing specialist with deep expertise in Playwright for robust, maintainable browser automation.
+
+## Role Definition
+
+You are a senior QA automation engineer with 8+ years of browser testing experience. You specialize in Playwright test architecture, Page Object Model, and debugging flaky tests. You write reliable, fast tests that run in CI/CD.
+
+## When to Use This Skill
+
+- Writing E2E tests with Playwright
+- Setting up Playwright test infrastructure
+- Debugging flaky browser tests
+- Implementing Page Object Model
+- API mocking in browser tests
+- Visual regression testing
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify user flows to test
+2. **Setup** - Configure Playwright with proper settings
+3. **Write tests** - Use POM pattern, proper selectors, auto-waiting
+4. **Debug** - Fix flaky tests, use traces
+5. **Integrate** - Add to CI/CD pipeline
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Selectors | `references/selectors-locators.md` | Writing selectors, locator priority |
+| Page Objects | `references/page-object-model.md` | POM patterns, fixtures |
+| API Mocking | `references/api-mocking.md` | Route interception, mocking |
+| Configuration | `references/configuration.md` | playwright.config.ts setup |
+| Debugging | `references/debugging-flaky.md` | Flaky tests, trace viewer |
+
+## Constraints
+
+### MUST DO
+- Use role-based selectors when possible
+- Leverage auto-waiting (don't add arbitrary timeouts)
+- Keep tests independent (no shared state)
+- Use Page Object Model for maintainability
+- Enable traces/screenshots for debugging
+- Run tests in parallel
+
+### MUST NOT DO
+- Use `waitForTimeout()` (use proper waits)
+- Rely on CSS class selectors (brittle)
+- Share state between tests
+- Ignore flaky tests
+- Use `first()`, `nth()` without good reason
+
+## Output Templates
+
+When implementing Playwright tests, provide:
+1. Page Object classes
+2. Test files with proper assertions
+3. Fixture setup if needed
+4. Configuration recommendations
+
+## Knowledge Reference
+
+Playwright, Page Object Model, auto-waiting, locators, fixtures, API mocking, trace viewer, visual comparisons, parallel execution, CI/CD integration

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/playwright-expert/references/api-mocking.md

@@ -0,0 +1,140 @@
+# API Mocking
+
+## Basic Route Mocking
+
+```typescript
+test('displays mocked user data', async ({ page }) => {
+  await page.route('**/api/users', route =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+      ]),
+    })
+  );
+
+  await page.goto('/users');
+  await expect(page.getByText('Alice')).toBeVisible();
+  await expect(page.getByText('Bob')).toBeVisible();
+});
+```
+
+## Mock Error Responses
+
+```typescript
+test('handles API error gracefully', async ({ page }) => {
+  await page.route('**/api/users', route =>
+    route.fulfill({
+      status: 500,
+      body: JSON.stringify({ error: 'Server error' }),
+    })
+  );
+
+  await page.goto('/users');
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+});
+```
+
+## Conditional Mocking
+
+```typescript
+test('mock specific requests', async ({ page }) => {
+  await page.route('**/api/**', route => {
+    const url = route.request().url();
+
+    if (url.includes('/api/users')) {
+      return route.fulfill({
+        status: 200,
+        json: [{ id: 1, name: 'Mocked User' }],
+      });
+    }
+
+    // Let other requests through
+    return route.continue();
+  });
+});
+```
+
+## Modify Responses
+
+```typescript
+test('modify API response', async ({ page }) => {
+  await page.route('**/api/products', async route => {
+    // Get real response
+    const response = await route.fetch();
+    const json = await response.json();
+
+    // Modify it
+    json.products = json.products.map(p => ({
+      ...p,
+      price: p.price * 0.9, // 10% discount
+    }));
+
+    // Return modified response
+    await route.fulfill({ json });
+  });
+});
+```
+
+## Wait for Response
+
+```typescript
+test('waits for API response', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  await page.getByRole('button', { name: 'Load Users' }).click();
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+```
+
+## Mock Network Conditions
+
+```typescript
+test('slow network', async ({ page }) => {
+  await page.route('**/api/**', async route => {
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    await route.continue();
+  });
+
+  await page.goto('/dashboard');
+  await expect(page.getByText('Loading...')).toBeVisible();
+});
+```
+
+## HAR File Mocking
+
+```typescript
+// Record responses
+await page.routeFromHAR('mocks/api.har', {
+  url: '**/api/**',
+  update: true, // Record new responses
+});
+
+// Playback recorded responses
+await page.routeFromHAR('mocks/api.har', {
+  url: '**/api/**',
+  update: false,
+});
+```
+
+## Quick Reference
+
+| Method | Purpose |
+|--------|---------|
+| `route.fulfill()` | Return mock response |
+| `route.continue()` | Pass to real server |
+| `route.fetch()` | Get real response |
+| `route.abort()` | Block request |
+| `waitForResponse()` | Wait for API call |
+| `routeFromHAR()` | Use recorded responses |
+
+| Pattern | Use Case |
+|---------|----------|
+| Mock all | Isolated testing |
+| Mock errors | Error handling |
+| Modify response | Test edge cases |
+| Network delay | Loading states |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/playwright-expert/references/configuration.md

@@ -0,0 +1,155 @@
+# Configuration
+
+## Full Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html'],
+    ['json', { outputFile: 'results.json' }],
+    ['junit', { outputFile: 'results.xml' }],
+  ],
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    testIdAttribute: 'data-testid',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+## Authentication Setup
+
+```typescript
+// global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  await page.goto('http://localhost:3000/login');
+  await page.getByLabel('Email').fill('user@test.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Log in' }).click();
+  await page.waitForURL(/dashboard/);
+
+  // Save auth state
+  await page.context().storageState({ path: 'auth.json' });
+  await browser.close();
+}
+
+export default globalSetup;
+
+// playwright.config.ts
+export default defineConfig({
+  globalSetup: require.resolve('./global-setup'),
+  use: {
+    storageState: 'auth.json',
+  },
+});
+```
+
+## Project Dependencies
+
+```typescript
+projects: [
+  {
+    name: 'setup',
+    testMatch: /global.setup\.ts/,
+  },
+  {
+    name: 'chromium',
+    use: { ...devices['Desktop Chrome'] },
+    dependencies: ['setup'],
+  },
+],
+```
+
+## Environment Variables
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+  },
+});
+
+// .env
+BASE_URL=https://staging.example.com
+```
+
+## CI Configuration
+
+```yaml
+# .github/workflows/playwright.yml
+name: Playwright Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Quick Reference
+
+| Option | Purpose |
+|--------|---------|
+| `testDir` | Test files location |
+| `fullyParallel` | Run tests in parallel |
+| `retries` | Retry failed tests |
+| `trace` | Record trace on failure |
+| `webServer` | Start dev server |
+| `globalSetup` | Run before all tests |
+| `storageState` | Reuse auth state |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/playwright-expert/references/debugging-flaky.md

@@ -0,0 +1,150 @@
+# Debugging & Flaky Tests
+
+## Debugging Tools
+
+```typescript
+// Pause execution and open inspector
+await page.pause();
+
+// Enable step-by-step mode
+PWDEBUG=1 npx playwright test
+
+// Slow motion
+test.use({ launchOptions: { slowMo: 500 } });
+
+// Headed mode
+npx playwright test --headed
+```
+
+## Trace Viewer
+
+```bash
+# View trace from failed test
+npx playwright show-trace trace.zip
+
+# Generate trace always
+test.use({ trace: 'on' });
+
+# View in UI mode
+npx playwright test --ui
+```
+
+## Common Flaky Test Causes
+
+### 1. Race Conditions
+
+```typescript
+// ❌ Bad: Element may not exist yet
+await page.click('.submit-btn');
+
+// ✅ Good: Auto-waiting built in
+await page.getByRole('button', { name: 'Submit' }).click();
+```
+
+### 2. Animation/Transitions
+
+```typescript
+// ❌ Bad: Click during animation
+await page.click('.menu-item');
+
+// ✅ Good: Wait for stable state
+await page.getByRole('menuitem').click();
+await expect(page.getByRole('menu')).toBeVisible();
+```
+
+### 3. Network Timing
+
+```typescript
+// ❌ Bad: Assumes data loaded
+await page.goto('/dashboard');
+expect(await page.textContent('.user-name')).toBe('John');
+
+// ✅ Good: Wait for network
+await page.goto('/dashboard');
+await page.waitForResponse('**/api/user');
+await expect(page.getByTestId('user-name')).toHaveText('John');
+```
+
+### 4. Test Isolation
+
+```typescript
+// ❌ Bad: Tests share state
+test('test 1', async () => { /* creates user */ });
+test('test 2', async () => { /* assumes user exists */ });
+
+// ✅ Good: Each test is independent
+test.beforeEach(async ({ page }) => {
+  await page.request.post('/api/test/reset');
+});
+```
+
+## Proper Waiting
+
+```typescript
+// Wait for element state
+await expect(page.getByText('Success')).toBeVisible();
+await expect(page.getByRole('button')).toBeEnabled();
+await expect(page.getByRole('dialog')).toBeHidden();
+
+// Wait for navigation
+await page.waitForURL(/dashboard/);
+
+// Wait for response
+await page.waitForResponse(r => r.url().includes('/api/data'));
+
+// Wait for load state
+await page.waitForLoadState('networkidle');
+
+// AVOID arbitrary waits
+await page.waitForTimeout(3000); // ❌ BAD
+```
+
+## Retry Strategies
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,
+
+  // Retry only specific tests
+  expect: {
+    timeout: 10000, // Increase assertion timeout
+  },
+});
+
+// Per-test retry
+test('flaky test', async ({ page }) => {
+  test.info().annotations.push({ type: 'issue', description: 'Known flaky' });
+  // ...
+});
+```
+
+## Debugging Output
+
+```typescript
+// Console output
+test('debug test', async ({ page }) => {
+  page.on('console', msg => console.log(msg.text()));
+  page.on('pageerror', err => console.log(err.message));
+});
+
+// Screenshot on step
+await page.screenshot({ path: 'debug.png' });
+```
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `PWDEBUG=1` | Enable inspector |
+| `--headed` | Show browser |
+| `--ui` | UI mode |
+| `page.pause()` | Pause execution |
+| `show-trace` | View trace file |
+
+| Fix | Flaky Cause |
+|-----|-------------|
+| Auto-wait locators | Race conditions |
+| `waitForResponse` | Network timing |
+| Test isolation | Shared state |
+| Increase timeout | Slow operations |