qa-flowkit 0.4.0-alpha.0

package/.qa-ai/adapters/aider/.aider/README.md

@@ -0,0 +1,25 @@
+# Aider Adapter
+
+Aider should read the generic project instructions and configured QA rules before editing.
+
+Related docs: [main README](../../../../README.md) | [agent compatibility](../../../../docs/qa-ai/agent-compatibility.md)
+
+## Read First
+
+| File | Purpose |
+|---|---|
+| `AGENTS.md` | Generic behavior and safety rules |
+| `qa-ai.config.yaml` | Target repository configuration |
+| `.qa-ai/rules/` | Mandatory QA workflow rules |
+| `.qa-ai/workflows/` | Task playbooks |
+
+## Commands
+
+| Aider Command | Purpose |
+|---|---|
+| `/run node .qa-ai/scripts/config.mjs --help` | Import/export reusable QA AI config profiles |
+| `/run node .qa-ai/scripts/doctor.mjs` | Check setup health |
+| `/run node .qa-ai/scripts/validate-features.mjs` | Validate `.feature` files after changes |
+| `/run node .qa-ai/scripts/clean.mjs` | Preview cleanup before removing generated files |
+
+Never overwrite existing files or delete generated artifacts without explicit user approval.

package/.qa-ai/adapters/aider/.aider.conf.yml

@@ -0,0 +1,6 @@
+read:
+  - AGENTS.md
+  - README.md
+  - qa-ai.config.yaml
+  - .qa-ai/rules/approval.rules.md
+  - .qa-ai/rules/gherkin.rules.md

package/.qa-ai/adapters/claude/agents/qa-workflow-orchestrator.md

@@ -0,0 +1,18 @@
+# QA Workflow Orchestrator
+
+You coordinate the complete AI-assisted QA workflow.
+
+## Responsibilities
+
+- Read `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/` and `.qa-ai/agents/README.md` before acting.
+- Read `.qa-ai/agents/specialists/active.md` when present and load only the listed specialist instructions from `.qa-ai/agents/specialists/available/`.
+- Use the configured interface language from `qa-ai.config.yaml` (`project.interfaceLanguage` / `project.defaultLanguage`) for questions and descriptions. Use `gherkin.language` only for generated `.feature` files.
+- Delegate to specialized agents conceptually.
+- Maintain traceability from configured requirement sources/RF/CA to features, test management and automation.
+- Present a plan before every change.
+- Ask for approval before writes or modifications.
+- Stop and ask when official RF ID is missing.
+
+## Output expectation
+
+Every workflow must produce or update the expected docs under `qa-ai-output/`.

package/.qa-ai/adapters/claude/commands/qa-add-tests.md

@@ -0,0 +1,42 @@
+---
+description: Add QA tests for a new RF / Anadir pruebas QA para un RF nuevo
+argument-hint: [requirement source or RF ID]
+---
+
+Add new QA tests to a repository that may already contain `.feature` files and automation tests.
+
+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 generated `.feature` files.
+
+If `$ARGUMENTS` is empty or ambiguous, ask the user:
+
+1. Where is the new requirement/RF source?
+2. What is the official RF ID?
+3. Should the first pass produce only proposal artifacts, or create new `.feature` files after approval?
+
+Stop before final `.feature` generation if the official RF ID is missing.
+
+Then present a concise plan before modifying files.
+
+Workflow:
+
+1. Inspect existing `.feature` files and configured automation paths to avoid duplicates.
+2. Analyze the new RF and acceptance criteria.
+3. Produce or update `qa-ai-output/requirement-analysis.md`.
+4. Produce or update `qa-ai-output/test-design-proposal.md` with only new tests to add and existing tests to reuse.
+5. After approval, create one `.feature` file per new test case under the configured `gherkin.featurePath`.
+6. Update `qa-ai-output/traceability-matrix.md` when useful.
+7. 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.
+
+Do not modify existing tests unless the user explicitly approves that scope. Do not write to configured external tools.

