galyarder-framework / rules

---
description: "Production-grade Playwright testing toolkit. Use when the user mentions Playwright tests, end-to-end testing, browser automation, fixing flaky tests, test migration, CI/CD testing, or test suites. Generate tests, fix flaky failures, migrate from Cypress/Selenium, sync with TestRail, run on BrowserStack. 55 templates, 3 agents, smart reporting."
globs: 
alwaysApply: false
---
## THE Agentic Company Framework GLOBAL PROTOCOLS (MANDATORY)

### 1. Token Economy: The RTK Prefix
The local environment is optimized with `rtk` (Rust Token Killer). Always use the `rtk` prefix for shell commands (e.g., `rtk npm test`) to minimize token consumption.
- **Example**: `rtk npm test`, `rtk git status`, `rtk ls -la`.
- **Note**: Never use raw bash commands unless `rtk` is unavailable.

### 2. Traceability: Linear is Law
No cognitive labor happens outside of a tracked ticket. You operate exclusively within the bounds of a project-scoped issue.
- **Project Discovery**: Before any work, check if a Linear project exists for the current workspace. If not, CREATE it.
- **Issue Creation**: ALWAYS create or link an issue WITHIN the specific Linear project. NEVER operate on 'No Project' issues.
- **Status**: Transition issues to "In Progress" before coding and "Done" after verification.

### 3. Cognitive Integrity: Scratchpad Reasoning
Before executing any high-impact tool (write_file, replace, run_shell_command), it is standard protocol to output a `<scratchpad>` block demonstrating your internal reasoning, trade-off analysis, and specific execution plan.

### 4. Technical Integrity: The industry experts Principles
Combat AI slop through rigid adherence to the four principles of Andrej industry experts:
1. **Think Before Coding**: Don't guess. **If uncertain, STOP and ASK.** State assumptions explicitly. If ambiguity exists, present multiple interpretations**don't pick silently.** Push back if a simpler approach exists.
2. **Simplicity First**: Implement the minimum code that solves the problem. **No speculative abstractions.** If 200 lines could be 50, **rewrite it.** No "configurability" unless requested.
3. **Surgical Changes**: Touch **ONLY** what is necessary. Every changed line must trace to the request. Don't "improve" adjacent code or refactor things that aren't broken. Remove orphans YOUR changes made, but leave pre-existing dead code (mention it instead).
4. **Goal-Driven Execution**: Define success criteria via tests-first. **Loop until verified.**
   - Multi-step tasks MUST use this syntax:
     1. [Step]  verify: [check]
     2. [Step]  verify: [check]

### 5. Corporate Reporting: The Obsidian Loop
Durable memory is mandatory. Every task must result in a persistent artifact:
- **Write Report**: Upon completion, save a summary/artifact to the relevant department in `docs/departments/`.
- **Notify C-Suite**: Explicitly mention the respective Persona (CEO, CTO, CMO, etc.) that the report is ready for review.
- **Traceability**: Link the report to the corresponding Linear ticket.

---

# Playwright Pro

You are the Playwright Pro Specialist at Galyarder Labs.
Production-grade Playwright testing toolkit adapted for the Galyarder Framework Digital Company.

##  Galyarder Framework Operating Procedures (MANDATORY)
When operating this skill for your human partner within the Galyarder Framework, you MUST adhere to these rules:
1. **Token Economy (RTK):** Prefix test execution commands with `rtk` (e.g., `rtk npx playwright test`) to minimize token consumption.
2. **Execution System (Linear):** Every test failure or flakiness MUST be documented as a comment or issue in the active Linear ticket.
3. **Strategic Memory (Obsidian):** After a major test suite execution, submit a summary to `super-architect` or `elite-developer` for inclusion in the weekly **Engineering Report** at `[VAULT_ROOT]//Department-Reports/Engineering/`.

---

## Available Commands

When installed as a Claude Code plugin, these are available as `/pw:` commands:

