opencastle 0.32.12 → 0.33.0

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.

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

@@ -7,79 +7,54 @@ description: "Figma design-to-code workflows, design token extraction, component
 
 # Figma Design
 
-Figma-specific design-to-code patterns and MCP tool usage. For project-specific design system details, see the **frontend-design** skill.
+For project-specific design system details, see the **frontend-design** skill.
 
 ## MCP Tools
 
-The Figma MCP server enables AI agents to inspect designs directly:
-
-| Tool | Purpose | Primary Agents |
-|------|---------|----------------|
-| `figma/get_file` | Retrieve full Figma file structure | UI/UX Expert |
-| `figma/get_file_nodes` | Get specific nodes/frames | UI/UX Expert, Developer |
-| `figma/get_images` | Export nodes as images | UI/UX Expert |
-| `figma/get_comments` | Read design review comments | UI/UX Expert |
-| `figma/get_styles` | Extract color/text/effect styles | Developer |
-| `figma/get_components` | List reusable components | Developer |
+| Tool | Purpose |
+|------|---------|
+| `figma/get_file` | Retrieve full Figma file structure |
+| `figma/get_file_nodes` | Get specific nodes/frames |
+| `figma/get_images` | Export nodes as images |
+| `figma/get_comments` | Read design review comments |
+| `figma/get_styles` | Extract color/text/effect styles |
+| `figma/get_components` | List reusable components |
+
+### Example MCP invocations
+
+```json
+// figma/get_file — full file structure
+{ "file_key": "a1b2C3d4E5", "depth": 2 }
+// figma/get_file_nodes — specific frames
+{ "file_key": "a1b2C3d4E5", "node_ids": ["123:45"] }
+// figma/get_images — export as PNG at 2x
+{ "file_key": "a1b2C3d4E5", "ids": ["123:45"], "format": "png", "scale": 2 }
+```
 
 ## Design-to-Code Workflow
 
