qa-flowkit 0.4.0-alpha.0

package/.qa-ai/adapters/opencode/commands/qa-gate.md

@@ -0,0 +1,36 @@
+---
+description: Release quality gate decision / Decisión de release gate
+argument-hint: [optional scope or RF ID]
+---
+
+Produce or update the formal release gate for this repository.
+
+Read first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml`
+- `.qa-ai/rules/approval.rules.md`
+- `.qa-ai/agents/release-gate-agent.md`
+- `.qa-ai/workflows/release-gate.md`
+
+Review QA artifacts (`qa-ai-output/pr-summary.md`, `qa-ai-output/traceability-matrix.md`, sync plan when present) and recent validator output.
+
+If useful, run:
+
+```bash
+node .qa-ai/scripts/validate-target.mjs
+```
+
+Present a short plan before editing `qa-ai-output/release-gate.yaml` (or the configured `release.gatePath`).
+
+Set `decision` to one of: `PASS`, `CONCERNS`, `FAIL`, `WAIVED`. Do not leave `PENDING` for a final release without user approval.
+
+After updating the gate file, run:
+
+```bash
+node .qa-ai/scripts/validate-release-gate.mjs
+```
+
+Then run `/qa-help` and share the result with the user.
+
+Do not perform external writes. Ask for explicit approval before `PASS` or `WAIVED` on regulated releases.

package/.qa-ai/adapters/opencode/commands/qa-help.md

@@ -0,0 +1,30 @@
+---
+description: QA workflow guidance — what to do next / Guía del flujo QA
+argument-hint: [optional question]
+---
+
+Provide context-aware guidance for the next QA workflow step in this repository.
+
+Read these files first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml` when present
+- `.qa-ai/agents/qa-workflow-orchestrator.md`
+
+Run:
+
+```bash
+node .qa-ai/scripts/qa-help.mjs
+```
+
+If `$ARGUMENTS` is provided, pass it as the question:
+
+```bash
+node .qa-ai/scripts/qa-help.mjs "$ARGUMENTS"
+```
+
+Present the CLI output clearly, grouped by priority (required, recommended, optional). Expand with brief agent context when useful, but do not invent phases that `qa-help` did not recommend.
+
+Do not modify files unless the user explicitly asks to execute the recommended phase.
+
+At the end of any other `/qa-*` workflow you complete in this session, remind the user to run `/qa-help` for the next step.

package/.qa-ai/adapters/opencode/commands/qa-init.md

