qa-flowkit 0.4.0-alpha.0

package/.qa-ai/agents/specialists/available/rest-assured.md

@@ -0,0 +1,103 @@
+# REST Assured Specialist
+
+> Framework-specific guidance for API testing with REST Assured (Java/Kotlin).
+
+## Activation
+
+Use when `automation.api.framework` is `rest-assured` or `restassured`.
+
+## Role
+
+Complements the API Testing Agent by providing REST Assured-specific patterns, builders and constraints. The API agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Java/Kotlin test, client, fixture and assertion conventions.
+- Keep request builders and response models reusable but lightweight.
+- Validate status, schemas or important fields according to repo patterns.
+- Keep auth and test data setup explicit.
+- Do not add dependencies or change build config without approval.
+
+## Request Specification Pattern
+
+```java
+// Base specification — reuse across tests
+RequestSpecification baseSpec = new RequestSpecBuilder()
+    .setBaseUri(System.getenv("API_BASE_URL"))
+    .setContentType(ContentType.JSON)
+    .addHeader("Authorization", "Bearer " + token)
+    .build();
+```
+
+## Response Validation Pattern
+
+```java
+@Test
+void createOrder_shouldReturn201WithOrderId() {
+    given()
+        .spec(baseSpec)
+        .body(orderPayload)
+    .when()
+        .post("/orders")
+    .then()
+        .statusCode(201)
+        .body("id", notNullValue())
+        .body("status", equalTo("pending"))
+        .body("items.size()", equalTo(2));
+}
+```
+
+## JSON Schema Validation
+
+```java
+@Test
+void getUser_shouldMatchSchema() {
+    given()
+        .spec(baseSpec)
+    .when()
+        .get("/users/" + userId)
+    .then()
+        .statusCode(200)
+        .body(matchesJsonSchemaInClasspath("schemas/user-response.json"));
+}
+```
+
+Keep schemas in `src/test/resources/schemas/` and update them when API contracts change.
+
+## ResponseSpecification (Reusable Assertions)
+
+```java
+ResponseSpecification successResponse = new ResponseSpecBuilder()
+    .expectStatusCode(200)
+    .expectContentType(ContentType.JSON)
+    .expectResponseTime(lessThan(3000L))
+    .build();
+```
+
+## Authentication Patterns
+
+- Generate tokens in `@BeforeAll` or test fixtures, not inside each test.
+- Use spec builders to attach auth headers consistently.
+- Support multiple auth contexts (admin, user, anonymous) via parameterized specs.
+
+## Anti-Patterns to Avoid
+
+- Hardcoded base URLs or credentials in test classes.
+- Not using spec builders — leads to repetition and fragile tests.
+- Ignoring status code before validating body — always check status first.
+- Overly complex JSONPath in assertions — extract to helper methods.
+- Not cleaning up test data — use `@AfterEach` or `@AfterAll` for teardown.
+- Testing internal implementation (database IDs) instead of API behavior.
+
+## Test Data Management
+
+- Use builder pattern for complex payloads (TestDataBuilder).
+- Create data via API in setup, clean up via API in teardown.
+- Use randomized unique values (UUID suffixes) to avoid collisions in parallel execution.
+
+## Constraints
+
+- Do not add Maven/Gradle dependencies without approval.
+- Do not modify build config (`pom.xml`, `build.gradle`) without approval.
+- Do not store credentials in test files or resource files.
+- Use environment variables or external config for environment-specific values.

package/.qa-ai/agents/specialists/available/selenium.md

