qa-flowkit 0.4.0-alpha.0

package/.qa-ai/workflows/context-intake.md

@@ -0,0 +1,66 @@
+# QA Context Intake Workflow
+
+Use this workflow when the user provides a repository-local folder that documents how QA works for their team.
+
+## Purpose
+
+Convert QA working-practice documentation into a proposed QA FlowKit configuration and durable local guidance for future agents.
+
+## Supported Input
+
+The MVP supports one repository-local folder:
+
+```bash
+node .qa-ai/scripts/init.mjs --qa-context qa-ai-knowledge
+```
+
+The folder may contain Markdown, text, YAML, JSON or other readable local documentation. Do not read files outside the repository. Do not read secrets.
+
+## Required Steps
+
+1. Read `AGENTS.md`, `.qa-ai/rules/`, `.qa-ai/agents/README.md` and this workflow.
+2. Load `.qa-ai/agents/qa-context-intake-agent.md`.
+3. Inspect the QA context folder structure and read only relevant documentation.
+4. Summarize explicit QA practices and separate them from inferred practices.
+5. Recommend init defaults:
+   - `--interface-language`
+   - `--gherkin-language`
+   - `--preset`
+   - `--requirements-source`
+   - `--test-management-tool`
+   - `--issue-tracker`
+   - `--ui-framework`
+   - `--api-framework`
+   - `--adapters`
+   - optional `--set key=value` overrides
+6. Present the recommendation and ask for approval.
+7. After approval, run `init.mjs` with `--qa-context <path>` plus the approved flags.
+8. Write or update the configured local artifacts:
+   - `qa-ai-output/qa-knowledge-summary.md`
+   - `qa-ai-output/qa-init-decisions.md`
+9. Run `node .qa-ai/scripts/doctor.mjs`.
+
+## Artifact Expectations
+
+`qa-ai-output/qa-knowledge-summary.md` should contain:
+
+- Source folder.
+- Files reviewed.
+- Explicit QA practices.
+- Inferred QA practices.
+- Pending decisions.
+- Workflow adaptations future agents must follow.
+
+`qa-ai-output/qa-init-decisions.md` should contain:
+
+- Approved init command.
+- Reasoning for selected defaults.
+- Explicit user approvals.
+- Deferred decisions.
+
+## Safety
+
+- Do not perform external writes.
+- Do not store secrets in generated artifacts.
+- Do not overwrite existing artifacts unless the user approves `--force` behavior.
+- If the context conflicts with `.qa-ai/rules/`, keep `.qa-ai/rules/` as the governing safety layer and document the conflict.

package/.qa-ai/workflows/full-flow.md