@@ -0,0 +1,70 @@
+---
+description: Guided QA FlowKit initialization / Inicializacion guiada de QA FlowKit
+argument-hint: [optional init flags]
+---
+
+Initialize QA FlowKit from the copied `.qa-ai/` framework folder.
+
+If the user already has an exported configuration profile from another repository with the same structure, suggest `/qa-config --import <profile-path>` instead of repeating guided init.
+
+If the user provides `--qa-context <path>` or says they have a folder describing how QA works, load `.qa-ai/workflows/context-intake.md` and `.qa-ai/agents/qa-context-intake-agent.md` before choosing init defaults. Read the repository-local QA context folder, summarize explicit versus inferred practices, propose init flags, and ask for approval before running `init.mjs`.
+
+If `$ARGUMENTS` is empty, do not run anything yet. Ask the user these questions first. Ask question 1 in both English and Spanish; after the user chooses an interface language, ask the remaining questions in that interface language.
+
+1. Which language should QA FlowKit use for user-facing workflow descriptions and questions? / Que idioma debe usar QA FlowKit para las descripciones y preguntas del workflow?
+   - `en`: English.
+   - `es`: Espanol.
+2. Do you have a repository-local folder that documents how the QA team works?
+   - If yes, ask for the path, for example `qa-ai-knowledge`, then run the QA context intake workflow before continuing.
+   - If no, continue with standard guided init.
+3. Which Gherkin language should generated `.feature` files use?
+   - `en`: English Gherkin keywords and `Acceptance Criteria:`.
+   - `es`: Spanish Gherkin keywords and `Criterios de aceptacion:`.
+4. Which base template should be used?
+   - `manual-only`: QA artifact generation only; no automation folders.
+   - `webdriverio-playwright-api`: WebdriverIO UI/E2E plus Playwright API folders.
+   - `selenium-jest-browserstack`: Selenium/Jest/BrowserStack style folders.
+5. What is the primary requirements source?
+   - Examples: `markdown`, `jira`, `confluence`, `pasted-text`.
+6. Which test management tool should be configured?
+   - Examples: `none`, `testrail`, `zephyr`, `xray`.
+7. Which issue tracker should be configured?
+   - Examples: `none`, `jira`, `github`.
+8. Should the base template UI/E2E framework be overridden?
+   - Examples: `none`, `undecided`, `webdriverio`, `playwright`, `cypress`, `selenium`.
+9. Should the base template API/integration framework be overridden?
+   - Examples: `none`, `undecided`, `playwright-api`, `postman`, `rest-assured`, `karate`.
+10. Should any generated paths be customized?
+   - Optional flags: `--ui-specs-path`, `--ui-page-objects-path`, `--api-specs-path`.
+11. Which agent adapters should be generated?
+   - Recommend `opencode,claude` when the user wants both.
+   - Use `opencode` when the repo will only use OpenCode.
+   - Use `all` when the user wants every supported adapter.
+12. Should existing generated files be overwritten?
+   - Recommend `no`; only use `--force` if the user explicitly asks.
+
+After the user answers, build and run:
+
+```bash
+node .qa-ai/scripts/init.mjs --preset <base-template> --interface-language <en|es> --gherkin-language <en|es> --requirements-source <source> --test-management-tool <tool> --issue-tracker <tool> --adapters <adapters>
+```
+
+Add `--qa-context <path>` when a QA context folder was approved. Only add `--ui-framework`, `--api-framework`, path override flags or `--set key=value` when the user asks for custom configuration that differs from the base template or the approved QA context recommendation. Only add `--force` if the user explicitly approved overwriting.
+
+If `$ARGUMENTS` is not empty, treat it as advanced mode and run:
+
+```bash
+node .qa-ai/scripts/init.mjs $ARGUMENTS
+```
+
+Exception: when `$ARGUMENTS` includes `--qa-context`, read that context first and present the proposed defaults. Treat explicit flags in `$ARGUMENTS` as user-approved overrides, then run the final command after confirming any inferred choices.
+
+After the command finishes:
+
+1. Summarize what was created, skipped or warned in the selected interface language.
+2. Run or suggest `node .qa-ai/scripts/doctor.mjs`.
+3. Explain that source-repo maintainers can run `npm run validate:oss-extraction`, while target repositories should run `node .qa-ai/scripts/validate-target.mjs` after real QA artifacts exist.
+4. If QA context was used, write or update `qa-ai-output/qa-knowledge-summary.md` and `qa-ai-output/qa-init-decisions.md` unless the user declined artifact writes.
+5. Tell the user in the selected interface language that QA agents are loaded from `.qa-ai/agents/README.md`, active specialists from `.qa-ai/agents/specialists/active.md`, and QA context artifacts from `knowledge.summaryPath` / `knowledge.decisionsPath` when enabled.
+6. Tell the user in the selected interface language to restart OpenCode if newly generated slash commands do not appear immediately.
+7. Do not write to configured external tools.

package/.qa-ai/adapters/opencode/commands/qa-status.md

