@esimplicitylabs/katalyst-xspec 0.6.0 → 0.7.1

package/skills/katalyst-bdd-create-test/references/hybrid-patterns.md

@@ -4,7 +4,7 @@ Common patterns for hybrid testing (combining API and UI) with the Katalyst BDD
 
 ## Core Principle
 
-Hybrid tests use `@hybrid` tag to access both API and UI steps. The typical flow:
+Hybrid tests are scenarios that mix API and UI steps. No tag is needed — every step works in any scenario. Put them in a folder a project reads (e.g. `features/ui/`). The typical flow:
 1. **Setup** - Create test data via API (fast, reliable)
 2. **Test** - Verify behavior in UI (user-facing validation)
 3. **Cleanup** - Remove test data via API (automatic)
@@ -14,7 +14,6 @@ Hybrid tests use `@hybrid` tag to access both API and UI steps. The typical flow
 ### Create via API, Verify in UI
 
 ```gherkin
-@hybrid
 Scenario: Create user via API, verify in admin panel
   # API: Create test data
   Given I am authenticated as an admin via API
@@ -39,7 +38,6 @@ Scenario: Create user via API, verify in admin panel
 ### Setup Data, Test Workflow
 
 ```gherkin
-@hybrid
 Scenario: Test order workflow with pre-created product
   # API: Create product
   Given I am authenticated as an admin via API
@@ -67,7 +65,6 @@ Scenario: Test order workflow with pre-created product
 ### Verify API Changes Reflect in UI
 
 ```gherkin
-@hybrid
 Scenario: API update reflects in UI
   # API: Create and update
   Given I am authenticated as an admin via API
@@ -96,7 +93,6 @@ Scenario: API update reflects in UI
 ### Share IDs Between Layers
 
 ```gherkin
-@hybrid
 Scenario: Use API-created ID in UI navigation
   # API: Create resource
   Given I am authenticated as an admin via API
@@ -117,7 +113,6 @@ Scenario: Use API-created ID in UI navigation
 ### Share Data Between Layers
 
 ```gherkin
-@hybrid
 Scenario: Verify API data in UI
   # Setup variables
   Given I generate a UUID and store as "runId"
@@ -148,7 +143,6 @@ Scenario: Verify API data in UI
 ### Separate API and UI Auth
 
 ```gherkin
-@hybrid
 Scenario: Different auth for API vs UI
   # API: Admin creates data
   Given I am authenticated as an admin via API
@@ -169,7 +163,6 @@ Scenario: Different auth for API vs UI
 ### Use API Token in UI
 
 ```gherkin
-@hybrid
 Scenario: Get token from API, use in UI
   # API: Login and get token
   When I POST "/auth/login" with JSON body:
@@ -190,7 +183,6 @@ Scenario: Get token from API, use in UI
 ### Multi-Step Business Process
 
 ```gherkin
-@hybrid
 Scenario: Complete order processing workflow
   # API: Setup - Create customer and product
   Given I am authenticated as an admin via API
@@ -228,7 +220,6 @@ Scenario: Complete order processing workflow
 ### Data Synchronization Test
 
 ```gherkin
-@hybrid
 Scenario: Real-time sync between API and UI
   Given I am authenticated as an admin via API
   Given I generate a UUID and store as "runId"
@@ -264,7 +255,6 @@ Scenario: Real-time sync between API and UI
 ### Clean State Between Tests
 
 ```gherkin
-@hybrid
 Feature: User Settings
   
   Background:
@@ -301,7 +291,6 @@ Feature: User Settings
 ### Seed Multiple Resources
 
 ```gherkin
-@hybrid
 Scenario: Dashboard with multiple data types
   Given I am authenticated as an admin via API
   Given I generate a UUID and store as "runId"
@@ -339,7 +328,6 @@ Scenario: Dashboard with multiple data types
 ### Test Error States
 
 ```gherkin
-@hybrid
 Scenario: UI shows error when API resource deleted
   # API: Create and immediately delete
   Given I am authenticated as an admin via API