@@ -0,0 +1,55 @@
+# Full Flow
+
+Run this workflow when a user asks for the complete requirements-to-PR QA flow.
+
+## QA track
+
+Read `project.qaTrack` from `qa-ai.config.yaml`:
+
+| Track | Steps to run |
+|---|---|
+| `quick` | Intake → normalization → Gherkin (proposal + features) → traceability → PR |
+| `standard` | Full sequence below including system and per-RF test design |
+| `enterprise` | Full sequence below; then release gate (`/qa-gate`) and `validate-target.mjs` + `validate-release-gate.mjs` |
+
+When unsure which track applies, run `node .qa-ai/scripts/qa-help.mjs`.
+
+## Required inputs
+
+- Requirement source: configured source, markdown RF/PRD or pasted requirement text.
+- Official RF ID before final `.feature` generation.
+- Target test management project/suite before coverage or sync planning when a tool is configured and track is not `quick`.
+
+## Sequence (standard / enterprise)
+
+1. Read `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/` and this workflow.
+2. Produce or update `qa-ai-output/requirement-analysis.md`.
+3. Stop if the official RF ID is missing.
+4. **Standard / enterprise:** produce `qa-ai-output/test-design-system.md` (see `.qa-ai/workflows/test-design-system.md`).
+5. Produce `qa-ai-output/test-design-proposal.md` for the active RF/epic and ask approval before creating `.feature` files.
+6. Generate one `.feature` file per approved test case in the configured Gherkin language from `qa-ai.config.yaml` (`gherkin.language`).
+7. Run `node .qa-ai/scripts/validate-test-design.mjs` and `node .qa-ai/scripts/validate-features.mjs`; fix issues.
+8. Produce or update `qa-ai-output/testrail-coverage-analysis.md` (skip on `quick` track or when test management is disabled).
+9. Produce or update `qa-ai-output/testrail-sync-plan.md`; do not write to external test management tools in the MVP (skip on `quick` track).
+10. Update `qa-ai-output/traceability-matrix.md`.
+11. Produce or update `qa-ai-output/automation-feasibility-report.md` (skip on `quick` track).
+12. Produce `qa-ai-output/automation-implementation-plan.md` and ask approval before automation code changes (skip on `quick` track).
+13. Implement only approved automation changes using repository conventions (skip on `quick` track).
+14. Prepare `qa-ai-output/pr-summary.md` with traceability, execution status and residual risk.
+15. **Enterprise track only:** produce `qa-ai-output/release-gate.yaml` with `PASS`, `CONCERNS`, `FAIL` or `WAIVED` (see `.qa-ai/workflows/release-gate.md`).
+
+After each major step, run `node .qa-ai/scripts/qa-help.mjs` (or `/qa-help`) to confirm the next phase.
+
+**Enterprise finale:**
+
+```bash
+node .qa-ai/scripts/validate-target.mjs
+node .qa-ai/scripts/validate-release-gate.mjs
+```
+
+## Safety gates
+
+- No external writes to configured external tools in the MVP.
+- Do not overwrite existing files unless the user approved it or `--force` behavior is explicitly requested.
+- Do not modify existing tests without approval.
+- Never store credentials or secrets in repository files.

package/.qa-ai/workflows/implementation.md

@@ -0,0 +1,24 @@
+# Implementation Workflow
+
+Implement only approved automation changes using repository conventions.
+
+## Before coding
+
+- Read `qa-ai.config.yaml` to identify UI/API frameworks and paths.
+- Inspect existing tests, helpers, fixtures and page objects before creating new patterns.
+- Confirm the approved automation implementation plan.
+- Ask approval before modifying existing tests or global framework config.
+
+## During coding
+
+- Use the configured UI/E2E framework for UI coverage.
+- Use the configured API/integration framework for API coverage.
+- Reuse existing selectors, clients, fixtures and schemas when possible.
+- Keep tests deterministic and isolated.
+- Do not add dependencies without approval.
+
+## After coding
+
+- Run the most relevant local tests when possible.
+- If tests cannot be executed, document first manual execution requirements.
+- Update `qa-ai-output/traceability-matrix.md` and `qa-ai-output/pr-summary.md`.

package/.qa-ai/workflows/intake.md

@@ -0,0 +1,3 @@
+# Intake Workflow
+
+Read requirement sources, normalize scope, extract RF/CA, identify ambiguity and output requirement analysis.

package/.qa-ai/workflows/pr.md

@@ -0,0 +1,3 @@
+# PR Workflow
+
+Prepare PR summary, risks, traceability and execution status.

package/.qa-ai/workflows/release-gate.md

@@ -0,0 +1,22 @@
+# Release Gate Workflow
+
+Run when `project.qaTrack` is `enterprise` or when the team needs a formal go/no-go record.
+
+## Prerequisites
+
+- Traceability matrix and PR summary exist.
+- Target validators have been run (`validate-target.mjs` recommended).
+
+## Steps
+
+1. Read `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/approval.rules.md` and `.qa-ai/agents/release-gate-agent.md`.
+2. Review validator output and QA artifacts listed in the template.
+3. Produce or update `qa-ai-output/release-gate.yaml` with decision, risks and evidence paths.
+4. Run `node .qa-ai/scripts/validate-release-gate.mjs`.
+5. Ask the user to confirm the decision before treating it as final.
+6. Run `/qa-help` to confirm there are no pending workflow phases.
+
+## Safety
+
+- Never set `PASS` while `validate-target.mjs` is failing unless the user explicitly accepts the risk in writing.
+- `WAIVED` requires approver name and `waived_reason`.