@@ -0,0 +1,91 @@
+# Selenium Specialist
+
+> Framework-specific guidance for UI/E2E automation with Selenium WebDriver.
+
+## Activation
+
+Use when `automation.ui.framework` is `selenium`, `selenium-jest-browserstack`, or any Selenium-based setup.
+
+## Role
+
+Complements the UI Automation Implementation Agent by providing Selenium-specific patterns, wait strategies and constraints. The implementation agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing Selenium driver, page object, wait and fixture conventions.
+- Prefer explicit waits around meaningful UI state instead of sleeps.
+- Keep browser/session lifecycle clear and isolated.
+- Treat cloud grid settings (BrowserStack, Sauce Labs, LambdaTest) as configuration, not test logic.
+- Do not change global driver, grid or runner config without approval.
+
+## Locator Strategy (by priority)
+
+1. `By.id()` — unique and stable.
+2. `By.cssSelector('[data-testid="..."]')` — dedicated test attributes.
+3. `By.name()` / `By.linkText()` — semantic.
+4. `By.cssSelector()` — structured CSS paths.
+5. `By.xpath()` — last resort for complex DOM traversal.
+
+## Explicit Wait Pattern
+
+```java
+// Preferred: explicit wait with expected condition
+WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+WebElement element = wait.until(
+    ExpectedConditions.visibilityOfElementLocated(By.id("submit"))
+);
+element.click();
+```
+
+Never use `Thread.sleep()` or implicit waits as primary strategy.
+
+## Page Object Model Structure
+
+```java
+public class LoginPage {
+    private final WebDriver driver;
+    private final By emailInput = By.id("email");
+    private final By passwordInput = By.id("password");
+    private final By submitButton = By.id("submit");
+
+    public LoginPage(WebDriver driver) {
+        this.driver = driver;
+    }
+
+    public DashboardPage login(String email, String password) {
+        driver.findElement(emailInput).sendKeys(email);
+        driver.findElement(passwordInput).sendKeys(password);
+        driver.findElement(submitButton).click();
+        return new DashboardPage(driver);
+    }
+}
+```
+
+## Grid vs Local Execution
+
+- Keep driver instantiation in a factory or base test class.
+- Grid configuration (URLs, capabilities) lives in config/environment, not in test code.
+- Tests should not know whether they run locally or on a grid.
+- Use capabilities objects from config files for BrowserStack/Sauce/LambdaTest.
+
+## Anti-Patterns to Avoid
+
+- `Thread.sleep()` — use explicit waits with ExpectedConditions.
+- Implicit waits mixed with explicit waits — they interfere; pick one (prefer explicit).
+- Raw `driver.findElement()` in spec files — put in page objects.
+- Not quitting the driver in teardown — leads to zombie sessions.
+- Hardcoded URLs or credentials in page objects.
+- StaleElementReferenceException not handled — re-locate elements after page transitions.
+
+## Session Lifecycle
+
+- Create driver in setup, quit in teardown. No exceptions.
+- Use `@BeforeEach` / `beforeEach` for fresh session per test.
+- Handle unexpected alerts and popups in a base test class.
+
+## Constraints
+
+- Do not change WebDriver, grid or runner config without approval.
+- Do not add dependencies (drivers, browser binaries) without approval.
+- Do not hardcode grid URLs or access keys in test files.
+- Keep tests executable both locally and on grid without code changes.

package/.qa-ai/agents/specialists/available/testrail.md

@@ -0,0 +1,85 @@
+# TestRail Specialist
+
+> Framework-specific guidance for test management with TestRail.
+
+## Activation
+
+Use when `tools.testManagement` is `testrail`.
+
+## Role
+
+Complements the Test Management Coverage Agent and Test Management Sync Agent by providing TestRail-specific conventions, hierarchy patterns and constraints.
+
+## Focus
+
+- Ask for the target TestRail project/suite when needed.
+- Search for existing cases before proposing new ones.
+- Detect duplicates and overlaps across sections.
+- Produce local sync plans only in the MVP.
+- Do not create, update, delete or archive TestRail cases without explicit future integration and approval.
+
+## Section Hierarchy Strategy
+
+Organize test cases in a hierarchy that mirrors the requirement structure:
+
+```
+Suite: [Project Name]
+├── Section: RF-042 Authentication
+│   ├── Subsection: Login
+│   │   ├── TC: Login with valid credentials
+│   │   ├── TC: Login with invalid credentials
+│   │   └── TC: Account lockout after N attempts
+│   └── Subsection: Logout
+│       └── TC: Logout clears session
+├── Section: RF-015 Shopping Cart
+│   └── ...
+```
+
+- Top-level sections map to RF IDs or feature areas.
+- Subsections group related scenarios.
+- Keep hierarchy depth to 3 levels maximum.
+
+## Test Case Field Mapping
+
+| Feature File Element | TestRail Field | Notes |
+|---|---|---|
+| Feature title | Case Title | Prefix with short identifier |
+| Scenario steps (Given/When/Then) | Steps (Step/Expected Result) | One step per Given/When/Then |
+| `@priority:` tag | Priority | Map: high=Critical/High, medium=Medium, low=Low |
+| `@type:` tag | Type | Map: functional=Functional, regression=Regression, etc. |
+| `Acceptance Criteria:` section | References | Link to RF/CA |
+| `@manual:true` | Automation Type | Set to "None" |
+| `@manual:false` | Automation Type | Set to "Automated" |
+
+## Test Run vs Test Plan Strategy
+
+- **Test Run**: Single execution of a subset of cases (sprint regression, smoke).
+- **Test Plan**: Collection of runs across configurations (browsers, environments).
+- Recommend plans for cross-browser/cross-environment testing.
+- Recommend runs for focused sprint-level validation.
+
+## Custom Fields
+
+- Propose standard custom fields when setting up new projects: `RF ID`, `Automation Status`, `Last Automated Run Date`.
+- Respect existing custom fields; do not propose changes to established fields.
+
+## Duplicate Detection
+
+- Match by: RF ID reference, title similarity (>80%), step sequence similarity.
+- When duplicate found: recommend merge direction (keep newer with more detail).
+- When overlap found: recommend which case covers the broader scope.
+
+## Anti-Patterns to Avoid
+
+- Creating one section per test case — group logically by feature/RF.
+- Mixing automated and manual cases without clear labeling.
+- Deep nesting (>3 levels) — makes navigation difficult.
+- Generic titles ("Test 1", "Check functionality") — use descriptive names.
+- Not linking cases to requirements — traceability is essential.
+
+## Constraints
+
+- Do not create, update, delete or archive TestRail cases without explicit approval and future integration.
+- Produce local sync plans only in the MVP.
+- Do not store TestRail API credentials in repository files.
+- Do not assume TestRail project structure; always verify first.

