bmad-studio 0.1.0 → 1.0.0

package/_bmad/tea/workflows/testarch/bmad-testarch-framework/checklist.md

@@ -1,345 +0,0 @@
-# Test Framework Setup - Validation Checklist
-
-This checklist ensures the framework workflow completes successfully and all deliverables meet quality standards.
-
----
-
-## Prerequisites
-
-Before starting the workflow:
-
-- [ ] Project root contains a valid project manifest (`package.json`, `pyproject.toml`, `pom.xml`, `build.gradle`, `go.mod`, `*.csproj`, `Gemfile`, or `Cargo.toml`)
-- [ ] No existing test framework detected that conflicts with the target setup
-- [ ] Project type identifiable (React, Vue, Angular, Next.js, Node, Python, Java, Go, .NET, Ruby, Rust, etc.)
-- [ ] Bundler identifiable (Vite, Webpack, Rollup, esbuild) or not applicable (backend projects)
-- [ ] User has write permissions to create directories and files
-
----
-
-## Process Steps
-
-### Step 1: Preflight Checks
-
-- [ ] Stack type detected (`frontend`, `backend`, or `fullstack`)
-- [ ] Project manifest successfully read and parsed (`package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, etc.)
-- [ ] Project type extracted correctly
-- [ ] Bundler identified (or marked as N/A for backend projects)
-- [ ] No framework conflicts detected
-- [ ] Architecture documents located (if available)
-
-### Step 2: Framework Selection
-
-- [ ] Framework auto-detection logic executed
-- [ ] Framework choice justified (Playwright vs Cypress for frontend; pytest/JUnit/Go test/xUnit/RSpec for backend)
-- [ ] Framework preference respected (if explicitly set via `config.test_framework`)
-- [ ] User notified of framework selection and rationale
-
-### Step 3: Directory Structure
-
-- [ ] `tests/` root directory created
-- [ ] `tests/e2e/` directory created (or user's preferred structure)
-- [ ] `tests/support/` directory created (critical pattern)
-- [ ] `tests/support/fixtures/` directory created
-- [ ] `tests/support/fixtures/factories/` directory created
-- [ ] `tests/support/helpers/` directory created
-- [ ] `tests/support/page-objects/` directory created (if applicable)
-- [ ] All directories have correct permissions
-
-**Note**: Test organization is flexible (e2e/, api/, integration/). The **support/** folder is the key pattern.
-
-### Step 4: Configuration Files
-
-- [ ] Framework config file created (`playwright.config.ts` or `cypress.config.ts`)
-- [ ] Config file uses TypeScript (if `use_typescript: true`)
-- [ ] Timeouts configured correctly (action: 15s, navigation: 30s, test: 60s)
-- [ ] Base URL configured with environment variable fallback
-- [ ] Trace/screenshot/video set to retain-on-failure
-- [ ] Multiple reporters configured (HTML + JUnit + console)
-- [ ] Parallel execution enabled
-- [ ] CI-specific settings configured (retries, workers)
-- [ ] Config file is syntactically valid (no compilation errors)
-
-### Step 5: Environment Configuration
-
-- [ ] `.env.example` created in project root
-- [ ] `TEST_ENV` variable defined
-- [ ] `BASE_URL` variable defined with default
-- [ ] `API_URL` variable defined (if applicable)
-- [ ] Authentication variables defined (if applicable)
-- [ ] Feature flag variables defined (if applicable)
-- [ ] `.nvmrc` created with appropriate Node version
-
-### Step 6: Fixture Architecture
-
-- [ ] `tests/support/fixtures/index.ts` created
-- [ ] Base fixture extended from Playwright/Cypress
-- [ ] Type definitions for fixtures created
-- [ ] mergeTests pattern implemented (if multiple fixtures)
-- [ ] Auto-cleanup logic included in fixtures
-- [ ] Fixture architecture follows knowledge base patterns
-
-### Step 7: Data Factories
-
-- [ ] At least one factory created (e.g., UserFactory)
-- [ ] Factories use @faker-js/faker for realistic data
-- [ ] Factories track created entities (for cleanup)
-- [ ] Factories implement `cleanup()` method
-- [ ] Factories integrate with fixtures
-- [ ] Factories follow knowledge base patterns
-
-### Step 8: Sample Tests
-
-- [ ] Example test file created (`tests/e2e/example.spec.ts`)
-- [ ] Test uses fixture architecture
-- [ ] Test demonstrates data factory usage
-- [ ] Test uses proper selector strategy (data-testid)
-- [ ] Test follows Given-When-Then structure
-- [ ] Test includes proper assertions
-- [ ] Network interception demonstrated (if applicable)
-
-### Step 9: Helper Utilities
-
-- [ ] API helper created (if API testing needed)
-- [ ] Network helper created (if network mocking needed)
-- [ ] Auth helper created (if authentication needed)
-- [ ] Helpers follow functional patterns
-- [ ] Helpers have proper error handling
-
-### Step 10: Documentation
-
-- [ ] `tests/README.md` created
-- [ ] Setup instructions included
-- [ ] Running tests section included
-- [ ] Architecture overview section included
-- [ ] Best practices section included
-- [ ] CI integration section included
-- [ ] Knowledge base references included
-- [ ] Troubleshooting section included
-
-### Step 11: Build & Test Script Updates
-
-- [ ] Minimal test script added to appropriate config (`package.json` for frontend, `Makefile`/`pyproject.toml`/`build.gradle` for backend)
-- [ ] Test framework dependency added (if not already present)
-- [ ] Type definitions added (if TypeScript)
-- [ ] Users can extend with additional scripts as needed
-
----
-
-## Output Validation
-
-### Configuration Validation
-
-- [ ] Config file loads without errors
-- [ ] Config file passes linting (if linter configured)
-- [ ] Config file uses correct syntax for chosen framework
-- [ ] All paths in config resolve correctly
-- [ ] Reporter output directories exist or are created on test run
-
-### Test Execution Validation
-
-- [ ] Sample test runs successfully
-- [ ] Test execution produces expected output (pass/fail)
-- [ ] Test artifacts generated correctly (traces, screenshots, videos)
-- [ ] Test report generated successfully
-- [ ] No console errors or warnings during test run
-
-### Directory Structure Validation
-
-- [ ] All required directories exist
-- [ ] Directory structure matches framework conventions
-- [ ] No duplicate or conflicting directories
-- [ ] Directories accessible with correct permissions
-
-### File Integrity Validation
-
-- [ ] All generated files are syntactically correct
-- [ ] No placeholder text left in files (e.g., "TODO", "FIXME")
-- [ ] All imports resolve correctly
-- [ ] No hardcoded credentials or secrets in files
-- [ ] All file paths use correct separators for OS
-
----
-
-## Quality Checks
-
-### Code Quality
-
-- [ ] Generated code follows project coding standards
-- [ ] TypeScript types are complete and accurate (no `any` unless necessary)
-- [ ] No unused imports or variables
-- [ ] Consistent code formatting (matches project style)
-- [ ] No linting errors in generated files
-
-### Best Practices Compliance
-
-- [ ] Fixture architecture follows pure function → fixture → mergeTests pattern
-- [ ] Data factories implement auto-cleanup
-- [ ] Network interception occurs before navigation
-- [ ] Selectors use data-testid strategy
-- [ ] Artifacts only captured on failure
-- [ ] Tests follow Given-When-Then structure
-- [ ] No hard-coded waits or sleeps
-
-### Knowledge Base Alignment
-
-- [ ] Fixture pattern matches `fixture-architecture.md`
-- [ ] Data factories match `data-factories.md`
-- [ ] Network handling matches `network-first.md`
-- [ ] Config follows `playwright-config.md` or `test-config.md`
-- [ ] Test quality matches `test-quality.md`
-
-### Pact Consumer CDC Alignment (when `tea_use_pactjs_utils` enabled)
-
-- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
-- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
-- [ ] Scripts source `env-setup.sh` inline in package.json
-- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
-- [ ] Shell scripts use `PACTICIPANT` env var pattern (not hardcoded service names)
-- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
-- [ ] `record-deployment.sh` has branch guard (only records on main/master)
-- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
-- [ ] CI workflow named `contract-test-consumer.yml`
-- [ ] CI has workflow-level env block (not per-step)
-- [ ] CI has `detect-breaking-change` step before install
-- [ ] CI step numbering skips (3) — webhook-triggered provider verification
-- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
-- [ ] CI has NO upload-artifact step (broker is source of truth)
-- [ ] `.github/actions/detect-breaking-change/action.yml` exists
-- [ ] Consumer tests use `.pacttest.ts` extension
-- [ ] Consumer tests use PactV4 `addInteraction()` builder (not PactV3 fluent API)
-- [ ] Consumer tests call REAL consumer code (actual API client functions), NOT raw `fetch()`
-- [ ] Consumer code exposes URL injection mechanism (`setApiUrl()`, env var, or constructor param)
-- [ ] Local consumer-helpers shim present if `@seontechnologies/pactjs-utils` not installed
-- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
-
-### Security Checks
-
-- [ ] No credentials in configuration files
-- [ ] .env.example contains placeholders, not real values
-- [ ] Sensitive test data handled securely
-- [ ] API keys and tokens use environment variables
-- [ ] No secrets committed to version control
-
----
-
-## Integration Points
-
-### Status File Integration
-
-- [ ] Framework initialization logged in Quality & Testing Progress section
-- [ ] Status file updated with completion timestamp
-- [ ] Status file shows framework: Playwright or Cypress
-
-### Knowledge Base Integration
-
-- [ ] Relevant knowledge fragments identified from tea-index.csv
-- [ ] Knowledge fragments successfully loaded
-- [ ] Patterns from knowledge base applied correctly
-- [ ] Knowledge base references included in documentation
-
-### Workflow Dependencies
-
-- [ ] Can proceed to `ci` workflow after completion
-- [ ] Can proceed to `test-design` workflow after completion
-- [ ] Can proceed to `atdd` workflow after completion
-- [ ] Framework setup compatible with downstream workflows
-
----
-
-## Completion Criteria
-
-**All of the following must be true:**
-
-- [ ] All prerequisite checks passed
-- [ ] All process steps completed without errors
-- [ ] All output validations passed
-- [ ] All quality checks passed
-- [ ] All integration points verified
-- [ ] Sample test executes successfully
-- [ ] User can run the appropriate test command without errors (`npm run test:e2e`, `pytest`, `go test ./...`, etc.)
-- [ ] Documentation is complete and accurate
-- [ ] No critical issues or blockers identified
-
----
-
-## Post-Workflow Actions
-
-**User must complete:**
-
-1. [ ] Copy `.env.example` to `.env`
-2. [ ] Fill in environment-specific values in `.env`
-3. [ ] Run `npm install` to install test dependencies
-4. [ ] Run `npm run test:e2e` to verify setup
-5. [ ] Review `tests/README.md` for project-specific guidance
-
-**Recommended next workflows:**
-
-1. [ ] Run `ci` workflow to set up CI/CD pipeline
-2. [ ] Run `test-design` workflow to plan test coverage
-3. [ ] Run `atdd` workflow when ready to develop stories
-
----
-
-## Rollback Procedure
-
-If workflow fails and needs to be rolled back:
-
-1. [ ] Delete `tests/` directory
-2. [ ] Remove test scripts from package.json
-3. [ ] Delete `.env.example` (if created)
-4. [ ] Delete `.nvmrc` (if created)
-5. [ ] Delete framework config file
-6. [ ] Remove test dependencies from package.json (if added)
-7. [ ] Run `npm install` to clean up node_modules
-
----
-
-## Notes
-
-### Common Issues
-
-**Issue**: Config file has TypeScript errors
-
-- **Solution**: Ensure `@playwright/test` or `cypress` types are installed
-
-**Issue**: Sample test fails to run
-
-- **Solution**: Check BASE_URL in .env, ensure app is running
-
-**Issue**: Fixture cleanup not working
-
-- **Solution**: Verify cleanup() is called in fixture teardown
-
-**Issue**: Network interception not working
-
-- **Solution**: Ensure route setup occurs before page.goto()
-
-### Framework-Specific Considerations
-
-**Playwright:**
-
-- Requires Node.js 18+
-- Browser binaries auto-installed on first run
-- Trace viewer requires running `npx playwright show-trace`
-
-**Cypress:**
-
-- Requires Node.js 18+
-- Cypress app opens on first run
-- Component testing requires additional setup
-
-### Version Compatibility
-
-- [ ] Node.js version matches .nvmrc
-- [ ] Framework version compatible with Node.js version
-- [ ] TypeScript version compatible with framework
-- [ ] All peer dependencies satisfied
-
----
-
-**Checklist Complete**: Sign off when all items checked and validated.
-
-**Completed by:** {name}
-**Date:** {date}
-**Framework:** { Playwright / Cypress or something else}
-**Notes:** {notes}

package/_bmad/tea/workflows/testarch/bmad-testarch-framework/instructions.md

@@ -1,45 +0,0 @@
-<!-- Powered by BMAD-CORE™ -->
-
-# Test Framework Setup
-
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-framework`
-**Version**: 5.0 (Step-File Architecture)
-
----
-
-## Overview
-
-Initialize a production-ready test framework (Playwright or Cypress) with fixtures, helpers, configuration, and best practices.
-
----
-
-## WORKFLOW ARCHITECTURE
-
-This workflow uses **step-file architecture**:
-
-- **Micro-file Design**: Each step is self-contained
-- **JIT Loading**: Only the current step file is in memory
-- **Sequential Enforcement**: Execute steps in order without skipping
-
----
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-From `workflow.yaml`, resolve:
-
-- `config_source`, `test_artifacts`, `user_name`, `communication_language`, `document_output_language`, `date`
-- `test_dir`, `use_typescript`, `framework_preference`, `project_size`
-
-### 2. First Step
-
-Load, read completely, and execute:
-`./steps-c/step-01-preflight.md`
-
-### 3. Resume Support
-
-If the user selects **Resume** mode, load, read completely, and execute:
-`./steps-c/step-01b-resume.md`
-
-This checks the output document for progress tracking frontmatter and routes to the next incomplete step.

package/_bmad/tea/workflows/testarch/bmad-testarch-framework/steps-c/step-01-preflight.md

@@ -1,132 +0,0 @@
----
-name: 'step-01-preflight'
-description: 'Verify prerequisites and gather project context'
-nextStepFile: './step-02-select-framework.md'
-outputFile: '{test_artifacts}/framework-setup-progress.md'
----
-
-# Step 1: Preflight Checks
-
-## STEP GOAL
-
-Verify the project is ready for framework scaffolding and gather key context.
-
-## MANDATORY EXECUTION RULES
-
-- 📖 Read the entire step file before acting
-- ✅ Speak in `{communication_language}`
-- 🚫 Halt if preflight requirements fail
-
----
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Record outputs before proceeding
-- 📖 Load the next step only when instructed
-
-## CONTEXT BOUNDARIES:
-
-- Available context: config, loaded artifacts, and knowledge fragments
-- Focus: this step's goal only
-- Limits: do not execute future steps
-- Dependencies: prior steps' outputs (if any)
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-## 1. Stack Detection
-
-**Read `config.test_stack_type`** from `{config_source}`.
-
-**Auto-Detection Algorithm** (when `test_stack_type` is `"auto"` or not configured):
-
-- Scan `{project-root}` for project manifests:
-  - **Frontend indicators**: `package.json` with react/vue/angular/next dependencies, `playwright.config.*`, `vite.config.*`, `webpack.config.*`
-  - **Backend indicators**: `pyproject.toml`, `pom.xml`/`build.gradle`, `go.mod`, `*.csproj`/`*.sln`, `Gemfile`, `Cargo.toml`
-  - **Both present** = `fullstack`; only frontend = `frontend`; only backend = `backend`
-- Explicit `test_stack_type` config value overrides auto-detection
-- **Backward compatibility**: if `test_stack_type` is not in config, treat as `"auto"` (preserves current frontend behavior for existing installs)
-
-Store result as `{detected_stack}` = `frontend` | `backend` | `fullstack`
-
----
-
-## 2. Validate Prerequisites
-
-**If {detected_stack} is `frontend` or `fullstack`:**
-
-- `package.json` exists in project root
-- No existing E2E framework (`playwright.config.*`, `cypress.config.*`, `cypress.json`)
-
-**If {detected_stack} is `backend` or `fullstack`:**
-
-- At least one backend project manifest exists (`pyproject.toml`, `pom.xml`, `build.gradle`, `go.mod`, `*.csproj`, `Gemfile`, `Cargo.toml`)
-- No existing test framework config that conflicts (e.g., `conftest.py` with full pytest suite, `src/test/` with JUnit suite)
-
-- Architecture/stack context available (project type, bundler, dependencies)
-
-If any fail, **HALT** and report the missing requirement.
-
----
-
-## 3. Gather Project Context
-
-**If {detected_stack} is `frontend` or `fullstack`:**
-
-- Read `package.json` to identify framework, bundler, dependencies
-
-**If {detected_stack} is `backend` or `fullstack`:**
-
-- Read the relevant project manifest (`pyproject.toml`, `pom.xml`, `go.mod`, `*.csproj`, `Gemfile`, `Cargo.toml`) to identify language, framework, and dependencies
-
-- Check for architecture docs (`architecture.md`, `tech-spec*.md`) if available
-- Note auth requirements and APIs (if documented)
-
----
-
-## 3. Confirm Findings
-
-Summarize:
-
-- Project type and bundler
-- Whether a framework is already installed
-- Any relevant context docs found
-
----
-
-### 4. Save Progress
-
-**Save this step's accumulated work to `{outputFile}`.**
-
-- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
-
-  ```yaml
-  ---
-  stepsCompleted: ['step-01-preflight']
-  lastStep: 'step-01-preflight'
-  lastSaved: '{date}'
-  ---
-  ```
-
-  Then write this step's output below the frontmatter.
-
-- **If `{outputFile}` already exists**, update:
-  - Add `'step-01-preflight'` to `stepsCompleted` array (only if not already present)
-  - Set `lastStep: 'step-01-preflight'`
-  - Set `lastSaved: '{date}'`
-  - Append this step's output to the appropriate section of the document.
-
-Load next step: `{nextStepFile}`
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
-
-### ✅ SUCCESS:
-
-- Step completed in full with required outputs
-
-### ❌ SYSTEM FAILURE:
-
-- Skipped sequence steps or missing outputs
-  **Master Rule:** Skipping steps is FORBIDDEN.

package/_bmad/tea/workflows/testarch/bmad-testarch-framework/steps-c/step-01b-resume.md

@@ -1,116 +0,0 @@
----
-name: 'step-01b-resume'
-description: 'Resume interrupted workflow from last completed step'
-outputFile: '{test_artifacts}/framework-setup-progress.md'
----
-
-# Step 1b: Resume Workflow
-
-## STEP GOAL
-
-Resume an interrupted workflow by loading the existing progress document, verifying previously created artifacts still exist on disk, displaying progress, and routing to the next incomplete step.
-
-## MANDATORY EXECUTION RULES
-
-- 📖 Read the entire step file before acting
-- ✅ Speak in `{communication_language}`
-
----
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 📖 Load the next step only when instructed
-
-## CONTEXT BOUNDARIES:
-
-- Available context: Output document with progress frontmatter
-- Focus: Load progress and route to next step
-- Limits: Do not re-execute completed steps
-- Dependencies: Output document must exist from a previous run
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-### 1. Load Output Document
-
-Read `{outputFile}` and parse YAML frontmatter for:
-
-- `stepsCompleted` — array of completed step names
-- `lastStep` — last completed step name
-- `lastSaved` — timestamp of last save
-
-**If `{outputFile}` does not exist**, display:
-
-"⚠️ **No previous progress found.** There is no output document to resume from. Please use **[C] Create** to start a fresh workflow run."
-
-**THEN:** Halt. Do not proceed.
-
----
-
-### 2. Verify Previously Created Artifacts
-
-Since this workflow creates code files, verify that artifacts from completed steps still exist on disk:
-
-- If `step-01-preflight` completed: Confirm `package.json` still exists
-- If `step-03-scaffold-framework` completed: Confirm directory structure and config files exist
-- If `step-04-docs-and-scripts` completed: Confirm `{test_dir}/README.md` exists
-
-If any expected artifacts are missing, warn the user and suggest re-running from the step that created them.
-
----
-
-### 3. Display Progress Dashboard
-
-Display:
-
-"📋 **Workflow Resume — Test Framework Setup**
-
-**Last saved:** {lastSaved}
-**Steps completed:** {stepsCompleted.length} of 5
-
-1. ✅/⬜ Preflight Checks (step-01-preflight)
-2. ✅/⬜ Select Framework (step-02-select-framework)
-3. ✅/⬜ Scaffold Framework (step-03-scaffold-framework)
-4. ✅/⬜ Docs & Scripts (step-04-docs-and-scripts)
-5. ✅/⬜ Validate & Summary (step-05-validate-and-summary)"
-
----
-
-### 4. Route to Next Step
-
-Based on `lastStep`, load the next incomplete step:
-
-- `'step-01-preflight'` → `./step-02-select-framework.md`
-- `'step-02-select-framework'` → `./step-03-scaffold-framework.md`
-- `'step-03-scaffold-framework'` → `./step-04-docs-and-scripts.md`
-- `'step-04-docs-and-scripts'` → `./step-05-validate-and-summary.md`
-- `'step-05-validate-and-summary'` → **Workflow already complete.** Display: "✅ **All steps completed.** Use **[V] Validate** to review outputs or **[E] Edit** to make revisions." Then halt.
-
-**If `lastStep` does not match any value above**, display: "⚠️ **Unknown progress state** (`lastStep`: {lastStep}). Please use **[C] Create** to start fresh." Then halt.
-
-**Otherwise**, load the identified step file, read completely, and execute.
-
-The existing content in `{outputFile}` provides context from previously completed steps.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Output document loaded and parsed correctly
-- Previously created artifacts verified on disk
-- Progress dashboard displayed accurately
-- Routed to correct next step
-
-### ❌ SYSTEM FAILURE:
-
-- Not loading output document
-- Not verifying existing artifacts
-- Incorrect progress display
-- Routing to wrong step
-- Re-executing completed steps
-
-**Master Rule:** Resume MUST route to the exact next incomplete step. Never re-execute completed steps.