@@ -361,7 +349,6 @@ Scenario: UI shows error when API resource deleted
 ## Complete Example: User Onboarding Flow
 
 ```gherkin
-@hybrid
 Feature: User Onboarding
   As a product owner
   I want to test the complete onboarding flow

package/skills/katalyst-bdd-create-test/references/tui-patterns.md

@@ -7,7 +7,6 @@ Common patterns for TUI (Terminal User Interface) testing with the Katalyst BDD
 ### Start and Verify
 
 ```gherkin
-@tui
 Scenario: Application starts successfully
   Given I start the TUI application
   When I wait for "Welcome"
@@ -17,7 +16,6 @@ Scenario: Application starts successfully
 ### Execute Command
 
 ```gherkin
-@tui
 Scenario: Run a command
   Given I start the TUI application
   When I type "help"
@@ -28,7 +26,6 @@ Scenario: Run a command
 ### Interactive Input
 
 ```gherkin
-@tui
 Scenario: Respond to prompt
   Given I start the TUI application
   When I wait for "Enter your name:"
@@ -42,7 +39,6 @@ Scenario: Respond to prompt
 ### Menu Navigation
 
 ```gherkin
-@tui
 Scenario: Navigate main menu
   Given I start the TUI application
   When I wait for "Main Menu"
@@ -61,7 +57,6 @@ Scenario: Navigate main menu
 ### Arrow Key Navigation
 
 ```gherkin
-@tui
 Scenario: Navigate with arrow keys
   Given I start the TUI application
   When I wait for "Select option:"
@@ -73,7 +68,6 @@ Scenario: Navigate with arrow keys
 ### Navigate to Specific Item
 
 ```gherkin
-@tui
 Scenario: Select specific menu item
   Given I start the TUI application
   When I wait for "Menu"
@@ -84,7 +78,6 @@ Scenario: Select specific menu item
 ### Back Navigation
 
 ```gherkin
-@tui
 Scenario: Go back to previous screen
   Given I start the TUI application
   When I navigate to "Settings" and select
@@ -98,7 +91,6 @@ Scenario: Go back to previous screen
 ### Fill Single Field
 
 ```gherkin
-@tui
 Scenario: Fill text field
   Given I start the TUI application
   When I wait for "Username:"
@@ -112,11 +104,10 @@ Scenario: Fill text field
 ### Fill Form with Table
 
 ```gherkin
-@tui
 Scenario: Fill complete form
   Given I start the TUI application
   When I wait for "New User"
-  And I fill the form:
+  And I fill the TUI form:
     | Field    | Value            |
     | Name     | John Doe         |
     | Email    | john@example.com |
@@ -128,7 +119,6 @@ Scenario: Fill complete form
 ### Select from Dropdown
 
 ```gherkin
-@tui
 Scenario: Select dropdown value
   Given I start the TUI application
   When I wait for "Configuration"
@@ -143,7 +133,6 @@ Scenario: Select dropdown value
 ### Special Keys
 
 ```gherkin
-@tui
 Scenario: Use special keys
   Given I start the TUI application
   When I press "F1"
@@ -155,7 +144,6 @@ Scenario: Use special keys
 ### Modifier Keys
 
 ```gherkin
-@tui
 Scenario: Keyboard shortcuts
   Given I start the TUI application
   When I press ctrl+s
@@ -171,7 +159,6 @@ Scenario: Keyboard shortcuts
 ### Text Editing
 
 ```gherkin
-@tui
 Scenario: Edit text
   Given I start the TUI application
   When I wait for "Editor"
@@ -254,7 +241,6 @@ Scenario: Long operation
 ### Confirm Dialog
 
 ```gherkin
-@tui
 Scenario: Confirm action
   Given I start the TUI application
   When I type "delete all"
@@ -267,7 +253,6 @@ Scenario: Confirm action
 ### Cancel Dialog
 
 ```gherkin
-@tui
 Scenario: Cancel action
   Given I start the TUI application
   When I type "delete all"
@@ -280,7 +265,6 @@ Scenario: Cancel action
 ### Dismiss Dialog
 
 ```gherkin
-@tui
 Scenario: Dismiss with escape
   Given I start the TUI application
   When I press "F1"
@@ -294,7 +278,6 @@ Scenario: Dismiss with escape
 ### Create Baseline Snapshot
 
 ```gherkin