package/.qa-ai/workflows/test-design-system.md

@@ -0,0 +1,33 @@
+# System Test Design Workflow
+
+Use this workflow on `standard` and `enterprise` tracks **after** requirements normalization and **before** per-RF test design proposals and `.feature` files.
+
+## Inputs
+
+- `qa-ai-output/normalized-requirements.md`
+- Optional: architecture docs, ADRs or diagrams referenced in requirements
+
+## Steps
+
+1. Read `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/` and `.qa-ai/agents/test-design-system-agent.md`.
+2. Produce or update `qa-ai-output/test-design-system.md` from `.qa-ai/templates/test-design-system.template.md`.
+3. Align with configured automation and test-management tools; note what stays manual vs automatable at system level.
+4. Stop with open questions when RF scope or official RF IDs are unclear.
+5. Ask for user approval before starting per-RF proposals.
+
+## Output
+
+- `qa-ai-output/test-design-system.md`
+
+## Validation
+
+```bash
+node .qa-ai/scripts/validate-test-design.mjs
+```
+
+Skipped on `quick` track (per-RF proposal and features may be produced in one Gherkin pass).
+
+## See also
+
+- [Test design (per RF)](test-design.md)
+- [Test design dual-mode](../../docs/qa-ai/test-design-dual-mode.md)

package/.qa-ai/workflows/test-design.md

@@ -0,0 +1,23 @@
+# Test Design Workflow (per RF / epic)
+
+Generate per-RF test proposals and Gherkin tests from approved requirements in the configured Gherkin language from `qa-ai.config.yaml` (`gherkin.language`): English (`en`) or Spanish (`es`).
+
+On `standard` and `enterprise` tracks, complete [system test design](test-design-system.md) first (`qa-ai-output/test-design-system.md`).
+
+## Rules
+
+- Do not generate final tests until the official RF ID is known.
+- Create one `.feature` file per test case.
+- Include exactly one configured scenario keyword per file: `Scenario:` / `Scenario Outline:` for English or `Escenario:` / `Esquema del escenario:` for Spanish.
+- Include the configured acceptance criteria label in every file: `Acceptance Criteria:` for English or `Criterios de aceptación:` for Spanish.
+- Include `# language: es` in Spanish `.feature` files.
+- Include required tag values from `qa-ai.config.yaml`; the default tags are `@priority:`, `@type:` and `@manual:`.
+- Manual tests must also have `.feature` files.
+- Do not generate unit tests.
+
+## Output
+
+- Per-RF proposal: `qa-ai-output/test-design-proposal.md`
+- Feature files: configured `gherkin.featurePath`, usually `features/`
+
+Run `node .qa-ai/scripts/validate-test-design.mjs` after updating proposals and `node .qa-ai/scripts/validate-features.mjs` after generating or changing `.feature` files.

package/.qa-ai/workflows/testrail-sync.md