-1. **Identify the frame** — get the Figma file URL or node ID from the task
-2. **Inspect the design** — use `get_file_nodes` to retrieve layout, spacing, colors, typography
-3. **Extract tokens** — map Figma styles to CSS custom properties or design tokens
-4. **Build components** — translate Figma components to React/framework components
-5. **Verify** — compare the implementation against the original design visually
-
-## Design Token Extraction
-
-### From Figma Styles to CSS
-
-```css
-/* Map Figma color styles to CSS custom properties */
-:root {
-  /* Primary */
-  --color-primary-50: #eff6ff;
-  --color-primary-500: #3b82f6;
-  --color-primary-900: #1e3a8a;
-
-  /* Typography (from Figma text styles) */
-  --font-heading: 'Inter', sans-serif;
-  --font-body: 'Inter', sans-serif;
-  --font-size-sm: 0.875rem;    /* 14px */
-  --font-size-base: 1rem;       /* 16px */
-  --font-size-lg: 1.125rem;     /* 18px */
-  --font-size-xl: 1.25rem;      /* 20px */
-
-  /* Spacing (from Figma auto-layout) */
-  --space-xs: 4px;
-  --space-sm: 8px;
-  --space-md: 16px;
-  --space-lg: 24px;
-  --space-xl: 32px;
+1. **Identify the frame** — obtain the Figma file key or node ID from the task input.
+2. **Inspect nodes** — call `figma/get_file_nodes` for the target node IDs and extract bounding boxes, fills, text styles, and auto-layout info.
+3. **Extract tokens** — map returned styles to token files (colors, typography, spacing) and commit tokens to `src/styles/tokens.css` or a token JSON.
+4. **Implement component** — scaffold a framework component that consumes tokens and matches layout properties (gap, padding, width). Import tokens (CSS variables or JSON) and attach a `data-testid` for programmatic verification.
+
+```tsx
+// src/components/ui/Card.tsx — consumes tokens, matches Figma layout
+import '../styles/tokens.css';
+interface CardProps { title: string; description?: string }
+export function Card({ title, description }: CardProps) {
+  return (
+    <div data-testid="card" className="card">
+      <span className="card-title">{title}</span>
+      {description && <p>{description}</p>}
+    </div>
+  );
 }
 ```
+5. **Verify programmatically** — run a visual diff or DOM-attribute check:
+  - Render in Storybook and compare DOM bounding boxes against Figma node metrics.
+  - Acceptance: differences <= 4px for spacing and matching token colors; fonts must match family and weight.
+6. **Feedback loop** — if implementation deviates beyond thresholds, update token mapping or request design clarification and repeat from step 2.
 
-### Translation Rules
-
-| 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 left` |
-| 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` |
-
-## Best Practices
+See REFERENCE.md for a verification script and Figma→CSS translation rules.
 
-- Always extract design tokens systematically — don't hardcode values from visual inspection
-- Use Figma's auto-layout values directly for flex/grid properties
-- Match Figma's responsive breakpoints to the project's breakpoint system
-- Export SVG assets directly from Figma via `get_images` — don't recreate manually
-- Cross-reference Figma component names with the codebase component library
-- When in doubt about values, inspect the Figma node — don't approximate
-- Keep a mapping document between Figma styles and CSS custom properties

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

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Jira advanced reference
+
+- JQL examples and common automation snippets
+- Epic/Story mapping templates and branch naming conventions
+- Project-specific mapping file: tracker-config.md (see ../../.opencastle/project/tracker-config.md)

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

@@ -1,44 +1,30 @@
 ---
 name: jira-management
-description: "Jira board conventions for tracking feature work — issue naming, labels, priorities, status workflow, and session continuity via Atlassian Rovo MCP. Use when decomposing features into tasks or resuming interrupted sessions."
+description: "Create and update Jira issues, epics, and sprints; manage backlog and sprint transitions. Use when you say: 'create a ticket', 'open a story', 'link an epic', 'start a sprint', or 'search the backlog'."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Task Management with Jira
 
-Conventions for tracking feature work on Jira via the Atlassian Rovo MCP server. For project-specific project keys, workflow state IDs, and board configuration, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
+For project-specific project keys, workflow state IDs, and board configuration, see [tracker-config.md](../../.opencastle/project/tracker-config.md).
 
-## Atlassian Rovo MCP Server
+## MCP Tool Examples
 
-The Atlassian Rovo MCP server connects to Jira (and Confluence) via `https://mcp.atlassian.com/v2/sse`. It uses OAuth authentication — users authenticate through their Atlassian account when the MCP connection is first established.
+```json
+// Search issues
+{ "jql": "project = PROJ AND status = 'In Progress' ORDER BY priority DESC" }
 
-**Available capabilities:**
-- Search Jira issues with JQL
-- Create and update issues
-- Read issue details, comments, and attachments
-- Search Confluence pages for context
-- Create Confluence pages
+// Create issue
+{ "project": "PROJ", "summary": "[UI] Build PriceRangeFilter", "type": "Task", "description": "Objective: ...\nFiles: ...\nAC: ..." }
 
-**Rate limits** (per hour):
-- Free: 500 calls
-- Standard: 1,000 calls
-- Premium/Enterprise: 1,000 + 20 per user (up to 10,000)
-
-## Discovered Issues (Bug Tickets)
+// Transition issue
+{ "issueKey": "PROJ-42", "status": "In Progress" }
+```
 
-When an agent encounters a pre-existing bug or issue unrelated to the current task, it must be tracked. Follow this flow:
+## Discovered Issues
 