package/.qa-ai/adapters/claude/commands/qa-automation-plan.md

@@ -0,0 +1,43 @@
+---
+description: Plan automation from existing QA tests / Planificar automatizacion desde pruebas existentes
+argument-hint: [feature path, RF ID, or test filter]
+---
+
+Create an automation feasibility and implementation plan from existing `.feature` tests.
+
+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/automation-feasibility-agent.md`
+- `.qa-ai/agents/webdriverio-implementation-agent.md` when UI automation is configured
+- `.qa-ai/agents/api-testing-agent.md` when API automation is configured
+- `.qa-ai/agents/specialists/active.md` when present
+- `.qa-ai/workflows/automation-analysis.md`
+- `.qa-ai/workflows/implementation.md`
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` for user-facing questions and summaries.
+
+If `$ARGUMENTS` is empty or ambiguous, ask the user:
+
+1. Which existing tests should be considered: all features, a folder, an RF ID, or specific files?
+2. Should this run only create the automation plan, or continue to implementation after approval?
+   - Recommend plan only first.
+3. Are there known environment, data, selector or credential constraints?
+
+Then present a concise plan before modifying files.
+
+Workflow:
+
+1. Inspect existing `.feature` files and configured automation paths.
+2. Inspect existing UI/API automation patterns before proposing code.
+3. Classify tests as automated, automatable, partial, manual, blocked or not automatable.
+4. Produce or update `qa-ai-output/automation-feasibility-report.md`.
+5. Produce or update `qa-ai-output/automation-implementation-plan.md`.
+6. If the user explicitly approves implementation, add automation code using the configured frameworks and local patterns.
+7. Run relevant project tests or explain why they cannot be run.
+
+Do not add dependencies, change global framework config or write to external tools without approval.

package/.qa-ai/adapters/claude/commands/qa-clean.md

@@ -0,0 +1,42 @@
+---
+description: Guided manifest-based QA AI cleanup / Limpieza guiada de QA FlowKit
+argument-hint: [optional clean flags]
+---
+
+Preview or execute cleanup for generated QA FlowKit artifacts.
+
+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.
+
+If `$ARGUMENTS` is empty, run the safe dry-run first:
+
+```bash
+node .qa-ai/scripts/clean.mjs
+```
+
+Summarize the cleanup plan, then ask the user:
+
+1. Which scope should be cleaned?
+   - `generated`: generated config, QA output artifacts and empty generated folders.
+   - `adapters`: generated agent adapter files.
+   - `empty-dirs`: tracked empty directories.
+   - `all`: all tracked entries.
+2. Should cleanup be executed with `--force`?
+   - Recommend `no` until the dry-run is reviewed.
+3. Should modified tracked files be deleted?
+   - Recommend `no`; only use `--include-modified` if the user explicitly wants to discard edits.
+
+If the user approves execution, build and run:
+
+```bash
+node .qa-ai/scripts/clean.mjs --<scope> --force
+```
+
+Only add `--include-modified` when explicitly approved.
+
+If `$ARGUMENTS` is not empty, treat it as advanced mode and run:
+
+```bash
+node .qa-ai/scripts/clean.mjs $ARGUMENTS
+```
+
+Do not delete anything outside the manifest-based clean script.

package/.qa-ai/adapters/claude/commands/qa-config.md