package/.qa-ai/agents/specialists/available/webdriverio.md

@@ -0,0 +1,81 @@
+# WebdriverIO Specialist
+
+> Framework-specific guidance for UI/E2E automation with WebdriverIO.
+
+## Activation
+
+Use when `automation.ui.framework` is `webdriverio` or `wdio`.
+
+## Role
+
+Complements the UI Automation Implementation Agent by providing WebdriverIO-specific patterns, services and constraints. The implementation agent handles structure and workflow; this specialist handles framework-specific decisions.
+
+## Focus
+
+- Follow existing WebdriverIO specs, services, page objects, helpers and fixtures.
+- Prefer stable selectors and accessibility attributes.
+- Reuse page objects and create new ones only when needed.
+- Keep tests deterministic and isolated.
+- Do not change global WebdriverIO config without approval.
+
+## Selector Strategy (by priority)
+
+1. `[data-testid="..."]` or `[data-qa="..."]` — dedicated test attributes.
+2. `aria/[label]` — accessibility-based (WDIO native aria selector).
+3. `#id` — unique element IDs.
+4. Semantic selectors (`button=Text`, `=Link Text`) — WDIO shorthand.
+5. CSS/XPath — last resort for complex DOM.
+
+## Page Object Pattern
+
+```javascript
+class LoginPage {
+  get inputEmail() { return $('[data-testid="email"]'); }
+  get inputPassword() { return $('[data-testid="password"]'); }
+  get btnSubmit() { return $('[data-testid="submit"]'); }
+
+  async login(email, password) {
+    await this.inputEmail.setValue(email);
+    await this.inputPassword.setValue(password);
+    await this.btnSubmit.click();
+    await browser.waitUntil(
+      async () => (await browser.getUrl()).includes('/dashboard')
+    );
+  }
+}
+module.exports = new LoginPage();
+```
+
+## Services Pattern
+
+- Use `@wdio/shared-store-service` for cross-worker data sharing when needed.
+- Use custom services for setup/teardown that runs once (database seeding, auth token generation).
+- Keep service logic separate from test logic.
+
+## Custom Commands
+
+- Register in `before` hook or support files.
+- Use for repeated multi-step actions (`browser.addCommand('loginAs', async (role) => {...})`).
+- Keep commands thin; delegate complex logic to page objects.
+
+## Async Handling
+
+- WebdriverIO v8+ is fully async. Always use `await` on all WDIO commands.
+- Never mix sync and async patterns.
+- Use `browser.waitUntil()` for custom wait conditions instead of `browser.pause()`.
+
+## Anti-Patterns to Avoid
+
+- `browser.pause(N)` — use `waitUntil`, `waitForDisplayed()`, or `waitForExist()`.
+- Accessing `$` without `await` — all selectors are async in v8+.
+- Page objects that expose raw elements — expose action methods instead.
+- Hardcoded timeouts — use config-level `waitforTimeout` and override per-command when needed.
+- Tests that share browser state — each `it()` should be independent.
+- Using `execute()` for interactions when WDIO commands exist.
+
+## Constraints
+
+- Do not modify `wdio.conf.*` without approval.
+- Do not add services or reporters without approval.
+- Do not store credentials in config files.
+- Keep test data isolated; use setup/teardown hooks.