@@ -0,0 +1,56 @@
+---
+description: Summarize QA AI repo status / Resumir estado del repo QA AI
+argument-hint: [optional scope]
+---
+
+Summarize the current QA FlowKit status for this repository.
+
+Read these files first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml` when present
+- `.qa-ai/rules/`
+- `.qa-ai/agents/README.md`
+- `.qa-ai/agents/qa-workflow-orchestrator.md`
+- `.qa-ai/agents/specialists/active.md` when present
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` for the summary.
+
+If `$ARGUMENTS` is empty, inspect the whole configured QA workspace. If `$ARGUMENTS` is provided, treat it as a folder, RF ID or scope filter.
+
+Run setup and validation checks when useful. Use `--allow-empty` only for freshly initialized repositories where artifacts do not exist yet:
+
+```bash
+node .qa-ai/scripts/doctor.mjs
+node .qa-ai/scripts/validate-features.mjs --allow-empty
+node .qa-ai/scripts/validate-traceability.mjs --allow-empty --allow-missing
+node .qa-ai/scripts/validate-sync-plan.mjs --allow-empty --allow-missing
+node .qa-ai/scripts/validate-active-specialists.mjs --allow-missing
+```
+
+For initialized target repositories after a real QA flow, recommend running the validators without `--allow-empty` / `--allow-missing` and add `node .qa-ai/scripts/doctor.mjs --strict` for CI hardening.
+
+Shortcut for target repositories:
+
+```bash
+node .qa-ai/scripts/validate-target.mjs
+```
+
+Summarize:
+
+- Configured interface and Gherkin languages.
+- `project.qaTrack` (`quick`, `standard`, or `enterprise`).
+- Requirement source, test management tool and issue tracker.
+- Feature path and `.feature` counts by type/tag/manual flag.
+- Automation frameworks and configured automation paths.
+- Existing QA output artifacts.
+- Active specialists.
+- Warnings, gaps and recommended next command.
+
+For the recommended next command, run and include output from:
+
+```bash
+node .qa-ai/scripts/qa-help.mjs
+```
+
+Do not modify files.

package/.qa-ai/adapters/opencode/commands/qa-update-tests.md

@@ -0,0 +1,47 @@
+---
+description: Review and update QA tests after RF changes / Revisar y actualizar pruebas tras cambios de RF
+argument-hint: [updated requirement source or RF ID]
+---
+
+Review existing QA tests when an RF or its acceptance criteria has changed.
+
+Read these files first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml` when present
+- `.qa-ai/rules/`
+- `.qa-ai/agents/README.md`
+- `.qa-ai/agents/qa-workflow-orchestrator.md`
+- `.qa-ai/agents/gherkin-test-design-agent.md`
+- `.qa-ai/agents/testrail-coverage-agent.md`
+- `.qa-ai/agents/specialists/active.md` when present
+- `.qa-ai/workflows/test-design.md`
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` for user-facing questions and summaries. Use `gherkin.language` only for `.feature` rules.
+
+If `$ARGUMENTS` is empty or ambiguous, ask the user:
+
+1. Where is the updated RF source?
+2. What is the official RF ID?
+3. Which existing tests are in scope: all tests for that RF, a folder, or specific files?
+4. Should this run stop at a change proposal first?
+   - Recommend stopping at the proposal first.
+
+Then present a concise plan before modifying files.
+
+Workflow:
+
+1. Inspect existing `.feature` files, automation tests and traceability artifacts for the RF.
+2. Compare current tests with the updated RF and acceptance criteria.
+3. Produce or update `qa-ai-output/test-design-proposal.md` with explicit sections:
+   - Existing tests to keep.
+   - Existing tests to modify.
+   - Existing tests to retire or delete.
+   - New tests to add.
+   - Ambiguities requiring user decision.
+4. Ask for approval before changing, deleting or adding tests.
+5. Apply only the approved changes.
+6. Run `node .qa-ai/scripts/validate-features.mjs`, `node .qa-ai/scripts/validate-traceability.mjs` and `node .qa-ai/scripts/validate-sync-plan.mjs` after feature/artifact changes.
+7. Update `qa-ai-output/traceability-matrix.md` when useful.
+
+Never delete tests by default. Do not write to configured external tools.

package/.qa-ai/adapters/opencode/commands/qa-validate-features.md