@@ -0,0 +1,51 @@
+---
+description: Import or export QA FlowKit configuration / Importar o exportar configuracion de QA FlowKit
+argument-hint: [--export path | --import path]
+---
+
+Import or export a reusable QA FlowKit configuration profile.
+
+Read these files first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml` when present
+- `.qa-ai/rules/`
+- `.qa-ai/agents/README.md`
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` when present for user-facing questions and summaries.
+
+If `$ARGUMENTS` is empty, ask the user:
+
+1. Do you want to export the current config or import an existing profile?
+2. What repo-local profile path should be used?
+   - Recommended export path: `.qa-ai/config-profiles/team.yaml`.
+3. If importing and `qa-ai.config.yaml` already exists, should it be overwritten?
+   - Recommend `no`; only use `--force` if the user explicitly approves.
+
+For export, run:
+
+```bash
+node .qa-ai/scripts/config.mjs --export <profile-path>
+```
+
+For import, run:
+
+```bash
+node .qa-ai/scripts/config.mjs --import <profile-path>
+```
+
+Only add `--force` when the user explicitly approves overwriting. Add `--no-structure` only when the user wants to import the YAML without creating configured folders or refreshing `.qa-ai/agents/specialists/active.md`.
+
+If `$ARGUMENTS` is not empty, treat it as advanced mode and run:
+
+```bash
+node .qa-ai/scripts/config.mjs $ARGUMENTS
+```
+
+After import, run or suggest:
+
+```bash
+node .qa-ai/scripts/doctor.mjs
+```
+
+Do not write to external tools.

package/.qa-ai/adapters/claude/commands/qa-coverage.md

@@ -0,0 +1,46 @@
+---
+description: Analyze QA functional coverage / Analizar cobertura funcional QA
+argument-hint: [RF ID, requirement source, or scope]
+---
+
+Analyze functional QA coverage across requirements, `.feature` files, manual tests and automated tests.
+
+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/testrail-coverage-agent.md`
+- `.qa-ai/agents/automation-feasibility-agent.md`
+- `.qa-ai/agents/specialists/active.md` when present
+- `.qa-ai/workflows/automation-analysis.md`
+- `.qa-ai/workflows/testrail-sync.md`
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` for user-facing questions and summaries.
+
+If `$ARGUMENTS` is empty or ambiguous, ask the user:
+
+1. What scope should be analyzed: one RF, a requirement source, a feature folder, or the whole repo?
+2. Where are the requirements or acceptance criteria for that scope?
+3. Should configured test management data be considered from local exports/mapping files?
+
+Then present a concise plan before modifying files.
+
+Coverage dimensions:
+
+- Requirement/RF coverage.
+- Acceptance criteria coverage.
+- Manual test coverage.
+- Automated test coverage.
+- Gaps, duplicates, overlaps and stale tests.
+- Automation candidates and blockers.
+
+Expected local artifacts:
+
+- `qa-ai-output/qa-coverage-report.md`
+- `qa-ai-output/testrail-coverage-analysis.md` when test management is configured or local mapping data exists
+- `qa-ai-output/traceability-matrix.md` when useful
+
+Do not modify tests or write to external tools unless the user explicitly asks and approves a follow-up change.

package/.qa-ai/adapters/claude/commands/qa-doctor.md

@@ -0,0 +1,11 @@
+# /qa-doctor
+
+Run the QA FlowKit doctor script and explain the results.
+
+Read `qa-ai.config.yaml` when present and explain results in its configured interface language (`project.interfaceLanguage` / `project.defaultLanguage`, `en` or `es`).
+
+For target-repository CI or post-flow hardening, tell the user they can run `node .qa-ai/scripts/validate-target.mjs`, which includes `doctor --strict`, feature validation, traceability validation, sync-plan validation and active-specialist validation.
+
+Command output:
+
+!`node .qa-ai/scripts/doctor.mjs`

package/.qa-ai/adapters/claude/commands/qa-full-flow.md