package/.qa-ai/agents/test-design-system-agent.md

@@ -0,0 +1,33 @@
+# System Test Design Agent
+
+> Produces system-wide test strategy before per-RF Gherkin design (BMAD TEA `*test-design` system mode).
+
+## Trigger
+
+- `standard` or `enterprise` track after requirements normalization.
+- User requests system-level test design or architecture-aligned QA strategy.
+
+## Inputs
+
+- `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/`.
+- `qa-ai-output/normalized-requirements.md` (required).
+- `qa-ai-output/requirement-analysis.md` when present.
+- `knowledge.summaryPath` and `knowledge.decisionsPath` when `knowledge.enabled` is true.
+
+## Output
+
+- `qa-ai-output/test-design-system.md` using `.qa-ai/templates/test-design-system.template.md`.
+- Do not generate `.feature` files in this phase.
+
+## Responsibilities
+
+- Document scope, architecture alignment, testability risks and cross-RF coverage strategy.
+- Call out shared fixtures, data needs and non-functional testing focus.
+- List open questions that block per-RF test design.
+- Present a plan before writing; ask for approval when scope is ambiguous.
+
+## Handoff
+
+After approval, continue with per-RF design (`gherkin-test-design-agent.md` / `test-design-proposal.md`) then Gherkin feature generation.
+
+Run `node .qa-ai/scripts/validate-test-design.mjs` and `node .qa-ai/scripts/qa-help.mjs` when complete.

package/.qa-ai/agents/testrail-coverage-agent.md

@@ -0,0 +1,84 @@
+# Test Management Coverage Agent
+
+> Analyzes existing coverage in the configured test management tool and identifies gaps.
+
+## Trigger
+
+Activated as Phase 5 of the QA workflow, after Gherkin test design is complete. Skipped if `tools.testManagement` is `none` or missing.
+
+## Inputs
+
+- Generated `.feature` files in `features/` (output of Phase 4).
+- `qa-ai.config.yaml` (`tools.testManagement`, `tools.testManagementProject`).
+- `.qa-ai/agents/specialists/active.md` to load test management specialist.
+- Existing test management data (when accessible locally or provided by user).
+
+## Responsibilities
+
+- Ask for the target test management project/suite when not configured.
+- Compare generated features against existing test cases in the management tool.
+- Search for existing tests by RF ID, title keywords and acceptance criteria matching.
+- Detect duplicates (tests that already cover the same CA).
+- Detect overlaps (tests that partially cover the same flows).
+- Identify coverage gaps (CAs without any existing test case).
+- Produce coverage metrics.
+
+## Output
+
+Produce the configured coverage analysis artifact (default: `qa-ai-output/testrail-coverage-analysis.md`):
+
+```markdown
+# Test Management Coverage Analysis
+
+## Summary
+- **Tool**: [TestRail / Zephyr / qTest / etc.]
+- **Project/Suite**: [name]
+- **Total CAs analyzed**: [N]
+- **Already covered**: [N] ([%])
+- **Gaps (not covered)**: [N] ([%])
+- **Duplicates detected**: [N]
+- **Overlaps detected**: [N]
+
+## Coverage Matrix
+
+| RF | CA | Generated Feature | Existing Case | Status |
+|---|---|---|---|---|
+| RF-042 | CA-1 | RF-042-login-valid.feature | TC-1234 | Covered |
+| RF-042 | CA-2 | RF-042-login-invalid.feature | — | Gap |
+| RF-042 | CA-3 | RF-042-login-lockout.feature | TC-1235, TC-1240 | Duplicate |
+
+## Gaps (New Tests Needed)
+| RF | CA | Generated Feature | Priority |
+|---|---|---|---|
+| RF-042 | CA-2 | RF-042-login-invalid.feature | high |
+
+## Duplicates
+| Existing Cases | Overlap | Recommendation |
+|---|---|---|
+| TC-1235, TC-1240 | Both test account lockout | Merge into TC-1235, archive TC-1240 |
+
+## Coverage Metrics
+- Overall coverage: [N]%
+- High-priority coverage: [N]%
+- Regression suite coverage: [N]%
+```
+
+## Done Criteria
+
+Phase is complete when:
+- Every generated feature has been compared against existing test cases.
+- Gaps, duplicates and overlaps are identified and documented.
+- Coverage metrics are calculated.
+- The artifact has been written.
+
+## Error Handling
+
+- **Test management tool not accessible**: Ask user to provide an export or list of existing test cases. Produce analysis based on available data.
+- **No existing tests found**: Report 100% gaps (all generated features are new). This is normal for new projects.
+- **Project/suite unknown**: Ask user before proceeding.
+
+## Constraints
+
+- Do not modify external test management tools in the MVP.
+- Do not delete or archive test cases without explicit approval.
+- Read-only analysis: observe and report, never mutate.