-@tui
 Scenario: Capture main screen
   Given I start the TUI application
   When I wait for "Dashboard"
@@ -304,7 +287,6 @@ Scenario: Capture main screen
 ### Verify Against Snapshot
 
 ```gherkin
-@tui
 Scenario: Verify screen matches snapshot
   Given I start the TUI application
   When I wait for "Dashboard"
@@ -314,7 +296,6 @@ Scenario: Verify screen matches snapshot
 ### Multiple Snapshots
 
 ```gherkin
-@tui
 Scenario: Capture workflow snapshots
   Given I start the TUI application
   When I wait for "Welcome"
@@ -332,7 +313,6 @@ Scenario: Capture workflow snapshots
 ### Error Messages
 
 ```gherkin
-@tui
 Scenario: Show error on invalid input
   Given I start the TUI application
   When I type "invalid-command"
@@ -343,11 +323,10 @@ Scenario: Show error on invalid input
 ### Validation Errors
 
 ```gherkin
-@tui
 Scenario: Form validation
   Given I start the TUI application
   When I wait for "New User"
-  And I fill the form:
+  And I fill the TUI form:
     | Field | Value         |
     | Email | not-an-email  |
   And I submit the form
@@ -359,7 +338,6 @@ Scenario: Form validation
 ### Restart Application
 
 ```gherkin
-@tui
 Scenario: Application restart
   Given I start the TUI application
   When I wait for "Ready"
@@ -375,7 +353,6 @@ Scenario: Application restart
 ### Quit Application
 
 ```gherkin
-@tui
 Scenario: Graceful quit
   Given I start the TUI application
   When I quit the application
@@ -390,7 +367,6 @@ Scenario: Force quit
 ## Complete Example: CLI Todo App
 
 ```gherkin
-@tui
 Feature: Todo CLI Application
   As a user
   I want to manage todos from the terminal
@@ -446,7 +422,7 @@ Feature: Todo CLI Application
     And I press enter
     Then I should see "Settings"
     
-    When I fill the form:
+    When I fill the TUI form:
       | Field     | Value |
       | Theme     | Dark  |
       | Compact   | Yes   |

package/skills/katalyst-bdd-create-test/references/ui-patterns.md

@@ -7,7 +7,6 @@ Common patterns for UI testing with the Katalyst BDD framework.
 ### Basic Navigation
 
 ```gherkin
-@ui
 Scenario: Navigate to page
   Given I navigate to "/dashboard"
   Then I should see text "Dashboard"
@@ -17,7 +16,6 @@ Scenario: Navigate to page
 ### Navigation with Auth
 
 ```gherkin
-@ui
 Scenario: Navigate after login
   Given I am authenticated in UI as "user"
   Given I navigate to "/profile"
@@ -27,7 +25,6 @@ Scenario: Navigate after login
 ### Back Navigation
 
 ```gherkin
-@ui
 Scenario: Go back to previous page
   Given I navigate to "/page1"
   When I click the link "Go to Page 2"
@@ -41,7 +38,6 @@ Scenario: Go back to previous page
 ### Simple Login Form
 
 ```gherkin
-@ui
 Scenario: User login
   Given I navigate to "/login"
   When I fill in "Email" with "user@example.com"
@@ -54,7 +50,6 @@ Scenario: User login
 ### Login with Fetch Intercept (Bypassing Auth)
 
 ```gherkin
-@ui
 Scenario: Test page as authenticated user
   Given I am authenticated in UI as "admin"
   Given I navigate to "/admin/dashboard"
@@ -64,7 +59,6 @@ Scenario: Test page as authenticated user
 ### Login with Specific Roles
 
 ```gherkin
-@ui
 Scenario: Test with multiple roles
   Given I am authenticated in UI as "admin,manager,editor"
   Given I navigate to "/settings"
@@ -75,7 +69,6 @@ Scenario: Test with multiple roles
 ### Login with Tenant
 
 ```gherkin