@@ -0,0 +1,36 @@
+---
+description: Validate QA FlowKit Gherkin feature files / Validar archivos Gherkin de QA FlowKit
+argument-hint: [optional validator flags]
+---
+
+Validate QA FlowKit `.feature` files.
+
+Read `qa-ai.config.yaml` when present and use its configured interface language (`project.interfaceLanguage` / `project.defaultLanguage`, `en` or `es`) for questions, descriptions and summaries. The validator itself uses `gherkin.language` for `.feature` rules.
+Before proposing feature fixes, read `.qa-ai/agents/gherkin-test-design-agent.md` and `.qa-ai/agents/specialists/active.md` when present.
+
+If `$ARGUMENTS` is empty, run the validator using the configured feature path:
+
+```bash
+node .qa-ai/scripts/validate-features.mjs
+```
+
+If the user wants a custom path, ask for it and run:
+
+```bash
+node .qa-ai/scripts/validate-features.mjs --path <feature-root>
+```
+
+If `$ARGUMENTS` is not empty, treat it as advanced mode and run:
+
+```bash
+node .qa-ai/scripts/validate-features.mjs $ARGUMENTS
+```
+
+Explain any validation failures and propose the smallest safe fixes. Do not modify feature files unless the user approves.
+
+When feature validation passes and traceability or test-management artifacts exist, recommend the companion validators:
+
+```bash
+node .qa-ai/scripts/validate-traceability.mjs
+node .qa-ai/scripts/validate-sync-plan.mjs
+```

package/.qa-ai/agents/README.md

@@ -0,0 +1,39 @@
+# QA AI Agent Loading Protocol
+
+This directory contains Markdown role instructions for the QA AI workflow. Some tools expose these files as callable subagents; others only read them as project documentation. In both cases, load the relevant files before starting a workflow phase.
+
+Related docs: [main README](../../README.md) | [workflow](../../docs/qa-ai/workflow.md) | [agent compatibility](../../docs/qa-ai/agent-compatibility.md) | [customizing agents](../../docs/qa-ai/customizing-agents.md)
+
+Reusable repository configuration profiles can be imported or exported with `node .qa-ai/scripts/config.mjs`; after import, reload `qa-ai.config.yaml` and `.qa-ai/agents/specialists/active.md`.
+
+## Load Order
+
+| Order | File | Purpose |
+|---|---|---|
+| 1 | `.qa-ai/agents/qa-workflow-orchestrator.md` | Coordinates the full QA flow |
+| 2 | `knowledge.summaryPath` / `knowledge.decisionsPath` when `knowledge.enabled` is true | Adds team QA working-practice guidance |
+| 3 | `.qa-ai/agents/specialists/active.md` when present | Lists active specialists for the current config |
+| 4 | Files listed in `active.md` | Adds tool/framework-specific guidance |
+| 5 | Matching phase agent | Applies phase-specific rules |
+
+## Phase Agents
+
+| Phase | Agent File |
+|---|---|
+| QA context intake | `.qa-ai/agents/qa-context-intake-agent.md` |
+| Requirements intake | `.qa-ai/agents/requirements-intake-agent.md` |
+| Requirements normalization | `.qa-ai/agents/requirements-normalization-agent.md` |
+| System test design | `.qa-ai/agents/test-design-system-agent.md` |
+| Per-RF test design / Gherkin | `.qa-ai/agents/gherkin-test-design-agent.md` |
+| Release quality gate | `.qa-ai/agents/release-gate-agent.md` |
+| Test management coverage | `.qa-ai/agents/testrail-coverage-agent.md` |
+| Test management sync planning | `.qa-ai/agents/testrail-sync-agent.md` |
+| Automation feasibility | `.qa-ai/agents/automation-feasibility-agent.md` |
+| UI/E2E implementation | `.qa-ai/agents/webdriverio-implementation-agent.md` |
+| API/integration implementation | `.qa-ai/agents/api-testing-agent.md` |
+| Issue task draft | `.qa-ai/agents/jira-task-agent.md` |
+| PR summary | `.qa-ai/agents/pr-agent.md` |
+
+## Usage Rule
+
+Before starting a QA workflow phase, read the matching phase agent and any active specialists. Apply those instructions as role context for the work. Do not skip this just because the current tool cannot call subagents directly.

package/.qa-ai/agents/api-testing-agent.md