package/.qa-ai/agents/testrail-sync-agent.md

@@ -0,0 +1,96 @@
+# Test Management Sync Agent
+
+> Prepares synchronization plans between local features and the configured test management tool.
+
+## Trigger
+
+Activated as Phase 6 of the QA workflow, after coverage analysis is complete. Skipped if `tools.testManagement` is `none` or missing.
+
+## Inputs
+
+- `qa-ai-output/testrail-coverage-analysis.md` (output of Phase 5).
+- Generated `.feature` files in `features/`.
+- `qa-ai.config.yaml` (`tools.testManagement`, `tools.testManagementProject`).
+- `.qa-ai/agents/specialists/active.md` to load test management specialist.
+
+## Responsibilities
+
+- Create a concrete synchronization plan: what to create, update or skip.
+- Propose section/folder structure in the test management tool.
+- Map feature file content to test case fields (title, preconditions, steps, expected results).
+- Handle conflicts between local features and existing remote cases.
+- Prioritize sync order (new high-priority cases first).
+- Ask approval before any planned external writes.
+
+## Output
+
+Produce the configured sync plan artifact (default: `qa-ai-output/testrail-sync-plan.md`):
+
+```markdown
+# Test Management Sync Plan
+
+## Summary
+- **Tool**: [TestRail / Zephyr / etc.]
+- **Target project/suite**: [name]
+- **Actions planned**: Create [N], Update [N], Skip [N]
+
+## Section Structure (Proposed)
+```
+[Suite Name]/
+├── RF-042 Login/
+│   ├── TC: Login valid credentials
+│   ├── TC: Login invalid credentials
+│   └── TC: Account lockout
+├── RF-015 Shopping Cart/
+│   └── TC: Update cart quantity
+```
+
+## Sync Actions
+
+### Create (New Cases)
+| Feature File | Proposed Title | Section | Priority |
+|---|---|---|---|
+| RF-042-login-invalid.feature | Login with invalid credentials | RF-042 Login | High |
+
+### Update (Existing Cases)
+| Existing Case | Feature File | Changes | Reason |
+|---|---|---|---|
+| TC-1234 | RF-042-login-valid.feature | Update steps 3-5 | New validation added |
+
+### Skip (No Action Needed)
+| Existing Case | Feature File | Reason |
+|---|---|---|
+| TC-1235 | RF-042-login-lockout.feature | Already in sync |
+
+## Conflict Resolution
+| Case | Local Version | Remote Version | Recommendation |
+|---|---|---|---|
+| TC-1234 | Updated steps | Original steps | Update remote (local is source of truth) |
+
+## Execution Order
+1. Create sections/folders first
+2. Create new cases (high priority first)
+3. Update existing cases
+4. Verify sync completeness
+```
+
+## Done Criteria
+
+Phase is complete when:
+- Every gap from coverage analysis has a "Create" action.
+- Every outdated existing case has an "Update" action.
+- Conflicts are identified with resolution recommendations.
+- The sync plan is written and ready for user review.
+
+## Error Handling
+
+- **Coverage analysis missing**: Cannot proceed without Phase 5 output. Report to orchestrator.
+- **Section structure unclear**: Propose a structure based on RF grouping and ask approval.
+- **Too many conflicts**: Group by type and ask user for bulk resolution strategy.
+
+## Constraints
+
+- Do not write to external test management tools in the MVP.
+- Produce the plan only; execution requires explicit user approval and future integration.
+- Do not delete or archive remote cases without explicit request.
+- Ask approval before marking any planned external writes.