@@ -0,0 +1,23 @@
+# Test Management Sync Workflow
+
+Produce a sync plan for the configured test management tool. Do not write externally in the MVP.
+
+## Inputs
+
+- Target test management project/suite.
+- Approved `.feature` files.
+- Existing case search results when available.
+- Traceability matrix.
+
+## Output
+
+Update `qa-ai-output/testrail-sync-plan.md` with:
+
+- Sections to create.
+- New cases to create.
+- Existing cases to keep.
+- Existing cases requiring changes.
+- Potential duplicates or overlaps.
+- Cases requiring user decision.
+
+Any future test management write integration must be approval-gated and proposal-first.

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- npm CLI package identity `qa-flowkit@0.4.0-alpha.0` with `npx qa-flowkit init`.
+- `bin/qa-flowkit.mjs` with `init`, `update`, `doctor`, `validate-target`, `validate-features`, `sync-adapters`, `help` and `clean`.
+- npm pack/install smoke coverage for CLI install, safe init refusal, update preservation and package file allowlist.
+- Explicit npm package `files` allowlist to avoid publishing root adapters, GitHub metadata, caches or target-repository artifacts.
+- `qa-help.mjs` and `qa-next-steps.mjs` for context-aware next-step guidance (BMAD-inspired).
+- `project.qaTrack` (`quick`, `standard`, `enterprise`) in presets and `init.mjs --qa-track`.
+- `/qa-help` slash commands for Claude Code and OpenCode adapters.
+- Release quality gate (`release-gate.yaml`, `validate-release-gate.mjs`, `/qa-gate`) with PASS/CONCERNS/FAIL/WAIVED decisions for enterprise track.
+- Dual-mode test design: system-level `test-design-system.md`, per-RF proposal, `validate-test-design.mjs` and `testDesign.*` config paths.
+- `doctor.mjs --strict` for initialized target repositories and CI hardening.
+- `validate-target.mjs` aggregated target-repository validation command.
+- Shared Markdown table parsing utilities for stronger validators.
+- Native Node unit tests for shared validator helpers.
+- Documented test-management mapping template.
+- Stronger traceability matrix validation for Markdown table shape, duplicate test case identifiers and duplicate feature file rows.
+- Stronger test-management sync plan validation for Markdown table shape, proposal-first rows, approval status and duplicate identifiers.
+- Stronger test-management mapping validation for entry shape, duplicate external IDs and secret-like values.
+- Smoke coverage for strict doctor success and failure paths.
+
+### Documentation
+
+- Added `docs/qa-ai/qa-help.md`, `release-gate.md` and `test-design-dual-mode.md`.
+- Framework upgrade guide in `README.md` and `README.es.md`.
+- Documented target-repository hardening status and strict doctor usage in README, roadmap, architecture and backlog.
+- Aligned Claude, OpenCode, Codex and generic adapter validation guidance with the hardened validator pipeline.
+
+## 0.3.0 - Context intake y agentes ampliados
+
+Release tras el merge de [#2](https://github.com/warante/QA_FlowKit/pull/2). Enfoque: carpeta de contexto QA del equipo, init/config refactorizados, agentes más accionables y más comandos `/qa-*` en adaptadores agent-first.
+
+### Added
+
+- Agente `qa-context-intake-agent` y workflow `context-intake.md` para prácticas QA locales en una carpeta del repo.
+- Scripts `config.mjs` y `lib/project-config.mjs`; comando npm `qa:config`.
+- Adaptador **Gemini CLI** (`GEMINI.md` en plantillas).
+- Comandos `/qa-*` ampliados en plantillas y salidas **Claude Code** y **OpenCode** (`qa-config`, `qa-status`, `qa-coverage`, `qa-add-tests`, `qa-update-tests`, `qa-automation-plan`, `qa-full-flow`, etc.).
+- Documentación de carpeta de contexto QA en README (EN/ES).
+
+### Changed
+
+- `init.mjs` simplificado y alineado con presets y lectura de contexto del proyecto.
+- Agentes de fase y especialistas (`available/*`) con guías operativas más detalladas.
+- `doctor.mjs` y `smoke-test.mjs` validan el nuevo flujo y utilidades de configuración.
+- Presets actualizados con soporte de carpeta de contexto.
+
+### Documentation
+
+- `README.md` / `README.es.md`: agent-first bootstrap, context folder y comandos.
+- `docs/qa-ai/*`: arquitectura, workflow, compatibilidad de agentes y backlog.
+
+## 0.2.0 - Workflow enhancements
+
+Major update after the first community release. Focus: agent-first bootstrap, specialist agents, stronger validation and clearer init defaults.
+
+### Added
+
+- Specialist agent catalog under `.qa-ai/agents/specialists/available/` (WebdriverIO, Playwright UI/API, Cypress, Selenium, TestRail, Jira, Karate, Postman, Rest Assured, Appium and generic test design).
+- Agent loading protocol in `.qa-ai/agents/README.md`.
+- OSS smoke test script (`.qa-ai/scripts/smoke-test.mjs`) and `npm run qa:smoke` / `validate:oss-extraction`.
+- Bilingual documentation: `README.es.md`.
+- Init options reference in README (EN/ES): base templates, languages, adapters and advanced overrides.
+- `.gitattributes` for consistent LF line endings.
+
+### Changed
+
+- **Breaking:** workflow artifacts now go to `qa-ai-output/` instead of `docs/qa/` (agents, workflows, adapters, presets and templates updated).
+- `init.mjs` runs with sensible defaults and no flags; adapters are optional via `--adapters` or bootstrap scripts.
+- Presets are documented as **base templates** (`--preset` kept for CLI compatibility).
+- `doctor.mjs` validates specialists, smoke-test script and expanded framework checks.
+- `validate-features.mjs` with stronger Gherkin convention checks.
+- Claude Code and OpenCode `/qa-init`, `/qa-full-flow` and `/qa-clean` commands aligned with agent-first flow and new output paths.
+- Generic `AGENTS.md` adapter reflects minimal default init vs optional adapter outputs.
+
+### Documentation
+
+- Restructured `README.md` with table of contents, quick start and agent-first bootstrap.
+- Updated `docs/qa-ai/*` (architecture, workflow, agent compatibility, implementation guide, backlog, cleanup).
+
+## 0.1.0 - MVP starter
+
+Initial open-source starter package.
+
+Included:
+
+- Portable `.qa-ai/` folder.
+- Preset-aware init, doctor, feature validation and adapter sync scripts.
+- Manifest-based clean script with dry-run default and hash protection.
+- Agent-first `/qa-init` bootstrap script and commands for Claude Code and OpenCode.
+- Rules, agents, workflows and templates.
+- Multi-agent documentation and adapters.
+- Roadmap and backlog for implementation with Codex Desktop.
+
+Refined:
+
+- Safe no-overwrite behavior unless `--force` is passed.
+- Config-aware doctor and feature validation.
+- Adapter selection with default all-adapter generation.
+- Init manifest tracking for generated files and adapter copies.
+- Claude and OpenCode slash commands for init, full flow, doctor, clean and feature validation.
+- Guided slash-command UX when commands are called without arguments.
+- Copy-only bootstrap flow: copy `.qa-ai/`, run `bootstrap-agent-adapters.mjs`, then open the agent.
+- End-to-end workflow documentation for folder-copy usage.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+This project follows a simple contributor covenant:
+
+- Be respectful.
+- Assume good intent.
+- Discuss ideas, not people.
+- Avoid harassment, discrimination or hostile behavior.
+- Keep technical disagreement constructive and evidence-based.
+
+Maintainers may remove comments, issues or contributions that violate these principles.

package/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thanks for contributing to QA FlowKit.
+
+## Principles
+
+- Keep the project repo-first and portable.
+- Do not require a hosted backend for the MVP.
+- Prefer explicit configuration over hidden behavior.
+- All generated test cases must use the configured Gherkin language (`en` or `es`).
+- Every destructive or external write operation must require user approval.
+- Preserve compatibility with multiple AI coding tools through `AGENTS.md`.
+
+## Development workflow
+
+1. Create an issue describing the problem or improvement.
+2. Create a branch from `main`.
+3. Add or update documentation when behavior changes.
+4. Add validation logic when adding a new rule.
+5. Run `npm run validate:oss-extraction` locally (same checks as the GitHub Actions CI workflow).
+6. Open a PR with a clear summary and manual validation steps.
+
+## Commit style
+
+Recommended prefixes:
+
+- `feat:` new behavior
+- `fix:` bug fix
+- `docs:` documentation only
+- `refactor:` internal restructuring
+- `chore:` maintenance
+
+## Pull request checklist
+
+- [ ] The change is documented.
+- [ ] New generated files do not include secrets.
+- [ ] Validation scripts still run.
+- [ ] The open-source license and attribution are preserved.
+- [ ] Any agent-specific instruction has an equivalent generic rule in `AGENTS.md` or `.qa-ai/rules/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QA FlowKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.