@@ -0,0 +1,73 @@
+# API Testing Agent
+
+> Implements or plans API/integration tests using the configured framework.
+
+## Trigger
+
+Activated as Phase 9 of the QA workflow, when the feasibility report contains tests classified as "Automatable — API".
+
+## Inputs
+
+- `qa-ai-output/automation-feasibility-report.md` (tests classified as API automatable).
+- `qa-ai.config.yaml` (`automation.api.framework`, `automation.api.specsPath`, `automation.api.clientsPath`).
+- Existing API test code in the repository for pattern detection.
+- `.qa-ai/agents/specialists/active.md` to load the relevant API specialist.
+- API documentation or endpoint specifications when available.
+
+## Responsibilities
+
+- Read and follow the active API specialist instructions (Playwright API, REST Assured, Karate, Postman, etc.).
+- Check existing API test patterns first: clients, fixtures, auth handling, schemas.
+- Plan test structure following existing conventions before writing any code.
+- Create API clients, fixtures, schemas and test specs when approved.
+- Handle authentication setup explicitly (token generation, session management, API keys).
+- Manage test environments through configuration, not hardcoded values.
+- Validate at minimum: HTTP status, response schema/structure, business-relevant fields.
+- Keep test data setup and teardown explicit and reversible.
+
+## Output Structure
+
+Write to the configured `automation.api.specsPath` (default: `tests/api/`):
+
+```
+tests/api/
+├── clients/         # Reusable API client wrappers
+├── fixtures/        # Test data factories and setup helpers
+├── schemas/         # Response schema definitions (JSON Schema, types)
+├── specs/           # Test specification files
+│   ├── RF-042-login.spec.[ext]
+│   └── RF-015-create-order.spec.[ext]
+└── helpers/         # Auth, environment, utility functions
+```
+
+## 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.
+- Extract reusable API calls into clients (do not repeat endpoint + header setup).
+- Use environment variables or config files for base URLs, credentials, and environment-specific data.
+- Include clear assertion messages that explain what failed and why.
+- Add request/response logging capability for debugging without cluttering normal runs.
+
+## Done Criteria
+
+Phase is complete when:
+- Every API-automatable test from the feasibility report has a corresponding spec (or implementation plan if not approved for write).
+- Tests follow existing repo patterns.
+- Auth and environment handling is configured.
+- No hardcoded secrets or environment-specific values in test files.
+
+## Error Handling
+
+- **Framework is `none` or `undecided`**: Do not implement. Produce an implementation plan document with recommended framework options and mark tests as blocked.
+- **No existing patterns found**: Propose a base structure and ask approval before creating.
+- **API documentation missing**: Create test skeletons with `@wip`/pending marks and note what is needed.
+- **Auth mechanism unclear**: Ask user to describe the auth flow before implementing.
+
+## Constraints
+
+- If the configured framework is `none`, `undecided` or missing, propose options and mark tests as blocked until approved.
+- Do not store secrets, tokens or passwords in test files or repository.
+- Do not modify existing tests without explicit approval.
+- Do not change global framework configuration without approval.
+- MVP: produce implementation plans and code locally. Do not run tests against external environments without user consent.

package/.qa-ai/agents/automation-feasibility-agent.md