-@ui
 Scenario: Multi-tenant login
   Given I am authenticated in UI as "admin" for tenant "acme-corp"
   Given I navigate to "/dashboard"
@@ -87,7 +80,6 @@ Scenario: Multi-tenant login
 ### Simple Form Fill
 
 ```gherkin
-@ui
 Scenario: Fill contact form
   Given I navigate to "/contact"
   When I fill in "Name" with "John Doe"
@@ -100,7 +92,6 @@ Scenario: Fill contact form
 ### Form with Data Table
 
 ```gherkin
-@ui
 Scenario: Fill registration form
   Given I navigate to "/register"
   When I fill the form:
@@ -117,7 +108,6 @@ Scenario: Fill registration form
 ### Form with Dropdowns
 
 ```gherkin
-@ui
 Scenario: Fill form with dropdown
   Given I navigate to "/settings"
   When I fill in "Display Name" with "John"
@@ -130,7 +120,6 @@ Scenario: Fill form with dropdown
 ### Clear and Fill Form
 
 ```gherkin
-@ui
 Scenario: Update existing form data
   Given I navigate to "/profile/edit"
   When I clear and fill the form:
@@ -144,7 +133,6 @@ Scenario: Update existing form data
 ### Form Validation
 
 ```gherkin
-@ui
 Scenario: Form shows validation errors
   Given I navigate to "/register"
   When I fill in "Email" with "invalid-email"
@@ -245,7 +233,6 @@ Then I verify that "first" element with "test ID" "result" becomes "visible" dur
 ### Modal Interaction
 
 ```gherkin
-@ui
 Scenario: Confirm deletion in modal
   Given I navigate to "/items"
   When I click the button "Delete"
@@ -259,7 +246,6 @@ Scenario: Confirm deletion in modal
 ### Cancel Modal
 
 ```gherkin
-@ui
 Scenario: Cancel modal
   Given I navigate to "/items"
   When I click the button "Delete"
@@ -273,7 +259,6 @@ Scenario: Cancel modal
 ### Tab Interaction
 
 ```gherkin
-@ui
 Scenario: Switch between tabs
   Given I navigate to "/settings"
   Then the "General" tab should be active
@@ -285,7 +270,6 @@ Scenario: Switch between tabs
 ### Sidebar Navigation
 
 ```gherkin
-@ui
 Scenario: Sidebar navigation
   Given I navigate to "/app"
   Then the sidebar should be visible
@@ -298,7 +282,6 @@ Scenario: Sidebar navigation
 ### Test Mobile View
 
 ```gherkin
-@ui
 Scenario: Mobile navigation
   Given the viewport is "mobile" size
   Given I navigate to "/home"
@@ -310,7 +293,6 @@ Scenario: Mobile navigation
 ### Test Custom Viewport
 
 ```gherkin
-@ui
 Scenario: Test at specific resolution
   Given the viewport is 1920x1080
   Given I navigate to "/dashboard"
@@ -362,7 +344,6 @@ Then I log all cookies
 ## Complete Example: E-commerce Checkout
 
 ```gherkin
-@ui
 Feature: Checkout Flow
   As a customer
   I want to complete checkout

package/skills/katalyst-bdd-quickstart/SKILL.md

@@ -9,22 +9,23 @@ This skill helps you get started with the @esimplicitylabs/katalyst-xspec BDD te
 
 ## Step 1: Scaffold a New Project
 
-Run the scaffolding command:
+Run the scaffolding command (positional target folder, or `.` for the current folder):
 
 ```bash
-npx @esimplicitylabs/katalyst-xspec init
+npx @esimplicitylabs/katalyst-xspec init my-tests
+cd my-tests
+npm install
+npx playwright install chromium   # REQUIRED once: UI tests fail without the browser
+npm test                          # scaffolded examples pass with no .env
 ```
 
 Options:
-- `--dir <name>` - Create in specific directory
+- `<dir>` or `--dir <name>` - Target directory (`init .` = current folder)
 - `--force` - Overwrite existing files
+- `--with-skills` / `--no-skills` - Install (or skip) agent skills without prompting
+- `--skills-agents opencode,claude-code,cursor,generic` - Which agents get skills
 