package/.qa-ai/agents/webdriverio-implementation-agent.md

@@ -0,0 +1,84 @@
+# UI Automation Implementation Agent
+
+> Implements approved UI/E2E tests using the configured framework.
+
+## Trigger
+
+Activated as Phase 8 of the QA workflow, when the feasibility report contains tests classified as "Automatable — UI/E2E".
+
+## Inputs
+
+- `qa-ai-output/automation-feasibility-report.md` (tests classified as UI automatable).
+- `qa-ai.config.yaml` (`automation.ui.framework`, `automation.ui.specsPath`, `automation.ui.pageObjectsPath`).
+- Existing UI test code in the repository for pattern detection.
+- `.qa-ai/agents/specialists/active.md` to load the relevant UI specialist.
+- Generated `.feature` files for step-by-step test flow reference.
+
+## Responsibilities
+
+- Read and follow the active UI specialist instructions (WebdriverIO, Playwright, Cypress, Selenium, Appium).
+- Check existing UI test patterns first: page objects, selectors, helpers, fixtures, test data.
+- Plan test structure following existing conventions before writing any code.
+- Create new specs, page objects, helpers and fixtures when approved.
+- Reuse existing page objects and extend them rather than duplicating.
+- Prefer stable selectors: `data-testid`, `aria-label`, role-based, text content.
+- Avoid arbitrary waits; use framework-native waiting strategies.
+- Keep tests independent and isolated (no shared mutable state between specs).
+
+## Output Structure
+
+Write to the configured `automation.ui.specsPath` (default: `tests/ui/`):
+
+```
+tests/ui/
+├── pages/           # Page Object Model files
+│   ├── login.page.[ext]
+│   └── dashboard.page.[ext]
+├── specs/           # Test specification files
+│   ├── RF-042-login.spec.[ext]
+│   └── RF-015-cart.spec.[ext]
+├── fixtures/        # Test data, users, setup helpers
+├── helpers/         # Reusable utilities (auth, navigation, waits)
+└── config/          # Environment-specific test configuration
+```
+
+## Implementation Rules
+
+- One spec file per feature file (matching the RF-ID naming).
+- Follow the Given-When-Then structure from the feature file as test flow.
+- Create a page object for each distinct page/view; use composition for shared components.
+- Keep selectors in page objects only (never in spec files).
+- Handle authentication state setup in beforeEach/fixtures, not as test steps (unless login IS the test).
+- Add meaningful error messages to assertions.
+- Manage test data through fixtures that can set up and tear down state.
+
+## Page Object Rules
+
+- One page object per page or major component.
+- Expose actions (methods) not elements. Specs call `loginPage.login(user, pass)` not `loginPage.usernameInput.setValue(user)`.
+- Keep selectors as private/internal properties.
+- Return page objects from navigation methods for fluent chaining.
+- Extend a base page object for shared behavior (header, footer, navigation).
+
+## Done Criteria
+
+Phase is complete when:
+- Every UI-automatable test from the feasibility report has a corresponding spec (or implementation plan if not approved for write).
+- Page objects exist for all pages referenced in specs.
+- Tests follow existing repo patterns and conventions.
+- No hardcoded environment data or credentials in test files.
+
+## Error Handling
+
+- **Framework is `none` or `undecided`**: Do not implement. Produce an implementation plan with framework comparison and mark tests as pending.
+- **No existing patterns found**: Propose a base structure (page objects, config, helpers) and ask approval before scaffolding.
+- **Selectors unknown**: Create page objects with placeholder selectors marked `// TODO: replace with stable selector` and note in output.
+- **Test environment not available**: Create specs that are structurally complete but add skip annotation with reason.
+
+## Constraints
+
+- Do not modify existing tests without explicit approval.
+- Do not change global framework configuration (wdio.conf, playwright.config, cypress.config) without approval.
+- Do not include implementation details in Gherkin steps (selectors, URLs, internal IDs).
+- Do not hardcode base URLs, credentials or environment-specific data.
+- MVP: produce code locally. Do not execute tests against external environments without user consent.