@@ -0,0 +1,59 @@
+---
+description: Guided full QA FlowKit workflow / Workflow completo guiado de QA FlowKit
+argument-hint: [optional requirement source]
+---
+
+Run the complete QA AI workflow for the configured requirement source, Markdown PRD/RF or pasted requirement.
+
+Read these files first:
+
+- `AGENTS.md`
+- `qa-ai.config.yaml`
+- `.qa-ai/rules/`
+- `.qa-ai/agents/README.md`
+- `.qa-ai/agents/qa-workflow-orchestrator.md`
+- `.qa-ai/agents/specialists/active.md` when present
+- `.qa-ai/workflows/full-flow.md`
+
+For each phase, load the matching phase agent from `.qa-ai/agents/README.md` and any active specialists before producing or changing artifacts. If the current tool cannot call subagents, treat those Markdown files as required role instructions.
+
+Use `project.interfaceLanguage` / `project.defaultLanguage` from `qa-ai.config.yaml` for user-facing questions and descriptions. Use `gherkin.language` only for generated `.feature` files. Supported values are `en` and `es`; default to `en` if the config is missing.
+
+If `$ARGUMENTS` is empty or the requirement source is ambiguous, ask the user:
+
+1. Where is the requirement source?
+   - Example: `docs/prd.md`, `docs/PRD/checkout.md`, pasted text, configured issue ID or documentation page reference.
+2. What is the official RF ID?
+   - If missing, say final `.feature` generation will pause until it is provided.
+3. What test management project/suite should be used for coverage/sync planning?
+   - If unknown, produce local placeholder analysis and mark the decision as pending.
+4. Should this run produce only proposal artifacts first, or continue to `.feature` generation after approval?
+   - Recommend proposal artifacts first.
+
+Then present a concise plan before modifying files.
+
+Expected local artifacts:
+
+- `qa-ai-output/requirement-analysis.md`
+- `qa-ai-output/testrail-coverage-analysis.md`
+- `qa-ai-output/test-design-proposal.md`
+- `.feature` files under the configured feature path after approval
+- `qa-ai-output/testrail-sync-plan.md`
+- `qa-ai-output/traceability-matrix.md`
+- `qa-ai-output/automation-feasibility-report.md`
+- `qa-ai-output/automation-implementation-plan.md`
+- `qa-ai-output/pr-summary.md`
+
+After feature and QA artifact changes, run the aggregated target-repository validator:
+
+```bash
+node .qa-ai/scripts/validate-target.mjs
+```
+
+For early/incomplete repositories, use `node .qa-ai/scripts/validate-target.mjs --allow-empty --allow-missing --no-strict-doctor`.
+
+Do not write to configured external tools. Ask for the official RF ID before final feature generation if it is missing.
+
+Respect `project.qaTrack` from `qa-ai.config.yaml` (see `.qa-ai/workflows/full-flow.md`).
+
+When this workflow step completes, run `/qa-help` or `node .qa-ai/scripts/qa-help.mjs` and share the recommended next phase.

package/.qa-ai/adapters/claude/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/claude/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/claude/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 `claude,opencode` when the user wants both.
+   - Use `claude` when the repo will only use Claude Code.
+   - 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 Claude Code if newly generated slash commands do not appear immediately.
+7. Do not write to configured external tools.

package/.qa-ai/adapters/claude/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/claude/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/claude/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/adapters/cline/.cline/README.md

@@ -0,0 +1,25 @@
+# Cline Adapter
+
+Use `.clinerules` plus `AGENTS.md` as the primary instruction layer for Cline.
+
+Related docs: [main README](../../../../README.md) | [agent compatibility](../../../../docs/qa-ai/agent-compatibility.md)
+
+## Read First
+
+| File | Purpose |
+|---|---|
+| `.clinerules` | Cline-specific behavior rules |
+| `AGENTS.md` | Generic behavior and safety rules |
+| `qa-ai.config.yaml` | Target repository configuration |
+| `.qa-ai/rules/` | Mandatory QA workflow rules |
+
+## Local Checks
+
+| Command | Purpose |
+|---|---|
+| `node .qa-ai/scripts/config.mjs --help` | Import/export reusable QA AI config profiles |
+| `node .qa-ai/scripts/doctor.mjs` | Check setup health |
+| `node .qa-ai/scripts/validate-features.mjs` | Validate `.feature` files |
+| `node .qa-ai/scripts/clean.mjs` | Preview generated artifact cleanup |
+
+Run cleanup as a dry-run before deleting anything, and ask for explicit approval before destructive actions.