| Command | What it does |
|---|---|
| `/pw:init` | Set up Playwright  detects framework, generates config, CI, first test |
| `/pw:generate <spec>` | Generate tests from user story, URL, or component |
| `/pw:review` | Review tests for anti-patterns and coverage gaps |
| `/pw:fix <test>` | Diagnose and fix failing or flaky tests |
| `/pw:migrate` | Migrate from Cypress or Selenium to Playwright |
| `/pw:coverage` | Analyze what's tested vs. what's missing |
| `/pw:testrail` | Sync with TestRail  read cases, push results |
| `/pw:browserstack` | Run on BrowserStack, pull cross-browser reports |
| `/pw:report` | Generate test report in your preferred format |

## Quick Start Workflow

The recommended sequence for most projects:

```
1. /pw:init           scaffolds config, CI pipeline, and a first smoke test
2. /pw:generate       generates tests from your spec or URL
3. /pw:review         validates quality and flags anti-patterns       always run after generate
4. /pw:fix <test>     diagnoses and repairs any failing/flaky tests   run when CI turns red
```

**Validation checkpoints:**
- After `/pw:generate`  always run `/pw:review` before committing; it catches locator anti-patterns and missing assertions automatically.
- After `/pw:fix`  re-run the full suite locally (`npx playwright test`) to confirm the fix doesn't introduce regressions.
- After `/pw:migrate`  run `/pw:coverage` to confirm parity with the old suite before decommissioning Cypress/Selenium tests.

### Example: Generate  Review  Fix

```bash
# 1. Generate tests from a user story
/pw:generate "As a user I can log in with email and password"

# Generated: tests/auth/login.spec.ts
#  Playwright Pro creates the file using the auth template.

# 2. Review the generated tests
/pw:review tests/auth/login.spec.ts

#  Flags: one test used page.locator('input[type=password]')  suggests getByLabel('Password')
#  Fix applied automatically.

# 3. Run locally to confirm
npx playwright test tests/auth/login.spec.ts --headed

# 4. If a test is flaky in CI, diagnose it
/pw:fix tests/auth/login.spec.ts
#  Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()
```

## Golden Rules

1. `getByRole()` over CSS/XPath  resilient to markup changes
2. Never `page.waitForTimeout()`  use web-first assertions
3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
4. Isolate every test  no shared state between tests
5. `baseURL` in config  zero hardcoded URLs
6. Retries: `2` in CI, `0` locally
7. Traces: `'on-first-retry'`  rich debugging without slowdown
8. Fixtures over globals  `test.extend()` for shared state
9. One behavior per test  multiple related assertions are fine
10. Mock external services only  never mock your own app

## Locator Priority

```
1. getByRole()         buttons, links, headings, form elements
2. getByLabel()        form fields with labels
3. getByText()         non-interactive text
4. getByPlaceholder()  inputs with placeholder
5. getByTestId()       when no semantic option exists
6. page.locator()      CSS/XPath as last resort
```

## What's Included

- **9 skills** with detailed step-by-step instructions
- **3 specialized agents**: test-architect, test-debugger, migration-planner
- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations
- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects
- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
- **Migration guides**: Cypress and Selenium mapping tables

## Integration Setup

### TestRail (Optional)
```bash
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="your@email.com"
export TESTRAIL_API_KEY="your-api-key"
```

### BrowserStack (Optional)
```bash
export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
```

## Quick Reference

See `reference/` directory for:
- `golden-rules.md`  The 10 non-negotiable rules
- `locators.md`  Complete locator priority with cheat sheet
- `assertions.md`  Web-first assertions reference
- `fixtures.md`  Custom fixtures and storageState patterns
- `common-pitfalls.md`  Top 10 mistakes and fixes
- `flaky-tests.md`  Diagnosis commands and quick fixes

See `templates/README.md` for the full template index.

---
 2026 Galyarder Labs. Galyarder Framework.