-Example:
-```bash
-npx @esimplicitylabs/katalyst-xspec init --dir my-tests
-cd my-tests
-npm install
-```
+The project's `package.json` name comes from the folder name (npm-safe, e.g. `My Demo` -> `my-demo`).
 
 ## Step 2: Understand the Project Structure
 
@@ -34,22 +35,20 @@ The scaffold creates:
 my-tests/
 ├── features/
 │   ├── api/
-│   │   └── 00_api_examples.feature    # API test examples
+│   │   └── example.feature   # JSONPlaceholder: GET /users/1, POST /posts
 │   ├── ui/
-│   │   └── 00_ui_examples.feature     # UI test examples
-│   ├── hybrid/
-│   │   └── 00_hybrid_examples.feature # Combined API+UI tests
-│   ├── tui/
-│   │   └── 00_tui_examples.feature    # Terminal UI tests
+│   │   └── example.feature   # Sauce Demo login (standard_user / secret_sauce)
 │   └── steps/
-│       ├── fixtures.ts                 # Adapter configuration
-│       └── steps.ts                    # Step registration
-├── playwright.config.ts                # BDD project config
-├── .env.example                        # Environment template
-├── tsconfig.json                       # TypeScript config
-└── package.json                        # Dependencies
+│       ├── fixtures.ts       # Adapter configuration
+│       └── steps.ts          # Step registration
+├── playwright.config.ts      # Projects: api, ui (tui commented out)
+├── .env.example              # Environment template
+├── tsconfig.json             # TypeScript config
+└── package.json              # Dependencies
 ```
 
+Each Playwright project reads one folder. Steps are untagged: any step works in any scenario. Do NOT add `@api`/`@ui`/`@hybrid`/`@tui` tags — they are not needed (and are ignored).
+
 ### Key Files
 
 **`features/steps/fixtures.ts`** - Configures adapters:
@@ -75,17 +74,21 @@ export { test };
 ```typescript
 import { defineBddProject } from 'playwright-bdd';
 
+import { tagsForProject, resolveExtraTags } from '@esimplicitylabs/katalyst-xspec';
+
+const tags = tagsForProject({ extraTags: resolveExtraTags(process.env.TEST_TAGS) });
+
 const apiBdd = defineBddProject({
   name: 'api',
-  features: 'features/api/**/*.feature',
+  features: 'features/api/**/*.feature',   // selected by folder only
   steps: 'features/steps/**/*.ts',
-  tags: '@api',
+  tags,                                     // only skips @Skip/@ignore + applies TEST_TAGS
 });
 ```
 
-## Step 3: Configure Environment
+## Step 3: Point It at Your App
 
-Copy the environment template:
+The examples use absolute URLs to public demo sites. To test your own app, copy the environment template:
 
 ```bash
 cp .env.example .env
@@ -99,9 +102,9 @@ API_BASE_URL=http://localhost:3000
 
 # Authentication (required -- no hardcoded defaults)
 DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_ADMIN_PASSWORD=changeme
 DEFAULT_USER_USERNAME=user@example.com
-DEFAULT_USER_PASSWORD=user123
+DEFAULT_USER_PASSWORD=changeme
 API_AUTH_LOGIN_PATH=/auth/login
 
 # UI Configuration
@@ -113,13 +116,15 @@ HEADLESS=true
 # CLEANUP_RULES='[{"varMatch":"user","path":"/api/users/{id}"}]'
 ```
 
-### Required Variables by Test Type
+Then use relative paths in features, e.g. `Given I navigate to "/login"`, `When I GET "/health"`.
 
-| Test Type | Required Variables |
+### Required Variables by Step Type
+
+| Steps used | Required Variables |
 |-----------|-------------------|
-| `@api` | `API_BASE_URL` |
-| `@ui` | `FRONTEND_URL` or `BASE_URL` |
-| `@hybrid` | Both API and UI variables |
+| API steps with relative paths | `API_BASE_URL` |
+| UI steps with relative paths | `FRONTEND_URL` or `BASE_URL` |
+| Both in one scenario | Both API and UI variables |
 | Auth steps | `DEFAULT_*_USERNAME`, `DEFAULT_*_PASSWORD` |
 
 ## Step 4: Write Your First Test
@@ -129,7 +134,6 @@ HEADLESS=true
 Create `features/api/health.feature`:
 
 ```gherkin