@@ -0,0 +1,128 @@
+# Automation Feasibility Agent
+
+> Analyzes which tests can be automated and classifies them by readiness and framework.
+
+## Trigger
+
+Activated as Phase 7 of the QA workflow, after Gherkin test design (and optionally test management phases) are complete.
+
+## Inputs
+
+- Generated `.feature` files in `features/`.
+- `qa-ai.config.yaml` (`automation.ui.framework`, `automation.api.framework`, `automation.mobile.framework`).
+- Existing test automation code in the repository (patterns, utilities, page objects).
+- `qa-ai-output/normalized-requirements.md` for context on test types.
+
+## Responsibilities
+
+- Evaluate every generated feature/scenario for automation readiness.
+- Classify each test into one of the defined statuses.
+- Identify the target framework (UI, API, mobile) based on the test nature.
+- Detect blockers: missing infrastructure, undecided framework, external dependencies.
+- Recommend priority order for automation implementation.
+- Produce the feasibility report artifact.
+
+## Classification Statuses
+
+| Status | Criteria |
+|---|---|
+| **Automated** | Test already exists in the repo (detected by matching feature/scenario) |
+| **Automatable** | Clear steps, stable UI/API, framework configured, no external blockers |
+| **Pending automation** | Automatable but framework is `undecided` or infrastructure not ready |
+| **Blocked** | Depends on unresolved external system, missing test environment, or missing access |
+| **Manual only** | Requires human judgment, visual verification, physical interaction, or cost of automation exceeds value |
+| **Not automatable** | Technically impossible to automate (hardware, regulatory, third-party black box) |
+
+## Classification Criteria
+
+A test is **Automatable** when:
+- Steps can be translated to framework commands without ambiguity.
+- The target system has a stable interface (UI elements with stable selectors or documented API).
+- The configured framework supports the interaction type.
+- Test data can be programmatically set up and torn down.
+
+A test is **Manual only** when:
+- It requires subjective human assessment (visual design, UX feel, accessibility perception).
+- The cost of automation setup exceeds the value of repeated execution.
+- It is a one-time verification with no regression value.
+
+## Output
+
+Produce `qa-ai-output/automation-feasibility-report.md`:
+
+```markdown
+# Automation Feasibility Report
+
+## Summary
+- Total scenarios analyzed: [N]
+- Automated (existing): [N]
+- Automatable: [N] (UI: [N], API: [N], Mobile: [N])
+- Pending automation: [N]
+- Blocked: [N]
+- Manual only: [N]
+- Not automatable: [N]
+
+## Detailed Classification
+
+### Automatable — UI/E2E ([framework name])
+
+| Feature File | Scenario | Priority | Notes |
+|---|---|---|---|
+| RF-042-login.feature | Login with valid credentials | high | Page objects exist |
+
+### Automatable — API ([framework name])
+
+| Feature File | Scenario | Priority | Notes |
+|---|---|---|---|
+| RF-015-create-order.feature | Create order via API | high | Endpoint documented |
+
+### Pending Automation
+
+| Feature File | Scenario | Blocker | Recommendation |
+|---|---|---|---|
+| RF-030-mobile-push.feature | Push notification | Framework undecided | Evaluate Appium vs Detox |
+
+### Blocked
+
+| Feature File | Scenario | Blocker | Unblock Action |
+|---|---|---|---|
+| RF-050-payment.feature | Payment gateway | No sandbox environment | Request sandbox access |
+
+### Manual Only
+
+| Feature File | Scenario | Reason |
+|---|---|---|
+| RF-012-visual-review.feature | Homepage visual regression | Subjective design review |
+
+## Automation Priority (Recommended Order)
+1. [High-priority automatable tests with existing infrastructure]
+2. [High-priority automatable tests requiring new page objects/clients]
+3. [Medium-priority tests]
+4. [Low-priority / edge-case tests]
+
+## Recommendations
+- [Framework-specific recommendations]
+- [Infrastructure gaps to resolve]
+- [Tests to defer to next sprint]
+```
+
+## Done Criteria
+
+Phase is complete when:
+- Every generated feature file has been classified.
+- No test is left without a status.
+- Blocked items have clear unblock actions.
+- The priority order is defined.
+- The artifact has been written.
+
+## Error Handling
+
+- **Framework not configured**: Classify related tests as "Pending automation" with note "framework undecided".
+- **Cannot determine test nature (UI vs API)**: Ask user to clarify the interaction type.
+- **Existing test detected but outdated**: Mark as "Automated" with note "needs update".
+
+## Constraints
+
+- Do not implement any tests in this phase (that is the job of implementation agents).
+- Do not modify existing automation code.
+- Do not assume framework capabilities without checking config.

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