-1. **Check** known issues docs and Jira (search for open bugs) to see if it's already tracked
-2. **If tracked** — skip it, continue with current work
-3. **If NOT tracked:**
-   - **Unfixable limitation** — add to known issues with Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
-   - **Fixable bug** — create a Jira issue:
-     - **Summary:** `[Area] Short description of the symptom`
-     - **Type:** Bug
-     - **Priority:** High if it affects users, Medium if cosmetic or non-blocking
-     - **Description:** Include symptoms, reproduction steps, affected files, and any error messages or screenshots
-     - **Status:** Backlog (unless it's blocking current work, then To Do)
+Check Jira first; if untracked, create a `[Bug]` issue in Backlog with symptoms, repro steps, and affected files.
 
 ## Issue Naming
 
@@ -54,17 +40,6 @@ Use `[Area] Short description` format in the Summary field:
 [Docs] Update data model documentation
 ```
 
-**Area prefixes:** `[Schema]`, `[DB]`, `[Query]`, `[UI]`, `[Page]`, `[API]`, `[Auth]`, `[Test]`, `[Docs]`, `[Deploy]`, `[Data]`, `[Perf]`, `[Security]`
-
-## Priority
-
-| Jira Priority | Meaning | When to use |
-|---------------|---------|-------------|
-| Highest | Blocker | Blocks other tasks, critical path |
-| High | Important | Core feature work, on critical path |
-| Medium | Normal | Supporting tasks, can be parallelized |
-| Low | Nice-to-have | Docs, cleanup, polish |
-| Lowest | Backlog | Captured for future consideration |
 
 ## Status Workflow
 
@@ -72,99 +47,36 @@ Use `[Area] Short description` format in the Summary field:
 Backlog → To Do → In Progress → In Review → Done
 ```
 
-- **Backlog** — Captured but not yet planned
-- **To Do** — Planned for current sprint/feature, ready to start
-- **In Progress** — Actively being worked on by an agent
-- **In Review** — PR opened, awaiting review/merge
-- **Done** — Completed and verified
-
-### Status Drivers
-
-Issue status is driven by **two sources** — the Team Lead agent (via MCP) and the Jira automation/GitHub integration (automatically).
-
-**Agent-driven transitions (via MCP):**
-- **To Do → In Progress** — when the agent starts working on a task
-- **In Progress → Done** — when non-PR tasks are verified (e.g., docs, config changes)
+### Transition Rules
 
-**Automation-driven transitions:**
-If your Jira project has GitHub integration or automation rules configured, PR lifecycle events can auto-update issue status. Configure these in Jira under *Project settings → Automation*.
-
-**Linking issues to PRs:** Include the Jira issue key (e.g., `PROJ-123`) in the branch name or PR title. Use the branch name format: `<type>/<issue-key>-<short-description>`.
+- Agent (via MCP): `To Do → In Progress` on start; `In Progress → Done` on verified completion.
+- Automation: PR events auto-update status when GitHub/Jira integration is configured.
+- Link via Jira key in branch/PR title (e.g., `PROJ-123`).
 
 ## Issue Descriptions
 
-Every issue must include:
-
-```markdown
-**Objective:** One sentence describing the deliverable
-
-**Files (partition):**
-- `path/to/relevant/file.ts`
-- `path/to/another/file.ts`
-
-**Acceptance Criteria:**
-- [ ] Specific, verifiable outcome 1
-- [ ] Specific, verifiable outcome 2
-
-**Dependencies:** PROJ-XX (if any)
-```
-
-The **Files (partition)** section defines which files this agent is allowed to modify. This prevents merge conflicts when multiple agents work in parallel — no two issues in the same phase should list overlapping files.
+Every issue must include: **Objective** (one sentence), **Files (partition)** (paths this agent may modify), **Acceptance Criteria** (verifiable checklist), **Dependencies** (issue keys).
 
-## Feature Grouping
-
-- Use a **Jira Epic** for each major feature
-- All related issues (Stories/Tasks) belong to that Epic
-- Issues track individual subtasks within the feature
-- Use components or labels for domain grouping (e.g., `frontend`, `backend`, `database`)
+Group related issues under a Jira Epic; use components or labels for domain grouping.
 
 ## Session Workflow
 
-### Starting a new feature
-
-1. Search the board (JQL) to check for existing in-progress work
-2. Decompose the feature into issues following the conventions above
-3. Create all issues in Jira with correct naming, type, priority, and descriptions
-4. Link dependencies between issues using Jira issue links
-5. Begin delegation
-
-### During execution
-
-- Move issue to **In Progress** before delegating to an agent
-- Move issue to **Done** immediately after the agent completes and output is verified
-- Add comments to the issue if a task is blocked, explaining the blocker
-
-### Resuming an interrupted session
-
-1. Search issues by status (In Progress, To Do) in the project
-2. Read issue descriptions to restore context
-3. Pick up where work left off — no need to re-analyze from scratch
-
-### Completing a feature
-
-1. Verify all issues in the Epic are **Done** or closed
-2. Run final build/lint/test checks
-3. Close the Epic
+1. Search the board (JQL) for existing in-progress work.
+2. Decompose the feature into issues; create all in Jira — verify each returns a valid issue key.
+3. Link dependencies between issues.
+4. Delegate: move issue to **In Progress** before starting; move to **Done** after verified.
+5. If creation/transition fails: retry once; check project key and workflow state IDs in [tracker-config.md](../../.opencastle/project/tracker-config.md).
+6. On resume: search by status (In Progress, To Do), read descriptions, continue.
+7. On completion: verify all Epic issues are Done, run build/lint/test, close the Epic.
 
 ## JQL Quick Reference
 
 Common queries for agent workflows:
 
 ```jql
-# Find in-progress work
 project = PROJ AND status = "In Progress" ORDER BY priority DESC
-
-# Find planned work
 project = PROJ AND status = "To Do" ORDER BY priority DESC
-
-# Find bugs
 project = PROJ AND type = Bug AND status != Done ORDER BY priority DESC
-
-# Find work in current sprint
 project = PROJ AND sprint in openSprints() ORDER BY priority DESC
-
-# Find blockers
 project = PROJ AND priority = Highest AND status != Done
 ```
-
-Replace `PROJ` with the actual project key from [tracker-config.md](../../.opencastle/project/tracker-config.md).