-@api
 Feature: Health Check
 
   Scenario: API is healthy
@@ -142,7 +146,6 @@ Feature: Health Check
 Create `features/ui/home.feature`:
 
 ```gherkin
-@ui
 Feature: Home Page
 
   Scenario: Home page loads
@@ -150,12 +153,11 @@ Feature: Home Page
     Then I should see text "Welcome"
 ```
 
-### Hybrid Test
+### Mixed API + UI Test
 
-Create `features/hybrid/workflow.feature`:
+Any scenario can mix API and UI steps — no tag or separate project needed. Put it in a folder a project reads (e.g. `features/ui/`, since it needs a browser). Create `features/ui/workflow.feature`:
 
 ```gherkin
-@hybrid
 Feature: User Workflow
 
   Scenario: Create via API, verify in UI
@@ -173,19 +175,18 @@ Feature: User Workflow
 
 ## Step 5: Run Tests
 
-**IMPORTANT:** You must generate Playwright tests before running.
+`npm test` runs `bddgen && playwright test` (generates specs from features, then runs them). If you call `npx playwright test` directly, run `npm run gen` first.
 
 ```bash
-# 1. Generate tests from feature files (REQUIRED)
-npm run gen
-
-# 2. Run all tests
+# Run all tests
 npm test
 
-# 3. Run specific project
-npx playwright test --project=api
-npx playwright test --project=ui
-npx playwright test --project=hybrid
+# Run one project (folder)
+npx playwright test --project api
+npx playwright test --project ui
+
+# Run only scenarios with your own tag
+TEST_TAGS=@smoke npm test
 ```
 
 ### Common Run Commands
@@ -225,16 +226,14 @@ Open the Playwright report:
 npx playwright show-report
 ```
 
-## Common Tags
+## Optional Tags
+
+Tags are only for your own grouping and filtering (`TEST_TAGS=@smoke npm test`, or `TEST_TAGS=smoke,critical`).
 
 | Tag | Purpose |
 |-----|---------|
-| `@api` | API-only tests |
-| `@ui` | UI-only tests |
-| `@tui` | Terminal UI tests |
-| `@hybrid` | Combined API+UI tests |
 | `@smoke` | Quick smoke tests |
-| `@Skip` | Skip this scenario |
+| `@Skip` / `@ignore` | Skip this scenario (excluded by default) |
 | `@wip` | Work in progress |
 
 ## Quick Reference: Essential Steps
@@ -266,14 +265,15 @@ Given I register cleanup DELETE "/resource/{id}"
 
 | Issue | Solution |
 |-------|----------|
-| "No tests found" | Run `npm run gen` first |
-| Steps not available | Check you have the correct tag |
+| "No tests found" | Run `npm run gen` first; check the feature is in a folder a project reads |
+| "Executable doesn't exist" | Run `npx playwright install chromium` |
+| Step not found | Check exact step wording in `katalyst-bdd-step-reference` (no tags needed) |
 | Auth fails | Verify `.env` credentials |
 | Can't find element | Use `When I pause for debugging` |
 
 ## Next Steps
 
-1. **Create more tests** - Add feature files to `features/api/`, `features/ui/`, etc.
+1. **Create more tests** - Add feature files to `features/api/` or `features/ui/`
 2. **Learn steps** - See full step reference with `katalyst-bdd-step-reference` skill
 3. **Patterns** - Learn test patterns with `katalyst-bdd-create-test` skill
 4. **Custom adapters** - Extend framework with `katalyst-bdd-architecture` skill
@@ -290,3 +290,5 @@ This updates:
 - Package dependencies
 - Configuration templates
 - Step definitions
+
+Upgrading from 0.6 or earlier: run `npx katalyst-xspec upgrade --migrate` to remove old `@api`/`@ui`/`@hybrid`/`@tui` tag filters from `playwright.config.*`. Old tags left in feature files are harmless.