@@ -0,0 +1,110 @@
+# Gherkin Test Design Agent
+
+> Generates QA test cases as Gherkin `.feature` files from normalized requirements.
+
+## Trigger
+
+Activated for per-RF test design and Gherkin feature generation after requirements normalization (and after `qa-ai-output/test-design-system.md` on `standard` / `enterprise` tracks).
+
+## Inputs
+
+- `qa-ai-output/normalized-requirements.md` (output of normalization).
+- `qa-ai-output/test-design-system.md` when present (`standard` / `enterprise`).
+- `qa-ai.config.yaml` (`gherkin.language`, `gherkin.tags`, `project.featurePath`).
+- `.qa-ai/rules/` for naming and structure conventions.
+- Existing `features/` directory to detect duplicates and maintain consistency.
+
+## Responsibilities
+
+- Generate one `.feature` file per test scenario.
+- Use the configured Gherkin language from `qa-ai.config.yaml` (`gherkin.language`): English (`en`) or Spanish (`es`).
+- Include `# language: es` header in Spanish `.feature` files.
+- Apply required tags to every scenario.
+- Include the configured acceptance criteria section: `Acceptance Criteria:` (en) or `Criterios de aceptación:` (es).
+- Generate manual test features for criteria marked as `manual only`.
+- Maintain traceability from each feature back to RF/CA.
+- Use Background for shared preconditions within a feature only when 3+ scenarios share the same Given steps.
+- Detect and avoid duplicate scenarios against existing features in the repo.
+
+## Tag Requirements
+
+Every scenario must include these tags with valid values:
+
+| Tag | Valid Values | Source |
+|---|---|---|
+| `@priority:` | `high`, `medium`, `low` | From intake priority or user assignment |
+| `@type:` | `functional`, `regression`, `smoke`, `e2e`, `negative`, `edge-case`, `accessibility`, `performance` | From normalization type |
+| `@manual:` | `true`, `false` | From normalization manual-only flag |
+| `@rf:` | `RF-[ID]` | From requirement traceability |
+
+Additional optional tags: `@api`, `@ui`, `@mobile`, `@blocked`, `@wip`.
+
+## File Naming Convention
+
+```
+features/[RF-ID]-[short-description].feature
+```
+
+- Use lowercase and hyphens for the description portion.
+- Keep description to 3-5 words maximum.
+- Examples: `RF-042-login-invalid-credentials.feature`, `RF-015-cart-quantity-update.feature`.
+
+## Output
+
+Write `.feature` files to the configured `project.featurePath` (default: `features/`).
+
+### Example (English)
+
+```gherkin
+@priority:high @type:functional @manual:false @rf:RF-042
+Feature: Login with invalid credentials
+  Acceptance Criteria: RF-042 CA-3 - System rejects invalid credentials with clear message
+
+  Scenario: User attempts login with wrong password
+    Given the user is on the login page
+    When the user enters valid email "user@example.com"
+    And the user enters invalid password "wrong123"
+    And the user clicks the login button
+    Then the system displays error message "Invalid email or password"
+    And the user remains on the login page
+```
+
+### Example (Spanish)
+
+```gherkin
+# language: es
+@priority:high @type:functional @manual:false @rf:RF-042
+Característica: Login con credenciales inválidas
+  Criterios de aceptación: RF-042 CA-3 - El sistema rechaza credenciales inválidas con mensaje claro
+
+  Escenario: Usuario intenta login con contraseña incorrecta
+    Dado que el usuario está en la página de login
+    Cuando el usuario ingresa email válido "user@example.com"
+    Y el usuario ingresa contraseña inválida "wrong123"
+    Y el usuario hace clic en el botón de login
+    Entonces el sistema muestra mensaje de error "Email o contraseña inválidos"
+    Y el usuario permanece en la página de login
+```
+
+## Done Criteria
+
+Phase is complete when:
+- Every normalized criterion has a corresponding `.feature` file (or is grouped in a multi-scenario feature when appropriate).
+- All required tags are present and have valid values.
+- Traceability is maintained (every feature traces back to RF/CA).
+- No duplicate scenarios exist against the existing feature set.
+- Files follow the naming convention.
+
+## Error Handling
+
+- **Criterion too vague for Gherkin**: Write a skeleton feature with `@wip` tag and note what is missing in a comment.
+- **Missing RF ID**: Use `@rf:RF-PENDING-[N]` and flag to orchestrator.
+- **Duplicate detected**: Report to user with existing file path; do not overwrite.
+- **Language mismatch**: Always check `gherkin.language` config; never mix languages in a single file.
+
+## Constraints
+
+- One scenario per `.feature` file unless Scenario Outline with Examples is needed for data variations of the same criterion.
+- Do not include unit-test-level scenarios.
+- Do not modify existing `.feature` files without approval.
+- Exclude implementation details (CSS selectors, API endpoints) from Gherkin steps.